picnoir/Systemd
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

man: document the new --wait switch of systemd-run

Browse source 
Also, make major improvements to the an page in general.
This commit is contained in:
Lennart Poettering 2016-08-18 21:53:38 +02:00
parent 2a453c2ee3
commit 014c4c98ba
1 changed files with 68 additions and 91 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

159
man/systemd-run.xml
View file

@ -68,42 +68,30 @@
<refsect1> <refsect1>
<title>Description</title> <title>Description</title>
<para><command>systemd-run</command> may be used to create and <para><command>systemd-run</command> may be used to create and start a transient <filename>.service</filename> or
start a transient <filename>.service</filename> or <filename>.scope</filename> unit and run the specified <replaceable>COMMAND</replaceable> in it. It may also be
<filename>.scope</filename> unit and run the specified used to create and start a transient <filename>.timer</filename> unit, that activates a
<replaceable>COMMAND</replaceable> in it. It may also be used to <filename>.service</filename> unit when elapsing.</para>
create and start transient <filename>.timer</filename>
units.</para>
<para>If a command is run as transient service unit, it will be <para>If a command is run as transient service unit, it will be started and managed by the service manager like any
started and managed by the service manager like any other service, other service, and thus shows up in the output of <command>systemctl list-units</command> like any other unit. It
and thus shows up in the output of <command>systemctl will run in a clean and detached execution environment, with the service manager as its parent process. In this
list-units</command> like any other unit. It will run in a clean mode, <command>systemd-run</command> will start the service asynchronously in the background and return after the
and detached execution environment, with the service manager as command has begun execution (unless <option>--no-block</option> or <option>--watch</option> are specified, see
its parent process. In this mode, <command>systemd-run</command> below).</para>
will start the service asynchronously in the background and return
after the command has begun execution.</para>
<para>If a command is run as transient scope unit, it will be <para>If a command is run as transient scope unit, it will be executed by <command>systemd-run</command> itself as
started by <command>systemd-run</command> itself as parent process parent process and will thus inherit the execution environment of the caller. However, the processes of the command
and will thus inherit the execution environment of the are managed by the service manager similar to normal services, and will show up in the output of <command>systemctl
caller. However, the processes of the command are managed by the list-units</command>. Execution in this case is synchronous, and will return only when the command finishes. This
service manager similar to normal services, and will show up in mode is enabled via the <option>--scope</option> switch (see below). </para>
the output of <command>systemctl list-units</command>. Execution
in this case is synchronous, and will return only when the command
finishes. This mode is enabled via the <option>--scope</option>
switch (see below). </para>
<para>If a command is run with timer options such as <para>If a command is run with timer options such as <option>--on-calendar=</option> (see below), a transient timer
<option>--on-calendar=</option> (see below), a transient timer unit is created alongside the service unit for the specified command. Only the transient timer unit is started
unit is created alongside the service unit for the specified immediately, the transient service unit will be started when the timer elapses. If the <option>--unit=</option>
command. Only the transient timer unit is started immediately, the option is specified, the <replaceable>COMMAND</replaceable> may be omitted. In this case,
transient service unit will be started when the transient timer <command>systemd-run</command> creates only a <filename>.timer</filename> unit that invokes the specified unit when
elapses. If the <option>--unit=</option> is specified, the elapsing.</para>
<replaceable>COMMAND</replaceable> may be omitted. In this case,
<command>systemd-run</command> only creates a
<filename>.timer</filename> unit that invokes the specified unit
when elapsing.</para>
</refsect1> </refsect1>
<refsect1> <refsect1>
@ -123,8 +111,8 @@
<term><option>--scope</option></term> <term><option>--scope</option></term>
<listitem> <listitem>
<para>Create a transient <filename>.scope</filename> unit instead of <para>Create a transient <filename>.scope</filename> unit instead of the default transient
the default transient <filename>.service</filename> unit. <filename>.service</filename> unit (see above).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -140,9 +128,8 @@
<term><option>--property=</option></term> <term><option>--property=</option></term>
<term><option>-p</option></term> <term><option>-p</option></term>
<listitem><para>Sets a unit property for the scope or service <listitem><para>Sets a property on the scope or service unit that is created. This option takes an assignment
unit that is created. This takes an assignment in the same in the same format as
format as
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
<command>set-property</command> command.</para> <command>set-property</command> command.</para>
</listitem> </listitem>
@ -151,9 +138,8 @@
<varlistentry> <varlistentry>
<term><option>--description=</option></term> <term><option>--description=</option></term>
<listitem><para>Provide a description for the service or scope <listitem><para>Provide a description for the service, scope or timer unit. If not specified, the command
unit. If not specified, the command itself will be used as a itself will be used as a description. See <varname>Description=</varname> in
description. See <varname>Description=</varname> in
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para></listitem> </para></listitem>
</varlistentry> </varlistentry>
@ -161,19 +147,16 @@
<varlistentry> <varlistentry>
<term><option>--slice=</option></term> <term><option>--slice=</option></term>
<listitem><para>Make the new <filename>.service</filename> or <listitem><para>Make the new <filename>.service</filename> or <filename>.scope</filename> unit part of the
<filename>.scope</filename> unit part of the specified slice, specified slice, instead of <filename>system.slice</filename>.</para>
instead of the <filename>system.slice</filename>.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><option>--remain-after-exit</option></term> <term><option>--remain-after-exit</option></term>
<listitem><para>After the service or scope process has <listitem><para>After the service process has terminated, keep the service around until it is explicitly
terminated, keep the service around until it is explicitly stopped. This is useful to collect runtime information about the service after it finished running. Also see
stopped. This is useful to collect runtime information about
the service after it finished running. Also see
<varname>RemainAfterExit=</varname> in <varname>RemainAfterExit=</varname> in
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>. <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para> </para>
@ -183,10 +166,8 @@
<varlistentry> <varlistentry>
<term><option>--send-sighup</option></term> <term><option>--send-sighup</option></term>
<listitem><para>When terminating the scope or service unit, <listitem><para>When terminating the scope or service unit, send a SIGHUP immediately after SIGTERM. This is
send a SIGHUP immediately after SIGTERM. This is useful to useful to indicate to shells and shell-like processes that the connection has been severed. Also see
indicate to shells and shell-like processes that the
connection has been severed. Also see
<varname>SendSIGHUP=</varname> in <varname>SendSIGHUP=</varname> in
<citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para> </para>
@ -209,9 +190,8 @@
<term><option>--uid=</option></term> <term><option>--uid=</option></term>
<term><option>--gid=</option></term> <term><option>--gid=</option></term>
<listitem><para>Runs the service process under the UNIX user <listitem><para>Runs the service process under the specified UNIX user and group. Also see
and group. Also see <varname>User=</varname> and <varname>User=</varname> and <varname>Group=</varname> in
<varname>Group=</varname> in
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -239,11 +219,9 @@
<term><option>--pty</option></term> <term><option>--pty</option></term>
<term><option>-t</option></term> <term><option>-t</option></term>
<listitem><para>When invoking a command, the service connects <listitem><para>When invoking the command, the transient service connects its standard input and output to the
its standard input and output to the invoking tty via a terminal <command>systemd-run</command> is invoked on, via a pseudo TTY device. This allows running binaries
pseudo TTY device. This allows invoking binaries as services that expect interactive user input as services, such as interactive command shells.</para></listitem>
that expect interactive user input, such as interactive
command shells.</para></listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
@ -263,44 +241,32 @@
<term><option>--on-unit-active=</option></term> <term><option>--on-unit-active=</option></term>
<term><option>--on-unit-inactive=</option></term> <term><option>--on-unit-inactive=</option></term>
<listitem><para>Defines monotonic timers relative to different <listitem><para>Defines a monotonic timer relative to different starting points for starting the specified
starting points. Also see <varname>OnActiveSec=</varname>, command. See <varname>OnActiveSec=</varname>, <varname>OnBootSec=</varname>, <varname>OnStartupSec=</varname>,
<varname>OnBootSec=</varname>, <varname>OnUnitActiveSec=</varname> and <varname>OnUnitInactiveSec=</varname> in
<varname>OnStartupSec=</varname>, <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
<varname>OnUnitActiveSec=</varname> and details. These options may not be combined with <option>--scope</option>.</para>
<varname>OnUnitInactiveSec=</varname> in
<citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This
options have no effect in conjunction with
<option>--scope</option>.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><option>--on-calendar=</option></term> <term><option>--on-calendar=</option></term>
<listitem><para>Defines realtime (i.e. wallclock) timers with <listitem><para>Defines a calendar timer for starting the specified command. See <varname>OnCalendar=</varname>
calendar event expressions. Also see in <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This
<varname>OnCalendar=</varname> in option may not be combined with <option>--scope</option>.</para>
<citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This
option has no effect in conjunction with
<option>--scope</option>.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><option>--timer-property=</option></term> <term><option>--timer-property=</option></term>
<listitem><para>Sets a timer unit property for the timer unit <listitem><para>Sets a property on the timer unit that is created. This option is similar to
that is created. It is similar with <option>--property=</option> but applies to the transient timer unit rather than the transient service unit
<option>--property</option> but only for created timer created. This option only has an effect in conjunction with <option>--on-active=</option>,
unit. This option only has effect in conjunction with <option>--on-boot=</option>, <option>--on-startup=</option>, <option>--on-unit-active=</option>,
<option>--on-active=</option>, <option>--on-boot=</option>, <option>--on-unit-inactive=</option> or <option>--on-calendar=</option>. This option takes an assignment in the
<option>--on-startup=</option>, same format as <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
<option>--on-unit-active=</option>,
<option>--on-unit-inactive=</option>,
<option>--on-calendar=</option>. This takes an assignment in
the same format as
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
<command>set-property</command> command.</para> </listitem> <command>set-property</command> command.</para> </listitem>
</varlistentry> </varlistentry>
@ -308,14 +274,25 @@
<term><option>--no-block</option></term> <term><option>--no-block</option></term>
<listitem> <listitem>
<para>Do not synchronously wait for the requested operation <para>Do not synchronously wait for the unit start operation to finish. If this option is not specified, the
to finish. If this is not specified, the job will be start request for the transient unit will be verified, enqueued and <command>systemd-run</command> will wait
verified, enqueued and <command>systemd-run</command> will until the unit's start-up is completed. By passing this argument, it is only verified and enqueued. This
wait until the unit's start-up is completed. By passing this option may not be combined with <option>--wait</option>.</para>
argument, it is only verified and enqueued.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry>
<term><option>--wait</option></term>
<listitem><para>Synchronously wait for the transient service to terminate. If this option is specified, the
start request for the transient unit is verified, enqueued, and waited for. Subsequently the invoked unit is
monitored, and it is waited until it is deactivated again (most likely because the specified command
completed). On exit, terse information about the unit's runtime is shown, including total runtime (as well as
CPU usage, if <option>--property=CPUAccounting=1</option> was set) and the exit code and status of the main
process. This output may be suppressed with <option>--quiet</option>. This option may not be combined with
<option>--no-block</option>, <option>--scope</option> or the various timer options.</para></listitem>
</varlistentry>
<xi:include href="user-system-options.xml" xpointer="user" /> <xi:include href="user-system-options.xml" xpointer="user" />
<xi:include href="user-system-options.xml" xpointer="system" /> <xi:include href="user-system-options.xml" xpointer="system" />
<xi:include href="user-system-options.xml" xpointer="host" /> <xi:include href="user-system-options.xml" xpointer="host" />