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 specifed
  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 dameon, 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       <xi:include href="standard-options.xml" xpointer="help" />
 119       <xi:include href="standard-options.xml" xpointer="version" />
 120     </variablelist>
 121   </refsect1>
 122
 123   <refsect1>
 124     <title>Environment variables</title>
 125     <variablelist class='environment-variables'>
 126       <varlistentry>
 127         <term><varname>$LISTEN_FDS</varname></term>
 128         <term><varname>$LISTEN_PID</varname></term>
 129
 130         <listitem><para>See
 131         <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
 132       </varlistentry>
 133
 134       <varlistentry>
 135         <term><varname>$SYSTEMD_LOG_TARGET</varname></term>
 136         <term><varname>$SYSTEMD_LOG_LEVEL</varname></term>
 137         <term><varname>$SYSTEMD_LOG_COLOR</varname></term>
 138         <term><varname>$SYSTEMD_LOG_LOCATION</varname></term>
 139
 140         <listitem><para>Same as in
 141         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
 142       </varlistentry>
 143     </variablelist>
 144   </refsect1>
 145
 146   <refsect1>
 147     <title>Examples</title>
 148
 149     <example>
 150       <title>Run an echo server on port 2000</title>
 151
 152       <programlisting>$ /usr/lib/systemd/systemd-activate -l 2000 -a cat</programlisting>
 153     </example>
 154
 155     <example>
 156       <title>Run a socket activated instance of <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry></title>
 157
 158       <programlisting>$ /usr/lib/systemd/systemd-activate -l 19531 /usr/lib/systemd/systemd-journal-gatewayd</programlisting>
 159     </example>
 160   </refsect1>
 161
 162   <refsect1>
 163     <title>See Also</title>
 164     <para>
 165       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 166       <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 167       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 168       <citerefentry><refentrytitle>cat</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 169     </para>
 170   </refsect1>
 171 </refentry>