man/systemd-run.xml

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