man/systemd-socket-activate.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7
   8   This file is part of systemd.
   9
  10   Copyright 2013 Zbigniew Jędrzejewski-Szmek
  11 -->
  12
  13 <refentry id="systemd-socket-activate"
  14           xmlns:xi="http://www.w3.org/2001/XInclude">
  15
  16   <refentryinfo>
  17     <title>systemd-socket-activate</title>
  18     <productname>systemd</productname>
  19
  20     <authorgroup>
  21       <author>
  22         <contrib>Developer</contrib>
  23         <firstname>Zbigniew</firstname>
  24         <surname>Jędrzejewski-Szmek</surname>
  25         <email>zbyszek@in.waw.pl</email>
  26       </author>
  27     </authorgroup>
  28   </refentryinfo>
  29
  30   <refmeta>
  31     <refentrytitle>systemd-socket-activate</refentrytitle>
  32     <manvolnum>1</manvolnum>
  33   </refmeta>
  34
  35   <refnamediv>
  36     <refname>systemd-socket-activate</refname>
  37     <refpurpose>Test socket activation of daemons</refpurpose>
  38   </refnamediv>
  39
  40   <refsynopsisdiv>
  41     <cmdsynopsis>
  42       <command>systemd-socket-activate</command>
  43       <arg choice="opt" rep="repeat">OPTIONS</arg>
  44       <arg choice="plain"><replaceable>daemon</replaceable></arg>
  45       <arg choice="opt" rep="repeat">OPTIONS</arg>
  46     </cmdsynopsis>
  47   </refsynopsisdiv>
  48
  49   <refsect1>
  50     <title>Description</title>
  51
  52     <para><command>systemd-socket-activate</command> may be used to launch a socket-activated service program from the
  53     command line for testing purposes. It may also be used to launch individual instances of the service program per
  54     connection.
  55     </para>
  56
  57     <para>The daemon to launch and its options should be specified
  58     after options intended for <command>systemd-socket-activate</command>.
  59     </para>
  60
  61     <para>If the <option>--inetd</option> option is given, the socket file descriptor will be used as the standard
  62     input and output of the launched process. Otherwise, standard input and output will be inherited, and sockets will
  63     be passed through file descriptors 3 and higher. Sockets passed through <varname>$LISTEN_FDS</varname> to
  64     <command>systemd-socket-activate</command> will be passed through to the daemon, in the original positions. Other sockets
  65     specified with <option>--listen=</option> will use consecutive descriptors.  By default,
  66     <command>systemd-socket-activate</command> listens on a stream socket, use <option>--datagram</option> and
  67     <option>--seqpacket</option> to listen on datagram or sequential packet sockets instead (see below).
  68     </para>
  69   </refsect1>
  70
  71   <refsect1>
  72     <title>Options</title>
  73     <variablelist>
  74       <varlistentry>
  75         <term><option>-l <replaceable>address</replaceable></option></term>
  76         <term><option>--listen=<replaceable>address</replaceable></option></term>
  77
  78         <listitem><para>Listen on this <replaceable>address</replaceable>.
  79         Takes a string like <literal>2000</literal> or
  80         <literal>127.0.0.1:2001</literal>.</para>
  81         </listitem>
  82       </varlistentry>
  83
  84       <varlistentry>
  85         <term><option>-a</option></term>
  86         <term><option>--accept</option></term>
  87
  88         <listitem><para>Launch an instance of the service program for each connection and pass the connection
  89         socket.</para></listitem>
  90       </varlistentry>
  91
  92       <varlistentry>
  93         <term><option>-d</option></term>
  94         <term><option>--datagram</option></term>
  95
  96         <listitem><para>Listen on a datagram socket (<constant>SOCK_DGRAM</constant>), instead of a stream socket
  97         (<constant>SOCK_STREAM</constant>). May not be combined with <option>--seqpacket</option>.</para></listitem>
  98       </varlistentry>
  99
 100       <varlistentry>
 101         <term><option>--seqpacket</option></term>
 102
 103         <listitem><para>Listen on a sequential packet socket (<constant>SOCK_SEQPACKET</constant>), instead of a stream
 104         socket (<constant>SOCK_STREAM</constant>). May not be combined with
 105         <option>--datagram</option>.</para></listitem>
 106       </varlistentry>
 107
 108       <varlistentry>
 109         <term><option>--inetd</option></term>
 110
 111         <listitem><para>Use the inetd protocol for passing file descriptors, i.e. as standard input and standard
 112         output, instead of the new-style protocol for passing file descriptors using <varname>$LISTEN_FDS</varname>
 113         (see above).</para></listitem>
 114       </varlistentry>
 115
 116       <varlistentry>
 117         <term><option>-E <replaceable>VAR</replaceable><optional>=<replaceable>VALUE</replaceable></optional></option></term>
 118         <term><option>--setenv=<replaceable>VAR</replaceable><optional>=<replaceable>VALUE</replaceable></optional></option></term>
 119
 120         <listitem><para>Add this variable to the environment of the
 121         launched process. If <replaceable>VAR</replaceable> is
 122         followed by <literal>=</literal>, assume that it is a
 123         variable–value pair. Otherwise, obtain the value from the
 124         environment of <command>systemd-socket-activate</command> itself.
 125         </para></listitem>
 126       </varlistentry>
 127
 128       <varlistentry>
 129         <term><option>--fdname=</option><replaceable>NAME</replaceable><optional>:<replaceable>NAME</replaceable>…</optional></term>
 130
 131         <listitem><para>Specify names for the file descriptors passed. This is equivalent to setting
 132         <varname>FileDescriptorName=</varname> in socket unit files, and enables use of
 133         <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 134         Multiple entries may be specifies using separate options or by separating names with colons
 135         (<literal>:</literal>) in one option. In case more names are given than descriptors, superfluous ones will be
 136         ignored. In case less names are given than descriptors, the remaining file descriptors will be unnamed.
 137         </para></listitem>
 138       </varlistentry>
 139
 140       <xi:include href="standard-options.xml" xpointer="help" />
 141       <xi:include href="standard-options.xml" xpointer="version" />
 142     </variablelist>
 143   </refsect1>
 144
 145   <refsect1>
 146     <title>Environment variables</title>
 147     <variablelist class='environment-variables'>
 148       <varlistentry>
 149         <term><varname>$LISTEN_FDS</varname></term>
 150         <term><varname>$LISTEN_PID</varname></term>
 151         <term><varname>$LISTEN_FDNAMES</varname></term>
 152
 153         <listitem><para>See
 154         <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
 155       </varlistentry>
 156
 157       <varlistentry>
 158         <term><varname>$SYSTEMD_LOG_TARGET</varname></term>
 159         <term><varname>$SYSTEMD_LOG_LEVEL</varname></term>
 160         <term><varname>$SYSTEMD_LOG_COLOR</varname></term>
 161         <term><varname>$SYSTEMD_LOG_LOCATION</varname></term>
 162
 163         <listitem><para>Same as in
 164         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
 165       </varlistentry>
 166     </variablelist>
 167   </refsect1>
 168
 169   <refsect1>
 170     <title>Examples</title>
 171
 172     <example>
 173       <title>Run an echo server on port 2000</title>
 174
 175       <programlisting>$ systemd-socket-activate -l 2000 --inetd -a cat</programlisting>
 176     </example>
 177
 178     <example>
 179       <title>Run a socket-activated instance of <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry></title>
 180
 181       <programlisting>$ systemd-socket-activate -l 19531 /usr/lib/systemd/systemd-journal-gatewayd</programlisting>
 182     </example>
 183   </refsect1>
 184
 185   <refsect1>
 186     <title>See Also</title>
 187     <para>
 188       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 189       <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 190       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 191       <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 192       <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 193       <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 194       <citerefentry project='man-pages'><refentrytitle>cat</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 195     </para>
 196   </refsect1>
 197 </refentry>