PUBLIC-INBOX-DAEMON(8)

💖 NAME 💖

okay so welcome to the public-inbox user manual page for PUBLIC-INBOX-DAEMON(8) — this is public-inbox-daemon, the page that covers the common usage for public-inbox network daemons. literally all the shared stuff across the daemon girlies. 💅

---

✨ SYNOPSIS ✨

public-inbox-netd
public-inbox-httpd
public-inbox-imapd
public-inbox-nntpd
public-inbox-pop3d

---

🦋 DESCRIPTION 🦋

bestie this manual is the shared lore for all the public-inbox network daemons. network daemons for public-inbox hand out read-only IMAP, HTTP, NNTP and POP3 access to public-inboxes. and no cap — write access to a public-inbox will never be required to run these. never ever. not once. 🫶

these daemons are built on a common core that uses non-blocking sockets and is optimized for fairness — like, even with thousands of connected clients over slow links. it's giving main character energy under pressure fr fr. 😤

they also do graceful shutdown/upgrade support so that existing connections don't get broken during software upgrades. no rude interruptions, no dropped besties. 💖

and they can also utilize multiple pre-forked worker processes to take advantage of multiple CPUs. slay, multi-core. 🔥

---

👑 OPTIONS 👑

• -l [PROTOCOL://]ADDRESS[?opt1=val1,opt2=val2]
• --listen [PROTOCOL://]ADDRESS[?opt1=val1,opt2=val2] — this one takes an absolute path to a Unix socket or a HOST:PORT to listen on. like, if you wanna listen to TCP connections on port 119, you go -l 0.0.0.0:119. it can also point at a Unix socket (-l /path/to/http.sock) for a reverse proxy like nginx(8) to use. 🎀

you can specify it multiple times to listen on multiple sockets. iconic, honestly.

unless per-listener options are in play (required for public-inbox-netd(1)), you don't have to specify this at all if you're relying on systemd.socket(5) or similar. lowkey optional, highkey convenient.

per-listener options go after the ? as KEY=VALUE pairs delimited by ,. see public-inbox-netd(1) for the docs on the cert=, key=, env.NAME=VALUE, out=, err=, and psgi= options available. iykyk. ✨

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 the stdout descriptor (1) to. doing it this way is preferable to setting up the redirect externally (e.g. >>/path/to/log in shell), because it lets SIGUSR1 be handled (peep the SIGNALS section below). 🫶

out= can also be specified on a per-listener basis.

Default: /dev/null with --daemonize, inherited otherwise.

• -2 PATH
• --stderr PATH — literally like --stdout but for the stderr descriptor (2). same energy, different fd. 💀

err= can also be specified on a per-listener basis.

Default: /dev/null with --daemonize, inherited otherwise.

• -W
• --worker-processes — sets the number of worker processes. 👑

normally you want this to match the number of CPUs on the system so you take full advantage of the hardware. but bestie, if you're on a memory-constrained system you may wanna lower it.

setting this to zero (-W0) disables the master/worker split — saves some memory, but it removes the ability to use SIGTTIN to increase worker processes, and removes the ability to have the worker restarted by the master on crashes. so, tradeoffs. 🙈

Default: 1

• --cert /path/to/cert — the default TLS certificate for HTTPS, IMAPS, NNTPS, POP3S and/or STARTTLS support, used when the cert option isn't given with --listen. 🔐

well-known TCP ports automatically get TLS or STARTTLS support. if you're using systemd-compatible socket activation and a TCP listener on well-known ports is inherited, then port 563 is automatically NNTPS when this option is given. and when a listener on port 119 is inherited and this option is given, it automatically gets STARTTLS support. 🎀

• --key /path/to/key — the default TLS certificate key for the default --cert or the per-listener cert= option. ngl the private key may be concatenated into the path used by the cert, in which case you don't need this option at all. 💅
• --multi-accept INTEGER — by default, each worker accepts one connection at-a-time to maximize fairness and minimize contention across multiple processes on a shared listen socket. accepting multiple connections at once may be useful in constrained deployments with few, heavily-loaded workers. 😭

negative values enable a worker to accept all available clients at once, possibly starving others in the process. -1 behaves like multi_accept yes in nginx, while 0 (the default) is multi_accept no in nginx. positive values let you fine-tune without the runaway behavior of -1. periodt.

this may be specified on a per-listener basis via the multi-accept= per-listener directive (e.g. -l http://127.0.0.1?multi-accept=1). 🦋

Default: 0

---

🌈 SIGNALS 🌈

most of our signal handling behavior is copied from nginx(8) and/or starman(1), so it's possible to reuse common scripts for managing them. cute, right? 🎀

• SIGUSR1 — reopens log files pointed to by the --stdout and --stderr options. ✨
• SIGUSR2 — spawns a new process with the intention to replace the running one. see UPGRADING below. 🔥
• SIGHUP — reloads config files associated with the process. (Note: broken for public-inbox-httpd(1) only in <= 1.6) 💀
• SIGTTIN — increases the number of running worker processes by one. 📈
• SIGTTOU — decreases the number of running worker processes by one. 📉
• SIGWINCH — stops all running worker processes. SIGHUP or SIGTTIN may be used to restart workers. 😴
• SIGQUIT — gracefully terminates the running process. bye bestie, no drama. 💅

heads up: SIGTTOU, SIGTTIN, SIGWINCH all have no effect when worker processes are disabled with -W0 on the command-line. nothing's listening, girl. 🫶

---

🌸 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 at 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. 🚀

no cap: public-inbox will never enable Inline::C automatically without this environment variable set, or without ~/.cache/public-inbox/inline-c being created by a user. see Inline and Inline::C for more details. ✨

---

🧚 UPGRADING 🧚

there are two ways to upgrade a running process. pick your fighter. 💅

users of process management systems with socket activation (systemd(1) or similar) may rely on multiple instances. for systemd, that 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. 🌈

either way, bestie: the old process will not truncate running responses, so responses to expensive requests don't get interrupted and lost. we do not drop the ball. periodt. 💖

---

🫶 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://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/> 🌐

---

💜 COPYRIGHT 💜

copyright 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-imapd(1), public-inbox-nntpd(1), public-inbox-pop3d(1), public-inbox-netd(1)

---

and that's the whole page bestie, no cap. this was public-inbox.git, dated 1993-10-02 — go forth and daemon responsibly. mwah. 💅💖✨