1SYSTEMD-RUN(1) systemd-run SYSTEMD-RUN(1)
2
6 systemd-run - Run programs in transient scope or service or timer units
7
9 systemd-run [OPTIONS...] COMMAND [ARGS...]
10 systemd-run [OPTIONS...] [TIMER OPTIONS...] {COMMAND} [ARGS...]
12
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 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 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 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
41 The following options are understood:
42 --scope
44 Create a transient .scope unit instead of the default transient
45 .service unit.
46 --unit=
48 Use this unit name instead of an automatically generated one.
49 --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 --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 --slice=
61 Make the new .service or .scope unit part of the specified slice,
62 instead of the system.slice.
63 --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 --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 --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 --uid=, --gid=
82 Runs the service process under the UNIX user and group. Also see
83 User= and Group= in systemd.exec(5).
84 --nice=
86 Runs the service process with the specified nice level. Also see
87 Nice= in systemd.exec(5).
88 --setenv=
90 Runs the service process with the specified environment variables
91 set. Also see Environment= in systemd.exec(5).
92 --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 --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 --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 --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 --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 --system
125 Talk to the service manager of the system. This is the implied
126 default.
127 -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 -M, --machine=
137 Execute operation on a local container. Specify a container name to
138 connect to.
139 -h, --help
141 Print a short help text and exit.
142 --version
144 Print a short version string and exit.
145 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
152 On success, 0 is returned, a non-zero failure code otherwise.
153
155 The following command will log the environment variables provided by
156 systemd to services:
157 # 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 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 # systemd-run -p BlockIOWeight=10 updatedb
172 The following command will touch a file after 30 seconds.
174 # 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 The following command invokes /bin/bash as a service passing its
189 standard input, output and error to the calling TTY.
190 # systemd-run -t /bin/bash
192
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)
197systemd 219 SYSTEMD-RUN(1)