PUBLIC-INBOX-DAEMON(8)     public-inbox user manual     PUBLIC-INBOX-DAEMON(8)

       public-inbox-daemon - common usage for public-inbox network daemons


       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.

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

           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 "cert=", "key=", "env.NAME=VALUE", "out=", "err=", and
           "psgi=" options available.

           Default: server-dependent unless socket activation is used with
           systemd(1) or similar (see systemd.socket(5)).

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

           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

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

       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

       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.

               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.

               The default config file, normally "~/.public-inbox/config".
               See public-inbox-config(5)

               Used by systemd (and compatible) installations for socket
               activation.  See systemd.socket(5) and sd_listen_fds(3).

               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.

       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.

       Feedback welcome via plain-text mail to <>

       The mail archives are hosted at <> and

       Copyright all contributors <>

       License: AGPL-3.0+ <>

       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)