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> 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. This parameter
 246         may be used more than once to set multiple variables. When <literal>=</literal> and
 247         <replaceable>VALUE</replaceable> are omitted, the value of the variable with the same name in the
 248         program environment will be used.</para>
 249
 250         <para>Also see <varname>Environment=</varname> in
 251         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 252         </listitem>
 253       </varlistentry>
 254
 255       <varlistentry>
 256         <term><option>--pty</option></term>
 257         <term><option>-t</option></term>
 258
 259         <listitem><para>When invoking the command, the transient service connects its standard input, output and error
 260         to the terminal <command>systemd-run</command> is invoked on, via a pseudo TTY device. This allows running
 261         programs that expect interactive user input/output as services, such as interactive command shells.</para>
 262
 263         <para>Note that
 264         <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 265         <command>shell</command> command is usually a better alternative for requesting a new, interactive login
 266         session on the local host or a local container.</para>
 267
 268         <para>See below for details on how this switch combines with <option>--pipe</option>.</para></listitem>
 269       </varlistentry>
 270
 271       <varlistentry>
 272         <term><option>--pipe</option></term>
 273         <term><option>-P</option></term>
 274
 275         <listitem><para>If specified, standard input, output, and error of the transient service are inherited from the
 276         <command>systemd-run</command> command itself. This allows <command>systemd-run</command>
 277         to be used within shell pipelines.
 278         Note that this mode is not suitable for interactive command shells and similar, as the
 279         service process will not become a TTY controller when invoked on a terminal. Use <option>--pty</option> instead
 280         in that case.</para>
 281
 282         <para>When both <option>--pipe</option> and <option>--pty</option> are used in combination the more appropriate
 283         option is automatically determined and used. Specifically, when invoked with standard input, output and error
 284         connected to a TTY <option>--pty</option> is used, and otherwise <option>--pipe</option>.</para>
 285
 286         <para>When this option is used the original file descriptors <command>systemd-run</command> receives are passed
 287         to the service processes as-is. If the service runs with different privileges than
 288         <command>systemd-run</command>, this means the service might not be able to re-open the passed file
 289         descriptors, due to normal file descriptor access restrictions. If the invoked process is a shell script that
 290         uses the <command>echo "hello" > /dev/stderr</command> construct for writing messages to stderr, this might
 291         cause problems, as this only works if stderr can be re-opened. To mitigate this use the construct <command>echo
 292         "hello" >&amp;2</command> instead, which is mostly equivalent and avoids this pitfall.</para></listitem>
 293       </varlistentry>
 294
 295       <varlistentry>
 296         <term><option>--shell</option></term>
 297         <term><option>-S</option></term>
 298
 299         <listitem><para>A shortcut for <literal>--pty --same-dir --wait --collect --service-type=exec $SHELL</literal>,
 300         i.e. requests an interactive shell in the current working directory, running in service context, accessible
 301         with a single switch.</para></listitem>
 302       </varlistentry>
 303
 304       <varlistentry>
 305         <term><option>--quiet</option></term>
 306         <term><option>-q</option></term>
 307
 308         <listitem><para>Suppresses additional informational output
 309         while running. This is particularly useful in combination with
 310         <option>--pty</option> when it will suppress the initial
 311         message explaining how to terminate the TTY connection.</para></listitem>
 312       </varlistentry>
 313
 314       <varlistentry>
 315         <term><option>--on-active=</option></term>
 316         <term><option>--on-boot=</option></term>
 317         <term><option>--on-startup=</option></term>
 318         <term><option>--on-unit-active=</option></term>
 319         <term><option>--on-unit-inactive=</option></term>
 320
 321         <listitem><para>Defines a monotonic timer relative to different starting points for starting the specified
 322         command. See <varname>OnActiveSec=</varname>, <varname>OnBootSec=</varname>, <varname>OnStartupSec=</varname>,
 323         <varname>OnUnitActiveSec=</varname> and <varname>OnUnitInactiveSec=</varname> in
 324         <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 325         details. These options are shortcuts for <command>--timer-property=</command> with the relevant properties.
 326         These options may not be combined with <option>--scope</option> or <option>--pty</option>.</para>
 327         </listitem>
 328       </varlistentry>
 329
 330       <varlistentry>
 331         <term><option>--on-calendar=</option></term>
 332
 333         <listitem><para>Defines a calendar timer for starting the specified command. See <varname>OnCalendar=</varname>
 334         in <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This
 335         option is a shortcut for <command>--timer-property=OnCalendar=</command>. This option may not be combined with
 336         <option>--scope</option> or <option>--pty</option>.</para>
 337         </listitem>
 338       </varlistentry>
 339
 340       <varlistentry>
 341         <term><option>--on-clock-change</option></term>
 342         <term><option>--on-timezone-change</option></term>
 343
 344         <listitem><para>Defines a trigger based on system clock jumps or timezone changes for starting the
 345         specified command. See <varname>OnClockChange=</varname> and <varname>OnTimezoneChange=</varname> in
 346         <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. These
 347         options are shortcuts for <command>--timer-property=OnClockChange=yes</command> and
 348         <command>--timer-property=OnTimezoneChange=yes</command>. These options may not be combined with
 349         <option>--scope</option> or <option>--pty</option>.</para></listitem>
 350       </varlistentry>
 351
 352       <varlistentry>
 353         <term><option>--path-property=</option></term>
 354         <term><option>--socket-property=</option></term>
 355         <term><option>--timer-property=</option></term>
 356
 357         <listitem><para>Sets a property on the path, socket, or timer unit that is created. This option is similar to
 358         <option>--property=</option> but applies to the transient path, socket, or timer unit rather than the
 359         transient service unit created. This option takes an assignment in the same format as
 360         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 361         <command>set-property</command> command. These options may not be combined with
 362         <option>--scope</option> or <option>--pty</option>.</para>
 363         </listitem>
 364       </varlistentry>
 365
 366       <varlistentry>
 367         <term><option>--no-block</option></term>
 368
 369         <listitem>
 370           <para>Do not synchronously wait for the unit start operation to finish. If this option is not specified, the
 371           start request for the transient unit will be verified, enqueued and <command>systemd-run</command> will wait
 372           until the unit's start-up is completed. By passing this argument, it is only verified and enqueued. This
 373           option may not be combined with <option>--wait</option>.</para>
 374         </listitem>
 375       </varlistentry>
 376
 377       <varlistentry>
 378         <term><option>--wait</option></term>
 379
 380         <listitem><para>Synchronously wait for the transient service to terminate. If this option is specified, the
 381         start request for the transient unit is verified, enqueued, and waited for. Subsequently the invoked unit is
 382         monitored, and it is waited until it is deactivated again (most likely because the specified command
 383         completed). On exit, terse information about the unit's runtime is shown, including total runtime (as well as
 384         CPU usage, if <option>--property=CPUAccounting=1</option> was set) and the exit code and status of the main
 385         process. This output may be suppressed with <option>--quiet</option>. This option may not be combined with
 386         <option>--no-block</option>, <option>--scope</option> or the various path, socket, or timer options.</para></listitem>
 387       </varlistentry>
 388
 389       <varlistentry>
 390         <term><option>-G</option></term>
 391         <term><option>--collect</option></term>
 392
 393         <listitem><para>Unload the transient unit after it completed, even if it failed. Normally, without this option,
 394         all units that ran and failed are kept in memory until the user explicitly resets their failure state with
 395         <command>systemctl reset-failed</command> or an equivalent command. On the other hand, units that ran
 396         successfully are unloaded immediately. If this option is turned on the "garbage collection" of units is more
 397         aggressive, and unloads units regardless if they exited successfully or failed. This option is a shortcut for
 398         <command>--property=CollectMode=inactive-or-failed</command>, see the explanation for
 399         <varname>CollectMode=</varname> in
 400         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for further
 401         information.</para></listitem>
 402       </varlistentry>
 403
 404       <xi:include href="user-system-options.xml" xpointer="user" />
 405       <xi:include href="user-system-options.xml" xpointer="system" />
 406       <xi:include href="user-system-options.xml" xpointer="host" />
 407       <xi:include href="user-system-options.xml" xpointer="machine" />
 408
 409       <xi:include href="standard-options.xml" xpointer="help" />
 410       <xi:include href="standard-options.xml" xpointer="version" />
 411     </variablelist>
 412
 413     <para>All command line arguments after the first non-option
 414     argument become part of the command line of the launched
 415     process. If a command is run as service unit, the first argument
 416     needs to be an absolute program path.</para>
 417   </refsect1>
 418
 419   <refsect1>
 420     <title>Exit status</title>
 421
 422     <para>On success, 0 is returned. If <command>systemd-run</command> failed to start the service, a
 423     non-zero return value will be returned. If <command>systemd-run</command> waits for the service to
 424     terminate, the return value will be propagated from the service. 0 will be returned on success, including
 425     all the cases where systemd considers a service to have exited cleanly, see the discussion of
 426     <varname>SuccessExitStatus=</varname> in
 427     <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 428     </para>
 429   </refsect1>
 430
 431   <refsect1>
 432     <title>Examples</title>
 433
 434     <example>
 435       <title>Logging environment variables provided by systemd to services</title>
 436
 437       <programlisting># systemd-run env
 438 Running as unit: run-19945.service
 439 # journalctl -u run-19945.service
 440 Sep 08 07:37:21 bupkis systemd[1]: Starting /usr/bin/env...
 441 Sep 08 07:37:21 bupkis systemd[1]: Started /usr/bin/env.
 442 Sep 08 07:37:21 bupkis env[19948]: PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin
 443 Sep 08 07:37:21 bupkis env[19948]: LANG=en_US.UTF-8
 444 Sep 08 07:37:21 bupkis env[19948]: BOOT_IMAGE=/vmlinuz-3.11.0-0.rc5.git6.2.fc20.x86_64</programlisting>
 445     </example>
 446
 447     <example>
 448       <title>Limiting resources available to a command</title>
 449
 450       <programlisting># systemd-run -p BlockIOWeight=10 updatedb</programlisting>
 451
 452       <para>This command invokes the
 453       <citerefentry project='man-pages'><refentrytitle>updatedb</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 454       tool, but lowers the block I/O weight for it to 10. See
 455       <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 456       for more information on the <varname>BlockIOWeight=</varname>
 457       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><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>