Documentation/public-inbox-daemon.pod

   1 =head1 NAME
   2
   3 public-inbox-daemon - common usage for public-inbox network daemons
   4
   5 =head1 SYNOPSIS
   6
   7         public-inbox-httpd
   8         public-inbox-nntpd
   9
  10 =head1 DESCRIPTION
  11
  12 This manual describes common options and behavior for
  13 public-inbox network daemons.  Network daemons for public-inbox
  14 provide read-only NNTP and HTTP access to public-inboxes.  Write
  15 access to a public-inbox will never be required to run these.
  16
  17 These daemons are implemented with a common core using
  18 non-blocking sockets and optimized for fairness; even with
  19 thousands of connected clients over slow links.
  20
  21 They also provide graceful shutdown/upgrade support to avoid
  22 breaking existing connections during software upgrades.
  23
  24 These daemons may also utilize multiple pre-forked worker
  25 processes to take advantage of multiple CPUs.
  26
  27 =head1 OPTIONS
  28
  29 =over
  30
  31 =item -l, --listen ADDRESS
  32
  33 This takes an absolute path to a Unix socket or HOST:PORT
  34 to listen on.  For example, to listen to TCP connections on
  35 port 119, use: C<-l 0.0.0.0:119>.  This may also point to
  36 a Unix socket (C<-l /path/to/http.sock>) for a reverse proxy
  37 like L<nginx(8)> to use.
  38
  39 May be specified multiple times to allow listening on multiple
  40 sockets.
  41
  42 This does not need to be specified at all if relying on
  43 L<systemd.socket(5)> or similar
  44
  45 Default: server-dependent unless socket activation is used with
  46 L<systemd(1)> or similar (see L<systemd.socket(5)>).
  47
  48 =item -1, --stdout PATH
  49
  50 Specify an appendable path to redirect stdout descriptor (1) to.
  51 Using this is preferable to setting up the redirect externally
  52 (e.g. E<gt>E<gt>/path/to/log in shell) since it allows
  53 SIGUSR1 to be handled (see L<SIGNALS/SIGNALS> below).
  54
  55 Default: /dev/null
  56
  57 =item -2, --stderr PATH
  58
  59 Like C<--stdout>, but for the stderr descriptor (2).
  60
  61 =item -W, --worker-processes
  62
  63 Set the number of worker processes.
  64
  65 Normally, this should match the number of CPUs on the system to
  66 take full advantage of the hardware.  However, users of
  67 memory-constrained systems may want to lower this.
  68
  69 Setting this to zero (C<-W0>) disables the master/worker split;
  70 saving some memory but removing the ability to use SIGTTIN
  71 to increase worker processes or have the worker restarted by
  72 the master on crashes.
  73
  74 Default: 1
  75
  76 =back
  77
  78 =head1 SIGNALS
  79
  80 Most of our signal handling behavior is copied from L<nginx(8)>
  81 and/or L<starman(1)>; so it is possible to reuse common scripts
  82 for managing them.
  83
  84 =over 8
  85
  86 =item SIGUSR1
  87
  88 Reopens log files pointed to by --stdout and --stderr options.
  89
  90 =item SIGUSR2
  91
  92 Spawn a new process with the intention to replace the running one.
  93 See L</UPGRADING> below.
  94
  95 =item SIGHUP
  96
  97 Reload config files associated with the process.
  98 (FIXME: not tested for -httpd, yet)
  99
 100 =item SIGTTIN
 101
 102 Increase the number of running workers processes by one.
 103
 104 =item SIGTTOU
 105
 106 Decrease the number of running worker processes by one.
 107
 108 =item SIGWINCH
 109
 110 Stop all running worker processes.   SIGHUP or SIGTTIN
 111 may be used to restart workers.
 112
 113 =item SIGQUIT
 114
 115 Gracefully terminate the running process.
 116
 117 =back
 118
 119 SIGTTOU, SIGTTIN, SIGWINCH all have no effect when worker
 120 processes are disabled with C<-W0> on the command-line.
 121
 122 =head1 ENVIRONMENT
 123
 124 =over 8
 125
 126 =item PI_CONFIG
 127
 128 The default config file, normally "~/.public-inbox/config".
 129 See L<public-inbox-config(5)>
 130
 131 =item LISTEN_FDS, LISTEN_PID
 132
 133 Used by systemd (and compatible) installations for socket
 134 activation.  See L<systemd.socket(5)> and L<sd_listen_fds(3)>.
 135
 136 =item PERL_INLINE_DIRECTORY
 137
 138 Pointing this to point to a writable directory enables the use
 139 of L<Inline> and L<Inline::C> extensions which may provide
 140 platform-specific performance improvements.  Currently, this
 141 enables the use of L<vfork(2)> which speeds up subprocess
 142 spawning with the Linux kernel.
 143
 144 public-inbox will never enable L<Inline::C> automatically without
 145 this environment variable set or C<~/.cache/public-inbox/inline-c>
 146 created by a user. See L<Inline> and L<Inline::C> for more details.
 147
 148 =back
 149
 150 =head1 UPGRADING
 151
 152 There are two ways to upgrade a running process.
 153
 154 Users of process management systems with socket activation
 155 (L<systemd(1)> or similar) may rely on multiple instances For
 156 systemd, this means using two (or more) '@' instances for each
 157 service (e.g. C<SERVICENAME@INSTANCE>) as documented in
 158 L<systemd.unit(5)>.
 159
 160 Users of traditional SysV init may use SIGUSR2 to spawn
 161 a replacement process and gracefully terminate the old
 162 process using SIGQUIT.
 163
 164 In either case, the old process will not truncate running
 165 responses; so responses to expensive requests do not get
 166 interrupted and lost.
 167
 168 =head1 CONTACT
 169
 170 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 171
 172 The mail archives are hosted at L<https://public-inbox.org/meta/>
 173 and L<http://hjrcffqmbrq6wope.onion/meta/>
 174
 175 =head1 COPYRIGHT
 176
 177 Copyright 2013-2021 all contributors L<mailto:meta@public-inbox.org>
 178
 179 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 180
 181 =head1 SEE ALSO
 182
 183 L<public-inbox-httpd(1)>, L<public-inbox-nntpd(1)>