<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
<refentry id="systemd-run"
command has begun execution (unless <option>--no-block</option> or <option>--wait</option> are specified, see
below).</para>
- <para>If a command is run as transient scope unit, it will be executed by <command>systemd-run</command> itself as
- parent process and will thus inherit the execution environment of the caller. However, the processes of the command
- are managed by the service manager similar to normal services, and will show up in 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 as transient scope unit, it will be executed by <command>systemd-run</command>
+ itself as parent process and will thus inherit the execution environment of the caller. However, the
+ processes of the command are managed by the service manager similarly to normal services, and will show
+ up in 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 path, socket, or timer options such as <option>--on-calendar=</option> (see below),
a transient path, socket, or timer unit is created alongside the service unit for the specified command. Only the
<filename>.path</filename>, <filename>.socket</filename>, or <filename>.timer</filename> unit that triggers the
specified unit.</para>
- <para>By default, services created with <command>systemd-run</command> default to the <option>simple</option> type,
- see the description of <varname>Type=</varname> in
+ <para>By default, services created with <command>systemd-run</command> default to the
+ <option>simple</option> type, see the description of <varname>Type=</varname> in
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
- details. Note that when this type is used the service manager (and thus the <command>systemd-run</command> command)
- considers service start-up successful as soon as the <function>fork()</function> for the main service process
- succeeded, i.e. before the <function>execve()</function> is invoked, and thus even if the specified command cannot
- be started. Consider using the <option>exec</option> service type (i.e. <option>--property=Type=exec</option>) to
- ensure that <command>systemd-run</command> returns successfully only if the specified command line has been
- successfully started.</para>
+ details. Note that when this type is used, the service manager (and thus the
+ <command>systemd-run</command> command) considers service start-up successful as soon as the
+ <function>fork()</function> for the main service process succeeded, i.e. before the
+ <function>execve()</function> is invoked, and thus even if the specified command cannot be started.
+ Consider using the <option>exec</option> service type (i.e. <option>--property=Type=exec</option>) to
+ ensure that <command>systemd-run</command> returns successfully only if the specified command line has
+ been successfully started.</para>
+
+ <para>After <command>systemd-run</command> passes the command to the service manager, the manager
+ performs variable expansion. This means that dollar characters (<literal>$</literal>) which should not be
+ expanded need to be escaped as <literal>$$</literal>. Expansion can also be disabled using
+ <varname>--expand-environment=no</varname>.</para>
</refsect1>
<refsect1>
<term><option>--no-ask-password</option></term>
<listitem><para>Do not query the user for authentication for
- privileged operations.</para></listitem>
+ privileged operations.</para>
+
+ <xi:include href="version-info.xml" xpointer="v226"/></listitem>
</varlistentry>
<varlistentry>
<para>Create a transient <filename>.scope</filename> unit instead of the default transient
<filename>.service</filename> unit (see above).
</para>
+
+ <xi:include href="version-info.xml" xpointer="v206"/>
</listitem>
</varlistentry>
<term><option>-u</option></term>
<listitem><para>Use this unit name instead of an automatically
- generated one.</para></listitem>
+ generated one.</para>
+
+ <xi:include href="version-info.xml" xpointer="v206"/></listitem>
</varlistentry>
<varlistentry>
in the same format as
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
<command>set-property</command> command.</para>
+
+ <xi:include href="version-info.xml" xpointer="v211"/>
</listitem>
</varlistentry>
<listitem><para>Provide a description for the service, scope, path, socket, or timer unit. If not specified,
the command itself will be used as a description. See <varname>Description=</varname> in
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
- </para></listitem>
+ </para>
+
+ <xi:include href="version-info.xml" xpointer="v206"/></listitem>
</varlistentry>
<varlistentry>
of the specified slice, instead of <filename>system.slice</filename> (when running in
<option>--system</option> mode) or the root slice (when running in <option>--user</option>
mode).</para>
+
+ <xi:include href="version-info.xml" xpointer="v206"/>
</listitem>
</varlistentry>
<term><option>--slice-inherit</option></term>
<listitem><para>Make the new <filename>.service</filename> or <filename>.scope</filename> unit part
- of the inherited slice. This option can be combined with <option>--slice=</option>.</para>
-
- <para>An inherited slice is located within <command>systemd-run</command> slice. Example: if
- <command>systemd-run</command> slice is <filename>foo.slice</filename>, and the
- <option>--slice=</option> argument is <filename>bar</filename>, the unit will be placed under the
+ of the slice the <command>systemd-run</command> itself has been invoked in. This option may be
+ combined with <option>--slice=</option>, in which case the slice specified via
+ <option>--slice=</option> is placed within the slice the <command>systemd-run</command> command is
+ invoked in.</para>
+
+ <para>Example: consider <command>systemd-run</command> being invoked in the slice
+ <filename>foo.slice</filename>, and the <option>--slice=</option> argument is
+ <filename>bar</filename>. The unit will then be placed under
<filename>foo-bar.slice</filename>.</para>
+ <xi:include href="version-info.xml" xpointer="v246"/>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--expand-environment=<replaceable>BOOL</replaceable></option></term>
+
+ <listitem><para>Expand environment variables in command arguments. If enabled, environment variables
+ specified as <literal>${<replaceable>VARIABLE</replaceable>}</literal> will be expanded in the same
+ way as in commands specified via <varname>ExecStart=</varname> in units. With
+ <varname>--scope</varname>, this expansion is performed by <command>systemd-run</command> itself, and
+ in other cases by the service manager that spawns the command. Note that this is similar to, but not
+ the same as variable expansion in
+ <citerefentry project='man-pages'><refentrytitle>bash</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ and other shells.</para>
+
+ <para>The default is to enable this option in all cases, except for <varname>--scope</varname> where
+ it is disabled by default, for backward compatibility reasons. Note that this will be changed in a
+ future release, where it will be switched to enabled by default as well.</para>
+
+ <para>See
+ <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for a description of variable expansion. Disabling variable expansion is useful if the specified
+ command includes or may include a <literal>$</literal> sign.</para>
+
+ <xi:include href="version-info.xml" xpointer="v254"/>
</listitem>
</varlistentry>
<varname>RemainAfterExit=</varname> in
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
+
+ <xi:include href="version-info.xml" xpointer="v207"/>
</listitem>
</varlistentry>
<varname>SendSIGHUP=</varname> in
<citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
+
+ <xi:include href="version-info.xml" xpointer="v207"/>
</listitem>
</varlistentry>
option has no effect in conjunction with
<option>--scope</option>. Defaults to
<constant>simple</constant>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v211"/>
</listitem>
</varlistentry>
<listitem><para>Runs the service process under the specified UNIX user and group. Also see
<varname>User=</varname> and <varname>Group=</varname> in
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v211"/>
</listitem>
</varlistentry>
<listitem><para>Runs the service process with the specified
nice level. Also see <varname>Nice=</varname> in
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v211"/>
</listitem>
</varlistentry>
<listitem><para>Runs the service process with the specified working directory. Also see
<varname>WorkingDirectory=</varname> in
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v240"/>
</listitem>
</varlistentry>
<term><option>--same-dir</option></term>
<term><option>-d</option></term>
- <listitem><para>Similar to <option>--working-directory=</option> but uses the current working directory of the
- caller for the service to execute.</para></listitem>
+ <listitem><para>Similar to <option>--working-directory=</option>, but uses the current working
+ directory of the caller for the service to execute.</para>
+
+ <xi:include href="version-info.xml" xpointer="v240"/></listitem>
</varlistentry>
<varlistentry>
<para>Also see <varname>Environment=</varname> in
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v211"/>
</listitem>
</varlistentry>
<command>shell</command> command is usually a better alternative for requesting a new, interactive login
session on the local host or a local container.</para>
- <para>See below for details on how this switch combines with <option>--pipe</option>.</para></listitem>
+ <para>See below for details on how this switch combines with <option>--pipe</option>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v219"/></listitem>
</varlistentry>
<varlistentry>
to the service processes as-is. If the service runs with different privileges than
<command>systemd-run</command>, this means the service might not be able to re-open the passed file
descriptors, due to normal file descriptor access restrictions. If the invoked process is a shell script that
- uses the <command>echo "hello" > /dev/stderr</command> construct for writing messages to stderr, this might
+ uses the <command>echo "hello" >/dev/stderr</command> construct for writing messages to stderr, this might
cause problems, as this only works if stderr can be re-opened. To mitigate this use the construct <command>echo
- "hello" >&2</command> instead, which is mostly equivalent and avoids this pitfall.</para></listitem>
+ "hello" >&2</command> instead, which is mostly equivalent and avoids this pitfall.</para>
+
+ <xi:include href="version-info.xml" xpointer="v235"/></listitem>
</varlistentry>
<varlistentry>
<listitem><para>A shortcut for <literal>--pty --same-dir --wait --collect --service-type=exec $SHELL</literal>,
i.e. requests an interactive shell in the current working directory, running in service context, accessible
- with a single switch.</para></listitem>
+ with a single switch.</para>
+
+ <xi:include href="version-info.xml" xpointer="v240"/></listitem>
</varlistentry>
<varlistentry>
<listitem><para>Suppresses additional informational output
while running. This is particularly useful in combination with
<option>--pty</option> when it will suppress the initial
- message explaining how to terminate the TTY connection.</para></listitem>
+ message explaining how to terminate the TTY connection.</para>
+
+ <xi:include href="version-info.xml" xpointer="v219"/></listitem>
</varlistentry>
<varlistentry>
<citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
details. These options are shortcuts for <command>--timer-property=</command> with the relevant properties.
These options may not be combined with <option>--scope</option> or <option>--pty</option>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v218"/>
</listitem>
</varlistentry>
in <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This
option is a shortcut for <command>--timer-property=OnCalendar=</command>. This option may not be combined with
<option>--scope</option> or <option>--pty</option>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v218"/>
</listitem>
</varlistentry>
<citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. These
options are shortcuts for <command>--timer-property=OnClockChange=yes</command> and
<command>--timer-property=OnTimezoneChange=yes</command>. These options may not be combined with
- <option>--scope</option> or <option>--pty</option>.</para></listitem>
+ <option>--scope</option> or <option>--pty</option>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v242"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--socket-property=</option></term>
<term><option>--timer-property=</option></term>
- <listitem><para>Sets a property on the path, socket, or timer unit that is created. This option is similar to
- <option>--property=</option> but applies to the transient path, socket, or timer unit rather than the
- transient service unit created. This option takes an assignment in the same format as
+ <listitem><para>Sets a property on the path, socket, or timer unit that is created. This option is
+ similar to <option>--property=</option>, but applies to the transient path, socket, or timer unit
+ rather than the transient service unit created. This option takes an assignment in the same format as
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
<command>set-property</command> command. These options may not be combined with
<option>--scope</option> or <option>--pty</option>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v218"/>
</listitem>
</varlistentry>
start request for the transient unit will be verified, enqueued and <command>systemd-run</command> will wait
until the unit's start-up is completed. By passing this argument, it is only verified and enqueued. This
option may not be combined with <option>--wait</option>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v220"/>
</listitem>
</varlistentry>
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 path, socket, or timer options.</para></listitem>
+ <option>--no-block</option>, <option>--scope</option> or the various path, socket, or timer options.</para>
+
+ <xi:include href="version-info.xml" xpointer="v232"/></listitem>
</varlistentry>
<varlistentry>
<command>--property=CollectMode=inactive-or-failed</command>, see the explanation for
<varname>CollectMode=</varname> in
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for further
- information.</para></listitem>
+ information.</para>
+
+ <xi:include href="version-info.xml" xpointer="v236"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--ignore-failure</option></term>
+
+ <listitem><para>By default, if the specified command fails the invoked unit will be marked failed
+ (though possibly still unloaded, see <option>--collect=</option>, above), and this is reported in the
+ logs. If this switch is specified this is suppressed and any non-success exit status/code of the
+ command is treated as success.</para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--background=<replaceable>COLOR</replaceable></option></term>
+
+ <listitem><para>Change the terminal background color to the specified ANSI color as long as the
+ session lasts. The color specified should be an ANSI X3.64 SGR background color, i.e. strings such as
+ <literal>40</literal>, <literal>41</literal>, …, <literal>47</literal>, <literal>48;2;…</literal>,
+ <literal>48;5;…</literal>. See <ulink
+ url="https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters">ANSI
+ Escape Code (Wikipedia)</ulink> for details.</para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/>
+ </listitem>
</varlistentry>
<xi:include href="user-system-options.xml" xpointer="user" />
<xi:include href="standard-options.xml" xpointer="version" />
</variablelist>
- <para>All command line arguments after the first non-option
- argument become part of the command line of the launched
- process. If a command is run as service unit, the first argument
- needs to be an absolute program path.</para>
+ <para>All command line arguments after the first non-option argument become part of the command line of
+ the launched process.</para>
</refsect1>
<refsect1>
<example>
<title>Limiting resources available to a command</title>
- <programlisting># systemd-run -p BlockIOWeight=10 updatedb</programlisting>
+ <programlisting># systemd-run -p IOWeight=10 updatedb</programlisting>
- <para>This command invokes the
- <citerefentry project='man-pages'><refentrytitle>updatedb</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ <para>This command invokes the <citerefentry
+ project='man-pages'><refentrytitle>updatedb</refentrytitle><manvolnum>8</manvolnum></citerefentry>
tool, but lowers the block I/O weight for it to 10. See
<citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for more information on the <varname>BlockIOWeight=</varname>
- property.</para>
+ for more information on the <varname>IOWeight=</varname> property.</para>
</example>
<example>
<example>
<title>Allowing access to the tty</title>
- <para>The following command invokes <citerefentry project='die-net'><refentrytitle>bash</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ <para>The following command invokes
+ <citerefentry project='man-pages'><refentrytitle>bash</refentrytitle><manvolnum>1</manvolnum></citerefentry>
as a service passing its standard input, output and error to the calling TTY.</para>
<programlisting># systemd-run -t --send-sighup bash</programlisting>
<programlisting>$ loginctl enable-linger</programlisting>
</example>
+ <example>
+ <title>Variable expansion by the manager</title>
+
+ <programlisting>$ systemd-run -t echo "<${INVOCATION_ID}>" '<${INVOCATION_ID}>'
+ <> <5d0149bfa2c34b79bccb13074001eb20>
+ </programlisting>
+
+ <para>The first argument is expanded by the shell (double quotes), but the second one is not expanded
+ by the shell (single quotes).
+ <citerefentry project='man-pages'><refentrytitle>echo</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ is called with [<literal>/usr/bin/echo</literal>,
+ <literal><></literal>, <literal><${INVOCATION_ID}></literal>] as the argument array, and then
+ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ generates <varname>${INVOCATION_ID}</varname> and substitutes it in the command-line. This substitution
+ could not be done on the client side, because the target ID that will be set for the service isn't
+ known before the call is made.</para>
+ </example>
+
+ <example>
+ <title>Variable expansion and output redirection using a shell</title>
+
+ <para>Variable expansion by
+ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ can be disabled with <varname>--expand-environment=no</varname>.</para>
+
+ <para>Disabling variable expansion can be useful if the command to execute contains dollar characters
+ and escaping them would be inconvenient. For example, when a shell is used:</para>
+
+ <programlisting>$ systemd-run --expand-environment=no -t bash \
+ -c 'echo $SHELL $$ >/dev/stdout'
+/bin/bash 12345
+ </programlisting>
+
+ <para>The last argument is passed verbatim to the
+ <citerefentry project='man-pages'><refentrytitle>bash</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ shell which is started by the service unit. The shell expands <literal>$SHELL</literal> to the path of
+ the shell, and <literal>$$</literal> to its process number, and then those strings are passed to the
+ <command>echo</command> built-in and printed to standard output (which in this case is connected to the
+ calling terminal).</para>
+ </example>
+
<example>
<title>Return value</title>
<programlisting>$ systemd-run --user --wait true
$ systemd-run --user --wait -p SuccessExitStatus=11 bash -c 'exit 11'
-$ systemd-run --user --wait -p SuccessExitStatus=SIGUSR1 bash -c 'kill -SIGUSR1 $$$$'</programlisting>
+$ systemd-run --user --wait -p SuccessExitStatus=SIGUSR1 --expand-environment=no \
+ bash -c 'kill -SIGUSR1 $$'</programlisting>
<para>Those three invocations will succeed, i.e. terminate with an exit code of 0.</para>
</example>
<refsect1>
<title>See Also</title>
- <para>
- <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd-mount</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- </para>
+ <para><simplelist type="inline">
+ <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd-mount</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>uid0</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ </simplelist></para>
</refsect1>
</refentry>
projects / thirdparty / systemd.git / blobdiff