about summary refs log tree commit homepage
path: root/Documentation
diff options
context:
space:
mode:
authorEric Wong <e@80x24.org>2022-08-01 21:24:43 +0000
committerEric Wong <e@80x24.org>2022-08-02 19:20:11 +0000
commitc38111d6f3877cf31d28b0a0339d063df0fa58f6 (patch)
tree8bf1d2c22d96a9bc3ca9c20b9c85eab46802c5be /Documentation
parenta55a38db0276a8ce1a09392573af6e1305cbaba9 (diff)
downloadpublic-inbox-c38111d6f3877cf31d28b0a0339d063df0fa58f6.tar.gz
This allows memory savings by allowing multiple, completely
unrelated-PSGI apps to run within the same process as IMAP,
NNTP, and POP3.
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/public-inbox-daemon.pod51
-rw-r--r--Documentation/public-inbox-netd.pod34
2 files changed, 67 insertions, 18 deletions
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<nginx(8)> 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<systemd.socket(5)> or similar
+Unless per-listener options are used (required for
+L<public-inbox-netd(1)>), this does not need to be specified at
+all if relying on L<systemd.socket(5)> or similar,
+
+Per-listener options may be specified after C<?> as C<KEY=VALUE>
+pairs delimited by C<,>.  See L<public-inbox-netd(1)> for
+documentation on the C<cert=>, C<key=>, C<env.NAME=VALUE>,
+C<out=>, C<err=>, and C<psgi=> options available.
 
 Default: server-dependent unless socket activation is used with
 L<systemd(1)> or similar (see L<systemd.socket(5)>).
@@ -57,7 +65,9 @@ Using this is preferable to setting up the redirect externally
 (e.g. E<gt>E<gt>/path/to/log in shell) since it allows
 SIGUSR1 to be handled (see L<SIGNALS/SIGNALS> below).
 
-Default: /dev/null
+C<out=> 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<err=> 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<cert> 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<cert=> 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<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 
 =head1 COPYRIGHT
 
-Copyright 2013-2021 all contributors L<mailto:meta@public-inbox.org>
+Copyright all contributors L<mailto:meta@public-inbox.org>
 
 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 
 =head1 SEE ALSO
 
 L<public-inbox-httpd(1)>, L<public-inbox-imapd(1)>,
-L<public-inbox-nntpd(1)>
+L<public-inbox-nntpd(1)>, L<public-inbox-pop3d(1)>, L<public-inbox-netd(1)>
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<public-inbox-daemon(8)> 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<public-inbox-daemon(8)> 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<public-inbox-daemon(8)/OPTIONS>.
 
 =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<public-inbox-daemon(8)>, the protocol prefix (e.g. C<nntp://> or
 C<nntps://>) may be specified to force a given protocol.
 
+Environment variable overrides in effect during loading and
+reloading (SIGHUP) can be specified as C<env.NAME=VALUE> for
+all protocols.
+
+HTTP(S) listeners may also specify C<psgi=> to use a different
+C<.psgi> file for each listener.
+
+C<err=/path/to/errors.log> may be used to isolate error/debug output
+for a particular listener away from C<--stderr>.
+
+Non-HTTP(S) listeners may also specify C<out=> for logging to
+C<stdout>.  HTTP(S) users are encouraged to configure
+L<Plack::Middleware::AccessLog> or
+L<Plack::Middleware::AccessLog::Timed>, instead.
+
 =item --cert /path/to/cert
 
-The default TLS certificate for optional TLS support
-if the C<cert> option is not given with C<--listen>.
+See L<public-inbox-daemon(1)>.
 
 =item --key /path/to/key
 
-The default private TLS certificate key for optional TLS support
-if the C<key> 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<public-inbox-daemon(1)>.
 
 =back
 
@@ -57,6 +71,8 @@ L<public-inbox-config(5)>.
 
 =item publicinbox.nntpserver
 
+=item publicinbox.pop3state
+
 =back
 
 See L<public-inbox-config(5)> for documentation on them.