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