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