public-inbox-daemon - Man Page

common usage for public-inbox network daemons

Synopsis

        public-inbox-httpd
        public-inbox-imapd
        public-inbox-nntpd

Description

This manual describes common options and behavior for public-inbox network daemons.  Network daemons for public-inbox provide read-only NNTP, IMAP and HTTP 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 ADDRESS
--listen ADDRESS

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.

This does not need to be specified at all if relying on systemd.socket(5) or similar

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).

Default: /dev/null

-2 PATH
--stderr PATH

Like --stdout, but for the stderr descriptor (2).

-W
--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 (-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

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 workers 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 point 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 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/>

See Also

public-inbox-httpd(1), public-inbox-imapd(1), public-inbox-nntpd(1)

Referenced By

lei-daemon(8), lei-security(7), public-inbox.cgi(1), public-inbox-config(5), public-inbox-httpd(1), public-inbox-imapd(1), public-inbox-nntpd(1), public-inbox-tuning(7), public-inbox-watch(1).

1993-10-02 public-inbox.git public-inbox user manual