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