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.5/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>, <option>--wait</option>, <option>--pipe</option>,
  68     or <option>--pty</option> are specified, see below).</para>
  69
  70     <para>If a command is run as transient scope unit, it will be executed by <command>systemd-run</command>
  71     itself as parent process and will thus inherit the execution environment of the caller. However, the
  72     processes of the command are managed by the service manager similarly to normal services, and will show
  73     up in the output of <command>systemctl list-units</command>. Execution in this case is synchronous, and
  74     will return only when the command finishes. This mode is enabled via the <option>--scope</option> switch
  75     (see below).</para>
  76
  77     <para>If a command is run with path, socket, or timer options such as <option>--on-calendar=</option> (see below),
  78     a transient path, socket, or timer unit is created alongside the service unit for the specified command. Only the
  79     transient path, socket, or timer unit is started immediately, the transient service unit will be triggered by the
  80     path, socket, or timer unit. If the <option>--unit=</option> option is specified, the
  81     <replaceable>COMMAND</replaceable> may be omitted. In this case, <command>systemd-run</command> creates only a
  82     <filename>.path</filename>, <filename>.socket</filename>, or <filename>.timer</filename> unit that triggers the
  83     specified unit.</para>
  84
  85     <para>By default, services created with <command>systemd-run</command> default to the
  86     <option>simple</option> type, see the description of <varname>Type=</varname> in
  87     <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
  88     details. Note that when this type is used, the service manager (and thus the
  89     <command>systemd-run</command> command) considers service start-up successful as soon as the
  90     <function>fork()</function> for the main service process succeeded, i.e. before the
  91     <function>execve()</function> is invoked, and thus even if the specified command cannot be started.
  92     Consider using the <option>exec</option> service type (i.e. <option>--property=Type=exec</option>) to
  93     ensure that <command>systemd-run</command> returns successfully only if the specified command line has
  94     been successfully started.</para>
  95
  96     <para>After <command>systemd-run</command> passes the command to the service manager, the manager
  97     performs variable expansion. This means that dollar characters (<literal>$</literal>) which should not be
  98     expanded need to be escaped as <literal>$$</literal>. Expansion can also be disabled using
  99     <varname>--expand-environment=no</varname>.</para>
 100   </refsect1>
 101
 102   <refsect1>
 103     <title>Options</title>
 104
 105     <para>The following options are understood:</para>
 106
 107     <variablelist>
 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
 116         <xi:include href="version-info.xml" xpointer="v206"/>
 117         </listitem>
 118       </varlistentry>
 119
 120       <varlistentry>
 121         <term><option>--unit=</option></term>
 122         <term><option>-u</option></term>
 123
 124         <listitem><para>Use this unit name instead of an automatically
 125         generated one.</para>
 126
 127         <xi:include href="version-info.xml" xpointer="v206"/></listitem>
 128       </varlistentry>
 129
 130       <varlistentry>
 131         <term><option>--property=</option></term>
 132         <term><option>-p</option></term>
 133
 134         <listitem><para>Sets a property on the scope or service unit that is created. This option takes an assignment
 135         in the same format as
 136         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 137         <command>set-property</command> command.</para>
 138
 139         <xi:include href="version-info.xml" xpointer="v211"/>
 140         </listitem>
 141       </varlistentry>
 142
 143       <varlistentry>
 144         <term><option>--description=</option></term>
 145
 146         <listitem><para>Provide a description for the service, scope, path, socket, or timer unit. If not specified,
 147         the command itself will be used as a description. See <varname>Description=</varname> in
 148         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 149         </para>
 150
 151         <xi:include href="version-info.xml" xpointer="v206"/></listitem>
 152       </varlistentry>
 153
 154       <varlistentry>
 155         <term><option>--slice=</option></term>
 156
 157         <listitem><para>Make the new <filename>.service</filename> or <filename>.scope</filename> unit part
 158         of the specified slice, instead of <filename>system.slice</filename> (when running in
 159         <option>--system</option> mode) or the root slice (when running in <option>--user</option>
 160         mode).</para>
 161
 162         <xi:include href="version-info.xml" xpointer="v206"/>
 163         </listitem>
 164       </varlistentry>
 165
 166       <varlistentry>
 167         <term><option>--slice-inherit</option></term>
 168
 169         <listitem><para>Make the new <filename>.service</filename> or <filename>.scope</filename> unit part
 170         of the slice the <command>systemd-run</command> itself has been invoked in. This option may be
 171         combined with <option>--slice=</option>, in which case the slice specified via
 172         <option>--slice=</option> is placed within the slice the <command>systemd-run</command> command is
 173         invoked in.</para>
 174
 175         <para>Example: consider <command>systemd-run</command> being invoked in the slice
 176         <filename>foo.slice</filename>, and the <option>--slice=</option> argument is
 177         <filename>bar</filename>. The unit will then be placed under
 178         <filename>foo-bar.slice</filename>.</para>
 179
 180         <xi:include href="version-info.xml" xpointer="v246"/>
 181
 182         </listitem>
 183       </varlistentry>
 184
 185       <varlistentry>
 186         <term><option>--expand-environment=<replaceable>BOOL</replaceable></option></term>
 187
 188         <listitem><para>Expand environment variables in command arguments. If enabled (the default),
 189         environment variables specified as <literal>${<replaceable>VARIABLE</replaceable>}</literal> will be
 190         expanded in the same way as in commands specified via <varname>ExecStart=</varname> in units. With
 191         <varname>--scope</varname>, this expansion is performed by <command>systemd-run</command> itself, and
 192         in other cases by the service manager that spawns the command. Note that this is similar to, but not
 193         the same as variable expansion in
 194         <citerefentry project='man-pages'><refentrytitle>bash</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 195         and other shells.</para>
 196
 197         <para>See
 198         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 199         for a description of variable expansion. Disabling variable expansion is useful if the specified
 200         command includes or may include a <literal>$</literal> sign.</para>
 201
 202         <xi:include href="version-info.xml" xpointer="v254"/>
 203         </listitem>
 204       </varlistentry>
 205
 206       <varlistentry>
 207         <term><option>-r</option></term>
 208         <term><option>--remain-after-exit</option></term>
 209
 210         <listitem><para>After the service process has terminated, keep the service around until it is explicitly
 211         stopped. This is useful to collect runtime information about the service after it finished running. Also see
 212         <varname>RemainAfterExit=</varname> in
 213         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 214         </para>
 215
 216         <xi:include href="version-info.xml" xpointer="v207"/>
 217         </listitem>
 218       </varlistentry>
 219
 220       <varlistentry>
 221         <term><option>--send-sighup</option></term>
 222
 223         <listitem><para>When terminating the scope or service unit, send a SIGHUP immediately after SIGTERM. This is
 224         useful to indicate to shells and shell-like processes that the connection has been severed. Also see
 225         <varname>SendSIGHUP=</varname> in
 226         <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 227         </para>
 228
 229         <xi:include href="version-info.xml" xpointer="v207"/>
 230         </listitem>
 231       </varlistentry>
 232
 233       <varlistentry>
 234         <term><option>--service-type=</option></term>
 235
 236         <listitem><para>Sets the service type. Also see
 237         <varname>Type=</varname> in
 238         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This
 239         option has no effect in conjunction with
 240         <option>--scope</option>. Defaults to
 241         <constant>simple</constant>.</para>
 242
 243         <xi:include href="version-info.xml" xpointer="v211"/>
 244         </listitem>
 245       </varlistentry>
 246
 247       <varlistentry>
 248         <term><option>--uid=</option></term>
 249         <term><option>--gid=</option></term>
 250
 251         <listitem><para>Runs the service process under the specified UNIX user and group. Also see
 252         <varname>User=</varname> and <varname>Group=</varname> in
 253         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 254
 255         <xi:include href="version-info.xml" xpointer="v211"/>
 256         </listitem>
 257       </varlistentry>
 258
 259       <varlistentry>
 260         <term><option>--nice=</option></term>
 261
 262         <listitem><para>Runs the service process with the specified
 263         nice level. Also see <varname>Nice=</varname> in
 264         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 265
 266         <xi:include href="version-info.xml" xpointer="v211"/>
 267         </listitem>
 268       </varlistentry>
 269
 270       <varlistentry>
 271         <term><option>--working-directory=</option></term>
 272
 273         <listitem><para>Runs the service process with the specified working directory. Also see
 274         <varname>WorkingDirectory=</varname> in
 275         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 276
 277         <xi:include href="version-info.xml" xpointer="v240"/>
 278         </listitem>
 279       </varlistentry>
 280
 281       <varlistentry>
 282         <term><option>--same-dir</option></term>
 283         <term><option>-d</option></term>
 284
 285         <listitem><para>Similar to <option>--working-directory=</option>, but uses the current working
 286         directory of the caller for the service to execute.</para>
 287
 288         <xi:include href="version-info.xml" xpointer="v240"/></listitem>
 289       </varlistentry>
 290
 291       <varlistentry>
 292         <term><option>-E <replaceable>NAME</replaceable>[=<replaceable>VALUE</replaceable>]</option></term>
 293         <term><option>--setenv=<replaceable>NAME</replaceable>[=<replaceable>VALUE</replaceable>]</option></term>
 294
 295         <listitem><para>Runs the service process with the specified environment variable set. This parameter
 296         may be used more than once to set multiple variables. When <literal>=</literal> and
 297         <replaceable>VALUE</replaceable> are omitted, the value of the variable with the same name in the
 298         program environment will be used.</para>
 299
 300         <para>Also see <varname>Environment=</varname> in
 301         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 302
 303         <xi:include href="version-info.xml" xpointer="v211"/>
 304         </listitem>
 305       </varlistentry>
 306
 307       <varlistentry>
 308         <term><option>--pty</option></term>
 309         <term><option>-t</option></term>
 310
 311         <listitem><para>When invoking the command, the transient service connects its standard input, output and error
 312         to the terminal <command>systemd-run</command> is invoked on, via a pseudo TTY device. This allows running
 313         programs that expect interactive user input/output as services, such as interactive command shells.</para>
 314
 315         <para>This option will result in <command>systemd-run</command> synchronously waiting for
 316         the transient service to terminate, similar to specifying <option>--wait</option>. If specified
 317         along with <option>--wait</option>, <command>systemd-run</command> will not exit when manually disconnecting
 318         from the pseudo TTY device.</para>
 319
 320         <para>Note that
 321         <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 322         <command>shell</command> command is usually a better alternative for requesting a new, interactive login
 323         session on the local host or a local container.</para>
 324
 325         <para>See below for details on how this switch combines with <option>--pipe</option>.</para>
 326
 327         <xi:include href="version-info.xml" xpointer="v219"/></listitem>
 328       </varlistentry>
 329
 330       <varlistentry>
 331         <term><option>--pipe</option></term>
 332         <term><option>-P</option></term>
 333
 334         <listitem><para>If specified, standard input, output, and error of the transient service are inherited from the
 335         <command>systemd-run</command> command itself. This allows <command>systemd-run</command>
 336         to be used within shell pipelines.</para>
 337
 338         <para>Note that this mode is not suitable for interactive command shells and similar, as the
 339         service process will not become a TTY controller when invoked on a terminal. Use <option>--pty</option>
 340         instead in that case.</para>
 341
 342         <para>When both <option>--pipe</option> and <option>--pty</option> are used in combination the more appropriate
 343         option is automatically determined and used. Specifically, when invoked with standard input, output and error
 344         connected to a TTY <option>--pty</option> is used, and otherwise <option>--pipe</option>.</para>
 345
 346         <para>This option will result in <command>systemd-run</command> synchronously waiting for
 347         the transient service to terminate, similar to specifying <option>--wait</option>.</para>
 348
 349         <para>When this option is used the original file descriptors <command>systemd-run</command> receives are passed
 350         to the service processes as-is. If the service runs with different privileges than
 351         <command>systemd-run</command>, this means the service might not be able to reopen the passed file
 352         descriptors, due to normal file descriptor access restrictions. If the invoked process is a shell script that
 353         uses the <command>echo "hello" >/dev/stderr</command> construct for writing messages to stderr, this might
 354         cause problems, as this only works if stderr can be reopened. To mitigate this use the construct <command>echo
 355         "hello" >&amp;2</command> instead, which is mostly equivalent and avoids this pitfall.</para>
 356
 357         <xi:include href="version-info.xml" xpointer="v235"/></listitem>
 358       </varlistentry>
 359
 360       <varlistentry>
 361         <term><option>--shell</option></term>
 362         <term><option>-S</option></term>
 363
 364         <listitem><para>A shortcut for <literal>--pty --same-dir --wait --collect --service-type=exec $SHELL</literal>,
 365         i.e. requests an interactive shell in the current working directory, running in service context, accessible
 366         with a single switch.</para>
 367
 368         <xi:include href="version-info.xml" xpointer="v240"/></listitem>
 369       </varlistentry>
 370
 371       <varlistentry>
 372         <term><option>--quiet</option></term>
 373         <term><option>-q</option></term>
 374
 375         <listitem><para>Suppresses additional informational output
 376         while running. This is particularly useful in combination with
 377         <option>--pty</option> when it will suppress the initial
 378         message explaining how to terminate the TTY connection.</para>
 379
 380         <xi:include href="version-info.xml" xpointer="v219"/></listitem>
 381       </varlistentry>
 382
 383       <varlistentry>
 384         <term><option>--on-active=</option></term>
 385         <term><option>--on-boot=</option></term>
 386         <term><option>--on-startup=</option></term>
 387         <term><option>--on-unit-active=</option></term>
 388         <term><option>--on-unit-inactive=</option></term>
 389
 390         <listitem><para>Defines a monotonic timer relative to different starting points for starting the specified
 391         command. See <varname>OnActiveSec=</varname>, <varname>OnBootSec=</varname>, <varname>OnStartupSec=</varname>,
 392         <varname>OnUnitActiveSec=</varname> and <varname>OnUnitInactiveSec=</varname> in
 393         <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 394         details. These options are shortcuts for <command>--timer-property=</command> with the relevant properties.
 395         These options may not be combined with <option>--scope</option> or <option>--pty</option>.</para>
 396
 397         <xi:include href="version-info.xml" xpointer="v218"/>
 398         </listitem>
 399       </varlistentry>
 400
 401       <varlistentry>
 402         <term><option>--on-calendar=</option></term>
 403
 404         <listitem><para>Defines a calendar timer for starting the specified command. See <varname>OnCalendar=</varname>
 405         in <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This
 406         option is a shortcut for <command>--timer-property=OnCalendar=</command>. This option may not be combined with
 407         <option>--scope</option> or <option>--pty</option>.</para>
 408
 409         <xi:include href="version-info.xml" xpointer="v218"/>
 410         </listitem>
 411       </varlistentry>
 412
 413       <varlistentry>
 414         <term><option>--on-clock-change</option></term>
 415         <term><option>--on-timezone-change</option></term>
 416
 417         <listitem><para>Defines a trigger based on system clock jumps or timezone changes for starting the
 418         specified command. See <varname>OnClockChange=</varname> and <varname>OnTimezoneChange=</varname> in
 419         <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. These
 420         options are shortcuts for <command>--timer-property=OnClockChange=yes</command> and
 421         <command>--timer-property=OnTimezoneChange=yes</command>. These options may not be combined with
 422         <option>--scope</option> or <option>--pty</option>.</para>
 423
 424         <xi:include href="version-info.xml" xpointer="v242"/></listitem>
 425       </varlistentry>
 426
 427       <varlistentry>
 428         <term><option>--path-property=</option></term>
 429         <term><option>--socket-property=</option></term>
 430         <term><option>--timer-property=</option></term>
 431
 432         <listitem><para>Sets a property on the path, socket, or timer unit that is created. This option is
 433         similar to <option>--property=</option>, but applies to the transient path, socket, or timer unit
 434         rather than the transient service unit created. This option takes an assignment in the same format as
 435         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 436         <command>set-property</command> command. These options may not be combined with
 437         <option>--scope</option> or <option>--pty</option>.</para>
 438
 439         <xi:include href="version-info.xml" xpointer="v218"/>
 440         </listitem>
 441       </varlistentry>
 442
 443       <varlistentry>
 444         <term><option>--no-block</option></term>
 445
 446         <listitem>
 447           <para>Do not synchronously wait for the unit start operation to finish. If this option is not specified, the
 448           start request for the transient unit will be verified, enqueued and <command>systemd-run</command> will wait
 449           until the unit's start-up is completed. By passing this argument, it is only verified and enqueued. This
 450           option may not be combined with <option>--wait</option>.</para>
 451
 452           <xi:include href="version-info.xml" xpointer="v220"/>
 453         </listitem>
 454       </varlistentry>
 455
 456       <varlistentry>
 457         <term><option>--wait</option></term>
 458
 459         <listitem><para>Synchronously wait for the transient service to terminate. If this option is specified, the
 460         start request for the transient unit is verified, enqueued, and waited for. Subsequently the invoked unit is
 461         monitored, and it is waited until it is deactivated again (most likely because the specified command
 462         completed). On exit, terse information about the unit's runtime is shown, including total runtime (as well as
 463         CPU usage, if <option>--property=CPUAccounting=1</option> was set) and the exit code and status of the main
 464         process. This output may be suppressed with <option>--quiet</option>. This option may not be combined with
 465         <option>--no-block</option>, <option>--scope</option> or the various path, socket, or timer options.</para>
 466
 467         <xi:include href="version-info.xml" xpointer="v232"/></listitem>
 468       </varlistentry>
 469
 470       <varlistentry>
 471         <term><option>-G</option></term>
 472         <term><option>--collect</option></term>
 473
 474         <listitem><para>Unload the transient unit after it completed, even if it failed. Normally, without this option,
 475         all units that ran and failed are kept in memory until the user explicitly resets their failure state with
 476         <command>systemctl reset-failed</command> or an equivalent command. On the other hand, units that ran
 477         successfully are unloaded immediately. If this option is turned on the "garbage collection" of units is more
 478         aggressive, and unloads units regardless of whether they exited successfully or failed. This option is a shortcut for
 479         <command>--property=CollectMode=inactive-or-failed</command>, see the explanation for
 480         <varname>CollectMode=</varname> in
 481         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for further
 482         information.</para>
 483
 484         <xi:include href="version-info.xml" xpointer="v236"/></listitem>
 485       </varlistentry>
 486
 487       <varlistentry>
 488         <term><option>--job-mode=<replaceable>MODE</replaceable></option></term>
 489
 490         <listitem>
 491           <para>When queuing a new job, this option controls how to deal with
 492           already queued jobs.</para>
 493
 494           <para>The option takes the same mode values as
 495           <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 496           <option>--job-mode=</option> option. The default job mode is <literal>fail</literal>.</para>
 497
 498           <para>Running <option>--job-mode=help</option> shows a list of available job modes.</para>
 499
 500           <xi:include href="version-info.xml" xpointer="v258"/>
 501         </listitem>
 502       </varlistentry>
 503
 504       <varlistentry>
 505         <term><option>--ignore-failure</option></term>
 506
 507         <listitem><para>By default, if the specified command fails the invoked unit will be marked failed
 508         (though possibly still unloaded, see <option>--collect=</option>, above), and this is reported in the
 509         logs. If this switch is specified this is suppressed and any non-success exit status/code of the
 510         command is treated as success.</para>
 511
 512         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 513       </varlistentry>
 514
 515       <varlistentry>
 516         <term><option>--background=<replaceable>COLOR</replaceable></option></term>
 517
 518         <listitem><para>Change the terminal background color to the specified ANSI color as long as the
 519         session lasts. The color specified should be an ANSI X3.64 SGR background color, i.e. strings such as
 520         <literal>40</literal>, <literal>41</literal>, …, <literal>47</literal>, <literal>48;2;…</literal>,
 521         <literal>48;5;…</literal>. See <ulink
 522         url="https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters">ANSI
 523         Escape Code (Wikipedia)</ulink> for details.</para>
 524
 525         <xi:include href="version-info.xml" xpointer="v256"/>
 526         </listitem>
 527       </varlistentry>
 528
 529       <xi:include href="user-system-options.xml" xpointer="user" />
 530       <xi:include href="user-system-options.xml" xpointer="system" />
 531       <xi:include href="user-system-options.xml" xpointer="host" />
 532       <xi:include href="user-system-options.xml" xpointer="machine" />
 533       <xi:include href="user-system-options.xml" xpointer="capsule" />
 534
 535       <xi:include href="standard-options.xml" xpointer="no-ask-password" />
 536       <xi:include href="standard-options.xml" xpointer="help" />
 537       <xi:include href="standard-options.xml" xpointer="version" />
 538       <xi:include href="standard-options.xml" xpointer="json" />
 539     </variablelist>
 540
 541     <para>All command line arguments after the first non-option argument become part of the command line of
 542     the launched process.</para>
 543   </refsect1>
 544
 545   <refsect1>
 546     <title>Exit status</title>
 547
 548     <para>On success, 0 is returned. If <command>systemd-run</command> failed to start the service, a
 549     non-zero return value will be returned. If <command>systemd-run</command> waits for the service to
 550     terminate, the return value will be propagated from the service. 0 will be returned on success, including
 551     all the cases where systemd considers a service to have exited cleanly, see the discussion of
 552     <varname>SuccessExitStatus=</varname> in
 553     <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 554     </para>
 555   </refsect1>
 556
 557   <refsect1>
 558     <title>Examples</title>
 559
 560     <example>
 561       <title>Logging environment variables provided by systemd to services</title>
 562
 563       <programlisting># systemd-run env
 564 Running as unit: run-19945.service
 565 # journalctl -u run-19945.service
 566 Sep 08 07:37:21 bupkis systemd[1]: Starting /usr/bin/env...
 567 Sep 08 07:37:21 bupkis systemd[1]: Started /usr/bin/env.
 568 Sep 08 07:37:21 bupkis env[19948]: PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin
 569 Sep 08 07:37:21 bupkis env[19948]: LANG=en_US.UTF-8
 570 Sep 08 07:37:21 bupkis env[19948]: BOOT_IMAGE=/vmlinuz-3.11.0-0.rc5.git6.2.fc20.x86_64</programlisting>
 571     </example>
 572
 573     <example>
 574       <title>Limiting resources available to a command</title>
 575
 576       <programlisting># systemd-run -p IOWeight=10 updatedb</programlisting>
 577
 578       <para>This command invokes the <citerefentry
 579       project='man-pages'><refentrytitle>updatedb</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 580       tool, but lowers the block I/O weight for it to 10. See
 581       <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 582       for more information on the <varname>IOWeight=</varname> property.</para>
 583     </example>
 584
 585     <example>
 586       <title>Running commands at a specified time</title>
 587
 588       <para>The following command will touch a file after 30 seconds.</para>
 589
 590       <programlisting># date; systemd-run --on-active=30 --timer-property=AccuracySec=100ms /bin/touch /tmp/foo
 591 Mon Dec  8 20:44:24 KST 2014
 592 Running as unit: run-71.timer
 593 Will run service as unit: run-71.service
 594 # journalctl -b -u run-71.timer
 595 -- Journal begins at Fri 2014-12-05 19:09:21 KST, ends at Mon 2014-12-08 20:44:54 KST. --
 596 Dec 08 20:44:38 container systemd[1]: Starting /bin/touch /tmp/foo.
 597 Dec 08 20:44:38 container systemd[1]: Started /bin/touch /tmp/foo.
 598 # journalctl -b -u run-71.service
 599 -- Journal begins at Fri 2014-12-05 19:09:21 KST, ends at Mon 2014-12-08 20:44:54 KST. --
 600 Dec 08 20:44:48 container systemd[1]: Starting /bin/touch /tmp/foo...
 601 Dec 08 20:44:48 container systemd[1]: Started /bin/touch /tmp/foo.</programlisting>
 602     </example>
 603
 604     <example>
 605       <title>Allowing access to the tty</title>
 606
 607       <para>The following command invokes
 608       <citerefentry project='man-pages'><refentrytitle>bash</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 609       as a service passing its standard input, output and error to the calling TTY.</para>
 610
 611       <programlisting># systemd-run -t --send-sighup bash</programlisting>
 612     </example>
 613
 614     <example>
 615       <title>Start <command>screen</command> as a user service</title>
 616
 617       <programlisting>$ systemd-run --scope --user screen
 618 Running scope as unit run-r14b0047ab6df45bfb45e7786cc839e76.scope.
 619
 620 $ screen -ls
 621 There is a screen on:
 622         492..laptop     (Detached)
 623 1 Socket in /var/run/screen/S-fatima.
 624 </programlisting>
 625
 626       <para>This starts the <command>screen</command> process as a child of the
 627       <command>systemd --user</command> process that was started by
 628       <filename>user@.service</filename>, in a scope unit. A
 629       <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 630       unit is used instead of a
 631       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 632       unit, because <command>screen</command> will exit when detaching from the terminal,
 633       and a service unit would be terminated. Running <command>screen</command>
 634       as a user unit has the advantage that it is not part of the session scope.
 635       If <varname>KillUserProcesses=yes</varname> is configured in
 636       <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 637       the default, the session scope will be terminated when the user logs
 638       out of that session.</para>
 639
 640       <para>The <filename>user@.service</filename> is started automatically
 641       when the user first logs in, and stays around as long as at least one
 642       login session is open. After the user logs out of the last session,
 643       <filename>user@.service</filename> and all services underneath it
 644       are terminated. This behavior is the default, when "lingering" is
 645       not enabled for that user. Enabling lingering means that
 646       <filename>user@.service</filename> is started automatically during
 647       boot, even if the user is not logged in, and that the service is
 648       not terminated when the user logs out.</para>
 649
 650       <para>Enabling lingering allows the user to run processes without being logged in,
 651       for example to allow <command>screen</command> to persist after the user logs out,
 652       even if the session scope is terminated. In the default configuration, users can
 653       enable lingering for themselves:</para>
 654
 655       <programlisting>$ loginctl enable-linger</programlisting>
 656     </example>
 657
 658     <example>
 659       <title>Variable expansion by the manager</title>
 660
 661       <programlisting>$ systemd-run -t echo "&lt;${INVOCATION_ID}>" '&lt;${INVOCATION_ID}>'
 662       &lt;> &lt;5d0149bfa2c34b79bccb13074001eb20>
 663 </programlisting>
 664
 665       <para>The first argument is expanded by the shell (double quotes), but the second one is not expanded
 666       by the shell (single quotes).
 667       <citerefentry project='man-pages'><refentrytitle>echo</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 668       is called with [<literal>/usr/bin/echo</literal>,
 669       <literal>&lt;></literal>, <literal>&lt;${INVOCATION_ID}></literal>] as the argument array, and then
 670       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 671       generates <varname>${INVOCATION_ID}</varname> and substitutes it in the command-line. This substitution
 672       could not be done on the client side, because the target ID that will be set for the service is not
 673       known before the call is made.</para>
 674     </example>
 675
 676     <example>
 677       <title>Variable expansion and output redirection using a shell</title>
 678
 679       <para>Variable expansion by
 680       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 681       can be disabled with <varname>--expand-environment=no</varname>.</para>
 682
 683       <para>Disabling variable expansion can be useful if the command to execute contains dollar characters
 684       and escaping them would be inconvenient. For example, when a shell is used:</para>
 685
 686       <programlisting>$ systemd-run --expand-environment=no -t bash \
 687       -c 'echo $SHELL $$ >/dev/stdout'
 688 /bin/bash 12345
 689 </programlisting>
 690
 691       <para>The last argument is passed verbatim to the
 692       <citerefentry project='man-pages'><refentrytitle>bash</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 693       shell which is started by the service unit. The shell expands <literal>$SHELL</literal> to the path of
 694       the shell, and <literal>$$</literal> to its process number, and then those strings are passed to the
 695       <command>echo</command> built-in and printed to standard output (which, in this case, is connected to the
 696       calling terminal).</para>
 697     </example>
 698
 699     <example>
 700       <title>Return value</title>
 701
 702       <programlisting>$ systemd-run --user --wait true
 703 $ systemd-run --user --wait -p SuccessExitStatus=11 bash -c 'exit 11'
 704 $ systemd-run --user --wait -p SuccessExitStatus=SIGUSR1 --expand-environment=no \
 705       bash -c 'kill -SIGUSR1 $$'</programlisting>
 706
 707       <para>Those three invocations will succeed, i.e. terminate with an exit code of 0.</para>
 708     </example>
 709   </refsect1>
 710
 711   <refsect1>
 712     <title>See Also</title>
 713     <para><simplelist type="inline">
 714       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 715       <member><citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 716       <member><citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 717       <member><citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 718       <member><citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 719       <member><citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 720       <member><citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 721       <member><citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 722       <member><citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 723       <member><citerefentry><refentrytitle>systemd-mount</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 724       <member><citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 725       <member><citerefentry><refentrytitle>run0</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 726     </simplelist></para>
 727   </refsect1>
 728
 729 </refentry>