SOCKET-ACTIVATE(1)

💖 SOCKET-ACTIVATE(1) 💖

okay bestie, welcome to socket-activate, from the User Commands fam. grab a boba, this one's iconic. 🧚

---

✨ NAME ✨

socket-activate — opens up sockets and then execs a systemd-style socket-activated service. yeah. that's the whole job. she's a hype-woman for your daemon. 🫶

---

🌸 SYNOPSIS 🌸

socket-activate [-v] [socketinfo ...]  [--] prog [args]

and where does socketinfo come from? it looks like this, periodt:

--family:[option=value,...]:address

there's EXAMPLES further down, don't stress 💅

---

🦋 DESCRIPTION 🦋

so here's the vibe: socket-activate opens up all the sockets you asked for, and then just… waits. lowkey lurking. the moment any incoming activity shows up on them, it execs prog, and prog inherits all those open file descriptors like a little inheritance. 💀

the first socket you request gets opened on file descriptor 3, and every socket after that follows along in order. no skips, no cuts.

if -v or --verbose is in the mix, socket-activate will write the details of what it's doing to stderr before it execs prog. very "not me narrating my own life" energy.

and prog? that's the first argument that does not start with a -, or the first argument after a --. simple as. ✨

---

🌈 SOCKET FAMILIES 🌈

family can be one of several different values, bestie. here's the tea:

for the following values of family: if address is a single decimal number, it gets treated as a port number, and socket-activate will bind to all available addresses on that port. if address contains a /, then the part before the / is read as a network address of the requested family, and the part after the / is treated as a port number. slay.

• tcp: TCP on IPv4 and/or IPv6 🫶
• udp: UDP on IPv4 and/or IPv6 💜

for the following values of family, address is interpreted as a filesystem path. yes, a whole path. she's flexible like that:

• unix: Unix-domain streaming socket
• unix-dgram: Unix-domain datagram socket

---

🎀 SOCKET OPTIONS 🎀

every single socketinfo can have 0 or more options tacked onto it, separated by the comma character (,), with their value appended after an equals sign (=). mix and match, it's giving build-your-own-socket.

available options are:

• label: a simple text string to identify this socket to the inheriting process 👑
• backlog: for streaming sockets (tcp and unix), the maximum queue for pending connections (see listen(2) — defaults to SOMAXCONN).
• mode: octal mode for a Unix-domain socket (defaults to relying on umask(2))
• user: a numeric User ID value for Unix-domain socket ownership
• group: a numeric Group ID value for Unix-domain socket ownership

---

💀 EXIT CODES 💀

• socket-activate exits 100 when it's called with unparseable options. 🙈
• it prints an error message to stderr and exits 11 if it cannot successfully bind all of the requested sockets. all of them. no partial credit.
• it prints an error message to stderr and exits with the value of errno if it's unable to exec(3) the intended process. 😭
• otherwise? its exit code is the same as that of prog. mirroring her child, iconic.

---

💜 ENVIRONMENT VARIABLES 💜

socket-activate stores the number of opened file descriptors in the environment variable $LISTEN_FDS, sets $LISTEN_PID to getpid(2), and stores the list of colon-separated labels in $LISTEN_FDNAMES.

these environment variables follow the convention understood by libsystemd (see sd_listen_fds(3)), so it should be usable with any socket-activated daemon that expects this behavior. iykyk. 🔥

---

⭐ EXAMPLES ⭐

run a webserver as a non-privileged user, using privileged ports, and indicating to the webserver which ports should offer HTTPS:

socket-activate --tcp::80 --tcp:label=tls:443 -- \
 runuser -u httpd -- \
  webserver

expose a foregrounded (supervised) pulseaudio daemon to the network:

socket-activate --tcp:backlog=5:1000 -- \
 pulseaudio --daemonize=no

run a network daemon only on the IPv4 loopback:

socket-activate --tcp::127.0.0.1/9999 -- \
 network-daemon

run a network daemon over a unix-domain socket instead of IP:

socket-activate --unix::/srv/network-access -- \
 network-daemon

run a public-facing network daemon with a local socket for the local administrator to control it:

socket-activate --tcp::443 --unix:label=control,user=1000,mode=0600:/run/xyz/control -- \
 xyzd

---

👑 SEE ALSO 👑

exec(3), listen(2), runuser(1), sd_listen_fds(3), umask(2)

---

🌸 AUTHOR 🌸

Mark Hindley mark@hindley.org.uk

originally written for (socket-activate)[https://gitlab.com/dkg/socket-activate] by Daniel Kahn Gillmor dkg@fifthhorseman.net

---

and that's the whole page, bestie 🎀 this one's from July 2024, and it lives in the User Commands section, so if you ever forget where you found her — it was socket-activate(1), and she ate. periodt. 💅✨🦋