PUBLIC-INBOX-DAEMON(8) public-inbox user manual PUBLIC-INBOX-DAEMON(8)
NAME
public-inbox-daemon - common usage for public-inbox network daemons
SYNOPSIS
public-inbox-netd
public-inbox-httpd
public-inbox-imapd
public-inbox-nntpd
public-inbox-pop3d
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.
OPTIONS
-l [PROTOCOL://]ADDRESS[?opt1=val1,opt2=val2]
--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:
"-l 0.0.0.0:119". This may also point to a Unix socket ("-l
/path/to/http.sock") for a reverse proxy like nginx(8) to use.
May be specified multiple times to allow listening on multiple
sockets.
Unless per-listener options are used (required for
public-inbox-netd(1)), this does not need to be specified at all if
relying on systemd.socket(5) or similar,
Per-listener options may be specified after "?" as "KEY=VALUE"
pairs delimited by ",". See public-inbox-netd(1) for documentation
on the "backlog=", "cert=", "key=", "env.NAME=VALUE", "out=",
"err=", "psgi=", "servername=", and "serverport=" options
available.
Default: server-dependent unless socket activation is used with
systemd(1) or similar (see systemd.socket(5)).
-1
--stdout PATH
Specify an appendable path to redirect stdout descriptor (1) to.
Using this is preferable to setting up the redirect externally
(e.g. >>/path/to/log in shell) since it allows SIGUSR1 to be
handled (see "SIGNALS" in SIGNALS below).
"out=" may also be specified on a per-listener basis.
Default: /dev/null with "--daemonize", inherited otherwise
-2 PATH
--stderr PATH
Like "--stdout", but for the stderr descriptor (2).
"err=" may also be specified on a per-listener basis.
Default: /dev/null with "--daemonize", inherited otherwise
-W INTEGER
--worker-processes INTEGER
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 ("-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
-X INTEGER
--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.
* "-X0" one worker, no manager process * "-X1" one worker, one
manager process ... * "-X8" eight workers, one manager process
As with the public-facing public-inbox-* daemons, sending "SIGTTIN"
or "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 "-X0".
A C++ compiler, pkg-config(1), and Xapian development files (e.g.
"libxapian-dev" or "xapian*-core-dev*") are required to gain access
to some expensive queries and significant memory savings.
Xapian helper workers are shared by all "--worker-processes" of the
Perl daemon for additional memory savings.
New in public-inbox 2.0.0.
Default: undefined, search queries are handled synchronously
--cert /path/to/cert
The default TLS certificate for HTTPS, IMAPS, NNTPS, POP3S and/or
STARTTLS support if the "cert" option is not given with "--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.
--key /path/to/key
The default TLS certificate key for the default "--cert" or per-
listener "cert=" option. The private key may be concatenated into
the cert file itself, in which case this option is not needed.
--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. "-1"
behaves like "multi_accept yes" in nginx; while 0 (the default) is
"multi_accept no" in nginx. Positive values allow fine-tuning
without the runaway behavior of "-1".
This may be specified on a per-listener basis via the
"multi-accept=" per-listener directive (e.g. "-l
http://127.0.0.1?multi-accept=1").
Default: 0
SIGNALS
Most of our signal handling behavior is copied from nginx(8) and/or
starman(1), so it is possible to reuse common scripts for managing
them.
SIGUSR1 Reopens log files pointed to by --stdout and --stderr options.
SIGUSR2 Spawn a new process with the intention to replace the running
one. See "UPGRADING" below.
SIGHUP Reload config files associated with the process. (Note: broken
for public-inbox-httpd(1) only in <= 1.6)
SIGTTIN Increase the number of running worker processes by one.
SIGTTOU Decrease the number of running worker processes by one.
SIGWINCH
Stop all running worker processes. SIGHUP or SIGTTIN may be
used to restart workers.
SIGQUIT Gracefully terminate the running process.
SIGTTOU, SIGTTIN, SIGWINCH all have no effect when worker processes are
disabled with "-W0" on the command-line.
ENVIRONMENT
PI_CONFIG
The default config file, normally "~/.public-inbox/config".
See public-inbox-config(5)
LISTEN_FDS, LISTEN_PID
Used by systemd (and compatible) installations for socket
activation. See systemd.socket(5) and sd_listen_fds(3).
PERL_INLINE_DIRECTORY
Pointing this to a writable directory enables the use of Inline
and Inline::C extensions which may provide platform-specific
performance improvements. Currently, this enables the use of
vfork(2) which speeds up subprocess spawning with the Linux
kernel.
public-inbox will never enable Inline::C automatically without
this environment variable set or
"~/.cache/public-inbox/inline-c" created by a user. See Inline
and Inline::C for more details.
UPGRADING
There are two ways to upgrade a running process.
Users of process management systems with socket activation (systemd(1)
or similar) may rely on multiple daemon instances. For systemd, this
means using two (or more) '@' instances for each service (e.g.
"SERVICENAME@INSTANCE") as documented in systemd.unit(5).
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.
CONTACT
Feedback welcome via plain-text mail to <mailto:meta@public-inbox.org>
The mail archives are hosted at <https://public-inbox.org/meta/> and
<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
COPYRIGHT
Copyright all contributors <mailto:meta@public-inbox.org>
License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
SEE ALSO
public-inbox-httpd(1), public-inbox-imapd(1), public-inbox-nntpd(1),
public-inbox-pop3d(1), public-inbox-netd(1)
public-inbox.git 1993-10-02 PUBLIC-INBOX-DAEMON(8)