1SYSTEMD-RUN(1)                    systemd-run                   SYSTEMD-RUN(1)
2
3
4

NAME

6       systemd-run - Run programs in transient scope units, service units, or
7       path-, socket-, or timer-triggered service units
8

SYNOPSIS

10       systemd-run [OPTIONS...] COMMAND [ARGS...]
11
12       systemd-run [OPTIONS...] [PATH OPTIONS...] {COMMAND} [ARGS...]
13
14       systemd-run [OPTIONS...] [SOCKET OPTIONS...] {COMMAND} [ARGS...]
15
16       systemd-run [OPTIONS...] [TIMER OPTIONS...] {COMMAND} [ARGS...]
17

DESCRIPTION

19       systemd-run may be used to create and start a transient .service or
20       .scope unit and run the specified COMMAND in it. It may also be used to
21       create and start a transient .path, .socket, or .timer unit, that
22       activates a .service unit when elapsing.
23
24       If a command is run as transient service unit, it will be started and
25       managed by the service manager like any other service, and thus shows
26       up in the output of systemctl list-units like any other unit. It will
27       run in a clean and detached execution environment, with the service
28       manager as its parent process. In this mode, systemd-run will start the
29       service asynchronously in the background and return after the command
30       has begun execution (unless --no-block or --wait are specified, see
31       below).
32
33       If a command is run as transient scope unit, it will be executed by
34       systemd-run itself as parent process and will thus inherit the
35       execution environment of the caller. However, the processes of the
36       command are managed by the service manager similar to normal services,
37       and will show up in the output of systemctl list-units. Execution in
38       this case is synchronous, and will return only when the command
39       finishes. This mode is enabled via the --scope switch (see below).
40
41       If a command is run with path, socket, or timer options such as
42       --on-calendar= (see below), a transient path, socket, or timer unit is
43       created alongside the service unit for the specified command. Only the
44       transient path, socket, or timer unit is started immediately, the
45       transient service unit will be triggered by the path, socket, or timer
46       unit. If the --unit= option is specified, the COMMAND may be omitted.
47       In this case, systemd-run creates only a .path, .socket, or .timer unit
48       that triggers the specified unit.
49
50       By default, services created with systemd-run default to the simple
51       type, see the description of Type= in systemd.service(5) for details.
52       Note that when this type is used the service manager (and thus the
53       systemd-run command) considers service start-up successful as soon as
54       the fork() for the main service process succeeded, i.e. before the
55       execve() is invoked, and thus even if the specified command cannot be
56       started. Consider using the exec service type (i.e.
57       --property=Type=exec) to ensure that systemd-run returns successfully
58       only if the specified command line has been successfully started.
59

OPTIONS

61       The following options are understood:
62
63       --no-ask-password
64           Do not query the user for authentication for privileged operations.
65
66       --scope
67           Create a transient .scope unit instead of the default transient
68           .service unit (see above).
69
70       --unit=, -u
71           Use this unit name instead of an automatically generated one.
72
73       --property=, -p
74           Sets a property on the scope or service unit that is created. This
75           option takes an assignment in the same format as systemctl(1)'s
76           set-property command.
77
78       --description=
79           Provide a description for the service, scope, path, socket, or
80           timer unit. If not specified, the command itself will be used as a
81           description. See Description= in systemd.unit(5).
82
83       --slice=
84           Make the new .service or .scope unit part of the specified slice,
85           instead of system.slice (when running in --system mode) or the root
86           slice (when running in --user mode).
87
88       --slice-inherit
89           Make the new .service or .scope unit part of the inherited slice.
90           This option can be combined with --slice=.
91
92           An inherited slice is located within systemd-run slice. Example: if
93           systemd-run slice is foo.slice, and the --slice= argument is bar,
94           the unit will be placed under the foo-bar.slice.
95
96       -r, --remain-after-exit
97           After the service process has terminated, keep the service around
98           until it is explicitly stopped. This is useful to collect runtime
99           information about the service after it finished running. Also see
100           RemainAfterExit= in systemd.service(5).
101
102       --send-sighup
103           When terminating the scope or service unit, send a SIGHUP
104           immediately after SIGTERM. This is useful to indicate to shells and
105           shell-like processes that the connection has been severed. Also see
106           SendSIGHUP= in systemd.kill(5).
107
108       --service-type=
109           Sets the service type. Also see Type= in systemd.service(5). This
110           option has no effect in conjunction with --scope. Defaults to
111           simple.
112
113       --uid=, --gid=
114           Runs the service process under the specified UNIX user and group.
115           Also see User= and Group= in systemd.exec(5).
116
117       --nice=
118           Runs the service process with the specified nice level. Also see
119           Nice= in systemd.exec(5).
120
121       --working-directory=
122           Runs the service process with the specified working directory. Also
123           see WorkingDirectory= in systemd.exec(5).
124
125       --same-dir, -d
126           Similar to --working-directory= but uses the current working
127           directory of the caller for the service to execute.
128
129       -E NAME[=VALUE], --setenv=NAME[=VALUE]
130           Runs the service process with the specified environment variable
131           set. This parameter may be used more than once to set multiple
132           variables. When "=" and VALUE are omitted, the value of the
133           variable with the same name in the program environment will be
134           used.
135
136           Also see Environment= in systemd.exec(5).
137
138       --pty, -t
139           When invoking the command, the transient service connects its
140           standard input, output and error to the terminal systemd-run is
141           invoked on, via a pseudo TTY device. This allows running programs
142           that expect interactive user input/output as services, such as
143           interactive command shells.
144
145           Note that machinectl(1)'s shell command is usually a better
146           alternative for requesting a new, interactive login session on the
147           local host or a local container.
148
149           See below for details on how this switch combines with --pipe.
150
151       --pipe, -P
152           If specified, standard input, output, and error of the transient
153           service are inherited from the systemd-run command itself. This
154           allows systemd-run to be used within shell pipelines. Note that
155           this mode is not suitable for interactive command shells and
156           similar, as the service process will not become a TTY controller
157           when invoked on a terminal. Use --pty instead in that case.
158
159           When both --pipe and --pty are used in combination the more
160           appropriate option is automatically determined and used.
161           Specifically, when invoked with standard input, output and error
162           connected to a TTY --pty is used, and otherwise --pipe.
163
164           When this option is used the original file descriptors systemd-run
165           receives are passed to the service processes as-is. If the service
166           runs with different privileges than systemd-run, this means the
167           service might not be able to re-open the passed file descriptors,
168           due to normal file descriptor access restrictions. If the invoked
169           process is a shell script that uses the echo "hello" > /dev/stderr
170           construct for writing messages to stderr, this might cause
171           problems, as this only works if stderr can be re-opened. To
172           mitigate this use the construct echo "hello" >&2 instead, which is
173           mostly equivalent and avoids this pitfall.
174
175       --shell, -S
176           A shortcut for "--pty --same-dir --wait --collect
177           --service-type=exec $SHELL", i.e. requests an interactive shell in
178           the current working directory, running in service context,
179           accessible with a single switch.
180
181       --quiet, -q
182           Suppresses additional informational output while running. This is
183           particularly useful in combination with --pty when it will suppress
184           the initial message explaining how to terminate the TTY connection.
185
186       --on-active=, --on-boot=, --on-startup=, --on-unit-active=,
187       --on-unit-inactive=
188           Defines a monotonic timer relative to different starting points for
189           starting the specified command. See OnActiveSec=, OnBootSec=,
190           OnStartupSec=, OnUnitActiveSec= and OnUnitInactiveSec= in
191           systemd.timer(5) for details. These options are shortcuts for
192           --timer-property= with the relevant properties. These options may
193           not be combined with --scope or --pty.
194
195       --on-calendar=
196           Defines a calendar timer for starting the specified command. See
197           OnCalendar= in systemd.timer(5). This option is a shortcut for
198           --timer-property=OnCalendar=. This option may not be combined with
199           --scope or --pty.
200
201       --on-clock-change, --on-timezone-change
202           Defines a trigger based on system clock jumps or timezone changes
203           for starting the specified command. See OnClockChange= and
204           OnTimezoneChange= in systemd.timer(5). These options are shortcuts
205           for --timer-property=OnClockChange=yes and
206           --timer-property=OnTimezoneChange=yes. These options may not be
207           combined with --scope or --pty.
208
209       --path-property=, --socket-property=, --timer-property=
210           Sets a property on the path, socket, or timer unit that is created.
211           This option is similar to --property= but applies to the transient
212           path, socket, or timer unit rather than the transient service unit
213           created. This option takes an assignment in the same format as
214           systemctl(1)'s set-property command. These options may not be
215           combined with --scope or --pty.
216
217       --no-block
218           Do not synchronously wait for the unit start operation to finish.
219           If this option is not specified, the start request for the
220           transient unit will be verified, enqueued and systemd-run will wait
221           until the unit's start-up is completed. By passing this argument,
222           it is only verified and enqueued. This option may not be combined
223           with --wait.
224
225       --wait
226           Synchronously wait for the transient service to terminate. If this
227           option is specified, the start request for the transient unit is
228           verified, enqueued, and waited for. Subsequently the invoked unit
229           is monitored, and it is waited until it is deactivated again (most
230           likely because the specified command completed). On exit, terse
231           information about the unit's runtime is shown, including total
232           runtime (as well as CPU usage, if --property=CPUAccounting=1 was
233           set) and the exit code and status of the main process. This output
234           may be suppressed with --quiet. This option may not be combined
235           with --no-block, --scope or the various path, socket, or timer
236           options.
237
238       -G, --collect
239           Unload the transient unit after it completed, even if it failed.
240           Normally, without this option, all units that ran and failed are
241           kept in memory until the user explicitly resets their failure state
242           with systemctl reset-failed or an equivalent command. On the other
243           hand, units that ran successfully are unloaded immediately. If this
244           option is turned on the "garbage collection" of units is more
245           aggressive, and unloads units regardless if they exited
246           successfully or failed. This option is a shortcut for
247           --property=CollectMode=inactive-or-failed, see the explanation for
248           CollectMode= in systemd.unit(5) for further information.
249
250       --user
251           Talk to the service manager of the calling user, rather than the
252           service manager of the system.
253
254       --system
255           Talk to the service manager of the system. This is the implied
256           default.
257
258       -H, --host=
259           Execute the operation remotely. Specify a hostname, or a username
260           and hostname separated by "@", to connect to. The hostname may
261           optionally be suffixed by a port ssh is listening on, separated by
262           ":", and then a container name, separated by "/", which connects
263           directly to a specific container on the specified host. This will
264           use SSH to talk to the remote machine manager instance. Container
265           names may be enumerated with machinectl -H HOST. Put IPv6 addresses
266           in brackets.
267
268       -M, --machine=
269           Execute operation on a local container. Specify a container name to
270           connect to, optionally prefixed by a user name to connect as and a
271           separating "@" character. If the special string ".host" is used in
272           place of the container name, a connection to the local system is
273           made (which is useful to connect to a specific user's user bus:
274           "--user --machine=lennart@.host"). If the "@" syntax is not used,
275           the connection is made as root user. If the "@" syntax is used
276           either the left hand side or the right hand side may be omitted
277           (but not both) in which case the local user name and ".host" are
278           implied.
279
280       -h, --help
281           Print a short help text and exit.
282
283       --version
284           Print a short version string and exit.
285
286       All command line arguments after the first non-option argument become
287       part of the command line of the launched process. If a command is run
288       as service unit, the first argument needs to be an absolute program
289       path.
290

EXIT STATUS

292       On success, 0 is returned. If systemd-run failed to start the service,
293       a non-zero return value will be returned. If systemd-run waits for the
294       service to terminate, the return value will be propagated from the
295       service. 0 will be returned on success, including all the cases where
296       systemd considers a service to have exited cleanly, see the discussion
297       of SuccessExitStatus= in systemd.service(5).
298

EXAMPLES

300       Example 1. Logging environment variables provided by systemd to
301       services
302
303           # systemd-run env
304           Running as unit: run-19945.service
305           # journalctl -u run-19945.service
306           Sep 08 07:37:21 bupkis systemd[1]: Starting /usr/bin/env...
307           Sep 08 07:37:21 bupkis systemd[1]: Started /usr/bin/env.
308           Sep 08 07:37:21 bupkis env[19948]: PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin
309           Sep 08 07:37:21 bupkis env[19948]: LANG=en_US.UTF-8
310           Sep 08 07:37:21 bupkis env[19948]: BOOT_IMAGE=/vmlinuz-3.11.0-0.rc5.git6.2.fc20.x86_64
311
312       Example 2. Limiting resources available to a command
313
314           # systemd-run -p BlockIOWeight=10 updatedb
315
316       This command invokes the updatedb(8) tool, but lowers the block I/O
317       weight for it to 10. See systemd.resource-control(5) for more
318       information on the BlockIOWeight= property.
319
320       Example 3. Running commands at a specified time
321
322       The following command will touch a file after 30 seconds.
323
324           # date; systemd-run --on-active=30 --timer-property=AccuracySec=100ms /bin/touch /tmp/foo
325           Mon Dec  8 20:44:24 KST 2014
326           Running as unit: run-71.timer
327           Will run service as unit: run-71.service
328           # journalctl -b -u run-71.timer
329           -- Journal begins at Fri 2014-12-05 19:09:21 KST, ends at Mon 2014-12-08 20:44:54 KST. --
330           Dec 08 20:44:38 container systemd[1]: Starting /bin/touch /tmp/foo.
331           Dec 08 20:44:38 container systemd[1]: Started /bin/touch /tmp/foo.
332           # journalctl -b -u run-71.service
333           -- Journal begins at Fri 2014-12-05 19:09:21 KST, ends at Mon 2014-12-08 20:44:54 KST. --
334           Dec 08 20:44:48 container systemd[1]: Starting /bin/touch /tmp/foo...
335           Dec 08 20:44:48 container systemd[1]: Started /bin/touch /tmp/foo.
336
337       Example 4. Allowing access to the tty
338
339       The following command invokes bash(1) as a service passing its standard
340       input, output and error to the calling TTY.
341
342           # systemd-run -t --send-sighup bash
343
344       Example 5. Start screen as a user service
345
346           $ systemd-run --scope --user screen
347           Running scope as unit run-r14b0047ab6df45bfb45e7786cc839e76.scope.
348
349           $ screen -ls
350           There is a screen on:
351                   492..laptop     (Detached)
352           1 Socket in /var/run/screen/S-fatima.
353
354       This starts the screen process as a child of the systemd --user process
355       that was started by user@.service, in a scope unit. A systemd.scope(5)
356       unit is used instead of a systemd.service(5) unit, because screen will
357       exit when detaching from the terminal, and a service unit would be
358       terminated. Running screen as a user unit has the advantage that it is
359       not part of the session scope. If KillUserProcesses=yes is configured
360       in logind.conf(5), the default, the session scope will be terminated
361       when the user logs out of that session.
362
363       The user@.service is started automatically when the user first logs in,
364       and stays around as long as at least one login session is open. After
365       the user logs out of the last session, user@.service and all services
366       underneath it are terminated. This behavior is the default, when
367       "lingering" is not enabled for that user. Enabling lingering means that
368       user@.service is started automatically during boot, even if the user is
369       not logged in, and that the service is not terminated when the user
370       logs out.
371
372       Enabling lingering allows the user to run processes without being
373       logged in, for example to allow screen to persist after the user logs
374       out, even if the session scope is terminated. In the default
375       configuration, users can enable lingering for themselves:
376
377           $ loginctl enable-linger
378
379       Example 6. Return value
380
381           $ systemd-run --user --wait true
382           $ systemd-run --user --wait -p SuccessExitStatus=11 bash -c 'exit 11'
383           $ systemd-run --user --wait -p SuccessExitStatus=SIGUSR1 bash -c 'kill -SIGUSR1 $$$$'
384
385       Those three invocations will succeed, i.e. terminate with an exit code
386       of 0.
387

SEE ALSO

389       systemd(1), systemctl(1), systemd.unit(5), systemd.service(5),
390       systemd.scope(5), systemd.slice(5), systemd.exec(5), systemd.resource-
391       control(5), systemd.timer(5), systemd-mount(1), machinectl(1)
392
393
394
395systemd 250                                                     SYSTEMD-RUN(1)
Impressum