systemd-socket-proxyd - Man Page

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 for IPv4, IPv6 and UNIX stream sockets​. It may be used to bi-directionally forward traffic from a local listening socket to a local or remote destination socket​.

One use of this tool is to provide socket activation support for services that do not natively support socket activation​. On behalf of the service to activate, the proxy inherits the socket from systemd, accepts each client connection, opens a connection to a configured server for each client, and then bidirectionally forwards data between the two​.

This utility's behavior is similar to socat(1)​. The main differences for systemd-socket-proxyd are support for socket activation with "Accept=no" and an event-driven design that scales better with the number of connections​.

Note that systemd-socket-proxyd will not forward socket side channel information, i​.e​. will not forward SCM_RIGHTS, SCM_CREDENTIALS, SCM_SECURITY, SO_PEERCRED, SO_PEERPIDFD, SO_PEERSEC, SO_PEERGROUPS and similar​.

Options

The following options are understood:

-h,  --help

Print a short help text and exit​.

--version

Print a short version string and exit​.

--connections-max=, -c

Sets the maximum number of simultaneous connections, defaults to 256​. If the limit of concurrent connections is reached further connections will be refused​.

Added in version 233​.

--exit-idle-time=

Sets the time before exiting when there are no connections, defaults to infinity​. Takes a unit-less value in seconds, or a time span value such as "5min 20s"​.

Added in version 246​.

--proxy-protocol=

Uses the PROXY protocol​[1] to communicate with the server​. This allows an appropriately configured server to know the real client IP address​. Takes the version of the PROXY protocol​[1] used, and only supports "v1" for now​. Default is not to use a PROXY protocol​.

Added in version 261​.

Exit Status

On success, 0 is returned, a non-zero failure code otherwise​.

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 allows both services to stop during idle periods​.

Namespace Example

Similar as above, but runs the socket proxy and the main service in the same private namespace, assuming that nginx​.service has PrivateTmp= and PrivateNetwork= set, too​.

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

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/

Referenced By

systemd.directives(7), systemd.index(7).

systemd 262~rc2