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 will never be required to run these.
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.
21 They also provide graceful shutdown/upgrade support to avoid
22 breaking existing connections during software upgrades.
24 These daemons may also utilize multiple pre-forked worker
25 processes to take advantage of multiple CPUs.
33 =item --listen ADDRESS
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.
41 May be specified multiple times to allow listening on multiple
44 This does not need to be specified at all if relying on
45 L<systemd.socket(5)> or similar
47 Default: server-dependent unless socket activation is used with
48 L<systemd(1)> or similar (see L<systemd.socket(5)>).
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).
65 Like C<--stdout>, but for the stderr descriptor (2).
69 =item --worker-processes
71 Set the number of worker processes.
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.
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.
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
96 Reopens log files pointed to by --stdout and --stderr options.
100 Spawn a new process with the intention to replace the running one.
101 See L</UPGRADING> below.
105 Reload config files associated with the process.
106 (FIXME: not tested for -httpd, yet)
110 Increase the number of running workers processes by one.
114 Decrease the number of running worker processes by one.
118 Stop all running worker processes. SIGHUP or SIGTTIN
119 may be used to restart workers.
123 Gracefully terminate the running process.
127 SIGTTOU, SIGTTIN, SIGWINCH all have no effect when worker
128 processes are disabled with C<-W0> on the command-line.
136 The default config file, normally "~/.public-inbox/config".
137 See L<public-inbox-config(5)>
139 =item LISTEN_FDS, LISTEN_PID
141 Used by systemd (and compatible) installations for socket
142 activation. See L<systemd.socket(5)> and L<sd_listen_fds(3)>.
144 =item PERL_INLINE_DIRECTORY
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.
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.
160 There are two ways to upgrade a running process.
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
168 Users of traditional SysV init may use SIGUSR2 to spawn
169 a replacement process and gracefully terminate the old
170 process using SIGQUIT.
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.
178 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
180 The mail archives are hosted at L<https://public-inbox.org/meta/> and
181 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
185 Copyright 2013-2021 all contributors L<mailto:meta@public-inbox.org>
187 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
191 L<public-inbox-httpd(1)>, L<public-inbox-nntpd(1)>