--- name: "public-inbox-daemon" section: "8" platform: "linux" package: "public-inbox" version: "1.9.0-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/public-inbox-daemon" --- # public-inbox-daemon(8) common usage for public-inbox network daemons ## 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)](/nginx/8.md) 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)](/public-inbox-netd/1.md)), this does not need to be specified at all if relying on [**systemd.socket**(5)](/systemd.socket/5.md) or similar, Per-listener options may be specified after `"?"` as `"KEY=VALUE"` pairs delimited by `","`. See [**public-inbox-netd**(1)](/public-inbox-netd/1.md) for documentation on the `"cert="`, `"key="`, `"env.NAME=VALUE"`, `"out="`, `"err="`, and `"psgi="` options available. Default: server-dependent unless socket activation is used with [**systemd**(1)](/systemd/1.md) or similar (see [**systemd.socket**(5)](/systemd.socket/5.md)). - \-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 - \--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 - \--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"`. Well-known TCP ports automatically get TLS or STARTTLS support If using systemd-compatible socket activation and a TCP listener on port well-known ports (563 is inherited, it is automatically NNTPS when this option is given. When a listener on port 119 is inherited and this option is given, it automatically gets STARTTLS support. - \--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 path used by the cert, in which case this option is not needed. ## SIGNALS Most of our signal handling behavior is copied from [**nginx**(8)](/nginx/8.md) 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)](/public-inbox-httpd/1.md) 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)](/public-inbox-config/5.md) - LISTEN\_FDS, LISTEN\_PID Used by systemd (and compatible) installations for socket activation. See [**systemd.socket**(5)](/systemd.socket/5.md) and [**sd\_listen\_fds**(3)](/sd_listen_fds/3.md). - 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)](/vfork/2.md) 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)](/systemd/1.md) 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)](/systemd.unit/5.md). 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 \ The mail archives are hosted at \ and \ ## COPYRIGHT Copyright all contributors \ License: AGPL-3.0+ \ ## SEE ALSO [**public-inbox-httpd**(1)](/public-inbox-httpd/1.md), [**public-inbox-imapd**(1)](/public-inbox-imapd/1.md), [**public-inbox-nntpd**(1)](/public-inbox-nntpd/1.md), [**public-inbox-pop3d**(1)](/public-inbox-pop3d/1.md), [**public-inbox-netd**(1)](/public-inbox-netd/1.md)