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

NAME

6       systemd-run - Run programs in transient scope or service or timer units
7

SYNOPSIS

9       systemd-run [OPTIONS...] COMMAND [ARGS...]
10
11       systemd-run [OPTIONS...] [TIMER OPTIONS...] {COMMAND} [ARGS...]
12

DESCRIPTION

14       systemd-run may be used to create and start a transient .service or a
15       transient .timer or a .scope unit and run the specified COMMAND in it.
16
17       If a command is run as transient service unit, it will be started and
18       managed by the service manager like any other service, and thus show up
19       in the output of systemctl list-units like any other unit. It will run
20       in a clean and detached execution environment.  systemd-run will start
21       the service asynchronously in the background and immediately return.
22
23       If a command is run with timer options, transient timer unit also be
24       created with transient service unit. But the transient timer unit is
25       only started immediately. The transient service unit will be started
26       when the transient timer is elapsed. If --unit= is specified with timer
27       options, the COMMAND can be omitted. In this case, systemd-run assumes
28       service unit is already loaded and creates transient timer unit only.
29       To successfully create timer unit, already loaded service unit should
30       be specified with --unit=. This transient timer unit can activate the
31       existing service unit like any other timer.
32
33       If a command is run as transient scope unit, it will be started
34       directly by systemd-run and thus inherit the execution environment of
35       the caller. It is however managed by the service manager similar to
36       normal services, and will also show up in the output of systemctl
37       list-units. Execution in this case is synchronous, and execution will
38       return only when the command finishes.
39

OPTIONS

41       The following options are understood:
42
43       --scope
44           Create a transient .scope unit instead of the default transient
45           .service unit.
46
47       --unit=
48           Use this unit name instead of an automatically generated one.
49
50       --property=, -p
51           Sets a unit property for the scope or service unit that is created.
52           This takes an assignment in the same format as systemctl(1)'s
53           set-property command.
54
55       --description=
56           Provide a description for the service or scope unit. If not
57           specified, the command itself will be used as a description. See
58           Description= in systemd.unit(5).
59
60       --slice=
61           Make the new .service or .scope unit part of the specified slice,
62           instead of the system.slice.
63
64       --remain-after-exit
65           After the service or scope process has terminated, keep the service
66           around until it is explicitly stopped. This is useful to collect
67           runtime information about the service after it finished running.
68           Also see RemainAfterExit= in systemd.service(5).
69
70       --send-sighup
71           When terminating the scope or service unit, send a SIGHUP
72           immediately after SIGTERM. This is useful to indicate to shells and
73           shell-like processes that the connection has been severed. Also see
74           SendSIGHUP= in systemd.kill(5).
75
76       --service-type=
77           Sets the service type. Also see Type= in systemd.service(5). This
78           option has no effect in conjunction with --scope. Defaults to
79           simple.
80
81       --uid=, --gid=
82           Runs the service process under the UNIX user and group. Also see
83           User= and Group= in systemd.exec(5).
84
85       --nice=
86           Runs the service process with the specified nice level. Also see
87           Nice= in systemd.exec(5).
88
89       --setenv=
90           Runs the service process with the specified environment variables
91           set. Also see Environment= in systemd.exec(5).
92
93       --pty, -t
94           When invoking a command as service connects its standard input and
95           output to the invoking tty via a pseudo TTY device. This allows
96           invoking binaries as services that expect interactive user input,
97           such as interactive command shells.
98
99       --quiet, -q
100           Suppresses additional informational output while running. This is
101           particularly useful in combination with --pty when it will suppress
102           the initial message explaining how to terminate the TTY connection.
103
104       --on-active=, --on-boot=, --on-startup=, --on-unit-active=,
105       --on-unit-inactive=
106           Defines monotonic timers relative to different starting points.
107           Also see OnActiveSec=, OnBootSec=, OnStartupSec=, OnUnitActiveSec=
108           and OnUnitInactiveSec= in systemd.timer(5). This options have no
109           effect in conjunction with --scope.
110
111       --on-calendar=
112           Defines realtime (i.e. wallclock) timers with calendar event
113           expressions. Also see OnCalendar= in systemd.timer(5). This option
114           has no effect in conjunction with --scope.
115
116       --timer-property=
117           Sets a timer unit property for the timer unit that is created. It
118           is similar with --property but only for created timer unit. This
119           option only has effect in conjunction with --on-active=,
120           --on-boot=, --on-startup=, --on-unit-active=, --on-unit-inactive=,
121           --on-calendar=. This takes an assignment in the same format as
122           systemctl(1)'s set-property command.
123
124       --system
125           Talk to the service manager of the system. This is the implied
126           default.
127
128       -H, --host=
129           Execute the operation remotely. Specify a hostname, or a username
130           and hostname separated by "@", to connect to. The hostname may
131           optionally be suffixed by a container name, separated by ":", which
132           connects directly to a specific container on the specified host.
133           This will use SSH to talk to the remote machine manager instance.
134           Container names may be enumerated with machinectl -H HOST.
135
136       -M, --machine=
137           Execute operation on a local container. Specify a container name to
138           connect to.
139
140       -h, --help
141           Print a short help text and exit.
142
143       --version
144           Print a short version string and exit.
145
146       All command line arguments after the first non-option argument become
147       part of the command line of the launched process. If a command is run
148       as service unit, its first argument needs to be an absolute binary
149       path.
150

EXIT STATUS

152       On success, 0 is returned, a non-zero failure code otherwise.
153

EXAMPLES

155       The following command will log the environment variables provided by
156       systemd to services:
157
158           # systemd-run env
159           Running as unit run-19945.service.
160           # journalctl -u run-19945.service
161           Sep 08 07:37:21 bupkis systemd[1]: Starting /usr/bin/env...
162           Sep 08 07:37:21 bupkis systemd[1]: Started /usr/bin/env.
163           Sep 08 07:37:21 bupkis env[19948]: PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin
164           Sep 08 07:37:21 bupkis env[19948]: LANG=en_US.UTF-8
165           Sep 08 07:37:21 bupkis env[19948]: BOOT_IMAGE=/vmlinuz-3.11.0-0.rc5.git6.2.fc20.x86_64
166
167       The following command invokes the updatedb(8) tool, but lowers the
168       block IO weight for it to 10. See systemd.resource-control(5) for more
169       information on the BlockIOWeight= property.
170
171           # systemd-run -p BlockIOWeight=10 updatedb
172
173       The following command will touch a file after 30 seconds.
174
175           # date; systemd-run --on-active=30 --timer-property=AccuracySec=100ms /bin/touch /tmp/foo
176           Mon Dec  8 20:44:24 KST 2014
177           Running as unit run-71.timer.
178           Will run as unit run-71.service.
179           # journalctl -b -u run-73.timer
180           -- Logs begin at Fri 2014-12-05 19:09:21 KST, end at Mon 2014-12-08 20:44:54 KST. --
181           Dec 08 20:44:38 container systemd[1]: Starting /bin/touch /tmp/foo.
182           Dec 08 20:44:38 container systemd[1]: Started /bin/touch /tmp/foo.
183           # journalctl -b -u run-73.service
184           -- Logs begin at Fri 2014-12-05 19:09:21 KST, end at Mon 2014-12-08 20:44:54 KST. --
185           Dec 08 20:44:48 container systemd[1]: Starting /bin/touch /tmp/foo...
186           Dec 08 20:44:48 container systemd[1]: Started /bin/touch /tmp/foo.
187
188       The following command invokes /bin/bash as a service passing its
189       standard input, output and error to the calling TTY.
190
191           # systemd-run -t /bin/bash
192

SEE ALSO

194       systemd(1), systemctl(1), systemd.unit(5), systemd.service(5),
195       systemd.scope(5), systemd.slice(5), systemd.exec(5), systemd.resource-
196       control(5), systemd.timer(5), machinectl(1)
197
198
199
200systemd 219                                                     SYSTEMD-RUN(1)
Impressum