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