From c38111d6f3877cf31d28b0a0339d063df0fa58f6 Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Mon, 1 Aug 2022 21:24:43 +0000 Subject: daemon: support per-listener env, .psgi, out, err This allows memory savings by allowing multiple, completely unrelated-PSGI apps to run within the same process as IMAP, NNTP, and POP3. --- Documentation/public-inbox-daemon.pod | 51 ++++++++++++++++++++++++++++------- Documentation/public-inbox-netd.pod | 34 ++++++++++++++++------- 2 files changed, 67 insertions(+), 18 deletions(-) (limited to 'Documentation') diff --git a/Documentation/public-inbox-daemon.pod b/Documentation/public-inbox-daemon.pod index f77fc3a9..5d26ce56 100644 --- a/Documentation/public-inbox-daemon.pod +++ b/Documentation/public-inbox-daemon.pod @@ -4,16 +4,18 @@ public-inbox-daemon - common usage for public-inbox network daemons =head1 SYNOPSIS + public-inbox-netd public-inbox-httpd public-inbox-imapd public-inbox-nntpd + public-inbox-pop3d =head1 DESCRIPTION This manual describes common options and behavior for public-inbox network daemons. Network daemons for public-inbox -provide read-only NNTP, IMAP and HTTP access to public-inboxes. Write -access to a public-inbox will never be required to run these. +provide read-only IMAP, HTTP, NNTP and POP3 access to public-inboxes. +Write access to a public-inbox will never be required to run these. These daemons are implemented with a common core using non-blocking sockets and optimized for fairness; even with @@ -29,9 +31,9 @@ processes to take advantage of multiple CPUs. =over -=item -l ADDRESS +=item -l [PROTO://]ADDRESS[?opt1=val1,opt2=val2] -=item --listen ADDRESS +=item --listen [PROTO://]ADDRESS[?opt1=val1,opt2=val2] This takes an absolute path to a Unix socket or HOST:PORT to listen on. For example, to listen to TCP connections on @@ -42,8 +44,14 @@ like L to use. May be specified multiple times to allow listening on multiple sockets. -This does not need to be specified at all if relying on -L or similar +Unless per-listener options are used (required for +L), this does not need to be specified at +all if relying on L or similar, + +Per-listener options may be specified after C as C +pairs delimited by C<,>. See L for +documentation on the C, C, C, +C, C, and C options available. Default: server-dependent unless socket activation is used with L or similar (see L). @@ -57,7 +65,9 @@ Using this is preferable to setting up the redirect externally (e.g. EE/path/to/log in shell) since it allows SIGUSR1 to be handled (see L below). -Default: /dev/null +C may also be specified on a per-listener basis. + +Default: /dev/null with C<--daemonize>, inherited otherwise =item -2 PATH @@ -65,6 +75,10 @@ Default: /dev/null Like C<--stdout>, but for the stderr descriptor (2). +C may also be specified on a per-listener basis. + +Default: /dev/null with C<--daemonize>, inherited otherwise + =item -W =item --worker-processes @@ -82,6 +96,25 @@ the master on crashes. Default: 1 +=item --cert /path/to/cert + +The default TLS certificate for HTTPS, IMAPS, NNTPS, POP3S and/or STARTTLS +support if the C option is not given with C<--listen>. + +Well-known TCP ports automatically get TLS or STARTTLS support +If using systemd-compatible socket activation and a TCP listener +on port well-known ports (563 is inherited, it is automatically +NNTPS when this option is given. When a listener on port 119 is +inherited and this option is given, it automatically gets +STARTTLS support. + +=item --key /path/to/key + +The default TLS certificate key for the default C<--cert> or +per-listener C option. The private key may be +concatenated into the path used by the cert, in which case this +option is not needed. + =back =head1 SIGNALS @@ -183,11 +216,11 @@ L =head1 COPYRIGHT -Copyright 2013-2021 all contributors L +Copyright all contributors L License: AGPL-3.0+ L =head1 SEE ALSO L, L, -L +L, L, L diff --git a/Documentation/public-inbox-netd.pod b/Documentation/public-inbox-netd.pod index dcf4d5b0..4dc27749 100644 --- a/Documentation/public-inbox-netd.pod +++ b/Documentation/public-inbox-netd.pod @@ -8,9 +8,10 @@ public-inbox-netd - read-only network daemon for sharing public-inboxes =head1 DESCRIPTION -public-inbox-netd provides a read-only HTTP/IMAP/NNTP/POP3 daemon for -public-inbox. It uses options and environment variables common -to all L implementations. +public-inbox-netd provides a read-only multi-protocol +(HTTP/IMAP/NNTP/POP3) daemon for public-inbox. It uses options +and environment variables common to all +L implementations. The default configuration will never require write access to the directory where the public-inbox is stored, so it @@ -28,21 +29,34 @@ See common options in L. =item --listen PROTO://ADDRESS/?cert=/path/to/cert,key=/path/to/key +=item -l http://ADDRESS/?env.PI_CONFIG=/path/to/cfg,psgi=/path/to/app.psgi + In addition to the normal C<-l>/C<--listen> switch described in L, the protocol prefix (e.g. C or C) may be specified to force a given protocol. +Environment variable overrides in effect during loading and +reloading (SIGHUP) can be specified as C for +all protocols. + +HTTP(S) listeners may also specify C to use a different +C<.psgi> file for each listener. + +C may be used to isolate error/debug output +for a particular listener away from C<--stderr>. + +Non-HTTP(S) listeners may also specify C for logging to +C. HTTP(S) users are encouraged to configure +L or +L, instead. + =item --cert /path/to/cert -The default TLS certificate for optional TLS support -if the C option is not given with C<--listen>. +See L. =item --key /path/to/key -The default private TLS certificate key for optional TLS support -if the C option is not given with C<--listen>. The private -key may be concatenated into the path used by C<--cert>, in which case this -option is not needed. +See L. =back @@ -57,6 +71,8 @@ L. =item publicinbox.nntpserver +=item publicinbox.pop3state + =back See L for documentation on them. -- cgit v1.2.3-24-ge0c7