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