man/systemd-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   This file is part of systemd.
   7
   8   Copyright 2013 Zbigniew Jędrzejewski-Szmek
   9
  10   systemd is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU Lesser General Public License as published by
  12   the Free Software Foundation; either version 2.1 of the License, or
  13   (at your option) any later version.
  14
  15   systemd is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="systemd-activate"
  25           xmlns:xi="http://www.w3.org/2001/XInclude">
  26
  27   <refentryinfo>
  28     <title>systemd-activate</title>
  29     <productname>systemd</productname>
  30
  31     <authorgroup>
  32       <author>
  33         <contrib>Developer</contrib>
  34         <firstname>Zbigniew</firstname>
  35         <surname>Jędrzejewski-Szmek</surname>
  36         <email>zbyszek@in.waw.pl</email>
  37       </author>
  38     </authorgroup>
  39   </refentryinfo>
  40
  41   <refmeta>
  42     <refentrytitle>systemd-activate</refentrytitle>
  43     <manvolnum>8</manvolnum>
  44   </refmeta>
  45
  46   <refnamediv>
  47     <refname>systemd-activate</refname>
  48     <refpurpose>Test socket activation of daemons</refpurpose>
  49   </refnamediv>
  50
  51   <refsynopsisdiv>
  52     <cmdsynopsis>
  53       <command>/usr/lib/systemd/systemd-activate</command>
  54       <arg choice="opt" rep="repeat">OPTIONS</arg>
  55       <arg choice="plain"><replaceable>daemon</replaceable></arg>
  56       <arg choice="opt" rep="repeat">OPTIONS</arg>
  57     </cmdsynopsis>
  58   </refsynopsisdiv>
  59
  60   <refsect1>
  61     <title>Description</title>
  62
  63     <para><command>systemd-activate</command> can be used to
  64     launch a socket-activated daemon from the command line for
  65     testing purposes. It can also be used to launch single instances
  66     of the daemon per connection (inetd-style).
  67     </para>
  68
  69     <para>The daemon to launch and its options should be specified
  70     after options intended for <command>systemd-activate</command>.
  71     </para>
  72
  73     <para>If the <option>-a</option> option is given, file descriptor
  74     of the connection will be used as the standard input and output of
  75     the launched process. Otherwise, standard input and output will be
  76     inherited, and sockets will be passed through file descriptors 3
  77     and higher. Sockets passed through <varname>$LISTEN_FDS</varname>
  78     to <command>systemd-activate</command> will be passed through to
  79     the daemon, in the original positions. Other sockets specified
  80     with <option>--listen</option> will use consecutive descriptors.
  81     </para>
  82   </refsect1>
  83
  84   <refsect1>
  85     <title>Options</title>
  86     <variablelist>
  87       <varlistentry>
  88         <term><option>-l <replaceable>address</replaceable></option></term>
  89         <term><option>--listen=<replaceable>address</replaceable></option></term>
  90
  91         <listitem><para>Listen on this <replaceable>address</replaceable>.
  92         Takes a string like <literal>2000</literal> or
  93         <literal>127.0.0.1:2001</literal>.</para>
  94         </listitem>
  95       </varlistentry>
  96
  97       <varlistentry>
  98         <term><option>-a</option></term>
  99         <term><option>--accept</option></term>
 100
 101         <listitem><para>Launch a separate instance of daemon per
 102         connection and pass the connection socket as standard input
 103         and standard output.</para></listitem>
 104       </varlistentry>
 105
 106       <varlistentry>
 107         <term><option>-E <replaceable>VAR</replaceable><optional>=<replaceable>VALUE</replaceable></optional></option></term>
 108         <term><option>--setenv=<replaceable>VAR</replaceable><optional>=<replaceable>VALUE</replaceable></optional></option></term>
 109
 110         <listitem><para>Add this variable to the environment of the
 111         launched process. If <replaceable>VAR</replaceable> is
 112         followed by <literal>=</literal>, assume that it is a
 113         variable–value pair. Otherwise, obtain the value from the
 114         environment of <command>systemd-activate</command> itself.
 115         </para></listitem>
 116       </varlistentry>
 117
 118       <varlistentry>
 119         <term><option>--fdname=</option><replaceable>NAME</replaceable></term>
 120
 121         <listitem><para>Specify a name for the activation file
 122         descriptors. This is equivalent to setting
 123         <varname>FileDescriptorName=</varname> in socket unit files, and
 124         enables use of
 125         <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
 126       </varlistentry>
 127
 128       <xi:include href="standard-options.xml" xpointer="help" />
 129       <xi:include href="standard-options.xml" xpointer="version" />
 130     </variablelist>
 131   </refsect1>
 132
 133   <refsect1>
 134     <title>Environment variables</title>
 135     <variablelist class='environment-variables'>
 136       <varlistentry>
 137         <term><varname>$LISTEN_FDS</varname></term>
 138         <term><varname>$LISTEN_PID</varname></term>
 139         <term><varname>$LISTEN_FDNAMES</varname></term>
 140
 141         <listitem><para>See
 142         <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
 143       </varlistentry>
 144
 145       <varlistentry>
 146         <term><varname>$SYSTEMD_LOG_TARGET</varname></term>
 147         <term><varname>$SYSTEMD_LOG_LEVEL</varname></term>
 148         <term><varname>$SYSTEMD_LOG_COLOR</varname></term>
 149         <term><varname>$SYSTEMD_LOG_LOCATION</varname></term>
 150
 151         <listitem><para>Same as in
 152         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
 153       </varlistentry>
 154     </variablelist>
 155   </refsect1>
 156
 157   <refsect1>
 158     <title>Examples</title>
 159
 160     <example>
 161       <title>Run an echo server on port 2000</title>
 162
 163       <programlisting>$ /usr/lib/systemd/systemd-activate -l 2000 -a cat</programlisting>
 164     </example>
 165
 166     <example>
 167       <title>Run a socket-activated instance of <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry></title>
 168
 169       <programlisting>$ /usr/lib/systemd/systemd-activate -l 19531 /usr/lib/systemd/systemd-journal-gatewayd</programlisting>
 170     </example>
 171   </refsect1>
 172
 173   <refsect1>
 174     <title>See Also</title>
 175     <para>
 176       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 177       <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 178       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 179       <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 180       <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 181       <citerefentry project='man-pages'><refentrytitle>cat</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 182     </para>
 183   </refsect1>
 184 </refentry>