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

OPTIONS

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

EXIT STATUS

236       On success, 0 is returned, a non-zero failure code otherwise.
237

EXAMPLES

239       Example 1. Logging environment variables provided by systemd to
240       services
241
242           # systemd-run env
243           Running as unit: run-19945.service
244           # journalctl -u run-19945.service
245           Sep 08 07:37:21 bupkis systemd[1]: Starting /usr/bin/env...
246           Sep 08 07:37:21 bupkis systemd[1]: Started /usr/bin/env.
247           Sep 08 07:37:21 bupkis env[19948]: PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin
248           Sep 08 07:37:21 bupkis env[19948]: LANG=en_US.UTF-8
249           Sep 08 07:37:21 bupkis env[19948]: BOOT_IMAGE=/vmlinuz-3.11.0-0.rc5.git6.2.fc20.x86_64
250
251       Example 2. Limiting resources available to a command
252
253           # systemd-run -p BlockIOWeight=10 updatedb
254
255       This command invokes the updatedb(8) tool, but lowers the block I/O
256       weight for it to 10. See systemd.resource-control(5) for more
257       information on the BlockIOWeight= property.
258
259       Example 3. Running commands at a specified time
260
261       The following command will touch a file after 30 seconds.
262
263           # date; systemd-run --on-active=30 --timer-property=AccuracySec=100ms /bin/touch /tmp/foo
264           Mon Dec  8 20:44:24 KST 2014
265           Running as unit: run-71.timer
266           Will run service as unit: run-71.service
267           # journalctl -b -u run-71.timer
268           -- Logs begin at Fri 2014-12-05 19:09:21 KST, end at Mon 2014-12-08 20:44:54 KST. --
269           Dec 08 20:44:38 container systemd[1]: Starting /bin/touch /tmp/foo.
270           Dec 08 20:44:38 container systemd[1]: Started /bin/touch /tmp/foo.
271           # journalctl -b -u run-71.service
272           -- Logs begin at Fri 2014-12-05 19:09:21 KST, end at Mon 2014-12-08 20:44:54 KST. --
273           Dec 08 20:44:48 container systemd[1]: Starting /bin/touch /tmp/foo...
274           Dec 08 20:44:48 container systemd[1]: Started /bin/touch /tmp/foo.
275
276       Example 4. Allowing access to the tty
277
278       The following command invokes /bin/bash as a service passing its
279       standard input, output and error to the calling TTY.
280
281           # systemd-run -t --send-sighup /bin/bash
282
283       Example 5. Start screen as a user service
284
285           $ systemd-run --scope --user screen
286           Running scope as unit run-r14b0047ab6df45bfb45e7786cc839e76.scope.
287
288           $ screen -ls
289           There is a screen on:
290                   492..laptop     (Detached)
291           1 Socket in /var/run/screen/S-fatima.
292
293       This starts the screen process as a child of the systemd --user process
294       that was started by user@.service, in a scope unit. A systemd.scope(5)
295       unit is used instead of a systemd.service(5) unit, because screen will
296       exit when detaching from the terminal, and a service unit would be
297       terminated. Running screen as a user unit has the advantage that it is
298       not part of the session scope. If KillUserProcesses=yes is configured
299       in logind.conf(5), the default, the session scope will be terminated
300       when the user logs out of that session.
301
302       The user@.service is started automatically when the user first logs in,
303       and stays around as long as at least one login session is open. After
304       the user logs out of the last session, user@.service and all services
305       underneath it are terminated. This behavior is the default, when
306       "lingering" is not enabled for that user. Enabling lingering means that
307       user@.service is started automatically during boot, even if the user is
308       not logged in, and that the service is not terminated when the user
309       logs out.
310
311       Enabling lingering allows the user to run processes without being
312       logged in, for example to allow screen to persist after the user logs
313       out, even if the session scope is terminated. In the default
314       configuration, users can enable lingering for themselves:
315
316           $ loginctl enable-linger
317

SEE ALSO

319       systemd(1), systemctl(1), systemd.unit(5), systemd.service(5),
320       systemd.scope(5), systemd.slice(5), systemd.exec(5), systemd.resource-
321       control(5), systemd.timer(5), systemd-mount(1), machinectl(1)
322
323
324
325systemd 239                                                     SYSTEMD-RUN(1)
Impressum