NAME

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

SYNOPSIS

               public-inbox-httpd
               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 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, --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, --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.  (FIXME: not tested for -httpd, yet)

       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://hjrcffqmbrq6wope.onion/meta/>

COPYRIGHT

       Copyright 2013-2020 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-nntpd(1)

public-inbox.git                                   1993-10-02                             PUBLIC-INBOX-DAEMON(8)