diff options
Diffstat (limited to 'Documentation/public-inbox-daemon.pod')
| -rw-r--r-- | Documentation/public-inbox-daemon.pod | 138 |
1 files changed, 115 insertions, 23 deletions
diff --git a/Documentation/public-inbox-daemon.pod b/Documentation/public-inbox-daemon.pod index cb903df2..092be667 100644 --- a/Documentation/public-inbox-daemon.pod +++ b/Documentation/public-inbox-daemon.pod @@ -4,16 +4,18 @@ 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 NNTP and HTTP access to public-inboxes. Write -access to a public-inbox repository will never be required to -run these. +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 @@ -29,7 +31,9 @@ processes to take advantage of multiple CPUs. =over -=item -l, --listen ADDRESS +=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 @@ -40,26 +44,44 @@ like L<nginx(8)> to use. May be specified multiple times to allow listening on multiple sockets. -This does not need to be specified at all if relying on -L<systemd.socket(5)> or similar +Unless per-listener options are used (required for +L<public-inbox-netd(1)>), this does not need to be specified at +all if relying on L<systemd.socket(5)> or similar, + +Per-listener options may be specified after C<?> as C<KEY=VALUE> +pairs delimited by C<,>. See L<public-inbox-netd(1)> for +documentation on the C<cert=>, C<key=>, C<env.NAME=VALUE>, +C<out=>, C<err=>, and C<psgi=> options available. Default: server-dependent unless socket activation is used with L<systemd(1)> or similar (see L<systemd.socket(5)>). -=item -1, --stdout PATH +=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. E<gt>E<gt>/path/to/log in shell) since it allows SIGUSR1 to be handled (see L<SIGNALS/SIGNALS> below). -Default: /dev/null +C<out=> may also be specified on a per-listener basis. + +Default: /dev/null with C<--daemonize>, inherited otherwise -=item -2, --stderr PATH +=item -2 PATH + +=item --stderr PATH Like C<--stdout>, but for the stderr descriptor (2). -=item -W, --worker-processes +C<err=> may also be specified on a per-listener basis. + +Default: /dev/null with C<--daemonize>, inherited otherwise + +=item -W INTEGER + +=item --worker-processes INTEGER Set the number of worker processes. @@ -74,12 +96,81 @@ the master on crashes. Default: 1 +=item -X INTEGER + +=item --xapian-helpers INTEGER + +Enables the use of Xapian helper processes to handle expensive, +non-deterministic Xapian search queries asynchronously without +blocking simple requests. + +With positive values, there is an additional manager process +that can be signaled to control the number of Xapian helper workers. + +* C<-X0> one worker, no manager process +* C<-X1> one worker, one manager process +... +* C<-X8> eight workers, one manager process + +As with the public-facing public-inbox-* daemons, sending C<SIGTTIN> +or C<SIGTTOU> to the Xapian helper manager process will increment or +decrement the number of workers. + +Both Xapian helper workers and managers automatically respawn if they +crash or are explicitly killed, even with C<-X0>. + +A C++ compiler, L<pkg-config(1)>, and Xapian development files (e.g. +C<libxapian-dev> or C<xapian*-core-dev*>) are required to gain access to +some expensive queries and significant memory savings. + +Xapian helper workers are shared by all C<--worker-processes> of the +Perl daemon for additional memory savings. + +New in public-inbox 2.0.0. + +Default: undefined, search queries are handled synchronously + +=item --cert /path/to/cert + +The default TLS certificate for HTTPS, IMAPS, NNTPS, POP3S and/or STARTTLS +support if the C<cert> 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<cert=> 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<multi_accept yes> in nginx; while C<0> (the default) is +C<multi_accept no> 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<multi-accept=> +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<nginx(8)> -and/or L<starman(1)>; so it is possible to reuse common scripts +and/or L<starman(1)>, so it is possible to reuse common scripts for managing them. =over 8 @@ -96,11 +187,11 @@ See L</UPGRADING> below. =item SIGHUP Reload config files associated with the process. -(FIXME: not tested for -httpd, yet) +(Note: broken for L<public-inbox-httpd(1)> only in E<lt>= 1.6) =item SIGTTIN -Increase the number of running workers processes by one. +Increase the number of running worker processes by one. =item SIGTTOU @@ -108,7 +199,7 @@ Decrease the number of running worker processes by one. =item SIGWINCH -Stop all running worker processes. SIGHUP or SIGTTIN +Stop all running worker processes. SIGHUP or SIGTTIN may be used to restart workers. =item SIGQUIT @@ -136,15 +227,15 @@ activation. See L<systemd.socket(5)> and L<sd_listen_fds(3)>. =item PERL_INLINE_DIRECTORY -Pointing this to point to a writable directory enables the use +Pointing this to a writable directory enables the use of L<Inline> and L<Inline::C> extensions which may provide platform-specific performance improvements. Currently, this enables the use of L<vfork(2)> which speeds up subprocess spawning with the Linux kernel. public-inbox will never enable L<Inline::C> automatically without -this environment variable set. See L<Inline> and L<Inline::C> -for more details. +this environment variable set or C<~/.cache/public-inbox/inline-c> +created by a user. See L<Inline> and L<Inline::C> for more details. =back @@ -153,8 +244,8 @@ for more details. There are two ways to upgrade a running process. Users of process management systems with socket activation -(L<systemd(1)> or similar) may rely on multiple instances For -systemd, this means using two (or more) '@' instances for each +(L<systemd(1)> or similar) may rely on multiple daemon instances. +For systemd, this means using two (or more) '@' instances for each service (e.g. C<SERVICENAME@INSTANCE>) as documented in L<systemd.unit(5)>. @@ -170,15 +261,16 @@ interrupted and lost. Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org> -The mail archives are hosted at L<https://public-inbox.org/meta/> -and L<http://hjrcffqmbrq6wope.onion/meta/> +The mail archives are hosted at L<https://public-inbox.org/meta/> and +L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/> =head1 COPYRIGHT -Copyright 2013-2020 all contributors L<mailto:meta@public-inbox.org> +Copyright all contributors L<mailto:meta@public-inbox.org> License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt> =head1 SEE ALSO -L<public-inbox-httpd(1)>, L<public-inbox-nntpd(1)> +L<public-inbox-httpd(1)>, L<public-inbox-imapd(1)>, +L<public-inbox-nntpd(1)>, L<public-inbox-pop3d(1)>, L<public-inbox-netd(1)> |