chiark / gitweb /
update TODO
[elogind.git] / 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>