]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/public-inbox-daemon.pod
lei: TSTP affects all curl and related subprocesses
[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-imapd
9         public-inbox-nntpd
10
11 =head1 DESCRIPTION
12
13 This manual describes common options and behavior for
14 public-inbox network daemons.  Network daemons for public-inbox
15 provide read-only NNTP, IMAP and HTTP access to public-inboxes.  Write
16 access to a public-inbox will never be required to 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 ADDRESS
33
34 =item --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
52
53 =item --stdout PATH
54
55 Specify an appendable path to redirect stdout descriptor (1) to.
56 Using this is preferable to setting up the redirect externally
57 (e.g. E<gt>E<gt>/path/to/log in shell) since it allows
58 SIGUSR1 to be handled (see L<SIGNALS/SIGNALS> below).
59
60 Default: /dev/null
61
62 =item -2 PATH
63
64 =item --stderr PATH
65
66 Like C<--stdout>, but for the stderr descriptor (2).
67
68 =item -W
69
70 =item --worker-processes
71
72 Set the number of worker processes.
73
74 Normally, this should match the number of CPUs on the system to
75 take full advantage of the hardware.  However, users of
76 memory-constrained systems may want to lower this.
77
78 Setting this to zero (C<-W0>) disables the master/worker split;
79 saving some memory but removing the ability to use SIGTTIN
80 to increase worker processes or have the worker restarted by
81 the master on crashes.
82
83 Default: 1
84
85 =back
86
87 =head1 SIGNALS
88
89 Most of our signal handling behavior is copied from L<nginx(8)>
90 and/or L<starman(1)>; so it is possible to reuse common scripts
91 for managing them.
92
93 =over 8
94
95 =item SIGUSR1
96
97 Reopens log files pointed to by --stdout and --stderr options.
98
99 =item SIGUSR2
100
101 Spawn a new process with the intention to replace the running one.
102 See L</UPGRADING> below.
103
104 =item SIGHUP
105
106 Reload config files associated with the process.
107 (Note: broken for L<public-inbox-httpd(1)> only in E<lt>= 1.6)
108
109 =item SIGTTIN
110
111 Increase the number of running workers processes by one.
112
113 =item SIGTTOU
114
115 Decrease the number of running worker processes by one.
116
117 =item SIGWINCH
118
119 Stop all running worker processes.   SIGHUP or SIGTTIN
120 may be used to restart workers.
121
122 =item SIGQUIT
123
124 Gracefully terminate the running process.
125
126 =back
127
128 SIGTTOU, SIGTTIN, SIGWINCH all have no effect when worker
129 processes are disabled with C<-W0> on the command-line.
130
131 =head1 ENVIRONMENT
132
133 =over 8
134
135 =item PI_CONFIG
136
137 The default config file, normally "~/.public-inbox/config".
138 See L<public-inbox-config(5)>
139
140 =item LISTEN_FDS, LISTEN_PID
141
142 Used by systemd (and compatible) installations for socket
143 activation.  See L<systemd.socket(5)> and L<sd_listen_fds(3)>.
144
145 =item PERL_INLINE_DIRECTORY
146
147 Pointing this to point to a writable directory enables the use
148 of L<Inline> and L<Inline::C> extensions which may provide
149 platform-specific performance improvements.  Currently, this
150 enables the use of L<vfork(2)> which speeds up subprocess
151 spawning with the Linux kernel.
152
153 public-inbox will never enable L<Inline::C> automatically without
154 this environment variable set or C<~/.cache/public-inbox/inline-c>
155 created by a user. See L<Inline> and L<Inline::C> for more details.
156
157 =back
158
159 =head1 UPGRADING
160
161 There are two ways to upgrade a running process.
162
163 Users of process management systems with socket activation
164 (L<systemd(1)> or similar) may rely on multiple instances For
165 systemd, this means using two (or more) '@' instances for each
166 service (e.g. C<SERVICENAME@INSTANCE>) as documented in
167 L<systemd.unit(5)>.
168
169 Users of traditional SysV init may use SIGUSR2 to spawn
170 a replacement process and gracefully terminate the old
171 process using SIGQUIT.
172
173 In either case, the old process will not truncate running
174 responses; so responses to expensive requests do not get
175 interrupted and lost.
176
177 =head1 CONTACT
178
179 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
180
181 The mail archives are hosted at L<https://public-inbox.org/meta/> and
182 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
183
184 =head1 COPYRIGHT
185
186 Copyright 2013-2021 all contributors L<mailto:meta@public-inbox.org>
187
188 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
189
190 =head1 SEE ALSO
191
192 L<public-inbox-httpd(1)>, L<public-inbox-imapd(1)>,
193 L<public-inbox-nntpd(1)>