'\" t
.TH "SYSTEMD\-SOCKET\-PROXYD" "8" "" "systemd 256~rc3" "systemd-socket-proxyd"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
systemd-socket-proxyd \- Bidirectionally proxy local sockets to another (possibly remote) socket
.SH "SYNOPSIS"
.HP \w'\fBsystemd\-socket\-proxyd\fR\ 'u
\fBsystemd\-socket\-proxyd\fR [\fIOPTIONS\fR...] \fIHOST\fR:\fIPORT\fR
.HP \w'\fBsystemd\-socket\-proxyd\fR\ 'u
\fBsystemd\-socket\-proxyd\fR [\fIOPTIONS\fR...] \fIUNIX\-DOMAIN\-SOCKET\-PATH\fR
.SH "DESCRIPTION"
.PP
\fBsystemd\-socket\-proxyd\fR
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\&.
.PP
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\&.
.PP
This utility\*(Aqs behavior is similar to
\fBsocat\fR(1)\&. The main differences for
\fBsystemd\-socket\-proxyd\fR
are support for socket activation with
"Accept=no"
and an event\-driven design that scales better with the number of connections\&.
.PP
Note that
\fBsystemd\-socket\-proxyd\fR
will not forward socket side channel information, i\&.e\&. will not forward
\fBSCM_RIGHTS\fR,
\fBSCM_CREDENTIALS\fR,
\fBSCM_SECURITY\fR,
\fBSO_PEERCRED\fR,
\fBSO_PEERPIDFD\fR,
\fBSO_PEERSEC\fR,
\fBSO_PEERGROUPS\fR
and similar\&.
.SH "OPTIONS"
.PP
The following options are understood:
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Print a short help text and exit\&.
.RE
.PP
\fB\-\-version\fR
.RS 4
Print a short version string and exit\&.
.RE
.PP
\fB\-\-connections\-max=\fR, \fB\-c\fR
.RS 4
Sets the maximum number of simultaneous connections, defaults to 256\&. If the limit of concurrent connections is reached further connections will be refused\&.
.sp
Added in version 233\&.
.RE
.PP
\fB\-\-exit\-idle\-time=\fR
.RS 4
Sets the time before exiting when there are no connections, defaults to
\fBinfinity\fR\&. Takes a unit\-less value in seconds, or a time span value such as
"5min 20s"\&.
.sp
Added in version 246\&.
.RE
.SH "EXIT STATUS"
.PP
On success, 0 is returned, a non\-zero failure code otherwise\&.
.SH "EXAMPLES"
.SS "Simple Example"
.PP
Use two services with a dependency and no namespace isolation\&.
.PP
\fBExample\ \&1.\ \&proxy\-to\-nginx\&.socket\fR
.sp
.if n \{\
.RS 4
.\}
.nf
[Socket]
ListenStream=80

[Install]
WantedBy=sockets\&.target
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&2.\ \&proxy\-to\-nginx\&.service\fR
.sp
.if n \{\
.RS 4
.\}
.nf
[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
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&3.\ \&nginx\&.conf\fR
.sp
.if n \{\
.RS 4
.\}
.nf
[\&...]
server {
    listen       unix:/run/nginx/socket;
    [\&...]
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&4.\ \&Enabling the proxy\fR
.sp
.if n \{\
.RS 4
.\}
.nf
# systemctl enable \-\-now proxy\-to\-nginx\&.socket
$ curl http://localhost:80/
.fi
.if n \{\
.RE
.\}
.PP
If
nginx\&.service
has
\fIStopWhenUnneeded=\fR
set, then passing
\fB\-\-exit\-idle\-time=\fR
to
\fBsystemd\-socket\-proxyd\fR
allows both services to stop during idle periods\&.
.SS "Namespace Example"
.PP
Similar as above, but runs the socket proxy and the main service in the same private namespace, assuming that
nginx\&.service
has
\fIPrivateTmp=\fR
and
\fIPrivateNetwork=\fR
set, too\&.
.PP
\fBExample\ \&5.\ \&proxy\-to\-nginx\&.socket\fR
.sp
.if n \{\
.RS 4
.\}
.nf
[Socket]
ListenStream=80

[Install]
WantedBy=sockets\&.target
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&6.\ \&proxy\-to\-nginx\&.service\fR
.sp
.if n \{\
.RS 4
.\}
.nf
[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
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&7.\ \&nginx\&.conf\fR
.sp
.if n \{\
.RS 4
.\}
.nf
[\&...]
server {
    listen       8080;
    [\&...]
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&8.\ \&Enabling the proxy\fR
.sp
.if n \{\
.RS 4
.\}
.nf
# systemctl enable \-\-now proxy\-to\-nginx\&.socket
$ curl http://localhost:80/
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1), \fBsystemd.socket\fR(5), \fBsystemd.service\fR(5), \fBsystemctl\fR(1), \fBsocat\fR(1), \fBnginx\fR(1), \fBcurl\fR(1)