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