=head1 NAME public-inbox-daemon - common usage for public-inbox network daemons =head1 SYNOPSIS public-inbox-netd public-inbox-httpd public-inbox-imapd public-inbox-nntpd public-inbox-pop3d =head1 DESCRIPTION This manual describes common options and behavior for public-inbox network daemons. Network daemons for public-inbox provide read-only IMAP, HTTP, NNTP and POP3 access to public-inboxes. Write access to a public-inbox will never be required to run these. These daemons are implemented with a common core using non-blocking sockets and optimized for fairness; even with thousands of connected clients over slow links. They also provide graceful shutdown/upgrade support to avoid breaking existing connections during software upgrades. These daemons may also utilize multiple pre-forked worker processes to take advantage of multiple CPUs. =head1 OPTIONS =over =item -l [PROTOCOL://]ADDRESS[?opt1=val1,opt2=val2] =item --listen [PROTOCOL://]ADDRESS[?opt1=val1,opt2=val2] This takes an absolute path to a Unix socket or HOST:PORT to listen on. For example, to listen to TCP connections on port 119, use: C<-l 0.0.0.0:119>. This may also point to a Unix socket (C<-l /path/to/http.sock>) for a reverse proxy like L to use. May be specified multiple times to allow listening on multiple sockets. Unless per-listener options are used (required for L), this does not need to be specified at all if relying on L or similar, Per-listener options may be specified after C as C pairs delimited by C<,>. See L for documentation on the C, C, C, C, C, and C options available. Default: server-dependent unless socket activation is used with L or similar (see L). =item -1 =item --stdout PATH Specify an appendable path to redirect stdout descriptor (1) to. Using this is preferable to setting up the redirect externally (e.g. EE/path/to/log in shell) since it allows SIGUSR1 to be handled (see L below). C may also be specified on a per-listener basis. Default: /dev/null with C<--daemonize>, inherited otherwise =item -2 PATH =item --stderr PATH Like C<--stdout>, but for the stderr descriptor (2). C may also be specified on a per-listener basis. Default: /dev/null with C<--daemonize>, inherited otherwise =item -W =item --worker-processes Set the number of worker processes. Normally, this should match the number of CPUs on the system to take full advantage of the hardware. However, users of memory-constrained systems may want to lower this. Setting this to zero (C<-W0>) disables the master/worker split; saving some memory but removing the ability to use SIGTTIN to increase worker processes or have the worker restarted by the master on crashes. Default: 1 =item --cert /path/to/cert The default TLS certificate for HTTPS, IMAPS, NNTPS, POP3S and/or STARTTLS support if the C option is not given with C<--listen>. With this option, well-known TCP ports automatically get TLS or STARTTLS support if using systemd-compatible socket activation. That is, ports 443, 563, 993, and 995 support HTTPS, NNTPS, IMAPS, and POP3S, respectively; while ports 110, 119, and 143 support STARTTLS on POP3, NNTP, and IMAP, respectively. =item --key /path/to/key The default TLS certificate key for the default C<--cert> or per-listener C option. The private key may be concatenated into the cert file itself, in which case this option is not needed. =item --multi-accept INTEGER By default, each worker accepts one connection at a time to maximize fairness and minimize contention across multiple processes on a shared listen socket. Accepting multiple connections at once may be useful in constrained deployments with few, heavily loaded workers. Negative values enables a worker to accept all available clients at once, possibly starving others in the process. C<-1> behaves like C in nginx; while C<0> (the default) is C in nginx. Positive values allow fine-tuning without the runaway behavior of C<-1>. This may be specified on a per-listener basis via the C per-listener directive (e.g. C<-l http://127.0.0.1?multi-accept=1>). Default: 0 =back =head1 SIGNALS Most of our signal handling behavior is copied from L and/or L, so it is possible to reuse common scripts for managing them. =over 8 =item SIGUSR1 Reopens log files pointed to by --stdout and --stderr options. =item SIGUSR2 Spawn a new process with the intention to replace the running one. See L below. =item SIGHUP Reload config files associated with the process. (Note: broken for L only in E= 1.6) =item SIGTTIN Increase the number of running worker processes by one. =item SIGTTOU Decrease the number of running worker processes by one. =item SIGWINCH Stop all running worker processes. SIGHUP or SIGTTIN may be used to restart workers. =item SIGQUIT Gracefully terminate the running process. =back SIGTTOU, SIGTTIN, SIGWINCH all have no effect when worker processes are disabled with C<-W0> on the command-line. =head1 ENVIRONMENT =over 8 =item PI_CONFIG The default config file, normally "~/.public-inbox/config". See L =item LISTEN_FDS, LISTEN_PID Used by systemd (and compatible) installations for socket activation. See L and L. =item PERL_INLINE_DIRECTORY Pointing this to a writable directory enables the use of L and L extensions which may provide platform-specific performance improvements. Currently, this enables the use of L which speeds up subprocess spawning with the Linux kernel. public-inbox will never enable L automatically without this environment variable set or C<~/.cache/public-inbox/inline-c> created by a user. See L and L for more details. =back =head1 UPGRADING There are two ways to upgrade a running process. Users of process management systems with socket activation (L or similar) may rely on multiple daemon instances. For systemd, this means using two (or more) '@' instances for each service (e.g. C) as documented in L. Users of traditional SysV init may use SIGUSR2 to spawn a replacement process and gracefully terminate the old process using SIGQUIT. In either case, the old process will not truncate running responses; so responses to expensive requests do not get interrupted and lost. =head1 CONTACT Feedback welcome via plain-text mail to L The mail archives are hosted at L and L =head1 COPYRIGHT Copyright all contributors L License: AGPL-3.0+ L =head1 SEE ALSO L, L, L, L, L