man/systemd-run.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="systemd-run"
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>systemd-run</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>systemd-run</refentrytitle>
  16     <manvolnum>1</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>systemd-run</refname>
  21     <refpurpose>Run programs in transient scope units, service units, or path-, socket-, or timer-triggered service units</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <cmdsynopsis>
  26       <command>systemd-run</command>
  27       <arg choice="opt" rep="repeat">OPTIONS</arg>
  28       <arg choice="plain"><replaceable>COMMAND</replaceable>
  29       <arg choice="opt" rep="repeat">ARGS</arg>
  30       </arg>
  31     </cmdsynopsis>
  32     <cmdsynopsis>
  33       <command>systemd-run</command>
  34       <arg choice="opt" rep="repeat">OPTIONS</arg>
  35       <arg choice="opt" rep="repeat">PATH OPTIONS</arg>
  36       <arg choice="req"><replaceable>COMMAND</replaceable></arg>
  37       <arg choice="opt" rep="repeat">ARGS</arg>
  38     </cmdsynopsis>
  39     <cmdsynopsis>
  40       <command>systemd-run</command>
  41       <arg choice="opt" rep="repeat">OPTIONS</arg>
  42       <arg choice="opt" rep="repeat">SOCKET OPTIONS</arg>
  43       <arg choice="req"><replaceable>COMMAND</replaceable></arg>
  44       <arg choice="opt" rep="repeat">ARGS</arg>
  45     </cmdsynopsis>
  46     <cmdsynopsis>
  47       <command>systemd-run</command>
  48       <arg choice="opt" rep="repeat">OPTIONS</arg>
  49       <arg choice="opt" rep="repeat">TIMER OPTIONS</arg>
  50       <arg choice="req"><replaceable>COMMAND</replaceable></arg>
  51       <arg choice="opt" rep="repeat">ARGS</arg>
  52     </cmdsynopsis>
  53   </refsynopsisdiv>
  54
  55   <refsect1>
  56     <title>Description</title>
  57
  58     <para><command>systemd-run</command> may be used to create and start a transient <filename>.service</filename> or
  59     <filename>.scope</filename> unit and run the specified <replaceable>COMMAND</replaceable> in it. It may also be
  60     used to create and start a transient <filename>.path</filename>, <filename>.socket</filename>, or
  61     <filename>.timer</filename> unit, that activates a <filename>.service</filename> unit when elapsing.</para>
  62
  63     <para>If a command is run as transient service unit, it will be started and managed by the service manager like any
  64     other service, and thus shows up in the output of <command>systemctl list-units</command> like any other unit. It
  65     will run in a clean and detached execution environment, with the service manager as its parent process. In this
  66     mode, <command>systemd-run</command> will start the service asynchronously in the background and return after the
  67     command has begun execution (unless <option>--no-block</option> or <option>--wait</option> are specified, see
  68     below).</para>
  69
  70     <para>If a command is run as transient scope unit, it will be executed by <command>systemd-run</command>
  71     itself as parent process and will thus inherit the execution environment of the caller. However, the
  72     processes of the command are managed by the service manager similarly to normal services, and will show
  73     up in the output of <command>systemctl list-units</command>. Execution in this case is synchronous, and
  74     will return only when the command finishes. This mode is enabled via the <option>--scope</option> switch
  75     (see below). </para>
  76
  77     <para>If a command is run with path, socket, or timer options such as <option>--on-calendar=</option> (see below),
  78     a transient path, socket, or timer unit is created alongside the service unit for the specified command. Only the
  79     transient path, socket, or timer unit is started immediately, the transient service unit will be triggered by the
  80     path, socket, or timer unit. If the <option>--unit=</option> option is specified, the
  81     <replaceable>COMMAND</replaceable> may be omitted. In this case, <command>systemd-run</command> creates only a
  82     <filename>.path</filename>, <filename>.socket</filename>, or <filename>.timer</filename> unit that triggers the
  83     specified unit.</para>
  84
  85     <para>By default, services created with <command>systemd-run</command> default to the <option>simple</option> type,
  86     see the description of <varname>Type=</varname> in
  87     <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
  88     details. Note that when this type is used the service manager (and thus the <command>systemd-run</command> command)
  89     considers service start-up successful as soon as the <function>fork()</function> for the main service process
  90     succeeded, i.e. before the <function>execve()</function> is invoked, and thus even if the specified command cannot
  91     be started. Consider using the <option>exec</option> service type (i.e. <option>--property=Type=exec</option>) to
  92     ensure that <command>systemd-run</command> returns successfully only if the specified command line has been
  93     successfully started.</para>
  94   </refsect1>
  95
  96   <refsect1>
  97     <title>Options</title>
  98
  99     <para>The following options are understood:</para>
 100
 101     <variablelist>
 102       <varlistentry>
 103         <term><option>--no-ask-password</option></term>
 104
 105         <listitem><para>Do not query the user for authentication for
 106         privileged operations.</para></listitem>
 107       </varlistentry>
 108
 109       <varlistentry>
 110         <term><option>--scope</option></term>
 111
 112         <listitem>
 113           <para>Create a transient <filename>.scope</filename> unit instead of the default transient
 114           <filename>.service</filename> unit (see above).
 115           </para>
 116         </listitem>
 117       </varlistentry>
 118
 119       <varlistentry>
 120         <term><option>--unit=</option></term>
 121         <term><option>-u</option></term>
 122
 123         <listitem><para>Use this unit name instead of an automatically
 124         generated one.</para></listitem>
 125       </varlistentry>
 126
 127       <varlistentry>
 128         <term><option>--property=</option></term>
 129         <term><option>-p</option></term>
 130
 131         <listitem><para>Sets a property on the scope or service unit that is created. This option takes an assignment
 132         in the same format as
 133         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 134         <command>set-property</command> command.</para>
 135         </listitem>
 136       </varlistentry>
 137
 138       <varlistentry>
 139         <term><option>--description=</option></term>
 140
 141         <listitem><para>Provide a description for the service, scope, path, socket, or timer unit. If not specified,
 142         the command itself will be used as a description. See <varname>Description=</varname> in
 143         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 144         </para></listitem>
 145       </varlistentry>
 146
 147       <varlistentry>
 148         <term><option>--slice=</option></term>
 149
 150         <listitem><para>Make the new <filename>.service</filename> or <filename>.scope</filename> unit part
 151         of the specified slice, instead of <filename>system.slice</filename> (when running in
 152         <option>--system</option> mode) or the root slice (when running in <option>--user</option>
 153         mode).</para>
 154         </listitem>
 155       </varlistentry>
 156
 157       <varlistentry>
 158         <term><option>--slice-inherit</option></term>
 159
 160         <listitem><para>Make the new <filename>.service</filename> or <filename>.scope</filename> unit part
 161         of the inherited slice. This option can be combined with <option>--slice=</option>.</para>
 162
 163         <para>An inherited slice is located within <command>systemd-run</command> slice. Example: if
 164         <command>systemd-run</command> slice is <filename>foo.slice</filename>, and the
 165         <option>--slice=</option> argument is <filename>bar</filename>, the unit will be placed under the
 166         <filename>foo-bar.slice</filename>.</para>
 167
 168         </listitem>
 169       </varlistentry>
 170
 171       <varlistentry>
 172         <term><option>-r</option></term>
 173         <term><option>--remain-after-exit</option></term>
 174
 175         <listitem><para>After the service process has terminated, keep the service around until it is explicitly
 176         stopped. This is useful to collect runtime information about the service after it finished running. Also see
 177         <varname>RemainAfterExit=</varname> in
 178         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 179         </para>
 180         </listitem>
 181       </varlistentry>
 182
 183       <varlistentry>
 184         <term><option>--send-sighup</option></term>
 185
 186         <listitem><para>When terminating the scope or service unit, send a SIGHUP immediately after SIGTERM. This is
 187         useful to indicate to shells and shell-like processes that the connection has been severed. Also see
 188         <varname>SendSIGHUP=</varname> in
 189         <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 190         </para>
 191         </listitem>
 192       </varlistentry>
 193
 194       <varlistentry>
 195         <term><option>--service-type=</option></term>
 196
 197         <listitem><para>Sets the service type. Also see
 198         <varname>Type=</varname> in
 199         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This
 200         option has no effect in conjunction with
 201         <option>--scope</option>. Defaults to
 202         <constant>simple</constant>.</para>
 203         </listitem>
 204       </varlistentry>
 205
 206       <varlistentry>
 207         <term><option>--uid=</option></term>
 208         <term><option>--gid=</option></term>
 209
 210         <listitem><para>Runs the service process under the specified UNIX user and group. Also see
 211         <varname>User=</varname> and <varname>Group=</varname> in
 212         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 213         </listitem>
 214       </varlistentry>
 215
 216       <varlistentry>
 217         <term><option>--nice=</option></term>
 218
 219         <listitem><para>Runs the service process with the specified
 220         nice level. Also see <varname>Nice=</varname> in
 221         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 222         </listitem>
 223       </varlistentry>
 224
 225       <varlistentry>
 226         <term><option>--working-directory=</option></term>
 227
 228         <listitem><para>Runs the service process with the specified working directory. Also see
 229         <varname>WorkingDirectory=</varname> in
 230         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 231         </listitem>
 232       </varlistentry>
 233
 234       <varlistentry>
 235         <term><option>--same-dir</option></term>
 236         <term><option>-d</option></term>
 237
 238         <listitem><para>Similar to <option>--working-directory=</option>, but uses the current working
 239         directory of the caller for the service to execute.</para></listitem>
 240       </varlistentry>
 241
 242       <varlistentry>
 243         <term><option>-E <replaceable>NAME</replaceable>[=<replaceable>VALUE</replaceable>]</option></term>
 244         <term><option>--setenv=<replaceable>NAME</replaceable>[=<replaceable>VALUE</replaceable>]</option></term>
 245
 246         <listitem><para>Runs the service process with the specified environment variable set. This parameter
 247         may be used more than once to set multiple variables. When <literal>=</literal> and
 248         <replaceable>VALUE</replaceable> are omitted, the value of the variable with the same name in the
 249         program environment will be used.</para>
 250
 251         <para>Also see <varname>Environment=</varname> in
 252         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 253         </listitem>
 254       </varlistentry>
 255
 256       <varlistentry>
 257         <term><option>--pty</option></term>
 258         <term><option>-t</option></term>
 259
 260         <listitem><para>When invoking the command, the transient service connects its standard input, output and error
 261         to the terminal <command>systemd-run</command> is invoked on, via a pseudo TTY device. This allows running
 262         programs that expect interactive user input/output as services, such as interactive command shells.</para>
 263
 264         <para>Note that
 265         <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 266         <command>shell</command> command is usually a better alternative for requesting a new, interactive login
 267         session on the local host or a local container.</para>
 268
 269         <para>See below for details on how this switch combines with <option>--pipe</option>.</para></listitem>
 270       </varlistentry>
 271
 272       <varlistentry>
 273         <term><option>--pipe</option></term>
 274         <term><option>-P</option></term>
 275
 276         <listitem><para>If specified, standard input, output, and error of the transient service are inherited from the
 277         <command>systemd-run</command> command itself. This allows <command>systemd-run</command>
 278         to be used within shell pipelines.
 279         Note that this mode is not suitable for interactive command shells and similar, as the
 280         service process will not become a TTY controller when invoked on a terminal. Use <option>--pty</option> instead
 281         in that case.</para>
 282
 283         <para>When both <option>--pipe</option> and <option>--pty</option> are used in combination the more appropriate
 284         option is automatically determined and used. Specifically, when invoked with standard input, output and error
 285         connected to a TTY <option>--pty</option> is used, and otherwise <option>--pipe</option>.</para>
 286
 287         <para>When this option is used the original file descriptors <command>systemd-run</command> receives are passed
 288         to the service processes as-is. If the service runs with different privileges than
 289         <command>systemd-run</command>, this means the service might not be able to re-open the passed file
 290         descriptors, due to normal file descriptor access restrictions. If the invoked process is a shell script that
 291         uses the <command>echo "hello" > /dev/stderr</command> construct for writing messages to stderr, this might
 292         cause problems, as this only works if stderr can be re-opened. To mitigate this use the construct <command>echo
 293         "hello" >&amp;2</command> instead, which is mostly equivalent and avoids this pitfall.</para></listitem>
 294       </varlistentry>
 295
 296       <varlistentry>
 297         <term><option>--shell</option></term>
 298         <term><option>-S</option></term>
 299
 300         <listitem><para>A shortcut for <literal>--pty --same-dir --wait --collect --service-type=exec $SHELL</literal>,
 301         i.e. requests an interactive shell in the current working directory, running in service context, accessible
 302         with a single switch.</para></listitem>
 303       </varlistentry>
 304
 305       <varlistentry>
 306         <term><option>--quiet</option></term>
 307         <term><option>-q</option></term>
 308
 309         <listitem><para>Suppresses additional informational output
 310         while running. This is particularly useful in combination with
 311         <option>--pty</option> when it will suppress the initial
 312         message explaining how to terminate the TTY connection.</para></listitem>
 313       </varlistentry>
 314
 315       <varlistentry>
 316         <term><option>--on-active=</option></term>
 317         <term><option>--on-boot=</option></term>
 318         <term><option>--on-startup=</option></term>
 319         <term><option>--on-unit-active=</option></term>
 320         <term><option>--on-unit-inactive=</option></term>
 321
 322         <listitem><para>Defines a monotonic timer relative to different starting points for starting the specified
 323         command. See <varname>OnActiveSec=</varname>, <varname>OnBootSec=</varname>, <varname>OnStartupSec=</varname>,
 324         <varname>OnUnitActiveSec=</varname> and <varname>OnUnitInactiveSec=</varname> in
 325         <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 326         details. These options are shortcuts for <command>--timer-property=</command> with the relevant properties.
 327         These options may not be combined with <option>--scope</option> or <option>--pty</option>.</para>
 328         </listitem>
 329       </varlistentry>
 330
 331       <varlistentry>
 332         <term><option>--on-calendar=</option></term>
 333
 334         <listitem><para>Defines a calendar timer for starting the specified command. See <varname>OnCalendar=</varname>
 335         in <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This
 336         option is a shortcut for <command>--timer-property=OnCalendar=</command>. This option may not be combined with
 337         <option>--scope</option> or <option>--pty</option>.</para>
 338         </listitem>
 339       </varlistentry>
 340
 341       <varlistentry>
 342         <term><option>--on-clock-change</option></term>
 343         <term><option>--on-timezone-change</option></term>
 344
 345         <listitem><para>Defines a trigger based on system clock jumps or timezone changes for starting the
 346         specified command. See <varname>OnClockChange=</varname> and <varname>OnTimezoneChange=</varname> in
 347         <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. These
 348         options are shortcuts for <command>--timer-property=OnClockChange=yes</command> and
 349         <command>--timer-property=OnTimezoneChange=yes</command>. These options may not be combined with
 350         <option>--scope</option> or <option>--pty</option>.</para></listitem>
 351       </varlistentry>
 352
 353       <varlistentry>
 354         <term><option>--path-property=</option></term>
 355         <term><option>--socket-property=</option></term>
 356         <term><option>--timer-property=</option></term>
 357
 358         <listitem><para>Sets a property on the path, socket, or timer unit that is created. This option is
 359         similar to <option>--property=</option>, but applies to the transient path, socket, or timer unit
 360         rather than the transient service unit created. This option takes an assignment in the same format as
 361         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 362         <command>set-property</command> command. These options may not be combined with
 363         <option>--scope</option> or <option>--pty</option>.</para>
 364         </listitem>
 365       </varlistentry>
 366
 367       <varlistentry>
 368         <term><option>--no-block</option></term>
 369
 370         <listitem>
 371           <para>Do not synchronously wait for the unit start operation to finish. If this option is not specified, the
 372           start request for the transient unit will be verified, enqueued and <command>systemd-run</command> will wait
 373           until the unit's start-up is completed. By passing this argument, it is only verified and enqueued. This
 374           option may not be combined with <option>--wait</option>.</para>
 375         </listitem>
 376       </varlistentry>
 377
 378       <varlistentry>
 379         <term><option>--wait</option></term>
 380
 381         <listitem><para>Synchronously wait for the transient service to terminate. If this option is specified, the
 382         start request for the transient unit is verified, enqueued, and waited for. Subsequently the invoked unit is
 383         monitored, and it is waited until it is deactivated again (most likely because the specified command
 384         completed). On exit, terse information about the unit's runtime is shown, including total runtime (as well as
 385         CPU usage, if <option>--property=CPUAccounting=1</option> was set) and the exit code and status of the main
 386         process. This output may be suppressed with <option>--quiet</option>. This option may not be combined with
 387         <option>--no-block</option>, <option>--scope</option> or the various path, socket, or timer options.</para></listitem>
 388       </varlistentry>
 389
 390       <varlistentry>
 391         <term><option>-G</option></term>
 392         <term><option>--collect</option></term>
 393
 394         <listitem><para>Unload the transient unit after it completed, even if it failed. Normally, without this option,
 395         all units that ran and failed are kept in memory until the user explicitly resets their failure state with
 396         <command>systemctl reset-failed</command> or an equivalent command. On the other hand, units that ran
 397         successfully are unloaded immediately. If this option is turned on the "garbage collection" of units is more
 398         aggressive, and unloads units regardless if they exited successfully or failed. This option is a shortcut for
 399         <command>--property=CollectMode=inactive-or-failed</command>, see the explanation for
 400         <varname>CollectMode=</varname> in
 401         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for further
 402         information.</para></listitem>
 403       </varlistentry>
 404
 405       <xi:include href="user-system-options.xml" xpointer="user" />
 406       <xi:include href="user-system-options.xml" xpointer="system" />
 407       <xi:include href="user-system-options.xml" xpointer="host" />
 408       <xi:include href="user-system-options.xml" xpointer="machine" />
 409
 410       <xi:include href="standard-options.xml" xpointer="help" />
 411       <xi:include href="standard-options.xml" xpointer="version" />
 412     </variablelist>
 413
 414     <para>All command line arguments after the first non-option
 415     argument become part of the command line of the launched
 416     process. If a command is run as service unit, the first argument
 417     needs to be an absolute program path.</para>
 418   </refsect1>
 419
 420   <refsect1>
 421     <title>Exit status</title>
 422
 423     <para>On success, 0 is returned. If <command>systemd-run</command> failed to start the service, a
 424     non-zero return value will be returned. If <command>systemd-run</command> waits for the service to
 425     terminate, the return value will be propagated from the service. 0 will be returned on success, including
 426     all the cases where systemd considers a service to have exited cleanly, see the discussion of
 427     <varname>SuccessExitStatus=</varname> in
 428     <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 429     </para>
 430   </refsect1>
 431
 432   <refsect1>
 433     <title>Examples</title>
 434
 435     <example>
 436       <title>Logging environment variables provided by systemd to services</title>
 437
 438       <programlisting># systemd-run env
 439 Running as unit: run-19945.service
 440 # journalctl -u run-19945.service
 441 Sep 08 07:37:21 bupkis systemd[1]: Starting /usr/bin/env...
 442 Sep 08 07:37:21 bupkis systemd[1]: Started /usr/bin/env.
 443 Sep 08 07:37:21 bupkis env[19948]: PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin
 444 Sep 08 07:37:21 bupkis env[19948]: LANG=en_US.UTF-8
 445 Sep 08 07:37:21 bupkis env[19948]: BOOT_IMAGE=/vmlinuz-3.11.0-0.rc5.git6.2.fc20.x86_64</programlisting>
 446     </example>
 447
 448     <example>
 449       <title>Limiting resources available to a command</title>
 450
 451       <programlisting># systemd-run -p IOWeight=10 updatedb</programlisting>
 452
 453       <para>This command invokes the <citerefentry
 454       project='man-pages'><refentrytitle>updatedb</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 455       tool, but lowers the block I/O weight for it to 10. See
 456       <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 457       for more information on the <varname>IOWeight=</varname> property.</para>
 458     </example>
 459
 460     <example>
 461       <title>Running commands at a specified time</title>
 462
 463       <para>The following command will touch a file after 30 seconds.</para>
 464
 465       <programlisting># date; systemd-run --on-active=30 --timer-property=AccuracySec=100ms /bin/touch /tmp/foo
 466 Mon Dec  8 20:44:24 KST 2014
 467 Running as unit: run-71.timer
 468 Will run service as unit: run-71.service
 469 # journalctl -b -u run-71.timer
 470 -- Journal begins at Fri 2014-12-05 19:09:21 KST, ends at Mon 2014-12-08 20:44:54 KST. --
 471 Dec 08 20:44:38 container systemd[1]: Starting /bin/touch /tmp/foo.
 472 Dec 08 20:44:38 container systemd[1]: Started /bin/touch /tmp/foo.
 473 # journalctl -b -u run-71.service
 474 -- Journal begins at Fri 2014-12-05 19:09:21 KST, ends at Mon 2014-12-08 20:44:54 KST. --
 475 Dec 08 20:44:48 container systemd[1]: Starting /bin/touch /tmp/foo...
 476 Dec 08 20:44:48 container systemd[1]: Started /bin/touch /tmp/foo.</programlisting>
 477     </example>
 478
 479     <example>
 480       <title>Allowing access to the tty</title>
 481
 482       <para>The following command invokes <citerefentry project='die-net'><refentrytitle>bash</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 483       as a service passing its standard input, output and error to the calling TTY.</para>
 484
 485       <programlisting># systemd-run -t --send-sighup bash</programlisting>
 486     </example>
 487
 488     <example>
 489       <title>Start <command>screen</command> as a user service</title>
 490
 491       <programlisting>$ systemd-run --scope --user screen
 492 Running scope as unit run-r14b0047ab6df45bfb45e7786cc839e76.scope.
 493
 494 $ screen -ls
 495 There is a screen on:
 496         492..laptop     (Detached)
 497 1 Socket in /var/run/screen/S-fatima.
 498 </programlisting>
 499
 500       <para>This starts the <command>screen</command> process as a child of the
 501       <command>systemd --user</command> process that was started by
 502       <filename>user@.service</filename>, in a scope unit. A
 503       <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 504       unit is used instead of a
 505       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 506       unit, because <command>screen</command> will exit when detaching from the terminal,
 507       and a service unit would be terminated. Running <command>screen</command>
 508       as a user unit has the advantage that it is not part of the session scope.
 509       If <varname>KillUserProcesses=yes</varname> is configured in
 510       <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 511       the default, the session scope will be terminated when the user logs
 512       out of that session.</para>
 513
 514       <para>The <filename>user@.service</filename> is started automatically
 515       when the user first logs in, and stays around as long as at least one
 516       login session is open. After the user logs out of the last session,
 517       <filename>user@.service</filename> and all services underneath it
 518       are terminated. This behavior is the default, when "lingering" is
 519       not enabled for that user. Enabling lingering means that
 520       <filename>user@.service</filename> is started automatically during
 521       boot, even if the user is not logged in, and that the service is
 522       not terminated when the user logs out.</para>
 523
 524       <para>Enabling lingering allows the user to run processes without being logged in,
 525       for example to allow <command>screen</command> to persist after the user logs out,
 526       even if the session scope is terminated. In the default configuration, users can
 527       enable lingering for themselves:</para>
 528
 529       <programlisting>$ loginctl enable-linger</programlisting>
 530     </example>
 531
 532     <example>
 533       <title>Return value</title>
 534
 535       <programlisting>$ systemd-run --user --wait true
 536 $ systemd-run --user --wait -p SuccessExitStatus=11 bash -c 'exit 11'
 537 $ systemd-run --user --wait -p SuccessExitStatus=SIGUSR1 bash -c 'kill -SIGUSR1 $$$$'</programlisting>
 538
 539       <para>Those three invocations will succeed, i.e. terminate with an exit code of 0.</para>
 540     </example>
 541   </refsect1>
 542
 543   <refsect1>
 544     <title>See Also</title>
 545     <para>
 546       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 547       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 548       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 549       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 550       <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 551       <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 552       <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 553       <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 554       <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 555       <citerefentry><refentrytitle>systemd-mount</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 556       <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 557     </para>
 558   </refsect1>
 559
 560 </refentry>