<?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"
<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>
<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>-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>
+ 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>
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
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>
<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" />
<example>
<title>Allowing access to the tty</title>
- <para>The following command invokes <citerefentry project='man-pages'><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>
<para>The first argument is expanded by the shell (double quotes), but the second one is not expanded
- by the shell (single quotes). <command>echo</command> is called with [<literal>/usr/bin/echo</literal>,
- <literal>[]</literal>, <literal>[${INVOCATION_ID}]</literal>] as the argument array, and then
- <command>systemd</command> 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>
+ 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 <command>systemd</command> can be disabled with
- <varname>--expand-environment=no</varname>.</para>
+ <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>
/bin/bash 12345
</programlisting>
- <para>The last argument is passed verbatim to the <command>bash</command> 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
+ <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>
<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