<?xml version="1.0"?>

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<refentry id="systemd-socket-proxyd">

<refentryinfo>

<title>systemd-socket-proxyd</title>

<productname>systemd</productname>

<authorgroup>

<author>

<contrib>Developer</contrib>

<firstname>David</firstname>

<surname>Strauss</surname>

<email>david@davidstrauss.net</email>

</author>

</authorgroup>

</refentryinfo>

<refmeta>

<refentrytitle>systemd-socket-proxyd</refentrytitle>

<manvolnum>1</manvolnum>

</refmeta>

<refnamediv>

<refname>systemd-socket-proxyd</refname>

<refpurpose>Bidirectionally proxy local sockets to another (possibly remote) socket.</refpurpose>

</refnamediv>

<refsynopsisdiv>

<cmdsynopsis>

<command>systemd-socket-proxyd</command>

<arg choice="opt" rep="repeat"><replaceable>OPTIONS</replaceable></arg>

<arg choice="plain"><replaceable>HOST</replaceable>:<replaceable>PORT</replaceable></arg>

</cmdsynopsis>

<cmdsynopsis>

<command>systemd-socket-proxyd</command>

<arg choice="opt" rep="repeat"><replaceable>OPTIONS</replaceable></arg>

<arg choice="plain"><replaceable>UNIX-DOMAIN-SOCKET-PATH</replaceable>

</arg>

</cmdsynopsis>

</refsynopsisdiv>

<refsect1>

<title>Description</title>

<para>

<command>systemd-socket-proxyd</command> 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.</para>

<para>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.</para>

<para>This utility's behavior is similar to

<citerefentry><refentrytitle>socat</refentrytitle><manvolnum>1</manvolnum></citerefentry>.

The main differences for <command>systemd-socket-proxyd</command>

are support for socket activation with

<literal>Accept=false</literal> and an event-driven

design that scales better with the number of

connections.</para>

</refsect1>

<refsect1>

<title>Options</title>

<para>The following options are understood:</para>

<variablelist>

<varlistentry>

<term><option>-h</option></term>

<term><option>--help</option></term>

<listitem>

<para>Prints a short help

text and exits.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>--version</option></term>

<listitem>

<para>Prints a version

string and exits.</para>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1>

<title>Exit status</title>

<para>On success, 0 is returned, a non-zero failure

code otherwise.</para>

</refsect1>

<refsect1>

<title>Examples</title>

<refsect2>

<title>Direct-Use Example</title>

<para>Use two services with a dependency

and no namespace isolation.</para>

<example label="proxy socket unit">

<title>/etc/systemd/system/proxy-to-nginx.socket</title>

<programlisting>

<![CDATA[[Socket]

WantedBy=sockets.target]]>

</programlisting>

</example>

<example label="proxy service unit">

<title>/etc/systemd/system/proxy-to-nginx.service</title>

<programlisting>

<![CDATA[[Unit]

PrivateNetwork=true]]>

</programlisting>

</example>

<example label="nginx configuration">

<title>/etc/nginx/nginx.conf</title>

<programlisting>

<![CDATA[[...]

[...]]]>

</programlisting>

</example>

<example label="commands">

<programlisting>

<![CDATA[# systemctl --system daemon-reload

$ curl http://localhost:80/]]>

</programlisting>

</example>

</refsect2>

<refsect2>

<title>Indirect-Use Example</title>

<para>Use a shell script to isolate the

service and proxy into the same namespace.

This is particularly useful for running

TCP-only daemons without the daemon

affecting ports on regular

interfaces.</para>

<example label="combined proxy and nginx socket unit">

<title>

/etc/systemd/system/proxy-with-nginx.socket</title>

<programlisting>

<![CDATA[[Socket]

WantedBy=sockets.target]]>

</programlisting>

</example>

<example label="combined proxy and nginx service unit">

<title>

/etc/systemd/system/proxy-with-nginx.service</title>

<programlisting>

<![CDATA[[Unit]

PrivateNetwork=true]]>

</programlisting>

</example>

<example label="shell script">

<title>

/usr/bin/socket-proxyd-nginx.sh</title>

<programlisting>

<![CDATA[#!/bin/sh

exec /usr/bin/systemd-socket-proxyd localhost 8080]]>

</programlisting>

</example>

<example label="nginx configuration">

<title>

/etc/nginx/nginx.conf</title>

<programlisting>

<![CDATA[[...]

[...]]]>

</programlisting>

</example>

<example label="commands">

<programlisting>

<![CDATA[# systemctl --system daemon-reload

$ curl http://localhost:80/]]>

</programlisting>

</example>

</refsect2>

</refsect1>

<refsect1>

<title>See Also</title>

<para>

<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>socat</refentrytitle><manvolnum>1</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>