public-inbox-daemon(8)

1PUBLIC-INBOX-DAEMON(8)     public-inbox user manual     PUBLIC-INBOX-DAEMON(8)
2
3
4

NAME

6       public-inbox-daemon - common usage for public-inbox network daemons
7

SYNOPSIS

9               public-inbox-netd
10               public-inbox-httpd
11               public-inbox-imapd
12               public-inbox-nntpd
13               public-inbox-pop3d
14

DESCRIPTION

16       This manual describes common options and behavior for public-inbox
17       network daemons.  Network daemons for public-inbox provide read-only
18       IMAP, HTTP, NNTP and POP3 access to public-inboxes.  Write access to a
19       public-inbox will never be required to run these.
20
21       These daemons are implemented with a common core using non-blocking
22       sockets and optimized for fairness; even with thousands of connected
23       clients over slow links.
24
25       They also provide graceful shutdown/upgrade support to avoid breaking
26       existing connections during software upgrades.
27
28       These daemons may also utilize multiple pre-forked worker processes to
29       take advantage of multiple CPUs.
30

OPTIONS

32       -l [PROTOCOL://]ADDRESS[?opt1=val1,opt2=val2]
33       --listen [PROTOCOL://]ADDRESS[?opt1=val1,opt2=val2]
34           This takes an absolute path to a Unix socket or HOST:PORT to listen
35           on.  For example, to listen to TCP connections on port 119, use:
36           "-l 0.0.0.0:119".  This may also point to a Unix socket ("-l
37           /path/to/http.sock") for a reverse proxy like nginx(8) to use.
38
39           May be specified multiple times to allow listening on multiple
40           sockets.
41
42           Unless per-listener options are used (required for
43           public-inbox-netd(1)), this does not need to be specified at all if
44           relying on systemd.socket(5) or similar,
45
46           Per-listener options may be specified after "?" as "KEY=VALUE"
47           pairs delimited by ",".  See public-inbox-netd(1) for documentation
48           on the "cert=", "key=", "env.NAME=VALUE", "out=", "err=", and
49           "psgi=" options available.
50
51           Default: server-dependent unless socket activation is used with
52           systemd(1) or similar (see systemd.socket(5)).
53
54       -1
55       --stdout PATH
56           Specify an appendable path to redirect stdout descriptor (1) to.
57           Using this is preferable to setting up the redirect externally
58           (e.g. >>/path/to/log in shell) since it allows SIGUSR1 to be
59           handled (see "SIGNALS" in SIGNALS below).
60
61           "out=" may also be specified on a per-listener basis.
62
63           Default: /dev/null with "--daemonize", inherited otherwise
64
65       -2 PATH
66       --stderr PATH
67           Like "--stdout", but for the stderr descriptor (2).
68
69           "err=" may also be specified on a per-listener basis.
70
71           Default: /dev/null with "--daemonize", inherited otherwise
72
73       -W
74       --worker-processes
75           Set the number of worker processes.
76
77           Normally, this should match the number of CPUs on the system to
78           take full advantage of the hardware.  However, users of memory-
79           constrained systems may want to lower this.
80
81           Setting this to zero ("-W0") disables the master/worker split;
82           saving some memory but removing the ability to use SIGTTIN to
83           increase worker processes or have the worker restarted by the
84           master on crashes.
85
86           Default: 1
87
88       --cert /path/to/cert
89           The default TLS certificate for HTTPS, IMAPS, NNTPS, POP3S and/or
90           STARTTLS support if the "cert" option is not given with "--listen".
91
92           Well-known TCP ports automatically get TLS or STARTTLS support If
93           using systemd-compatible socket activation and a TCP listener on
94           port well-known ports (563 is inherited, it is automatically NNTPS
95           when this option is given.  When a listener on port 119 is
96           inherited and this option is given, it automatically gets STARTTLS
97           support.
98
99       --key /path/to/key
100           The default TLS certificate key for the default "--cert" or per-
101           listener "cert=" option.  The private key may be concatenated into
102           the path used by the cert, in which case this option is not needed.
103
104       --multi-accept INTEGER
105           By default, each worker accepts one connection at-a-time to
106           maximize fairness and minimize contention across multiple processes
107           on a shared listen socket.  Accepting multiple connections at once
108           may be useful in constrained deployments with few, heavily-loaded
109           workers.  Negative values enables a worker to accept all available
110           clients at once, possibly starving others in the process.  -1
111           behaves like "multi_accept yes" in nginx; while 0 (the default) is
112           "multi_accept no" in nginx.  Positive values allow fine-tuning
113           without the runaway behavior of -1.
114
115           This may be specified on a per-listener basis via the
116           "multi-accept=" per-listener directive (e.g. "-l
117           http://127.0.0.1?multi-accept=1").
118
119           Default: 0
120

SIGNALS

122       Most of our signal handling behavior is copied from nginx(8) and/or
123       starman(1); so it is possible to reuse common scripts for managing
124       them.
125
126       SIGUSR1 Reopens log files pointed to by --stdout and --stderr options.
127
128       SIGUSR2 Spawn a new process with the intention to replace the running
129               one.  See "UPGRADING" below.
130
131       SIGHUP  Reload config files associated with the process.  (Note: broken
132               for public-inbox-httpd(1) only in <= 1.6)
133
134       SIGTTIN Increase the number of running workers processes by one.
135
136       SIGTTOU Decrease the number of running worker processes by one.
137
138       SIGWINCH
139               Stop all running worker processes.   SIGHUP or SIGTTIN may be
140               used to restart workers.
141
142       SIGQUIT Gracefully terminate the running process.
143
144       SIGTTOU, SIGTTIN, SIGWINCH all have no effect when worker processes are
145       disabled with "-W0" on the command-line.
146

ENVIRONMENT

148       PI_CONFIG
149               The default config file, normally "~/.public-inbox/config".
150               See public-inbox-config(5)
151
152       LISTEN_FDS, LISTEN_PID
153               Used by systemd (and compatible) installations for socket
154               activation.  See systemd.socket(5) and sd_listen_fds(3).
155
156       PERL_INLINE_DIRECTORY
157               Pointing this to point to a writable directory enables the use
158               of Inline and Inline::C extensions which may provide platform-
159               specific performance improvements.  Currently, this enables the
160               use of vfork(2) which speeds up subprocess spawning with the
161               Linux kernel.
162
163               public-inbox will never enable Inline::C automatically without
164               this environment variable set or
165               "~/.cache/public-inbox/inline-c" created by a user. See Inline
166               and Inline::C for more details.
167

UPGRADING

169       There are two ways to upgrade a running process.
170
171       Users of process management systems with socket activation (systemd(1)
172       or similar) may rely on multiple instances For systemd, this means
173       using two (or more) '@' instances for each service (e.g.
174       "SERVICENAME@INSTANCE") as documented in systemd.unit(5).
175
176       Users of traditional SysV init may use SIGUSR2 to spawn a replacement
177       process and gracefully terminate the old process using SIGQUIT.
178
179       In either case, the old process will not truncate running responses; so
180       responses to expensive requests do not get interrupted and lost.
181

CONTACT

183       Feedback welcome via plain-text mail to <mailto:meta@public-inbox.org>
184
185       The mail archives are hosted at <https://public-inbox.org/meta/> and
186       <http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
187

COPYRIGHT

189       Copyright all contributors <mailto:meta@public-inbox.org>
190
191       License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
192