public-inbox.git  about / heads / tags
an "archives first" approach to mailing lists
blob 6f1e3b53513d02bc3fd11a8ee06fcdd546eb3a48 7205 bytes (raw)
$ git show HEAD:Documentation/public-inbox-daemon.pod	# shows this blob on the CLI

  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
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
 
=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>.

With this option, well-known TCP ports automatically get TLS or STARTTLS
support if using systemd-compatible socket activation.  That is, ports
443, 563, 993, and 995 support HTTPS, NNTPS, IMAPS, and POP3S,
respectively; while ports 110, 119, and 143 support STARTTLS on POP3,
NNTP, and IMAP, respectively.

=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 cert file itself, in which case this
option is not needed.

=item --multi-accept INTEGER

By default, each worker accepts one connection at a time to maximize
fairness and minimize contention across multiple processes on a
shared listen socket.  Accepting multiple connections at once may be
useful in constrained deployments with few, heavily loaded workers.
Negative values enables a worker to accept all available clients at
once, possibly starving others in the process.  C<-1> behaves like
C<multi_accept yes> in nginx; while C<0> (the default) is
C<multi_accept no> in nginx.  Positive values allow
fine-tuning without the runaway behavior of C<-1>.

This may be specified on a per-listener basis via the C<multi-accept=>
per-listener directive (e.g. C<-l http://127.0.0.1?multi-accept=1>).

Default: 0

=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 worker 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 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 daemon 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)>

git clone https://public-inbox.org/public-inbox.git
git clone http://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/public-inbox.git