Documentation/public-inbox-daemon.pod

   1 =head1 NAME
   2
   3 public-inbox-daemon - common usage for public-inbox network daemons
   4
   5 =head1 SYNOPSIS
   6
   7         public-inbox-httpd
   8         public-inbox-imapd
   9         public-inbox-nntpd
  10
  11 =head1 DESCRIPTION
  12
  13 This manual describes common options and behavior for
  14 public-inbox network daemons.  Network daemons for public-inbox
  15 provide read-only NNTP, IMAP and HTTP access to public-inboxes.  Write
  16 access to a public-inbox will never be required to run these.
  17
  18 These daemons are implemented with a common core using
  19 non-blocking sockets and optimized for fairness; even with
  20 thousands of connected clients over slow links.
  21
  22 They also provide graceful shutdown/upgrade support to avoid
  23 breaking existing connections during software upgrades.
  24
  25 These daemons may also utilize multiple pre-forked worker
  26 processes to take advantage of multiple CPUs.
  27
  28 =head1 OPTIONS
  29
  30 =over
  31
  32 =item -l ADDRESS
  33
  34 =item --listen ADDRESS
  35
  36 This takes an absolute path to a Unix socket or HOST:PORT
  37 to listen on.  For example, to listen to TCP connections on
  38 port 119, use: C<-l 0.0.0.0:119>.  This may also point to
  39 a Unix socket (C<-l /path/to/http.sock>) for a reverse proxy
  40 like L<nginx(8)> to use.
  41
  42 May be specified multiple times to allow listening on multiple
  43 sockets.
  44
  45 This does not need to be specified at all if relying on
  46 L<systemd.socket(5)> or similar
  47
  48 Default: server-dependent unless socket activation is used with
  49 L<systemd(1)> or similar (see L<systemd.socket(5)>).
  50
  51 =item -1
  52
  53 =item --stdout PATH
  54
  55 Specify an appendable path to redirect stdout descriptor (1) to.
  56 Using this is preferable to setting up the redirect externally
  57 (e.g. E<gt>E<gt>/path/to/log in shell) since it allows
  58 SIGUSR1 to be handled (see L<SIGNALS/SIGNALS> below).
  59
  60 Default: /dev/null
  61
  62 =item -2 PATH
  63
  64 =item --stderr PATH
  65
  66 Like C<--stdout>, but for the stderr descriptor (2).
  67
  68 =item -W
  69
  70 =item --worker-processes
  71
  72 Set the number of worker processes.
  73
  74 Normally, this should match the number of CPUs on the system to
  75 take full advantage of the hardware.  However, users of
  76 memory-constrained systems may want to lower this.
  77
  78 Setting this to zero (C<-W0>) disables the master/worker split;
  79 saving some memory but removing the ability to use SIGTTIN
  80 to increase worker processes or have the worker restarted by
  81 the master on crashes.
  82
  83 Default: 1
  84
  85 =back
  86
  87 =head1 SIGNALS
  88
  89 Most of our signal handling behavior is copied from L<nginx(8)>
  90 and/or L<starman(1)>; so it is possible to reuse common scripts
  91 for managing them.
  92
  93 =over 8
  94
  95 =item SIGUSR1
  96
  97 Reopens log files pointed to by --stdout and --stderr options.
  98
  99 =item SIGUSR2
 100
 101 Spawn a new process with the intention to replace the running one.
 102 See L</UPGRADING> below.
 103
 104 =item SIGHUP
 105
 106 Reload config files associated with the process.
 107 (Note: broken for L<public-inbox-httpd(1)> only in E<lt>= 1.6)
 108
 109 =item SIGTTIN
 110
 111 Increase the number of running workers processes by one.
 112
 113 =item SIGTTOU
 114
 115 Decrease the number of running worker processes by one.
 116
 117 =item SIGWINCH
 118
 119 Stop all running worker processes.   SIGHUP or SIGTTIN
 120 may be used to restart workers.
 121
 122 =item SIGQUIT
 123
 124 Gracefully terminate the running process.
 125
 126 =back
 127
 128 SIGTTOU, SIGTTIN, SIGWINCH all have no effect when worker
 129 processes are disabled with C<-W0> on the command-line.
 130
 131 =head1 ENVIRONMENT
 132
 133 =over 8
 134
 135 =item PI_CONFIG
 136
 137 The default config file, normally "~/.public-inbox/config".
 138 See L<public-inbox-config(5)>
 139
 140 =item LISTEN_FDS, LISTEN_PID
 141
 142 Used by systemd (and compatible) installations for socket
 143 activation.  See L<systemd.socket(5)> and L<sd_listen_fds(3)>.
 144
 145 =item PERL_INLINE_DIRECTORY
 146
 147 Pointing this to point to a writable directory enables the use
 148 of L<Inline> and L<Inline::C> extensions which may provide
 149 platform-specific performance improvements.  Currently, this
 150 enables the use of L<vfork(2)> which speeds up subprocess
 151 spawning with the Linux kernel.
 152
 153 public-inbox will never enable L<Inline::C> automatically without
 154 this environment variable set or C<~/.cache/public-inbox/inline-c>
 155 created by a user. See L<Inline> and L<Inline::C> for more details.
 156
 157 =back
 158
 159 =head1 UPGRADING
 160
 161 There are two ways to upgrade a running process.
 162
 163 Users of process management systems with socket activation
 164 (L<systemd(1)> or similar) may rely on multiple instances For
 165 systemd, this means using two (or more) '@' instances for each
 166 service (e.g. C<SERVICENAME@INSTANCE>) as documented in
 167 L<systemd.unit(5)>.
 168
 169 Users of traditional SysV init may use SIGUSR2 to spawn
 170 a replacement process and gracefully terminate the old
 171 process using SIGQUIT.
 172
 173 In either case, the old process will not truncate running
 174 responses; so responses to expensive requests do not get
 175 interrupted and lost.
 176
 177 =head1 CONTACT
 178
 179 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 180
 181 The mail archives are hosted at L<https://public-inbox.org/meta/> and
 182 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 183
 184 =head1 COPYRIGHT
 185
 186 Copyright 2013-2021 all contributors L<mailto:meta@public-inbox.org>
 187
 188 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 189
 190 =head1 SEE ALSO
 191
 192 L<public-inbox-httpd(1)>, L<public-inbox-imapd(1)>,
 193 L<public-inbox-nntpd(1)>