<?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>-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>
<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"/>
<varname>RemainAfterExit=</varname> in
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
+
+ <xi:include href="version-info.xml" xpointer="v207"/>
</listitem>
</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="v250"/>
+ <xi:include href="version-info.xml" xpointer="v211"/>
</listitem>
</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>
<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="user-system-options.xml" xpointer="system" />
<xi:include href="user-system-options.xml" xpointer="host" />
<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