diff options
Diffstat (limited to 'man/systemd-run.xml')
| -rw-r--r-- | man/systemd-run.xml | 93 |
1 files changed, 66 insertions, 27 deletions
diff --git a/man/systemd-run.xml b/man/systemd-run.xml index 5be9823..e1986c1 100644 --- a/man/systemd-run.xml +++ b/man/systemd-run.xml @@ -1,6 +1,6 @@ <?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" @@ -64,8 +64,8 @@ other service, and thus shows up in the output of <command>systemctl list-units</command> like any other unit. It will run in a clean and detached execution environment, with the service manager as its parent process. In this mode, <command>systemd-run</command> will start the service asynchronously in the background and return after the - command has begun execution (unless <option>--no-block</option> or <option>--wait</option> are specified, see - below).</para> + command has begun execution (unless <option>--no-block</option>, <option>--wait</option>, <option>--pipe</option>, + or <option>--pty</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 @@ -176,11 +176,14 @@ <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"/> @@ -322,6 +325,11 @@ to the terminal <command>systemd-run</command> is invoked on, via a pseudo TTY device. This allows running programs that expect interactive user input/output as services, such as interactive command shells.</para> + <para>This option will result in <command>systemd-run</command> synchronously waiting for + the transient service to terminate, similar to specifying <option>--wait</option>. If specified + along with <option>--wait</option>, <command>systemd-run</command> won't exit when manually disconnecting + from the pseudo TTY device.</para> + <para>Note that <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s <command>shell</command> command is usually a better alternative for requesting a new, interactive login @@ -338,21 +346,25 @@ <listitem><para>If specified, standard input, output, and error of the transient service are inherited from the <command>systemd-run</command> command itself. This allows <command>systemd-run</command> - to be used within shell pipelines. - Note that this mode is not suitable for interactive command shells and similar, as the - service process will not become a TTY controller when invoked on a terminal. Use <option>--pty</option> instead - in that case.</para> + to be used within shell pipelines.</para> + + <para>Note that this mode is not suitable for interactive command shells and similar, as the + service process will not become a TTY controller when invoked on a terminal. Use <option>--pty</option> + instead in that case.</para> <para>When both <option>--pipe</option> and <option>--pty</option> are used in combination the more appropriate option is automatically determined and used. Specifically, when invoked with standard input, output and error connected to a TTY <option>--pty</option> is used, and otherwise <option>--pipe</option>.</para> + <para>This option will result in <command>systemd-run</command> synchronously waiting for + the transient service to terminate, similar to specifying <option>--wait</option>.</para> + <para>When this option is used the original file descriptors <command>systemd-run</command> receives are passed 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 + <command>systemd-run</command>, this means the service might not be able to reopen 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 - cause problems, as this only works if stderr can be re-opened. To mitigate this use the construct <command>echo + cause problems, as this only works if stderr can be reopened. To mitigate this use the construct <command>echo "hello" >&2</command> instead, which is mostly equivalent and avoids this pitfall.</para> <xi:include href="version-info.xml" xpointer="v235"/></listitem> @@ -485,10 +497,36 @@ <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" /> <xi:include href="user-system-options.xml" xpointer="machine" /> + <xi:include href="user-system-options.xml" xpointer="capsule" /> <xi:include href="standard-options.xml" xpointer="help" /> <xi:include href="standard-options.xml" xpointer="version" /> @@ -666,19 +704,20 @@ $ systemd-run --user --wait -p SuccessExitStatus=SIGUSR1 --expand-environment=no <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>run0</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> + </simplelist></para> </refsect1> </refentry> |