.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "PUBLIC-INBOX-DAEMON 8" .TH PUBLIC-INBOX-DAEMON 8 "1993-10-02" "public-inbox.git" "public-inbox user manual" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" public\-inbox\-daemon \- common usage for public\-inbox network daemons .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 5 \& public\-inbox\-netd \& public\-inbox\-httpd \& public\-inbox\-imapd \& public\-inbox\-nntpd \& public\-inbox\-pop3d .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This manual describes common options and behavior for public-inbox network daemons. Network daemons for public-inbox provide read-only \s-1IMAP, HTTP, NNTP\s0 and \s-1POP3\s0 access to public-inboxes. Write access to a public-inbox will never be required to run these. .PP 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. .PP They also provide graceful shutdown/upgrade support to avoid breaking existing connections during software upgrades. .PP These daemons may also utilize multiple pre-forked worker processes to take advantage of multiple CPUs. .SH "OPTIONS" .IX Header "OPTIONS" .IP "\-l [\s-1PROTOCOL://\s0]ADDRESS[?opt1=val1,opt2=val2]" 4 .IX Item "-l [PROTOCOL://]ADDRESS[?opt1=val1,opt2=val2]" .PD 0 .IP "\-\-listen [\s-1PROTOCOL://\s0]ADDRESS[?opt1=val1,opt2=val2]" 4 .IX Item "--listen [PROTOCOL://]ADDRESS[?opt1=val1,opt2=val2]" .PD This takes an absolute path to a Unix socket or \s-1HOST:PORT\s0 to listen on. For example, to listen to \s-1TCP\s0 connections on port 119, use: \f(CW\*(C`\-l 0.0.0.0:119\*(C'\fR. This may also point to a Unix socket (\f(CW\*(C`\-l /path/to/http.sock\*(C'\fR) for a reverse proxy like \fBnginx\fR\|(8) to use. .Sp May be specified multiple times to allow listening on multiple sockets. .Sp Unless per-listener options are used (required for \&\fBpublic\-inbox\-netd\fR\|(1)), this does not need to be specified at all if relying on \fBsystemd.socket\fR\|(5) or similar, .Sp Per-listener options may be specified after \f(CW\*(C`?\*(C'\fR as \f(CW\*(C`KEY=VALUE\*(C'\fR pairs delimited by \f(CW\*(C`,\*(C'\fR. See \fBpublic\-inbox\-netd\fR\|(1) for documentation on the \f(CW\*(C`cert=\*(C'\fR, \f(CW\*(C`key=\*(C'\fR, \f(CW\*(C`env.NAME=VALUE\*(C'\fR, \&\f(CW\*(C`out=\*(C'\fR, \f(CW\*(C`err=\*(C'\fR, and \f(CW\*(C`psgi=\*(C'\fR options available. .Sp Default: server-dependent unless socket activation is used with \&\fBsystemd\fR\|(1) or similar (see \fBsystemd.socket\fR\|(5)). .IP "\-1" 4 .IX Item "-1" .PD 0 .IP "\-\-stdout \s-1PATH\s0" 4 .IX Item "--stdout PATH" .PD Specify an appendable path to redirect stdout descriptor (1) to. Using this is preferable to setting up the redirect externally (e.g. >>/path/to/log in shell) since it allows \&\s-1SIGUSR1\s0 to be handled (see \*(L"\s-1SIGNALS\*(R"\s0 in \s-1SIGNALS\s0 below). .Sp \&\f(CW\*(C`out=\*(C'\fR may also be specified on a per-listener basis. .Sp Default: /dev/null with \f(CW\*(C`\-\-daemonize\*(C'\fR, inherited otherwise .IP "\-2 \s-1PATH\s0" 4 .IX Item "-2 PATH" .PD 0 .IP "\-\-stderr \s-1PATH\s0" 4 .IX Item "--stderr PATH" .PD Like \f(CW\*(C`\-\-stdout\*(C'\fR, but for the stderr descriptor (2). .Sp \&\f(CW\*(C`err=\*(C'\fR may also be specified on a per-listener basis. .Sp Default: /dev/null with \f(CW\*(C`\-\-daemonize\*(C'\fR, inherited otherwise .IP "\-W" 4 .IX Item "-W" .PD 0 .IP "\-\-worker\-processes" 4 .IX Item "--worker-processes" .PD Set the number of worker processes. .Sp 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. .Sp Setting this to zero (\f(CW\*(C`\-W0\*(C'\fR) disables the master/worker split; saving some memory but removing the ability to use \s-1SIGTTIN\s0 to increase worker processes or have the worker restarted by the master on crashes. .Sp Default: 1 .IP "\-\-cert /path/to/cert" 4 .IX Item "--cert /path/to/cert" The default \s-1TLS\s0 certificate for \s-1HTTPS, IMAPS, NNTPS, POP3S\s0 and/or \s-1STARTTLS\s0 support if the \f(CW\*(C`cert\*(C'\fR option is not given with \f(CW\*(C`\-\-listen\*(C'\fR. .Sp Well-known \s-1TCP\s0 ports automatically get \s-1TLS\s0 or \s-1STARTTLS\s0 support If using systemd-compatible socket activation and a \s-1TCP\s0 listener on port well-known ports (563 is inherited, it is automatically \&\s-1NNTPS\s0 when this option is given. When a listener on port 119 is inherited and this option is given, it automatically gets \&\s-1STARTTLS\s0 support. .IP "\-\-key /path/to/key" 4 .IX Item "--key /path/to/key" The default \s-1TLS\s0 certificate key for the default \f(CW\*(C`\-\-cert\*(C'\fR or per-listener \f(CW\*(C`cert=\*(C'\fR option. The private key may be concatenated into the path used by the cert, in which case this option is not needed. .SH "SIGNALS" .IX Header "SIGNALS" Most of our signal handling behavior is copied from \fBnginx\fR\|(8) and/or \fBstarman\fR\|(1); so it is possible to reuse common scripts for managing them. .IP "\s-1SIGUSR1\s0" 8 .IX Item "SIGUSR1" Reopens log files pointed to by \-\-stdout and \-\-stderr options. .IP "\s-1SIGUSR2\s0" 8 .IX Item "SIGUSR2" Spawn a new process with the intention to replace the running one. See \*(L"\s-1UPGRADING\*(R"\s0 below. .IP "\s-1SIGHUP\s0" 8 .IX Item "SIGHUP" Reload config files associated with the process. (Note: broken for \fBpublic\-inbox\-httpd\fR\|(1) only in <= 1.6) .IP "\s-1SIGTTIN\s0" 8 .IX Item "SIGTTIN" Increase the number of running workers processes by one. .IP "\s-1SIGTTOU\s0" 8 .IX Item "SIGTTOU" Decrease the number of running worker processes by one. .IP "\s-1SIGWINCH\s0" 8 .IX Item "SIGWINCH" Stop all running worker processes. \s-1SIGHUP\s0 or \s-1SIGTTIN\s0 may be used to restart workers. .IP "\s-1SIGQUIT\s0" 8 .IX Item "SIGQUIT" Gracefully terminate the running process. .PP \&\s-1SIGTTOU, SIGTTIN, SIGWINCH\s0 all have no effect when worker processes are disabled with \f(CW\*(C`\-W0\*(C'\fR on the command-line. .SH "ENVIRONMENT" .IX Header "ENVIRONMENT" .IP "\s-1PI_CONFIG\s0" 8 .IX Item "PI_CONFIG" The default config file, normally \*(L"~/.public\-inbox/config\*(R". See \fBpublic\-inbox\-config\fR\|(5) .IP "\s-1LISTEN_FDS, LISTEN_PID\s0" 8 .IX Item "LISTEN_FDS, LISTEN_PID" Used by systemd (and compatible) installations for socket activation. See \fBsystemd.socket\fR\|(5) and \fBsd_listen_fds\fR\|(3). .IP "\s-1PERL_INLINE_DIRECTORY\s0" 8 .IX Item "PERL_INLINE_DIRECTORY" Pointing this to point to a writable directory enables the use of Inline and Inline::C extensions which may provide platform-specific performance improvements. Currently, this enables the use of \fBvfork\fR\|(2) which speeds up subprocess spawning with the Linux kernel. .Sp public-inbox will never enable Inline::C automatically without this environment variable set or \f(CW\*(C`~/.cache/public\-inbox/inline\-c\*(C'\fR created by a user. See Inline and Inline::C for more details. .SH "UPGRADING" .IX Header "UPGRADING" There are two ways to upgrade a running process. .PP Users of process management systems with socket activation (\fBsystemd\fR\|(1) or similar) may rely on multiple instances For systemd, this means using two (or more) '@' instances for each service (e.g. \f(CW\*(C`SERVICENAME@INSTANCE\*(C'\fR) as documented in \&\fBsystemd.unit\fR\|(5). .PP Users of traditional SysV init may use \s-1SIGUSR2\s0 to spawn a replacement process and gracefully terminate the old process using \s-1SIGQUIT.\s0 .PP In either case, the old process will not truncate running responses; so responses to expensive requests do not get interrupted and lost. .SH "CONTACT" .IX Header "CONTACT" Feedback welcome via plain-text mail to .PP The mail archives are hosted at and .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright all contributors .PP License: \s-1AGPL\-3.0+\s0 .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBpublic\-inbox\-httpd\fR\|(1), \fBpublic\-inbox\-imapd\fR\|(1), \&\fBpublic\-inbox\-nntpd\fR\|(1), \fBpublic\-inbox\-pop3d\fR\|(1), \fBpublic\-inbox\-netd\fR\|(1)