1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
|
=head1 NAME
public-inbox-daemon - common usage for public-inbox network daemons
=head1 SYNOPSIS
public-inbox-netd
public-inbox-httpd
public-inbox-imapd
public-inbox-nntpd
public-inbox-pop3d
=head1 DESCRIPTION
This manual describes common options and behavior for
public-inbox network daemons. Network daemons for public-inbox
provide read-only IMAP, HTTP, NNTP and POP3 access to public-inboxes.
Write access to a public-inbox will never be required to run these.
These daemons are implemented with a common core using
non-blocking sockets and optimized for fairness; even with
thousands of connected clients over slow links.
They also provide graceful shutdown/upgrade support to avoid
breaking existing connections during software upgrades.
These daemons may also utilize multiple pre-forked worker
processes to take advantage of multiple CPUs.
=head1 OPTIONS
=over
=item -l [PROTOCOL://]ADDRESS[?opt1=val1,opt2=val2]
=item --listen [PROTOCOL://]ADDRESS[?opt1=val1,opt2=val2]
This takes an absolute path to a Unix socket or HOST:PORT
to listen on. For example, to listen to TCP connections on
port 119, use: C<-l 0.0.0.0:119>. This may also point to
a Unix socket (C<-l /path/to/http.sock>) for a reverse proxy
like L<nginx(8)> to use.
May be specified multiple times to allow listening on multiple
sockets.
Unless per-listener options are used (required for
L<public-inbox-netd(1)>), this does not need to be specified at
all if relying on L<systemd.socket(5)> or similar,
Per-listener options may be specified after C<?> as C<KEY=VALUE>
pairs delimited by C<,>. See L<public-inbox-netd(1)> for
documentation on the C<cert=>, C<key=>, C<env.NAME=VALUE>,
C<out=>, C<err=>, and C<psgi=> options available.
Default: server-dependent unless socket activation is used with
L<systemd(1)> or similar (see L<systemd.socket(5)>).
=item -1
=item --stdout PATH
Specify an appendable path to redirect stdout descriptor (1) to.
Using this is preferable to setting up the redirect externally
(e.g. E<gt>E<gt>/path/to/log in shell) since it allows
SIGUSR1 to be handled (see L<SIGNALS/SIGNALS> below).
C<out=> may also be specified on a per-listener basis.
Default: /dev/null with C<--daemonize>, inherited otherwise
=item -2 PATH
=item --stderr PATH
Like C<--stdout>, but for the stderr descriptor (2).
C<err=> may also be specified on a per-listener basis.
Default: /dev/null with C<--daemonize>, inherited otherwise
=item -W
=item --worker-processes
Set the number of worker processes.
Normally, this should match the number of CPUs on the system to
take full advantage of the hardware. However, users of
memory-constrained systems may want to lower this.
Setting this to zero (C<-W0>) disables the master/worker split;
saving some memory but removing the ability to use SIGTTIN
to increase worker processes or have the worker restarted by
the master on crashes.
Default: 1
=item --cert /path/to/cert
The default TLS certificate for HTTPS, IMAPS, NNTPS, POP3S and/or STARTTLS
support if the C<cert> option is not given with C<--listen>.
Well-known TCP ports automatically get TLS or STARTTLS support
If using systemd-compatible socket activation and a TCP listener
on port well-known ports (563 is inherited, it is automatically
NNTPS when this option is given. When a listener on port 119 is
inherited and this option is given, it automatically gets
STARTTLS support.
=item --key /path/to/key
The default TLS certificate key for the default C<--cert> or
per-listener C<cert=> option. The private key may be
concatenated into the path used by the cert, in which case this
option is not needed.
=back
=head1 SIGNALS
Most of our signal handling behavior is copied from L<nginx(8)>
and/or L<starman(1)>; so it is possible to reuse common scripts
for managing them.
=over 8
=item SIGUSR1
Reopens log files pointed to by --stdout and --stderr options.
=item SIGUSR2
Spawn a new process with the intention to replace the running one.
See L</UPGRADING> below.
=item SIGHUP
Reload config files associated with the process.
(Note: broken for L<public-inbox-httpd(1)> only in E<lt>= 1.6)
=item SIGTTIN
Increase the number of running workers processes by one.
=item SIGTTOU
Decrease the number of running worker processes by one.
=item SIGWINCH
Stop all running worker processes. SIGHUP or SIGTTIN
may be used to restart workers.
=item SIGQUIT
Gracefully terminate the running process.
=back
SIGTTOU, SIGTTIN, SIGWINCH all have no effect when worker
processes are disabled with C<-W0> on the command-line.
=head1 ENVIRONMENT
=over 8
=item PI_CONFIG
The default config file, normally "~/.public-inbox/config".
See L<public-inbox-config(5)>
=item LISTEN_FDS, LISTEN_PID
Used by systemd (and compatible) installations for socket
activation. See L<systemd.socket(5)> and L<sd_listen_fds(3)>.
=item PERL_INLINE_DIRECTORY
Pointing this to point to a writable directory enables the use
of L<Inline> and L<Inline::C> extensions which may provide
platform-specific performance improvements. Currently, this
enables the use of L<vfork(2)> which speeds up subprocess
spawning with the Linux kernel.
public-inbox will never enable L<Inline::C> automatically without
this environment variable set or C<~/.cache/public-inbox/inline-c>
created by a user. See L<Inline> and L<Inline::C> for more details.
=back
=head1 UPGRADING
There are two ways to upgrade a running process.
Users of process management systems with socket activation
(L<systemd(1)> or similar) may rely on multiple instances For
systemd, this means using two (or more) '@' instances for each
service (e.g. C<SERVICENAME@INSTANCE>) as documented in
L<systemd.unit(5)>.
Users of traditional SysV init may use SIGUSR2 to spawn
a replacement process and gracefully terminate the old
process using SIGQUIT.
In either case, the old process will not truncate running
responses; so responses to expensive requests do not get
interrupted and lost.
=head1 CONTACT
Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
The mail archives are hosted at L<https://public-inbox.org/meta/> and
L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
=head1 COPYRIGHT
Copyright all contributors L<mailto:meta@public-inbox.org>
License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
=head1 SEE ALSO
L<public-inbox-httpd(1)>, L<public-inbox-imapd(1)>,
L<public-inbox-nntpd(1)>, L<public-inbox-pop3d(1)>, L<public-inbox-netd(1)>
|
