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