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-httpd
10               public-inbox-imapd
11               public-inbox-nntpd
12

DESCRIPTION

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

OPTIONS

30       -l ADDRESS
31       --listen ADDRESS
32           This takes an absolute path to a Unix socket or HOST:PORT to listen
33           on.  For example, to listen to TCP connections on port 119, use:
34           "-l 0.0.0.0:119".  This may also point to a Unix socket ("-l
35           /path/to/http.sock") for a reverse proxy like nginx(8) to use.
36
37           May be specified multiple times to allow listening on multiple
38           sockets.
39
40           This does not need to be specified at all if relying on
41           systemd.socket(5) or similar
42
43           Default: server-dependent unless socket activation is used with
44           systemd(1) or similar (see systemd.socket(5)).
45
46       -1
47       --stdout PATH
48           Specify an appendable path to redirect stdout descriptor (1) to.
49           Using this is preferable to setting up the redirect externally
50           (e.g. >>/path/to/log in shell) since it allows SIGUSR1 to be
51           handled (see "SIGNALS" in SIGNALS below).
52
53           Default: /dev/null
54
55       -2 PATH
56       --stderr PATH
57           Like "--stdout", but for the stderr descriptor (2).
58
59       -W
60       --worker-processes
61           Set the number of worker processes.
62
63           Normally, this should match the number of CPUs on the system to
64           take full advantage of the hardware.  However, users of memory-
65           constrained systems may want to lower this.
66
67           Setting this to zero ("-W0") disables the master/worker split;
68           saving some memory but removing the ability to use SIGTTIN to
69           increase worker processes or have the worker restarted by the
70           master on crashes.
71
72           Default: 1
73

SIGNALS

75       Most of our signal handling behavior is copied from nginx(8) and/or
76       starman(1); so it is possible to reuse common scripts for managing
77       them.
78
79       SIGUSR1 Reopens log files pointed to by --stdout and --stderr options.
80
81       SIGUSR2 Spawn a new process with the intention to replace the running
82               one.  See "UPGRADING" below.
83
84       SIGHUP  Reload config files associated with the process.  (Note: broken
85               for public-inbox-httpd(1) only in <= 1.6)
86
87       SIGTTIN Increase the number of running workers processes by one.
88
89       SIGTTOU Decrease the number of running worker processes by one.
90
91       SIGWINCH
92               Stop all running worker processes.   SIGHUP or SIGTTIN may be
93               used to restart workers.
94
95       SIGQUIT Gracefully terminate the running process.
96
97       SIGTTOU, SIGTTIN, SIGWINCH all have no effect when worker processes are
98       disabled with "-W0" on the command-line.
99

ENVIRONMENT

101       PI_CONFIG
102               The default config file, normally "~/.public-inbox/config".
103               See public-inbox-config(5)
104
105       LISTEN_FDS, LISTEN_PID
106               Used by systemd (and compatible) installations for socket
107               activation.  See systemd.socket(5) and sd_listen_fds(3).
108
109       PERL_INLINE_DIRECTORY
110               Pointing this to point to a writable directory enables the use
111               of Inline and Inline::C extensions which may provide platform-
112               specific performance improvements.  Currently, this enables the
113               use of vfork(2) which speeds up subprocess spawning with the
114               Linux kernel.
115
116               public-inbox will never enable Inline::C automatically without
117               this environment variable set or
118               "~/.cache/public-inbox/inline-c" created by a user. See Inline
119               and Inline::C for more details.
120

UPGRADING

122       There are two ways to upgrade a running process.
123
124       Users of process management systems with socket activation (systemd(1)
125       or similar) may rely on multiple instances For systemd, this means
126       using two (or more) '@' instances for each service (e.g.
127       "SERVICENAME@INSTANCE") as documented in systemd.unit(5).
128
129       Users of traditional SysV init may use SIGUSR2 to spawn a replacement
130       process and gracefully terminate the old process using SIGQUIT.
131
132       In either case, the old process will not truncate running responses; so
133       responses to expensive requests do not get interrupted and lost.
134

CONTACT

136       Feedback welcome via plain-text mail to <mailto:meta@public-inbox.org>
137
138       The mail archives are hosted at <https://public-inbox.org/meta/> and
139       <http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
140

COPYRIGHT

142       Copyright 2013-2021 all contributors <mailto:meta@public-inbox.org>
143
144       License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
145