NAME
    public-inbox-daemon - common usage for public-inbox network daemons

SYNOPSIS
            public-inbox-httpd
            public-inbox-nntpd

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.

    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.

    They also provide graceful shutdown/upgrade support to avoid 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.

OPTIONS
    -l, --listen ADDRESS
        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: "-l
        0.0.0.0:119". This may also point to a Unix socket ("-l
        /path/to/http.sock") for a reverse proxy like nginx(1) to use.

        May be specified multiple times to allow listening on multiple
        sockets.

        Default: server-dependent unless socket activation is used with
        systemd(1) or similar (see systemd.socket(5)).

    -1, --stdout PATH
        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 SIGUSR1 to be handled (see
        "SIGNALS" in SIGNALS below).

        Default: /dev/null

    -2, --stderr PATH
        Like "--stdout", but for the stderr descriptor (2).

    -W, --worker-processes
        Set the number of worker processes.

        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.

        Setting this to zero ("-W0") disables the master/worker split;
        saving some memory but removing the ability to use SIGTTIN to
        increase worker processes or have the worker restarted by the master
        on crashes.

        Default: 1

SIGNALS
    Most of our signal handling behavior is copied from nginx(1) and/or
    starman(1); so it is possible to reuse common scripts for managing them.

    SIGUSR1 Reopens log files pointed to by --stdout and --stderr options.

    SIGUSR2 Spawn a new process with the intention to replace the running
            one. See "UPGRADING" below.

    SIGHUP  Reload config files associated with the process. (FIXME: not
            tested for -httpd, yet)

    SIGTTIN Increase the number of running workers processes by one.

    SIGTTOU Decrease the number of running worker processes by one.

    SIGWINCH
            Stop all running worker processes. SIGHUP or SIGTTIN may be used
            to restart workers.

    SIGQUIT Gracefully terminate the running process.

    SIGTTOU, SIGTTIN, SIGWINCH all have no effect when worker processes are
    disabled with "-W0" on the command-line.

ENVIRONMENT
    PI_CONFIG
            The default config file, normally "~/.public-inbox/config". See
            public-inbox-config(5)

    LISTEN_FDS, LISTEN_PID
            Used by systemd (and compatible) installations for socket
            activation. See systemd.socket(5) and sd_listen_fds(3).

    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 vfork(2) which speeds up subprocess spawning
            with the Linux kernel.

            public-inbox will never enable Inline::C automatically without
            this environment variable set. See Inline and Inline::C for more
            details.

UPGRADING
    There are two ways to upgrade a running process.

    Users of process management systems with socket activation (systemd(1)
    or similar) may rely on multiple instances For systemd, this means using
    two (or more) '@' instances for each service (e.g.
    "SERVICENAME@INSTANCE") as documented in systemd.unit(5).

    Users of traditional SysV init may use SIGUSR2 to spawn a replacement
    process and gracefully terminate the old process using SIGQUIT.

    In either case, the old process will not truncate running responses; so
    responses to expensive requests do not get interrupted and lost.

CONTACT
    Feedback welcome via plain-text mail to <mailto:meta@public-inbox.org>

    The mail archives are hosted at <https://public-inbox.org/meta/> and
    <http://hjrcffqmbrq6wope.onion/meta/>

COPYRIGHT
    Copyright 2013-2016 all contributors <mailto:meta@public-inbox.org>

    License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>

SEE ALSO
    public-inbox-httpd(1), public-inbox-nntpd(1)