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