X-Git-Url: http://www.git.stargrave.org/?a=blobdiff_plain;f=Documentation%2Fpublic-inbox-daemon.pod;h=f77fc3a9f732e44c738946edb95ee3b972256713;hb=refs%2Fheads%2Fmaster;hp=42beda69927d5104769145eeac01d5cb8c5a04ef;hpb=66c6699142d95cce9e5c9d49e0498161a776cc22;p=public-inbox.git

diff --git a/Documentation/public-inbox-daemon.pod b/Documentation/public-inbox-daemon.pod
index 42beda69..81a79a10 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 and HTTP access to public-inboxes.  Write
-access to a public-inbox repository 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
@@ -25,40 +27,61 @@ breaking existing connections during software upgrades.
 These daemons may also utilize multiple pre-forked worker
 processes to take advantage of multiple CPUs.
 
-Native TLS (Transport Layer Security) support is planned.
-
 =head1 OPTIONS
 
 =over
 
-=item -l, --listen ADDRESS
+=item -l [PROTOCOL://]ADDRESS[?opt1=val1,opt2=val2]
+
+=item --listen [PROTOCOL://]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
 port 119, use: C<-l 0.0.0.0:119>.  This may also point to
 a Unix socket (C<-l /path/to/http.sock>) for a reverse proxy
-like L<nginx(1)> to use.
+like L<nginx(8)> to use.
 
 May be specified multiple times to allow listening on multiple
 sockets.
 
+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)>).
 
-=item -1, --stdout PATH
+=item -1
+
+=item --stdout PATH
 
 Specify an appendable path to redirect stdout descriptor (1) to.
 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.
 
-=item -2, --stderr PATH
+Default: /dev/null with C<--daemonize>, inherited otherwise
+
+=item -2 PATH
+
+=item --stderr PATH
 
 Like C<--stdout>, but for the stderr descriptor (2).
 
-=item -W, --worker-processes
+C<err=> may also be specified on a per-listener basis.
+
+Default: /dev/null with C<--daemonize>, inherited otherwise
+
+=item -W
+
+=item --worker-processes
 
 Set the number of worker processes.
 
@@ -73,11 +96,30 @@ 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
 
-Most of our signal handling behavior is copied from L<nginx(1)>
+Most of our signal handling behavior is copied from L<nginx(8)>
 and/or L<starman(1)>; so it is possible to reuse common scripts
 for managing them.
 
@@ -95,7 +137,7 @@ See L</UPGRADING> below.
 =item SIGHUP
 
 Reload config files associated with the process.
-(FIXME: not tested for -httpd, yet)
+(Note: broken for L<public-inbox-httpd(1)> only in E<lt>= 1.6)
 
 =item SIGTTIN
 
@@ -133,6 +175,18 @@ See L<public-inbox-config(5)>
 Used by systemd (and compatible) installations for socket
 activation.  See L<systemd.socket(5)> and L<sd_listen_fds(3)>.
 
+=item PERL_INLINE_DIRECTORY
+
+Pointing this to point to a writable directory enables the use
+of L<Inline> and L<Inline::C> extensions which may provide
+platform-specific performance improvements.  Currently, this
+enables the use of L<vfork(2)> which speeds up subprocess
+spawning with the Linux kernel.
+
+public-inbox will never enable L<Inline::C> automatically without
+this environment variable set or C<~/.cache/public-inbox/inline-c>
+created by a user. See L<Inline> and L<Inline::C> for more details.
+
 =back
 
 =head1 UPGRADING
@@ -157,15 +211,16 @@ interrupted and lost.
 
 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 
-The mail archives are hosted at L<https://public-inbox.org/meta/>
-and L<http://hjrcffqmbrq6wope.onion/meta/>
+The mail archives are hosted at L<https://public-inbox.org/meta/> and
+L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 
 =head1 COPYRIGHT
 
-Copyright 2013-2016 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-nntpd(1)>
+L<public-inbox-httpd(1)>, L<public-inbox-imapd(1)>,
+L<public-inbox-nntpd(1)>, L<public-inbox-pop3d(1)>, L<public-inbox-netd(1)>