3 public-inbox-daemon - common usage for public-inbox network daemons
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
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.
22 They also provide graceful shutdown/upgrade support to avoid
23 breaking existing connections during software upgrades.
25 These daemons may also utilize multiple pre-forked worker
26 processes to take advantage of multiple CPUs.
28 Native TLS (Transport Layer Security) support is planned.
34 =item -l, --listen ADDRESS
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.
42 May be specified multiple times to allow listening on multiple
45 This does not need to be specified at all if relying on
46 L<systemd.socket(5)> or similar
48 Default: server-dependent unless socket activation is used with
49 L<systemd(1)> or similar (see L<systemd.socket(5)>).
51 =item -1, --stdout PATH
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).
60 =item -2, --stderr PATH
62 Like C<--stdout>, but for the stderr descriptor (2).
64 =item -W, --worker-processes
66 Set the number of worker processes.
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.
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.
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
91 Reopens log files pointed to by --stdout and --stderr options.
95 Spawn a new process with the intention to replace the running one.
96 See L</UPGRADING> below.
100 Reload config files associated with the process.
101 (FIXME: not tested for -httpd, yet)
105 Increase the number of running workers processes by one.
109 Decrease the number of running worker processes by one.
113 Stop all running worker processes. SIGHUP or SIGTTIN
114 may be used to restart workers.
118 Gracefully terminate the running process.
122 SIGTTOU, SIGTTIN, SIGWINCH all have no effect when worker
123 processes are disabled with C<-W0> on the command-line.
131 The default config file, normally "~/.public-inbox/config".
132 See L<public-inbox-config(5)>
134 =item LISTEN_FDS, LISTEN_PID
136 Used by systemd (and compatible) installations for socket
137 activation. See L<systemd.socket(5)> and L<sd_listen_fds(3)>.
139 =item PERL_INLINE_DIRECTORY
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.
147 public-inbox will never enable L<Inline::C> automatically without
148 this environment variable set. See L<Inline> and L<Inline::C>
155 There are two ways to upgrade a running process.
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
163 Users of traditional SysV init may use SIGUSR2 to spawn
164 a replacement process and gracefully terminate the old
165 process using SIGQUIT.
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.
173 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
175 The mail archives are hosted at L<https://public-inbox.org/meta/>
176 and L<http://hjrcffqmbrq6wope.onion/meta/>
180 Copyright 2013-2019 all contributors L<mailto:meta@public-inbox.org>
182 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
186 L<public-inbox-httpd(1)>, L<public-inbox-nntpd(1)>