]>
Commit | Line | Data |
---|---|---|
14228c0d | 1 | '\" t |
e3bff60a | 2 | .TH "SYSTEMD\-RUN" "1" "" "systemd 220" "systemd-run" |
14228c0d MB |
3 | .\" ----------------------------------------------------------------- |
4 | .\" * Define some portability stuff | |
5 | .\" ----------------------------------------------------------------- | |
6 | .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
7 | .\" http://bugs.debian.org/507673 | |
8 | .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html | |
9 | .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
10 | .ie \n(.g .ds Aq \(aq | |
11 | .el .ds Aq ' | |
12 | .\" ----------------------------------------------------------------- | |
13 | .\" * set default formatting | |
14 | .\" ----------------------------------------------------------------- | |
15 | .\" disable hyphenation | |
16 | .nh | |
17 | .\" disable justification (adjust text to left margin only) | |
18 | .ad l | |
19 | .\" ----------------------------------------------------------------- | |
20 | .\" * MAIN CONTENT STARTS HERE * | |
21 | .\" ----------------------------------------------------------------- | |
22 | .SH "NAME" | |
f47781d8 | 23 | systemd-run \- Run programs in transient scope or service or timer units |
14228c0d MB |
24 | .SH "SYNOPSIS" |
25 | .HP \w'\fBsystemd\-run\fR\ 'u | |
26 | \fBsystemd\-run\fR [OPTIONS...] \fICOMMAND\fR\ [ARGS...] | |
f47781d8 MP |
27 | .HP \w'\fBsystemd\-run\fR\ 'u |
28 | \fBsystemd\-run\fR [OPTIONS...] [TIMER\ OPTIONS...] {\fICOMMAND\fR} [ARGS...] | |
14228c0d MB |
29 | .SH "DESCRIPTION" |
30 | .PP | |
31 | \fBsystemd\-run\fR | |
60f067b4 | 32 | may be used to create and start a transient |
14228c0d | 33 | \&.service |
f47781d8 MP |
34 | or a transient |
35 | \&.timer | |
14228c0d MB |
36 | or a |
37 | \&.scope | |
38 | unit and run the specified | |
39 | \fICOMMAND\fR | |
40 | in it\&. | |
41 | .PP | |
42 | If a command is run as transient service unit, it will be started and managed by the service manager like any other service, and thus show up in the output of | |
43 | \fBsystemctl list\-units\fR | |
44 | like any other unit\&. It will run in a clean and detached execution environment\&. | |
45 | \fBsystemd\-run\fR | |
46 | will start the service asynchronously in the background and immediately return\&. | |
47 | .PP | |
f47781d8 MP |
48 | If a command is run with timer options, transient timer unit also be created with transient service unit\&. But the transient timer unit is only started immediately\&. The transient service unit will be started when the transient timer is elapsed\&. If |
49 | \fB\-\-unit=\fR | |
50 | is specified with timer options, the | |
51 | \fICOMMAND\fR | |
52 | can be omitted\&. In this case, | |
53 | \fBsystemd\-run\fR | |
54 | assumes service unit is already loaded and creates transient timer unit only\&. To successfully create timer unit, already loaded service unit should be specified with | |
55 | \fB\-\-unit=\fR\&. This transient timer unit can activate the existing service unit like any other timer\&. | |
56 | .PP | |
14228c0d MB |
57 | If a command is run as transient scope unit, it will be started directly by |
58 | \fBsystemd\-run\fR | |
59 | and thus inherit the execution environment of the caller\&. It is however managed by the service manager similar to normal services, and will also show up in the output of | |
60 | \fBsystemctl list\-units\fR\&. Execution in this case is synchronous, and execution will return only when the command finishes\&. | |
61 | .SH "OPTIONS" | |
62 | .PP | |
63 | The following options are understood: | |
64 | .PP | |
14228c0d MB |
65 | \fB\-\-scope\fR |
66 | .RS 4 | |
67 | Create a transient | |
68 | \&.scope | |
69 | unit instead of the default transient | |
70 | \&.service | |
71 | unit\&. | |
72 | .RE | |
73 | .PP | |
74 | \fB\-\-unit=\fR | |
75 | .RS 4 | |
76 | Use this unit name instead of an automatically generated one\&. | |
77 | .RE | |
78 | .PP | |
60f067b4 JS |
79 | \fB\-\-property=\fR, \fB\-p\fR |
80 | .RS 4 | |
81 | Sets a unit property for the scope or service unit that is created\&. This takes an assignment in the same format as | |
82 | \fBsystemctl\fR(1)\*(Aqs | |
83 | \fBset\-property\fR | |
84 | command\&. | |
85 | .RE | |
86 | .PP | |
14228c0d MB |
87 | \fB\-\-description=\fR |
88 | .RS 4 | |
60f067b4 | 89 | Provide a description for the service or scope unit\&. If not specified, the command itself will be used as a description\&. See |
14228c0d MB |
90 | \fIDescription=\fR |
91 | in | |
92 | \fBsystemd.unit\fR(5)\&. | |
93 | .RE | |
94 | .PP | |
95 | \fB\-\-slice=\fR | |
96 | .RS 4 | |
97 | Make the new | |
98 | \&.service | |
99 | or | |
100 | \&.scope | |
101 | unit part of the specified slice, instead of the | |
102 | system\&.slice\&. | |
103 | .RE | |
104 | .PP | |
105 | \fB\-\-remain\-after\-exit\fR | |
106 | .RS 4 | |
60f067b4 | 107 | After the service or scope process has terminated, keep the service around until it is explicitly stopped\&. This is useful to collect runtime information about the service after it finished running\&. Also see |
14228c0d MB |
108 | \fIRemainAfterExit=\fR |
109 | in | |
110 | \fBsystemd.service\fR(5)\&. | |
111 | .RE | |
112 | .PP | |
113 | \fB\-\-send\-sighup\fR | |
114 | .RS 4 | |
60f067b4 | 115 | When terminating the scope or service unit, send a SIGHUP immediately after SIGTERM\&. This is useful to indicate to shells and shell\-like processes that the connection has been severed\&. Also see |
14228c0d MB |
116 | \fISendSIGHUP=\fR |
117 | in | |
118 | \fBsystemd.kill\fR(5)\&. | |
119 | .RE | |
120 | .PP | |
60f067b4 JS |
121 | \fB\-\-service\-type=\fR |
122 | .RS 4 | |
123 | Sets the service type\&. Also see | |
124 | \fIType=\fR | |
125 | in | |
126 | \fBsystemd.service\fR(5)\&. This option has no effect in conjunction with | |
127 | \fB\-\-scope\fR\&. Defaults to | |
128 | \fBsimple\fR\&. | |
129 | .RE | |
130 | .PP | |
131 | \fB\-\-uid=\fR, \fB\-\-gid=\fR | |
132 | .RS 4 | |
133 | Runs the service process under the UNIX user and group\&. Also see | |
134 | \fIUser=\fR | |
135 | and | |
136 | \fIGroup=\fR | |
137 | in | |
138 | \fBsystemd.exec\fR(5)\&. | |
139 | .RE | |
140 | .PP | |
141 | \fB\-\-nice=\fR | |
142 | .RS 4 | |
143 | Runs the service process with the specified nice level\&. Also see | |
144 | \fINice=\fR | |
145 | in | |
146 | \fBsystemd.exec\fR(5)\&. | |
147 | .RE | |
148 | .PP | |
149 | \fB\-\-setenv=\fR | |
150 | .RS 4 | |
151 | Runs the service process with the specified environment variables set\&. Also see | |
152 | \fIEnvironment=\fR | |
153 | in | |
154 | \fBsystemd.exec\fR(5)\&. | |
155 | .RE | |
156 | .PP | |
e735f4d4 | 157 | \fB\-\-pty\fR, \fB\-t\fR |
60f067b4 | 158 | .RS 4 |
e735f4d4 | 159 | When invoking a command as service connects its standard input and output to the invoking tty via a pseudo TTY device\&. This allows invoking binaries as services that expect interactive user input, such as interactive command shells\&. |
60f067b4 JS |
160 | .RE |
161 | .PP | |
e735f4d4 | 162 | \fB\-\-quiet\fR, \fB\-q\fR |
60f067b4 | 163 | .RS 4 |
e735f4d4 MP |
164 | Suppresses additional informational output while running\&. This is particularly useful in combination with |
165 | \fB\-\-pty\fR | |
166 | when it will suppress the initial message explaining how to terminate the TTY connection\&. | |
60f067b4 JS |
167 | .RE |
168 | .PP | |
f47781d8 MP |
169 | \fB\-\-on\-active=\fR, \fB\-\-on\-boot=\fR, \fB\-\-on\-startup=\fR, \fB\-\-on\-unit\-active=\fR, \fB\-\-on\-unit\-inactive=\fR |
170 | .RS 4 | |
171 | Defines monotonic timers relative to different starting points\&. Also see | |
172 | \fIOnActiveSec=\fR, | |
173 | \fIOnBootSec=\fR, | |
174 | \fIOnStartupSec=\fR, | |
175 | \fIOnUnitActiveSec=\fR | |
176 | and | |
177 | \fIOnUnitInactiveSec=\fR | |
178 | in | |
179 | \fBsystemd.timer\fR(5)\&. This options have no effect in conjunction with | |
180 | \fB\-\-scope\fR\&. | |
181 | .RE | |
182 | .PP | |
183 | \fB\-\-on\-calendar=\fR | |
184 | .RS 4 | |
185 | Defines realtime (i\&.e\&. wallclock) timers with calendar event expressions\&. Also see | |
186 | \fIOnCalendar=\fR | |
187 | in | |
188 | \fBsystemd.timer\fR(5)\&. This option has no effect in conjunction with | |
189 | \fB\-\-scope\fR\&. | |
190 | .RE | |
191 | .PP | |
192 | \fB\-\-timer\-property=\fR | |
193 | .RS 4 | |
194 | Sets a timer unit property for the timer unit that is created\&. It is similar with | |
195 | \fB\-\-property\fR | |
196 | but only for created timer unit\&. This option only has effect in conjunction with | |
197 | \fB\-\-on\-active=\fR, | |
198 | \fB\-\-on\-boot=\fR, | |
199 | \fB\-\-on\-startup=\fR, | |
200 | \fB\-\-on\-unit\-active=\fR, | |
201 | \fB\-\-on\-unit\-inactive=\fR, | |
202 | \fB\-\-on\-calendar=\fR\&. This takes an assignment in the same format as | |
203 | \fBsystemctl\fR(1)\*(Aqs | |
204 | \fBset\-property\fR | |
205 | command\&. | |
206 | .RE | |
207 | .PP | |
e3bff60a MP |
208 | \fB\-\-no\-block\fR |
209 | .RS 4 | |
210 | Do not synchronously wait for the requested operation to finish\&. If this is not specified, the job will be verified, enqueued and | |
211 | \fBsystemd\-run\fR | |
212 | will wait until the unit\*(Aqs start\-up is completed\&. By passing this argument, it is only verified and enqueued\&. | |
213 | .RE | |
214 | .PP | |
e735f4d4 MP |
215 | \fB\-\-user\fR |
216 | .RS 4 | |
217 | Talk to the service manager of the calling user, rather than the service manager of the system\&. | |
218 | .RE | |
219 | .PP | |
220 | \fB\-\-system\fR | |
221 | .RS 4 | |
222 | Talk to the service manager of the system\&. This is the implied default\&. | |
223 | .RE | |
224 | .PP | |
225 | \fB\-H\fR, \fB\-\-host=\fR | |
226 | .RS 4 | |
227 | Execute the operation remotely\&. Specify a hostname, or a username and hostname separated by | |
228 | "@", to connect to\&. The hostname may optionally be suffixed by a container name, separated by | |
229 | ":", which connects directly to a specific container on the specified host\&. This will use SSH to talk to the remote machine manager instance\&. Container names may be enumerated with | |
230 | \fBmachinectl \-H \fR\fB\fIHOST\fR\fR\&. | |
231 | .RE | |
232 | .PP | |
233 | \fB\-M\fR, \fB\-\-machine=\fR | |
234 | .RS 4 | |
235 | Execute operation on a local container\&. Specify a container name to connect to\&. | |
236 | .RE | |
237 | .PP | |
60f067b4 JS |
238 | \fB\-h\fR, \fB\-\-help\fR |
239 | .RS 4 | |
240 | Print a short help text and exit\&. | |
241 | .RE | |
242 | .PP | |
243 | \fB\-\-version\fR | |
244 | .RS 4 | |
245 | Print a short version string and exit\&. | |
246 | .RE | |
247 | .PP | |
f47781d8 | 248 | All command line arguments after the first non\-option argument become part of the command line of the launched process\&. If a command is run as service unit, its first argument needs to be an absolute binary path\&. |
14228c0d MB |
249 | .SH "EXIT STATUS" |
250 | .PP | |
251 | On success, 0 is returned, a non\-zero failure code otherwise\&. | |
60f067b4 | 252 | .SH "EXAMPLES" |
14228c0d MB |
253 | .PP |
254 | The following command will log the environment variables provided by systemd to services: | |
255 | .sp | |
256 | .if n \{\ | |
257 | .RS 4 | |
258 | .\} | |
259 | .nf | |
260 | # systemd\-run env | |
261 | Running as unit run\-19945\&.service\&. | |
262 | # journalctl \-u run\-19945\&.service | |
263 | Sep 08 07:37:21 bupkis systemd[1]: Starting /usr/bin/env\&.\&.\&. | |
264 | Sep 08 07:37:21 bupkis systemd[1]: Started /usr/bin/env\&. | |
265 | Sep 08 07:37:21 bupkis env[19948]: PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin | |
266 | Sep 08 07:37:21 bupkis env[19948]: LANG=en_US\&.UTF\-8 | |
267 | Sep 08 07:37:21 bupkis env[19948]: BOOT_IMAGE=/vmlinuz\-3\&.11\&.0\-0\&.rc5\&.git6\&.2\&.fc20\&.x86_64 | |
60f067b4 JS |
268 | .fi |
269 | .if n \{\ | |
270 | .RE | |
271 | .\} | |
272 | .PP | |
273 | The following command invokes the | |
274 | \fBupdatedb\fR(8) | |
275 | tool, but lowers the block IO weight for it to 10\&. See | |
276 | \fBsystemd.resource-control\fR(5) | |
277 | for more information on the | |
278 | \fIBlockIOWeight=\fR | |
279 | property\&. | |
280 | .sp | |
281 | .if n \{\ | |
282 | .RS 4 | |
283 | .\} | |
284 | .nf | |
285 | # systemd\-run \-p BlockIOWeight=10 updatedb | |
14228c0d MB |
286 | .fi |
287 | .if n \{\ | |
288 | .RE | |
289 | .\} | |
f47781d8 MP |
290 | .PP |
291 | The following command will touch a file after 30 seconds\&. | |
292 | .sp | |
293 | .if n \{\ | |
294 | .RS 4 | |
295 | .\} | |
296 | .nf | |
297 | # date; systemd\-run \-\-on\-active=30 \-\-timer\-property=AccuracySec=100ms /bin/touch /tmp/foo | |
298 | Mon Dec 8 20:44:24 KST 2014 | |
299 | Running as unit run\-71\&.timer\&. | |
300 | Will run as unit run\-71\&.service\&. | |
e3bff60a | 301 | # journalctl \-b \-u run\-71\&.timer |
f47781d8 MP |
302 | \-\- Logs begin at Fri 2014\-12\-05 19:09:21 KST, end at Mon 2014\-12\-08 20:44:54 KST\&. \-\- |
303 | Dec 08 20:44:38 container systemd[1]: Starting /bin/touch /tmp/foo\&. | |
304 | Dec 08 20:44:38 container systemd[1]: Started /bin/touch /tmp/foo\&. | |
e3bff60a | 305 | # journalctl \-b \-u run\-71\&.service |
f47781d8 MP |
306 | \-\- Logs begin at Fri 2014\-12\-05 19:09:21 KST, end at Mon 2014\-12\-08 20:44:54 KST\&. \-\- |
307 | Dec 08 20:44:48 container systemd[1]: Starting /bin/touch /tmp/foo\&.\&.\&. | |
308 | Dec 08 20:44:48 container systemd[1]: Started /bin/touch /tmp/foo\&. | |
309 | .fi | |
310 | .if n \{\ | |
311 | .RE | |
312 | .\} | |
e735f4d4 MP |
313 | .PP |
314 | The following command invokes | |
315 | /bin/bash | |
316 | as a service passing its standard input, output and error to the calling TTY\&. | |
317 | .sp | |
318 | .if n \{\ | |
319 | .RS 4 | |
320 | .\} | |
321 | .nf | |
322 | # systemd\-run \-t /bin/bash | |
323 | .fi | |
324 | .if n \{\ | |
325 | .RE | |
326 | .\} | |
14228c0d MB |
327 | .SH "SEE ALSO" |
328 | .PP | |
329 | \fBsystemd\fR(1), | |
330 | \fBsystemctl\fR(1), | |
331 | \fBsystemd.unit\fR(5), | |
332 | \fBsystemd.service\fR(5), | |
333 | \fBsystemd.scope\fR(5), | |
60f067b4 JS |
334 | \fBsystemd.slice\fR(5), |
335 | \fBsystemd.exec\fR(5), | |
336 | \fBsystemd.resource-control\fR(5), | |
f47781d8 | 337 | \fBsystemd.timer\fR(5), |
60f067b4 | 338 | \fBmachinectl\fR(1) |