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