1PUBLIC-INBOX-DAEMON(8) public-inbox user manual PUBLIC-INBOX-DAEMON(8)
2
3
4
6 public-inbox-daemon - common usage for public-inbox network daemons
7
9 public-inbox-netd
10 public-inbox-httpd
11 public-inbox-imapd
12 public-inbox-nntpd
13 public-inbox-pop3d
14
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
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
105 Most of our signal handling behavior is copied from nginx(8) and/or
106 starman(1); so it is possible to reuse common scripts for managing
107 them.
108
109 SIGUSR1 Reopens log files pointed to by --stdout and --stderr options.
110
111 SIGUSR2 Spawn a new process with the intention to replace the running
112 one. See "UPGRADING" below.
113
114 SIGHUP Reload config files associated with the process. (Note: broken
115 for public-inbox-httpd(1) only in <= 1.6)
116
117 SIGTTIN Increase the number of running workers processes by one.
118
119 SIGTTOU Decrease the number of running worker processes by one.
120
121 SIGWINCH
122 Stop all running worker processes. SIGHUP or SIGTTIN may be
123 used to restart workers.
124
125 SIGQUIT Gracefully terminate the running process.
126
127 SIGTTOU, SIGTTIN, SIGWINCH all have no effect when worker processes are
128 disabled with "-W0" on the command-line.
129
131 PI_CONFIG
132 The default config file, normally "~/.public-inbox/config".
133 See public-inbox-config(5)
134
135 LISTEN_FDS, LISTEN_PID
136 Used by systemd (and compatible) installations for socket
137 activation. See systemd.socket(5) and sd_listen_fds(3).
138
139 PERL_INLINE_DIRECTORY
140 Pointing this to point to a writable directory enables the use
141 of Inline and Inline::C extensions which may provide platform-
142 specific performance improvements. Currently, this enables the
143 use of vfork(2) which speeds up subprocess spawning with the
144 Linux kernel.
145
146 public-inbox will never enable Inline::C automatically without
147 this environment variable set or
148 "~/.cache/public-inbox/inline-c" created by a user. See Inline
149 and Inline::C for more details.
150
152 There are two ways to upgrade a running process.
153
154 Users of process management systems with socket activation (systemd(1)
155 or similar) may rely on multiple instances For systemd, this means
156 using two (or more) '@' instances for each service (e.g.
157 "SERVICENAME@INSTANCE") as documented in systemd.unit(5).
158
159 Users of traditional SysV init may use SIGUSR2 to spawn a replacement
160 process and gracefully terminate the old process using SIGQUIT.
161
162 In either case, the old process will not truncate running responses; so
163 responses to expensive requests do not get interrupted and lost.
164
166 Feedback welcome via plain-text mail to <mailto:meta@public-inbox.org>
167
168 The mail archives are hosted at <https://public-inbox.org/meta/> and
169 <http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
170
172 Copyright all contributors <mailto:meta@public-inbox.org>
173
174 License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
175
177 public-inbox-httpd(1), public-inbox-imapd(1), public-inbox-nntpd(1),
178 public-inbox-pop3d(1), public-inbox-netd(1)
179
180
181
182public-inbox.git 1993-10-02 PUBLIC-INBOX-DAEMON(8)