man/systemd-run.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="systemd-run"
  10           xmlns:xi="http://www.w3.org/2001/XInclude">
  11
  12   <refentryinfo>
  13     <title>systemd-run</title>
  14     <productname>systemd</productname>
  15   </refentryinfo>
  16
  17   <refmeta>
  18     <refentrytitle>systemd-run</refentrytitle>
  19     <manvolnum>1</manvolnum>
  20   </refmeta>
  21
  22   <refnamediv>
  23     <refname>systemd-run</refname>
  24     <refpurpose>Run programs in transient scope units, service units, or path-, socket-, or timer-triggered service units</refpurpose>
  25   </refnamediv>
  26
  27   <refsynopsisdiv>
  28     <cmdsynopsis>
  29       <command>systemd-run</command>
  30       <arg choice="opt" rep="repeat">OPTIONS</arg>
  31       <arg choice="plain"><replaceable>COMMAND</replaceable>
  32       <arg choice="opt" rep="repeat">ARGS</arg>
  33       </arg>
  34     </cmdsynopsis>
  35     <cmdsynopsis>
  36       <command>systemd-run</command>
  37       <arg choice="opt" rep="repeat">OPTIONS</arg>
  38       <arg choice="opt" rep="repeat">PATH OPTIONS</arg>
  39       <arg choice="req"><replaceable>COMMAND</replaceable></arg>
  40       <arg choice="opt" rep="repeat">ARGS</arg>
  41     </cmdsynopsis>
  42     <cmdsynopsis>
  43       <command>systemd-run</command>
  44       <arg choice="opt" rep="repeat">OPTIONS</arg>
  45       <arg choice="opt" rep="repeat">SOCKET OPTIONS</arg>
  46       <arg choice="req"><replaceable>COMMAND</replaceable></arg>
  47       <arg choice="opt" rep="repeat">ARGS</arg>
  48     </cmdsynopsis>
  49     <cmdsynopsis>
  50       <command>systemd-run</command>
  51       <arg choice="opt" rep="repeat">OPTIONS</arg>
  52       <arg choice="opt" rep="repeat">TIMER OPTIONS</arg>
  53       <arg choice="req"><replaceable>COMMAND</replaceable></arg>
  54       <arg choice="opt" rep="repeat">ARGS</arg>
  55     </cmdsynopsis>
  56   </refsynopsisdiv>
  57
  58   <refsect1>
  59     <title>Description</title>
  60
  61     <para><command>systemd-run</command> may be used to create and start a transient <filename>.service</filename> or
  62     <filename>.scope</filename> unit and run the specified <replaceable>COMMAND</replaceable> in it. It may also be
  63     used to create and start a transient <filename>.path</filename>, <filename>.socket</filename>, or
  64     <filename>.timer</filename> unit, that activates a <filename>.service</filename> unit when elapsing.</para>
  65
  66     <para>If a command is run as transient service unit, it will be started and managed by the service manager like any
  67     other service, and thus shows up in the output of <command>systemctl list-units</command> like any other unit. It
  68     will run in a clean and detached execution environment, with the service manager as its parent process. In this
  69     mode, <command>systemd-run</command> will start the service asynchronously in the background and return after the
  70     command has begun execution (unless <option>--no-block</option> or <option>--wait</option> are specified, see
  71     below).</para>
  72
  73     <para>If a command is run as transient scope unit, it will be executed by <command>systemd-run</command> itself as
  74     parent process and will thus inherit the execution environment of the caller. However, the processes of the command
  75     are managed by the service manager similar to normal services, and will show up in the output of <command>systemctl
  76     list-units</command>. Execution in this case is synchronous, and will return only when the command finishes. This
  77     mode is enabled via the <option>--scope</option> switch (see below). </para>
  78
  79     <para>If a command is run with path, socket, or timer options such as <option>--on-calendar=</option> (see below),
  80     a transient path, socket, or timer unit is created alongside the service unit for the specified command. Only the
  81     transient path, socket, or timer unit is started immediately, the transient service unit will be triggered by the
  82     path, socket, or timer unit. If the <option>--unit=</option> option is specified, the
  83     <replaceable>COMMAND</replaceable> may be omitted. In this case, <command>systemd-run</command> creates only a
  84     <filename>.path</filename>, <filename>.socket</filename>, or <filename>.timer</filename> unit that triggers the
  85     specified unit.</para>
  86   </refsect1>
  87
  88   <refsect1>
  89     <title>Options</title>
  90
  91     <para>The following options are understood:</para>
  92
  93     <variablelist>
  94       <varlistentry>
  95         <term><option>--no-ask-password</option></term>
  96
  97         <listitem><para>Do not query the user for authentication for
  98         privileged operations.</para></listitem>
  99       </varlistentry>
 100
 101       <varlistentry>
 102         <term><option>--scope</option></term>
 103
 104         <listitem>
 105           <para>Create a transient <filename>.scope</filename> unit instead of the default transient
 106           <filename>.service</filename> unit (see above).
 107           </para>
 108         </listitem>
 109       </varlistentry>
 110
 111       <varlistentry>
 112         <term><option>--unit=</option></term>
 113
 114         <listitem><para>Use this unit name instead of an automatically
 115         generated one.</para></listitem>
 116       </varlistentry>
 117
 118       <varlistentry>
 119         <term><option>--property=</option></term>
 120         <term><option>-p</option></term>
 121
 122         <listitem><para>Sets a property on the scope or service unit that is created. This option takes an assignment
 123         in the same format as
 124         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 125         <command>set-property</command> command.</para>
 126         </listitem>
 127       </varlistentry>
 128
 129       <varlistentry>
 130         <term><option>--description=</option></term>
 131
 132         <listitem><para>Provide a description for the service, scope, path, socket, or timer unit. If not specified,
 133         the command itself will be used as a description. See <varname>Description=</varname> in
 134         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 135         </para></listitem>
 136       </varlistentry>
 137
 138       <varlistentry>
 139         <term><option>--slice=</option></term>
 140
 141         <listitem><para>Make the new <filename>.service</filename> or <filename>.scope</filename> unit part of the
 142         specified slice, instead of <filename>system.slice</filename>.</para>
 143         </listitem>
 144       </varlistentry>
 145
 146       <varlistentry>
 147         <term><option>-r</option></term>
 148         <term><option>--remain-after-exit</option></term>
 149
 150         <listitem><para>After the service process has terminated, keep the service around until it is explicitly
 151         stopped. This is useful to collect runtime information about the service after it finished running. Also see
 152         <varname>RemainAfterExit=</varname> in
 153         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 154         </para>
 155         </listitem>
 156       </varlistentry>
 157
 158       <varlistentry>
 159         <term><option>--send-sighup</option></term>
 160
 161         <listitem><para>When terminating the scope or service unit, send a SIGHUP immediately after SIGTERM. This is
 162         useful to indicate to shells and shell-like processes that the connection has been severed. Also see
 163         <varname>SendSIGHUP=</varname> in
 164         <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 165         </para>
 166         </listitem>
 167       </varlistentry>
 168
 169       <varlistentry>
 170         <term><option>--service-type=</option></term>
 171
 172         <listitem><para>Sets the service type. Also see
 173         <varname>Type=</varname> in
 174         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This
 175         option has no effect in conjunction with
 176         <option>--scope</option>. Defaults to
 177         <constant>simple</constant>.</para>
 178         </listitem>
 179       </varlistentry>
 180
 181       <varlistentry>
 182         <term><option>--uid=</option></term>
 183         <term><option>--gid=</option></term>
 184
 185         <listitem><para>Runs the service process under the specified UNIX user and group. Also see
 186         <varname>User=</varname> and <varname>Group=</varname> in
 187         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 188         </listitem>
 189       </varlistentry>
 190
 191       <varlistentry>
 192         <term><option>--nice=</option></term>
 193
 194         <listitem><para>Runs the service process with the specified
 195         nice level. Also see <varname>Nice=</varname> in
 196         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 197         </listitem>
 198       </varlistentry>
 199
 200       <varlistentry>
 201         <term><option>-E <replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term>
 202         <term><option>--setenv=<replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term>
 203
 204         <listitem><para>Runs the service process with the specified environment variable set.
 205         Also see <varname>Environment=</varname> in
 206         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 207         </listitem>
 208       </varlistentry>
 209
 210       <varlistentry>
 211         <term><option>--pty</option></term>
 212         <term><option>-t</option></term>
 213
 214         <listitem><para>When invoking the command, the transient service connects its standard input, output and error
 215         to the terminal <command>systemd-run</command> is invoked on, via a pseudo TTY device. This allows running
 216         programs that expect interactive user input/output as services, such as interactive command shells.</para>
 217
 218         <para>Note that
 219         <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 220         <command>shell</command> command is usually a better alternative for requesting a new, interactive login
 221         session on the local host or a local container.</para>
 222
 223         <para>See below for details on how this switch combines with <option>--pipe</option>.</para></listitem>
 224       </varlistentry>
 225
 226       <varlistentry>
 227         <term><option>--pipe</option></term>
 228         <term><option>-P</option></term>
 229
 230         <listitem><para>If specified, standard input, output, and error of the transient service are inherited from the
 231         <command>systemd-run</command> command itself. This allows <command>systemd-run</command>
 232         to be used within shell pipelines.
 233         Note that this mode is not suitable for interactive command shells and similar, as the
 234         service process will not become a TTY controller when invoked on a terminal. Use <option>--pty</option> instead
 235         in that case.</para>
 236
 237         <para>When both <option>--pipe</option> and <option>--pty</option> are used in combination the more appropriate
 238         option is automatically determined and used. Specifically, when invoked with standard input, output and error
 239         connected to a TTY <option>--pty</option> is used, and otherwise <option>--pipe</option>.</para>
 240
 241         <para>When this option is used the original file descriptors <command>systemd-run</command> receives are passed
 242         to the service processes as-is. If the service runs with different privileges than
 243         <command>systemd-run</command>, this means the service might not be able to re-open the passed file
 244         descriptors, due to normal file descriptor access restrictions. If the invoked process is a shell script that
 245         uses the <command>echo "hello" > /dev/stderr</command> construct for writing messages to stderr, this might
 246         cause problems, as this only works if stderr can be re-opened. To mitigate this use the construct <command>echo
 247         "hello" >&amp;2</command> instead, which is mostly equivalent and avoids this pitfall.</para></listitem>
 248       </varlistentry>
 249
 250       <varlistentry>
 251         <term><option>--quiet</option></term>
 252         <term><option>-q</option></term>
 253
 254         <listitem><para>Suppresses additional informational output
 255         while running. This is particularly useful in combination with
 256         <option>--pty</option> when it will suppress the initial
 257         message explaining how to terminate the TTY connection.</para></listitem>
 258       </varlistentry>
 259
 260       <varlistentry>
 261         <term><option>--on-active=</option></term>
 262         <term><option>--on-boot=</option></term>
 263         <term><option>--on-startup=</option></term>
 264         <term><option>--on-unit-active=</option></term>
 265         <term><option>--on-unit-inactive=</option></term>
 266
 267         <listitem><para>Defines a monotonic timer relative to different starting points for starting the specified
 268         command. See <varname>OnActiveSec=</varname>, <varname>OnBootSec=</varname>, <varname>OnStartupSec=</varname>,
 269         <varname>OnUnitActiveSec=</varname> and <varname>OnUnitInactiveSec=</varname> in
 270         <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 271         details. These options are shortcuts for <command>--timer-property=</command> with the relevant properties.
 272         These options may not be combined with <option>--scope</option> or <option>--pty</option>.</para>
 273         </listitem>
 274       </varlistentry>
 275
 276       <varlistentry>
 277         <term><option>--on-calendar=</option></term>
 278
 279         <listitem><para>Defines a calendar timer for starting the specified command. See <varname>OnCalendar=</varname>
 280         in <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This
 281         option is a shortcut for <command>--timer-property=OnCalendar=</command>. This option may not be combined with
 282         <option>--scope</option> or <option>--pty</option>.</para>
 283         </listitem>
 284       </varlistentry>
 285
 286       <varlistentry>
 287         <term><option>--path-property=</option></term>
 288         <term><option>--socket-property=</option></term>
 289         <term><option>--timer-property=</option></term>
 290
 291         <listitem><para>Sets a property on the path, socket, or timer unit that is created. This option is similar to
 292         <option>--property=</option> but applies to the transient path, socket, or timer unit rather than the
 293         transient service unit created. This option takes an assignment in the same format as
 294         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 295         <command>set-property</command> command. These options may not be combined with
 296         <option>--scope</option> or <option>--pty</option>.</para>
 297         </listitem>
 298       </varlistentry>
 299
 300       <varlistentry>
 301         <term><option>--no-block</option></term>
 302
 303         <listitem>
 304           <para>Do not synchronously wait for the unit start operation to finish. If this option is not specified, the
 305           start request for the transient unit will be verified, enqueued and <command>systemd-run</command> will wait
 306           until the unit's start-up is completed. By passing this argument, it is only verified and enqueued. This
 307           option may not be combined with <option>--wait</option>.</para>
 308         </listitem>
 309       </varlistentry>
 310
 311       <varlistentry>
 312         <term><option>--wait</option></term>
 313
 314         <listitem><para>Synchronously wait for the transient service to terminate. If this option is specified, the
 315         start request for the transient unit is verified, enqueued, and waited for. Subsequently the invoked unit is
 316         monitored, and it is waited until it is deactivated again (most likely because the specified command
 317         completed). On exit, terse information about the unit's runtime is shown, including total runtime (as well as
 318         CPU usage, if <option>--property=CPUAccounting=1</option> was set) and the exit code and status of the main
 319         process. This output may be suppressed with <option>--quiet</option>. This option may not be combined with
 320         <option>--no-block</option>, <option>--scope</option> or the various path, socket, or timer options.</para></listitem>
 321       </varlistentry>
 322
 323       <varlistentry>
 324         <term><option>-G</option></term>
 325         <term><option>--collect</option></term>
 326
 327         <listitem><para>Unload the transient unit after it completed, even if it failed. Normally, without this option,
 328         all units that ran and failed are kept in memory until the user explicitly resets their failure state with
 329         <command>systemctl reset-failed</command> or an equivalent command. On the other hand, units that ran
 330         successfully are unloaded immediately. If this option is turned on the "garbage collection" of units is more
 331         aggressive, and unloads units regardless if they exited successfully or failed. This option is a shortcut for
 332         <command>--property=CollectMode=inactive-or-failed</command>, see the explanation for
 333         <varname>CollectMode=</varname> in
 334         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for further
 335         information.</para></listitem>
 336       </varlistentry>
 337
 338       <xi:include href="user-system-options.xml" xpointer="user" />
 339       <xi:include href="user-system-options.xml" xpointer="system" />
 340       <xi:include href="user-system-options.xml" xpointer="host" />
 341       <xi:include href="user-system-options.xml" xpointer="machine" />
 342
 343       <xi:include href="standard-options.xml" xpointer="help" />
 344       <xi:include href="standard-options.xml" xpointer="version" />
 345     </variablelist>
 346
 347     <para>All command line arguments after the first non-option
 348     argument become part of the command line of the launched
 349     process. If a command is run as service unit, the first argument
 350     needs to be an absolute program path.</para>
 351   </refsect1>
 352
 353   <refsect1>
 354     <title>Exit status</title>
 355
 356     <para>On success, 0 is returned, a non-zero failure
 357     code otherwise.</para>
 358   </refsect1>
 359
 360   <refsect1>
 361     <title>Examples</title>
 362
 363     <example>
 364       <title>Logging environment variables provided by systemd to services</title>
 365
 366       <programlisting># systemd-run env
 367 Running as unit: run-19945.service
 368 # journalctl -u run-19945.service
 369 Sep 08 07:37:21 bupkis systemd[1]: Starting /usr/bin/env...
 370 Sep 08 07:37:21 bupkis systemd[1]: Started /usr/bin/env.
 371 Sep 08 07:37:21 bupkis env[19948]: PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin
 372 Sep 08 07:37:21 bupkis env[19948]: LANG=en_US.UTF-8
 373 Sep 08 07:37:21 bupkis env[19948]: BOOT_IMAGE=/vmlinuz-3.11.0-0.rc5.git6.2.fc20.x86_64</programlisting>
 374     </example>
 375
 376     <example>
 377       <title>Limiting resources available to a command</title>
 378
 379       <programlisting># systemd-run -p BlockIOWeight=10 updatedb</programlisting>
 380
 381       <para>This command invokes the
 382       <citerefentry project='man-pages'><refentrytitle>updatedb</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 383       tool, but lowers the block I/O weight for it to 10. See
 384       <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 385       for more information on the <varname>BlockIOWeight=</varname>
 386       property.</para>
 387     </example>
 388
 389     <example>
 390       <title>Running commands at a specified time</title>
 391
 392       <para>The following command will touch a file after 30 seconds.</para>
 393
 394       <programlisting># date; systemd-run --on-active=30 --timer-property=AccuracySec=100ms /bin/touch /tmp/foo
 395 Mon Dec  8 20:44:24 KST 2014
 396 Running as unit: run-71.timer
 397 Will run service as unit: run-71.service
 398 # journalctl -b -u run-71.timer
 399 -- Logs begin at Fri 2014-12-05 19:09:21 KST, end at Mon 2014-12-08 20:44:54 KST. --
 400 Dec 08 20:44:38 container systemd[1]: Starting /bin/touch /tmp/foo.
 401 Dec 08 20:44:38 container systemd[1]: Started /bin/touch /tmp/foo.
 402 # journalctl -b -u run-71.service
 403 -- Logs begin at Fri 2014-12-05 19:09:21 KST, end at Mon 2014-12-08 20:44:54 KST. --
 404 Dec 08 20:44:48 container systemd[1]: Starting /bin/touch /tmp/foo...
 405 Dec 08 20:44:48 container systemd[1]: Started /bin/touch /tmp/foo.</programlisting>
 406     </example>
 407
 408     <example>
 409       <title>Allowing access to the tty</title>
 410
 411       <para>The following command invokes <filename>/bin/bash</filename> as a service
 412       passing its standard input, output and error to the calling TTY.</para>
 413
 414       <programlisting># systemd-run -t --send-sighup /bin/bash</programlisting>
 415     </example>
 416
 417     <example>
 418       <title>Start <command>screen</command> as a user service</title>
 419
 420       <programlisting>$ systemd-run --scope --user screen
 421 Running scope as unit run-r14b0047ab6df45bfb45e7786cc839e76.scope.
 422
 423 $ screen -ls
 424 There is a screen on:
 425         492..laptop     (Detached)
 426 1 Socket in /var/run/screen/S-fatima.
 427 </programlisting>
 428
 429       <para>This starts the <command>screen</command> process as a child of the
 430       <command>systemd --user</command> process that was started by
 431       <filename>user@.service</filename>, in a scope unit. A
 432       <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 433       unit is used instead of a
 434       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 435       unit, because <command>screen</command> will exit when detaching from the terminal,
 436       and a service unit would be terminated. Running <command>screen</command>
 437       as a user unit has the advantage that it is not part of the session scope.
 438       If <varname>KillUserProcesses=yes</varname> is configured in
 439       <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 440       the default, the session scope will be terminated when the user logs
 441       out of that session.</para>
 442
 443       <para>The <filename>user@.service</filename> is started automatically
 444       when the user first logs in, and stays around as long as at least one
 445       login session is open. After the user logs out of the last session,
 446       <filename>user@.service</filename> and all services underneath it
 447       are terminated. This behavior is the default, when "lingering" is
 448       not enabled for that user. Enabling lingering means that
 449       <filename>user@.service</filename> is started automatically during
 450       boot, even if the user is not logged in, and that the service is
 451       not terminated when the user logs out.</para>
 452
 453       <para>Enabling lingering allows the user to run processes without being logged in,
 454       for example to allow <command>screen</command> to persist after the user logs out,
 455       even if the session scope is terminated. In the default configuration, users can
 456       enable lingering for themselves:</para>
 457
 458       <programlisting>$ loginctl enable-linger</programlisting>
 459     </example>
 460   </refsect1>
 461
 462   <refsect1>
 463     <title>See Also</title>
 464     <para>
 465       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 466       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 467       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 468       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 469       <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 470       <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 471       <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 472       <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 473       <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 474       <citerefentry><refentrytitle>systemd-mount</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 475       <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 476     </para>
 477   </refsect1>
 478
 479 </refentry>