SYSTEMD-SOCKET-PROXYD(8)

💖 systemd-socket-proxyd(8) 💖

okay bestie, so this is the manual page for systemd-socket-proxyd, from the systemd fam (version 262.1, for the record). it's a lil daemon with main character energy and it does exactly one thing but does it SO well. sit down, grab a strawberry 🍓, let's go.

---

✨ NAME ✨

systemd-socket-proxyd — bidirectionally proxy local sockets to another (possibly remote) socket 🦋

---

🎀 SYNOPSIS 🎀

systemd-socket-proxyd [OPTIONS...] HOST:PORT

systemd-socket-proxyd [OPTIONS...] UNIX-DOMAIN-SOCKET-PATH

---

🌸 DESCRIPTION 🌸

systemd-socket-proxyd is a generic socket-activated network socket forwarder proxy daemon, and it handles IPv4, IPv6 and UNIX stream sockets. literally all three. it's that versatile 💅

what it does is take traffic coming into a local listening socket and bi-directionally forward it to a local or remote destination socket. both ways. like a group chat relay but for sockets.

so here's the iconic use case: some services are, sadly, not born with socket activation support (tragic, i know 😭). this tool fixes that. on behalf of the service you wanna activate, the proxy inherits the socket from systemd, accepts every single client connection, opens a connection to a configured server for each one of those clients, and then bidirectionally forwards data between the two. slay.

ngl the behavior is similar to socat(1). but here's the glow-up: systemd-socket-proxyd supports socket activation with Accept=no, and it has an event-driven design that scales way better as the number of connections grows. so when things get busy it doesn't crumble. periodt.

⚠️ important bestie: systemd-socket-proxyd will not forward socket side channel information. that means no SCM_RIGHTS, no SCM_CREDENTIALS, no SCM_SECURITY, no SO_PEERCRED, no SO_PEERPIDFD, no SO_PEERSEC, no SO_PEERGROUPS, and nothing similar. it's just not doing it. don't ask 💀

---

✨ OPTIONS ✨

here's what it understands, bestie:

• -h, --help — prints a short help text and dips. 🫶
• --version — prints a short version string and dips. 🌈
• --connections-max=, -c — sets the max number of simultaneous connections. defaults to 256. if you hit the limit of concurrent connections, any further connections get refused. sorry babe, capacity is capacity 💅

Added in version 233.

• --exit-idle-time= — sets how long it waits before exiting when there are zero connections. defaults to infinity (so... never, lowkey immortal). takes a unit-less value in seconds, or a time span value like "5min 20s". 🕐

Added in version 246.

• --proxy-protocol= — uses the PROXY protocol[1] to talk to the server. this lets an appropriately configured server know the real client IP address. takes the version of the PROXY protocol[1] used, and only supports "v1" for now. default is to not use a PROXY protocol at all.

Added in version 261.

---

🔥 EXIT STATUS 🔥

on success, 0 is returned. a non-zero failure code otherwise. that's it, that's the whole vibe check. ✅

---

👑 EXAMPLES 👑

🧚 Simple Example

use two services with a dependency and no namespace isolation.

Example 1. proxy-to-nginx.socket

[Socket]
ListenStream=80

[Install]
WantedBy=sockets.target

Example 2. proxy-to-nginx.service

[Unit]
Requires=nginx.service
After=nginx.service
Requires=proxy-to-nginx.socket
After=proxy-to-nginx.socket

[Service]
Type=notify
ExecStart=/usr/lib/systemd/systemd-socket-proxyd /run/nginx/socket
PrivateTmp=yes
PrivateNetwork=yes

Example 3. nginx.conf

[...]
server {
    listen       unix:/run/nginx/socket;
    [...]

Example 4. Enabling the proxy

# systemctl enable --now proxy-to-nginx.socket
$ curl http://localhost:80/

if nginx.service has StopWhenUnneeded= set, then passing --exit-idle-time= to systemd-socket-proxyd lets both services stop during idle periods. cute, efficient, no wasted resources. obsessed. 💖

---

🦋 Namespace Example

similar as above, but it runs the socket proxy and the main service in the same private namespace — assuming that nginx.service has PrivateTmp= and PrivateNetwork= set, too. everyone's in the same lil room together 🫶

Example 5. proxy-to-nginx.socket

[Socket]
ListenStream=80

[Install]
WantedBy=sockets.target

Example 6. proxy-to-nginx.service

[Unit]
Requires=nginx.service
After=nginx.service
Requires=proxy-to-nginx.socket
After=proxy-to-nginx.socket
JoinsNamespaceOf=nginx.service

[Service]
Type=notify
ExecStart=/usr/lib/systemd/systemd-socket-proxyd 127.0.0.1:8080
PrivateTmp=yes
PrivateNetwork=yes

Example 7. nginx.conf

[...]
server {
    listen       8080;
    [...]

Example 8. Enabling the proxy

# systemctl enable --now proxy-to-nginx.socket
$ curl http://localhost:80/

---

🌈 PROXY protocol example with nginx

systemd-socket-proxyd and nginx, using the PROXY protocol. the crossover episode nobody knew they needed ✨

Example 9. proxy-to-nginx.socket

[Socket]
ListenStream=80

[Install]
WantedBy=sockets.target

Example 10. proxy-to-nginx.service

[Unit]
Requires=nginx.service
After=nginx.service
Requires=proxy-to-nginx.socket
After=proxy-to-nginx.socket

[Service]
Type=notify
ExecStart=/usr/lib/systemd/systemd-socket-proxyd --proxy-protocol=v1 /run/nginx/socket
PrivateTmp=yes
PrivateNetwork=yes

Example 11. nginx.conf

[...]
server {
    listen         unix:/run/nginx/socket proxy_protocol;
    real_ip_header proxy_protocol;
    [...]

Example 12. Enabling the proxy

# systemctl enable --now proxy-to-nginx.socket
$ curl http://localhost:80/

---

⭐ SEE ALSO ⭐

systemd(1), systemd.socket(5), systemd.service(5), systemctl(1), socat(1), nginx(1), curl(1), PROXY protocol specification[1], nginx: Accepting the PROXY Protocol[2]

---

📝 NOTES 📝

1. PROXY protocol https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt
2. nginx: Accepting the PROXY Protocol https://docs.nginx.com/nginx/admin-guide/load-balancer/using-proxy-protocol/

---

and that's the whole page, bestie!! 💜 this was systemd 262.1, SYSTEMD-SOCKET-PROXYD(8), and honestly? iconic of it. go forth and proxy bidirectionally, you absolute legend 🎀✨🦋