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