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 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7
   8 <!--
   9   This file is part of systemd.
  10
  11   Copyright 2013 Zbigniew Jędrzejewski-Szmek
  12
  13   systemd is free software; you can redistribute it and/or modify it
  14   under the terms of the GNU Lesser General Public License as published by
  15   the Free Software Foundation; either version 2.1 of the License, or
  16   (at your option) any later version.
  17
  18   systemd is distributed in the hope that it will be useful, but
  19   WITHOUT ANY WARRANTY; without even the implied warranty of
  20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  21   Lesser General Public License for more details.
  22
  23   You should have received a copy of the GNU Lesser General Public License
  24   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  25 -->
  26
  27 <refentry id="systemd-run"
  28           xmlns:xi="http://www.w3.org/2001/XInclude">
  29
  30   <refentryinfo>
  31     <title>systemd-run</title>
  32     <productname>systemd</productname>
  33
  34     <authorgroup>
  35       <author>
  36         <contrib>Developer</contrib>
  37         <firstname>Lennart</firstname>
  38         <surname>Poettering</surname>
  39         <email>lennart@poettering.net</email>
  40       </author>
  41     </authorgroup>
  42   </refentryinfo>
  43
  44   <refmeta>
  45     <refentrytitle>systemd-run</refentrytitle>
  46     <manvolnum>1</manvolnum>
  47   </refmeta>
  48
  49   <refnamediv>
  50     <refname>systemd-run</refname>
  51     <refpurpose>Run programs in transient scope or service or timer units</refpurpose>
  52   </refnamediv>
  53
  54   <refsynopsisdiv>
  55     <cmdsynopsis>
  56       <command>systemd-run</command>
  57       <arg choice="opt" rep="repeat">OPTIONS</arg>
  58       <arg choice="plain"><replaceable>COMMAND</replaceable>
  59       <arg choice="opt" rep="repeat">ARGS</arg>
  60       </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
  75     start a transient <filename>.service</filename> or a transient
  76     <filename>.timer</filename> or a <filename>.scope</filename> unit
  77     and run the specified <replaceable>COMMAND</replaceable> in
  78     it.</para>
  79
  80     <para>If a command is run as transient service unit, it will be
  81     started and managed by the service manager like any other service,
  82     and thus show up in the output of <command>systemctl
  83     list-units</command> like any other unit. It will run in a clean
  84     and detached execution environment. <command>systemd-run</command>
  85     will start the service asynchronously in the background and
  86     immediately return.</para>
  87
  88     <para>If a command is run with timer options, transient timer unit
  89     also be created with transient service unit. But the transient
  90     timer unit is only started immediately. The transient service unit
  91     will be started when the transient timer is elapsed. If
  92     <option>--unit=</option> is specified with timer options, the
  93     <replaceable>COMMAND</replaceable> can be omitted. In this case,
  94     <command>systemd-run</command> assumes service unit is already
  95     loaded and creates transient timer unit only. To successfully
  96     create timer unit, already loaded service unit should be specified
  97     with <option>--unit=</option>. This transient timer unit can
  98     activate the existing service unit like any other timer.</para>
  99
 100     <para>If a command is run as transient scope unit, it will be
 101     started directly by <command>systemd-run</command> and thus
 102     inherit the execution environment of the caller. It is however
 103     managed by the service manager similar to normal services, and
 104     will also show up in the output of <command>systemctl
 105     list-units</command>. Execution in this case is synchronous, and
 106     execution will return only when the command finishes.</para>
 107   </refsect1>
 108
 109   <refsect1>
 110     <title>Options</title>
 111
 112     <para>The following options are understood:</para>
 113
 114     <variablelist>
 115       <varlistentry>
 116         <term><option>--scope</option></term>
 117
 118         <listitem>
 119           <para>Create a transient <filename>.scope</filename> unit instead of
 120           the default transient <filename>.service</filename> unit.
 121           </para>
 122         </listitem>
 123       </varlistentry>
 124
 125       <varlistentry>
 126         <term><option>--unit=</option></term>
 127
 128         <listitem><para>Use this unit name instead of an automatically
 129         generated one.</para></listitem>
 130       </varlistentry>
 131
 132       <varlistentry>
 133         <term><option>--property=</option></term>
 134         <term><option>-p</option></term>
 135
 136         <listitem><para>Sets a unit property for the scope or service
 137         unit that is created. This takes an assignment in the same
 138         format as
 139         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 140         <command>set-property</command> command.</para>
 141         </listitem>
 142       </varlistentry>
 143
 144       <varlistentry>
 145         <term><option>--description=</option></term>
 146
 147         <listitem><para>Provide a description for the service or scope
 148         unit. If not specified, the command itself will be used as a
 149         description. See <varname>Description=</varname> in
 150         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 151         </para></listitem>
 152       </varlistentry>
 153
 154       <varlistentry>
 155         <term><option>--slice=</option></term>
 156
 157         <listitem><para>Make the new <filename>.service</filename> or
 158         <filename>.scope</filename> unit part of the specified slice,
 159         instead of the <filename>system.slice</filename>.</para>
 160         </listitem>
 161       </varlistentry>
 162
 163       <varlistentry>
 164         <term><option>--remain-after-exit</option></term>
 165
 166         <listitem><para>After the service or scope process has
 167         terminated, keep the service around until it is explicitly
 168         stopped. This is useful to collect runtime information about
 169         the service after it finished running. Also see
 170         <varname>RemainAfterExit=</varname> in
 171         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 172         </para>
 173         </listitem>
 174       </varlistentry>
 175
 176       <varlistentry>
 177         <term><option>--send-sighup</option></term>
 178
 179         <listitem><para>When terminating the scope or service unit,
 180         send a SIGHUP immediately after SIGTERM. This is useful to
 181         indicate to shells and shell-like processes that the
 182         connection has been severed. Also see
 183         <varname>SendSIGHUP=</varname> in
 184         <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 185         </para>
 186         </listitem>
 187       </varlistentry>
 188
 189       <varlistentry>
 190         <term><option>--service-type=</option></term>
 191
 192         <listitem><para>Sets the service type. Also see
 193         <varname>Type=</varname> in
 194         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This
 195         option has no effect in conjunction with
 196         <option>--scope</option>. Defaults to
 197         <constant>simple</constant>.</para>
 198         </listitem>
 199       </varlistentry>
 200
 201       <varlistentry>
 202         <term><option>--uid=</option></term>
 203         <term><option>--gid=</option></term>
 204
 205         <listitem><para>Runs the service process under the UNIX user
 206         and group. Also see <varname>User=</varname> and
 207         <varname>Group=</varname> in
 208         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 209         </listitem>
 210       </varlistentry>
 211
 212       <varlistentry>
 213         <term><option>--nice=</option></term>
 214
 215         <listitem><para>Runs the service process with the specified
 216         nice level. Also see <varname>Nice=</varname> in
 217         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 218         </listitem>
 219       </varlistentry>
 220
 221       <varlistentry>
 222         <term><option>--setenv=</option></term>
 223
 224         <listitem><para>Runs the service process with the specified
 225         environment variables set. Also see
 226         <varname>Environment=</varname> in
 227         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 228         </listitem>
 229       </varlistentry>
 230
 231       <varlistentry>
 232         <term><option>--pty</option></term>
 233         <term><option>-t</option></term>
 234
 235         <listitem><para>When invoking a command as service connects
 236         its standard input and output to the invoking tty via a
 237         pseudo TTY device. This allows invoking binaries as services
 238         that expect interactive user input, such as interactive
 239         command shells.</para></listitem>
 240       </varlistentry>
 241
 242       <varlistentry>
 243         <term><option>--quiet</option></term>
 244         <term><option>-q</option></term>
 245
 246         <listitem><para>Suppresses additional informational output
 247         while running. This is particularly useful in combination with
 248         <option>--pty</option> when it will suppress the initial
 249         message explaining how to terminate the TTY connection.</para></listitem>
 250       </varlistentry>
 251
 252       <varlistentry>
 253         <term><option>--on-active=</option></term>
 254         <term><option>--on-boot=</option></term>
 255         <term><option>--on-startup=</option></term>
 256         <term><option>--on-unit-active=</option></term>
 257         <term><option>--on-unit-inactive=</option></term>
 258
 259         <listitem><para>Defines monotonic timers relative to different
 260         starting points. Also see <varname>OnActiveSec=</varname>,
 261         <varname>OnBootSec=</varname>,
 262         <varname>OnStartupSec=</varname>,
 263         <varname>OnUnitActiveSec=</varname> and
 264         <varname>OnUnitInactiveSec=</varname> in
 265         <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This
 266         options have no effect in conjunction with
 267         <option>--scope</option>.</para>
 268         </listitem>
 269       </varlistentry>
 270
 271       <varlistentry>
 272         <term><option>--on-calendar=</option></term>
 273
 274         <listitem><para>Defines realtime (i.e. wallclock) timers with
 275         calendar event expressions. Also see
 276         <varname>OnCalendar=</varname> in
 277         <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This
 278         option has no effect in conjunction with
 279         <option>--scope</option>.</para>
 280         </listitem>
 281       </varlistentry>
 282
 283       <varlistentry>
 284         <term><option>--timer-property=</option></term>
 285
 286         <listitem><para>Sets a timer unit property for the timer unit
 287         that is created. It is similar with
 288         <option>--property</option> but only for created timer
 289         unit. This option only has effect in conjunction with
 290         <option>--on-active=</option>, <option>--on-boot=</option>,
 291         <option>--on-startup=</option>,
 292         <option>--on-unit-active=</option>,
 293         <option>--on-unit-inactive=</option>,
 294         <option>--on-calendar=</option>. This takes an assignment in
 295         the same format as
 296         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 297         <command>set-property</command> command.</para> </listitem>
 298       </varlistentry>
 299
 300       <varlistentry>
 301         <term><option>--no-block</option></term>
 302
 303         <listitem>
 304           <para>Do not synchronously wait for the requested operation
 305           to finish. If this is not specified, the job will be
 306           verified, enqueued and <command>systemd-run</command> will
 307           wait until the unit's start-up is completed. By passing this
 308           argument, it is only verified and enqueued.</para>
 309         </listitem>
 310       </varlistentry>
 311
 312       <xi:include href="user-system-options.xml" xpointer="user" />
 313       <xi:include href="user-system-options.xml" xpointer="system" />
 314       <xi:include href="user-system-options.xml" xpointer="host" />
 315       <xi:include href="user-system-options.xml" xpointer="machine" />
 316
 317       <xi:include href="standard-options.xml" xpointer="help" />
 318       <xi:include href="standard-options.xml" xpointer="version" />
 319     </variablelist>
 320
 321     <para>All command line arguments after the first non-option
 322     argument become part of the command line of the launched
 323     process. If a command is run as service unit, its first argument
 324     needs to be an absolute binary path.</para>
 325   </refsect1>
 326
 327   <refsect1>
 328     <title>Exit status</title>
 329
 330     <para>On success, 0 is returned, a non-zero failure
 331     code otherwise.</para>
 332   </refsect1>
 333
 334   <refsect1>
 335     <title>Examples</title>
 336
 337     <para>The following command will log the environment variables
 338     provided by systemd to services:</para>
 339
 340     <programlisting># systemd-run env
 341 Running as unit run-19945.service.
 342 # journalctl -u run-19945.service
 343 Sep 08 07:37:21 bupkis systemd[1]: Starting /usr/bin/env...
 344 Sep 08 07:37:21 bupkis systemd[1]: Started /usr/bin/env.
 345 Sep 08 07:37:21 bupkis env[19948]: PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin
 346 Sep 08 07:37:21 bupkis env[19948]: LANG=en_US.UTF-8
 347 Sep 08 07:37:21 bupkis env[19948]: BOOT_IMAGE=/vmlinuz-3.11.0-0.rc5.git6.2.fc20.x86_64</programlisting>
 348
 349     <para>The following command invokes the
 350     <citerefentry project='man-pages'><refentrytitle>updatedb</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 351     tool, but lowers the block IO weight for it to 10. See
 352     <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 353     for more information on the <varname>BlockIOWeight=</varname>
 354     property.</para>
 355
 356     <programlisting># systemd-run -p BlockIOWeight=10 updatedb</programlisting>
 357
 358     <para>The following command will touch a file after 30 seconds.</para>
 359
 360     <programlisting># date; systemd-run --on-active=30 --timer-property=AccuracySec=100ms /bin/touch /tmp/foo
 361 Mon Dec  8 20:44:24 KST 2014
 362 Running as unit run-71.timer.
 363 Will run as unit run-71.service.
 364 # journalctl -b -u run-71.timer
 365 -- Logs begin at Fri 2014-12-05 19:09:21 KST, end at Mon 2014-12-08 20:44:54 KST. --
 366 Dec 08 20:44:38 container systemd[1]: Starting /bin/touch /tmp/foo.
 367 Dec 08 20:44:38 container systemd[1]: Started /bin/touch /tmp/foo.
 368 # journalctl -b -u run-71.service
 369 -- Logs begin at Fri 2014-12-05 19:09:21 KST, end at Mon 2014-12-08 20:44:54 KST. --
 370 Dec 08 20:44:48 container systemd[1]: Starting /bin/touch /tmp/foo...
 371 Dec 08 20:44:48 container systemd[1]: Started /bin/touch /tmp/foo.</programlisting>
 372
 373     <para>The following command invokes <filename>/bin/bash</filename>
 374     as a service passing its standard input, output and error to
 375     the calling TTY.</para>
 376
 377     <programlisting># systemd-run -t /bin/bash</programlisting>
 378
 379   </refsect1>
 380
 381   <refsect1>
 382     <title>See Also</title>
 383     <para>
 384       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 385       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 386       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 387       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 388       <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 389       <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 390       <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 391       <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 392       <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 393       <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 394     </para>
 395   </refsect1>
 396
 397 </refentry>