<?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>Inherit a socket. Bidirectionally

proxy.</refpurpose>

</refnamediv>

<refsynopsisdiv>

<cmdsynopsis>

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

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

<arg choice="plain"><replaceable>HOSTNAME-OR-IPADDR</replaceable></arg>

<arg choice="plain"><replaceable>PORT-OR-SERVICE</replaceable></arg>

</cmdsynopsis>

<cmdsynopsis>

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

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

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

</arg>

</cmdsynopsis>

</refsynopsisdiv>

<refsect1>

<title>Description</title>

<para>

<command>systemd-socket-proxyd</command> provides a proxy

to socket-activate services that do not yet support

native socket activation. On behalf of the daemon,

the proxy inherits the socket from systemd, accepts

each client connection, opens a connection to the 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>

<varlistentry>

<term><option>--ignore-env</option></term>

<listitem>

<para>Skips verification of

the expected PID and file

descriptor numbers. Use this if

invoked indirectly, for

example, with a shell script

rather than with

<option>ExecStart=/usr/lib/systemd/systemd-socket-proxyd</option>

</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[$ sudo 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

/usr/bin/systemd-socket-proxyd --ignore-env localhost 8080]]>

</programlisting>

</example>

<example label="nginx configuration">

<title>

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

<programlisting>

<![CDATA[[...]

[...]]]>

</programlisting>

</example>

<example label="commands">

<programlisting>

<![CDATA[$ sudo systemctl --system daemon-reload

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

</programlisting>

</example>

</refsect2>

</refsect1>

<refsect1>

<title>See Also</title>

<para>

<citerefentry>

<refentrytitle>

systemd.service</refentrytitle>

<manvolnum>5</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>

systemd.socket</refentrytitle>

<manvolnum>5</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>systemctl</refentrytitle>

<manvolnum>1</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>socat</refentrytitle>

<manvolnum>1</manvolnum>

</citerefentry></para>

</refsect1>

</refentry>