]> git.ipfire.org Git - thirdparty/systemd.git/blame - man/systemd-run.xml
Fix man page links
[thirdparty/systemd.git] / man / systemd-run.xml
CommitLineData
514094f9 1<?xml version='1.0'?>
3a54a157
ZJS
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
db9ecf05 4<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
f09114bc 5
dfdebb1b
ZJS
6<refentry id="systemd-run"
7 xmlns:xi="http://www.w3.org/2001/XInclude">
f09114bc
ZJS
8
9 <refentryinfo>
10 <title>systemd-run</title>
11 <productname>systemd</productname>
f09114bc
ZJS
12 </refentryinfo>
13
14 <refmeta>
15 <refentrytitle>systemd-run</refentrytitle>
16 <manvolnum>1</manvolnum>
17 </refmeta>
18
19 <refnamediv>
20 <refname>systemd-run</refname>
624dd009 21 <refpurpose>Run programs in transient scope units, service units, or path-, socket-, or timer-triggered service units</refpurpose>
f09114bc
ZJS
22 </refnamediv>
23
24 <refsynopsisdiv>
25 <cmdsynopsis>
26 <command>systemd-run</command>
27 <arg choice="opt" rep="repeat">OPTIONS</arg>
28 <arg choice="plain"><replaceable>COMMAND</replaceable>
29 <arg choice="opt" rep="repeat">ARGS</arg>
30 </arg>
31 </cmdsynopsis>
624dd009
YW
32 <cmdsynopsis>
33 <command>systemd-run</command>
34 <arg choice="opt" rep="repeat">OPTIONS</arg>
35 <arg choice="opt" rep="repeat">PATH OPTIONS</arg>
36 <arg choice="req"><replaceable>COMMAND</replaceable></arg>
37 <arg choice="opt" rep="repeat">ARGS</arg>
38 </cmdsynopsis>
39 <cmdsynopsis>
40 <command>systemd-run</command>
41 <arg choice="opt" rep="repeat">OPTIONS</arg>
42 <arg choice="opt" rep="repeat">SOCKET OPTIONS</arg>
43 <arg choice="req"><replaceable>COMMAND</replaceable></arg>
44 <arg choice="opt" rep="repeat">ARGS</arg>
45 </cmdsynopsis>
4c213d6c
WC
46 <cmdsynopsis>
47 <command>systemd-run</command>
48 <arg choice="opt" rep="repeat">OPTIONS</arg>
49 <arg choice="opt" rep="repeat">TIMER OPTIONS</arg>
50 <arg choice="req"><replaceable>COMMAND</replaceable></arg>
51 <arg choice="opt" rep="repeat">ARGS</arg>
52 </cmdsynopsis>
f09114bc
ZJS
53 </refsynopsisdiv>
54
55 <refsect1>
56 <title>Description</title>
57
014c4c98
LP
58 <para><command>systemd-run</command> may be used to create and start a transient <filename>.service</filename> or
59 <filename>.scope</filename> unit and run the specified <replaceable>COMMAND</replaceable> in it. It may also be
624dd009
YW
60 used to create and start a transient <filename>.path</filename>, <filename>.socket</filename>, or
61 <filename>.timer</filename> unit, that activates a <filename>.service</filename> unit when elapsing.</para>
014c4c98
LP
62
63 <para>If a command is run as transient service unit, it will be started and managed by the service manager like any
64 other service, and thus shows up in the output of <command>systemctl list-units</command> like any other unit. It
65 will run in a clean and detached execution environment, with the service manager as its parent process. In this
66 mode, <command>systemd-run</command> will start the service asynchronously in the background and return after the
b03ec009 67 command has begun execution (unless <option>--no-block</option> or <option>--wait</option> are specified, see
014c4c98
LP
68 below).</para>
69
70 <para>If a command is run as transient scope unit, it will be executed by <command>systemd-run</command> itself as
71 parent process and will thus inherit the execution environment of the caller. However, the processes of the command
72 are managed by the service manager similar to normal services, and will show up in the output of <command>systemctl
73 list-units</command>. Execution in this case is synchronous, and will return only when the command finishes. This
74 mode is enabled via the <option>--scope</option> switch (see below). </para>
75
624dd009
YW
76 <para>If a command is run with path, socket, or timer options such as <option>--on-calendar=</option> (see below),
77 a transient path, socket, or timer unit is created alongside the service unit for the specified command. Only the
78 transient path, socket, or timer unit is started immediately, the transient service unit will be triggered by the
79 path, socket, or timer unit. If the <option>--unit=</option> option is specified, the
80 <replaceable>COMMAND</replaceable> may be omitted. In this case, <command>systemd-run</command> creates only a
81 <filename>.path</filename>, <filename>.socket</filename>, or <filename>.timer</filename> unit that triggers the
82 specified unit.</para>
79905a24
LP
83
84 <para>By default, services created with <command>systemd-run</command> default to the <option>simple</option> type,
85 see the description of <varname>Type=</varname> in
86 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
87 details. Note that when this type is used the service manager (and thus the <command>systemd-run</command> command)
88 considers service start-up successful as soon as the <function>fork()</function> for the main service process
89 succeeded, i.e. before the <function>execve()</function> is invoked, and thus even if the specified command cannot
90 be started. Consider using the <option>exec</option> service type (i.e. <option>--property=Type=exec</option>) to
91 ensure that <command>systemd-run</command> returns successfully only if the specified command line has been
92 successfully started.</para>
f09114bc
ZJS
93 </refsect1>
94
95 <refsect1>
96 <title>Options</title>
97
98 <para>The following options are understood:</para>
99
100 <variablelist>
8c7db2fb
EV
101 <varlistentry>
102 <term><option>--no-ask-password</option></term>
103
104 <listitem><para>Do not query the user for authentication for
105 privileged operations.</para></listitem>
106 </varlistentry>
107
f09114bc
ZJS
108 <varlistentry>
109 <term><option>--scope</option></term>
110
111 <listitem>
014c4c98
LP
112 <para>Create a transient <filename>.scope</filename> unit instead of the default transient
113 <filename>.service</filename> unit (see above).
f09114bc
ZJS
114 </para>
115 </listitem>
116 </varlistentry>
117
118 <varlistentry>
119 <term><option>--unit=</option></term>
7976b9f0 120 <term><option>-u</option></term>
f09114bc
ZJS
121
122 <listitem><para>Use this unit name instead of an automatically
123 generated one.</para></listitem>
124 </varlistentry>
125
df31a6c0
LP
126 <varlistentry>
127 <term><option>--property=</option></term>
128 <term><option>-p</option></term>
129
014c4c98
LP
130 <listitem><para>Sets a property on the scope or service unit that is created. This option takes an assignment
131 in the same format as
df31a6c0
LP
132 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
133 <command>set-property</command> command.</para>
134 </listitem>
135 </varlistentry>
136
f09114bc
ZJS
137 <varlistentry>
138 <term><option>--description=</option></term>
139
624dd009
YW
140 <listitem><para>Provide a description for the service, scope, path, socket, or timer unit. If not specified,
141 the command itself will be used as a description. See <varname>Description=</varname> in
f09114bc
ZJS
142 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
143 </para></listitem>
144 </varlistentry>
145
146 <varlistentry>
147 <term><option>--slice=</option></term>
148
ba455349
LP
149 <listitem><para>Make the new <filename>.service</filename> or <filename>.scope</filename> unit part
150 of the specified slice, instead of <filename>system.slice</filename> (when running in
151 <option>--system</option> mode) or the root slice (when running in <option>--user</option>
152 mode).</para>
f09114bc
ZJS
153 </listitem>
154 </varlistentry>
6577c7ce 155
2c7039b3
MAL
156 <varlistentry>
157 <term><option>--slice-inherit</option></term>
158
159 <listitem><para>Make the new <filename>.service</filename> or <filename>.scope</filename> unit part
160 of the inherited slice. This option can be combined with <option>--slice=</option>.</para>
161
162 <para>An inherited slice is located within <command>systemd-run</command> slice. Example: if
163 <command>systemd-run</command> slice is <filename>foo.slice</filename>, and the
164 <option>--slice=</option> argument is <filename>bar</filename>, the unit will be placed under the
165 <filename>foo-bar.slice</filename>.</para>
166
167 </listitem>
168 </varlistentry>
169
6577c7ce 170 <varlistentry>
a953b31a 171 <term><option>-r</option></term>
6577c7ce
LP
172 <term><option>--remain-after-exit</option></term>
173
014c4c98
LP
174 <listitem><para>After the service process has terminated, keep the service around until it is explicitly
175 stopped. This is useful to collect runtime information about the service after it finished running. Also see
6577c7ce
LP
176 <varname>RemainAfterExit=</varname> in
177 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
178 </para>
179 </listitem>
180 </varlistentry>
a6c0353b
LP
181
182 <varlistentry>
183 <term><option>--send-sighup</option></term>
184
014c4c98
LP
185 <listitem><para>When terminating the scope or service unit, send a SIGHUP immediately after SIGTERM. This is
186 useful to indicate to shells and shell-like processes that the connection has been severed. Also see
981ee551 187 <varname>SendSIGHUP=</varname> in
a6c0353b
LP
188 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
189 </para>
190 </listitem>
191 </varlistentry>
dfdebb1b 192
981ee551
LP
193 <varlistentry>
194 <term><option>--service-type=</option></term>
195
196 <listitem><para>Sets the service type. Also see
197 <varname>Type=</varname> in
198 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This
199 option has no effect in conjunction with
200 <option>--scope</option>. Defaults to
201 <constant>simple</constant>.</para>
202 </listitem>
203 </varlistentry>
204
205 <varlistentry>
206 <term><option>--uid=</option></term>
207 <term><option>--gid=</option></term>
208
014c4c98
LP
209 <listitem><para>Runs the service process under the specified UNIX user and group. Also see
210 <varname>User=</varname> and <varname>Group=</varname> in
4de33e7f 211 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
981ee551
LP
212 </listitem>
213 </varlistentry>
214
215 <varlistentry>
216 <term><option>--nice=</option></term>
217
218 <listitem><para>Runs the service process with the specified
219 nice level. Also see <varname>Nice=</varname> in
4de33e7f 220 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
981ee551 221 </listitem>
2d21165a
LP
222 </varlistentry>
223
224 <varlistentry>
225 <term><option>--working-directory=</option></term>
226
227 <listitem><para>Runs the service process with the specified working directory. Also see
228 <varname>WorkingDirectory=</varname> in
229 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
230 </listitem>
231 </varlistentry>
232
233 <varlistentry>
234 <term><option>--same-dir</option></term>
235 <term><option>-d</option></term>
236
237 <listitem><para>Similar to <option>--working-directory=</option> but uses the current working directory of the
238 caller for the service to execute.</para></listitem>
981ee551
LP
239 </varlistentry>
240
241 <varlistentry>
0337b3d5
ZJS
242 <term><option>-E <replaceable>NAME</replaceable>[=<replaceable>VALUE</replaceable>]</option></term>
243 <term><option>--setenv=<replaceable>NAME</replaceable>[=<replaceable>VALUE</replaceable>]</option></term>
981ee551 244
0337b3d5
ZJS
245 <listitem><para>Runs the service process with the specified environment variable set. This parameter
246 may be used more than once to set multiple variables. When <literal>=</literal> and
247 <replaceable>VALUE</replaceable> are omitted, the value of the variable with the same name in the
248 program environment will be used.</para>
249
250 <para>Also see <varname>Environment=</varname> in
4de33e7f 251 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
981ee551
LP
252 </listitem>
253 </varlistentry>
254
9b15b784
LP
255 <varlistentry>
256 <term><option>--pty</option></term>
257 <term><option>-t</option></term>
258
5dca7739
LP
259 <listitem><para>When invoking the command, the transient service connects its standard input, output and error
260 to the terminal <command>systemd-run</command> is invoked on, via a pseudo TTY device. This allows running
156d6036 261 programs that expect interactive user input/output as services, such as interactive command shells.</para>
7f129a1f
LP
262
263 <para>Note that
264 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
265 <command>shell</command> command is usually a better alternative for requesting a new, interactive login
5dca7739
LP
266 session on the local host or a local container.</para>
267
268 <para>See below for details on how this switch combines with <option>--pipe</option>.</para></listitem>
269 </varlistentry>
270
271 <varlistentry>
272 <term><option>--pipe</option></term>
273 <term><option>-P</option></term>
274
275 <listitem><para>If specified, standard input, output, and error of the transient service are inherited from the
156d6036
ZJS
276 <command>systemd-run</command> command itself. This allows <command>systemd-run</command>
277 to be used within shell pipelines.
278 Note that this mode is not suitable for interactive command shells and similar, as the
960d20e1 279 service process will not become a TTY controller when invoked on a terminal. Use <option>--pty</option> instead
5dca7739
LP
280 in that case.</para>
281
282 <para>When both <option>--pipe</option> and <option>--pty</option> are used in combination the more appropriate
283 option is automatically determined and used. Specifically, when invoked with standard input, output and error
b0e8cec2
LP
284 connected to a TTY <option>--pty</option> is used, and otherwise <option>--pipe</option>.</para>
285
286 <para>When this option is used the original file descriptors <command>systemd-run</command> receives are passed
287 to the service processes as-is. If the service runs with different privileges than
288 <command>systemd-run</command>, this means the service might not be able to re-open the passed file
289 descriptors, due to normal file descriptor access restrictions. If the invoked process is a shell script that
290 uses the <command>echo "hello" > /dev/stderr</command> construct for writing messages to stderr, this might
291 cause problems, as this only works if stderr can be re-opened. To mitigate this use the construct <command>echo
292 "hello" >&amp;2</command> instead, which is mostly equivalent and avoids this pitfall.</para></listitem>
9b15b784 293 </varlistentry>
88ae7333 294
badd28e1
LP
295 <varlistentry>
296 <term><option>--shell</option></term>
297 <term><option>-S</option></term>
298
299 <listitem><para>A shortcut for <literal>--pty --same-dir --wait --collect --service-type=exec $SHELL</literal>,
300 i.e. requests an interactive shell in the current working directory, running in service context, accessible
301 with a single switch.</para></listitem>
302 </varlistentry>
303
095dc596
LP
304 <varlistentry>
305 <term><option>--quiet</option></term>
306 <term><option>-q</option></term>
307
308 <listitem><para>Suppresses additional informational output
309 while running. This is particularly useful in combination with
310 <option>--pty</option> when it will suppress the initial
311 message explaining how to terminate the TTY connection.</para></listitem>
312 </varlistentry>
313
4c213d6c
WC
314 <varlistentry>
315 <term><option>--on-active=</option></term>
316 <term><option>--on-boot=</option></term>
317 <term><option>--on-startup=</option></term>
318 <term><option>--on-unit-active=</option></term>
319 <term><option>--on-unit-inactive=</option></term>
320
014c4c98
LP
321 <listitem><para>Defines a monotonic timer relative to different starting points for starting the specified
322 command. See <varname>OnActiveSec=</varname>, <varname>OnBootSec=</varname>, <varname>OnStartupSec=</varname>,
323 <varname>OnUnitActiveSec=</varname> and <varname>OnUnitInactiveSec=</varname> in
324 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
624dd009
YW
325 details. These options are shortcuts for <command>--timer-property=</command> with the relevant properties.
326 These options may not be combined with <option>--scope</option> or <option>--pty</option>.</para>
4c213d6c
WC
327 </listitem>
328 </varlistentry>
329
330 <varlistentry>
331 <term><option>--on-calendar=</option></term>
332
014c4c98
LP
333 <listitem><para>Defines a calendar timer for starting the specified command. See <varname>OnCalendar=</varname>
334 in <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This
624dd009
YW
335 option is a shortcut for <command>--timer-property=OnCalendar=</command>. This option may not be combined with
336 <option>--scope</option> or <option>--pty</option>.</para>
4c213d6c
WC
337 </listitem>
338 </varlistentry>
339
d9b8c2ef
LP
340 <varlistentry>
341 <term><option>--on-clock-change</option></term>
342 <term><option>--on-timezone-change</option></term>
343
344 <listitem><para>Defines a trigger based on system clock jumps or timezone changes for starting the
345 specified command. See <varname>OnClockChange=</varname> and <varname>OnTimezoneChange=</varname> in
346 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. These
347 options are shortcuts for <command>--timer-property=OnClockChange=yes</command> and
348 <command>--timer-property=OnTimezoneChange=yes</command>. These options may not be combined with
349 <option>--scope</option> or <option>--pty</option>.</para></listitem>
350 </varlistentry>
351
4c213d6c 352 <varlistentry>
624dd009
YW
353 <term><option>--path-property=</option></term>
354 <term><option>--socket-property=</option></term>
4c213d6c
WC
355 <term><option>--timer-property=</option></term>
356
624dd009
YW
357 <listitem><para>Sets a property on the path, socket, or timer unit that is created. This option is similar to
358 <option>--property=</option> but applies to the transient path, socket, or timer unit rather than the
359 transient service unit created. This option takes an assignment in the same format as
360 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
361 <command>set-property</command> command. These options may not be combined with
362 <option>--scope</option> or <option>--pty</option>.</para>
363 </listitem>
4c213d6c
WC
364 </varlistentry>
365
3d161f99
LP
366 <varlistentry>
367 <term><option>--no-block</option></term>
368
369 <listitem>
014c4c98
LP
370 <para>Do not synchronously wait for the unit start operation to finish. If this option is not specified, the
371 start request for the transient unit will be verified, enqueued and <command>systemd-run</command> will wait
372 until the unit's start-up is completed. By passing this argument, it is only verified and enqueued. This
373 option may not be combined with <option>--wait</option>.</para>
3d161f99
LP
374 </listitem>
375 </varlistentry>
376
014c4c98
LP
377 <varlistentry>
378 <term><option>--wait</option></term>
379
380 <listitem><para>Synchronously wait for the transient service to terminate. If this option is specified, the
381 start request for the transient unit is verified, enqueued, and waited for. Subsequently the invoked unit is
382 monitored, and it is waited until it is deactivated again (most likely because the specified command
383 completed). On exit, terse information about the unit's runtime is shown, including total runtime (as well as
384 CPU usage, if <option>--property=CPUAccounting=1</option> was set) and the exit code and status of the main
385 process. This output may be suppressed with <option>--quiet</option>. This option may not be combined with
624dd009 386 <option>--no-block</option>, <option>--scope</option> or the various path, socket, or timer options.</para></listitem>
014c4c98
LP
387 </varlistentry>
388
fe9d0be9
LP
389 <varlistentry>
390 <term><option>-G</option></term>
391 <term><option>--collect</option></term>
392
393 <listitem><para>Unload the transient unit after it completed, even if it failed. Normally, without this option,
394 all units that ran and failed are kept in memory until the user explicitly resets their failure state with
395 <command>systemctl reset-failed</command> or an equivalent command. On the other hand, units that ran
396 successfully are unloaded immediately. If this option is turned on the "garbage collection" of units is more
397 aggressive, and unloads units regardless if they exited successfully or failed. This option is a shortcut for
398 <command>--property=CollectMode=inactive-or-failed</command>, see the explanation for
399 <varname>CollectMode=</varname> in
400 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for further
401 information.</para></listitem>
402 </varlistentry>
403
9b15b784
LP
404 <xi:include href="user-system-options.xml" xpointer="user" />
405 <xi:include href="user-system-options.xml" xpointer="system" />
406 <xi:include href="user-system-options.xml" xpointer="host" />
407 <xi:include href="user-system-options.xml" xpointer="machine" />
408
dfdebb1b
ZJS
409 <xi:include href="standard-options.xml" xpointer="help" />
410 <xi:include href="standard-options.xml" xpointer="version" />
f09114bc
ZJS
411 </variablelist>
412
81c7dd89 413 <para>All command line arguments after the first non-option
3f85ef0f 414 argument become part of the command line of the launched
3f2d1365
AJ
415 process. If a command is run as service unit, the first argument
416 needs to be an absolute program path.</para>
f09114bc
ZJS
417 </refsect1>
418
419 <refsect1>
420 <title>Exit status</title>
421
7f3614e5
ZJS
422 <para>On success, 0 is returned. If <command>systemd-run</command> failed to start the service, a
423 non-zero return value will be returned. If <command>systemd-run</command> waits for the service to
424 terminate, the return value will be propagated from the service. 0 will be returned on success, including
425 all the cases where systemd considers a service to have exited cleanly, see the discussion of
426 <varname>SuccessExitStatus=</varname> in
427 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
428 </para>
f09114bc
ZJS
429 </refsect1>
430
c9d954b2 431 <refsect1>
df31a6c0 432 <title>Examples</title>
c9d954b2 433
4eac7f5c
ZJS
434 <example>
435 <title>Logging environment variables provided by systemd to services</title>
c9d954b2 436
4eac7f5c 437 <programlisting># systemd-run env
f3ea87af 438Running as unit: run-19945.service
c9d954b2
ZJS
439# journalctl -u run-19945.service
440Sep 08 07:37:21 bupkis systemd[1]: Starting /usr/bin/env...
441Sep 08 07:37:21 bupkis systemd[1]: Started /usr/bin/env.
442Sep 08 07:37:21 bupkis env[19948]: PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin
443Sep 08 07:37:21 bupkis env[19948]: LANG=en_US.UTF-8
9fccdb0f 444Sep 08 07:37:21 bupkis env[19948]: BOOT_IMAGE=/vmlinuz-3.11.0-0.rc5.git6.2.fc20.x86_64</programlisting>
4eac7f5c 445 </example>
df31a6c0 446
4eac7f5c
ZJS
447 <example>
448 <title>Limiting resources available to a command</title>
df31a6c0 449
4eac7f5c 450 <programlisting># systemd-run -p BlockIOWeight=10 updatedb</programlisting>
4c213d6c 451
4eac7f5c
ZJS
452 <para>This command invokes the
453 <citerefentry project='man-pages'><refentrytitle>updatedb</refentrytitle><manvolnum>8</manvolnum></citerefentry>
454 tool, but lowers the block I/O weight for it to 10. See
455 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
456 for more information on the <varname>BlockIOWeight=</varname>
457 property.</para>
458 </example>
4c213d6c 459
4eac7f5c
ZJS
460 <example>
461 <title>Running commands at a specified time</title>
462
463 <para>The following command will touch a file after 30 seconds.</para>
464
465 <programlisting># date; systemd-run --on-active=30 --timer-property=AccuracySec=100ms /bin/touch /tmp/foo
4c213d6c 466Mon Dec 8 20:44:24 KST 2014
f3ea87af
ILG
467Running as unit: run-71.timer
468Will run service as unit: run-71.service
85fb8031 469# journalctl -b -u run-71.timer
b91ae210 470-- Journal begins at Fri 2014-12-05 19:09:21 KST, ends at Mon 2014-12-08 20:44:54 KST. --
4c213d6c
WC
471Dec 08 20:44:38 container systemd[1]: Starting /bin/touch /tmp/foo.
472Dec 08 20:44:38 container systemd[1]: Started /bin/touch /tmp/foo.
85fb8031 473# journalctl -b -u run-71.service
b91ae210 474-- Journal begins at Fri 2014-12-05 19:09:21 KST, ends at Mon 2014-12-08 20:44:54 KST. --
4c213d6c
WC
475Dec 08 20:44:48 container systemd[1]: Starting /bin/touch /tmp/foo...
476Dec 08 20:44:48 container systemd[1]: Started /bin/touch /tmp/foo.</programlisting>
4eac7f5c 477 </example>
9b15b784 478
4eac7f5c
ZJS
479 <example>
480 <title>Allowing access to the tty</title>
9b15b784 481
ff9412c1 482 <para>The following command invokes <citerefentry project='die-net'><refentrytitle>bash</refentrytitle><manvolnum>1</manvolnum></citerefentry>
1e8c094c 483 as a service passing its standard input, output and error to the calling TTY.</para>
9b15b784 484
1e8c094c 485 <programlisting># systemd-run -t --send-sighup bash</programlisting>
4eac7f5c 486 </example>
65eb37f8
ZJS
487
488 <example>
489 <title>Start <command>screen</command> as a user service</title>
490
491 <programlisting>$ systemd-run --scope --user screen
492Running scope as unit run-r14b0047ab6df45bfb45e7786cc839e76.scope.
493
494$ screen -ls
495There is a screen on:
496 492..laptop (Detached)
4971 Socket in /var/run/screen/S-fatima.
498</programlisting>
499
500 <para>This starts the <command>screen</command> process as a child of the
501 <command>systemd --user</command> process that was started by
502 <filename>user@.service</filename>, in a scope unit. A
503 <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>
504 unit is used instead of a
505 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
506 unit, because <command>screen</command> will exit when detaching from the terminal,
507 and a service unit would be terminated. Running <command>screen</command>
508 as a user unit has the advantage that it is not part of the session scope.
509 If <varname>KillUserProcesses=yes</varname> is configured in
510 <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
511 the default, the session scope will be terminated when the user logs
512 out of that session.</para>
513
514 <para>The <filename>user@.service</filename> is started automatically
515 when the user first logs in, and stays around as long as at least one
516 login session is open. After the user logs out of the last session,
517 <filename>user@.service</filename> and all services underneath it
2dd67817 518 are terminated. This behavior is the default, when "lingering" is
65eb37f8
ZJS
519 not enabled for that user. Enabling lingering means that
520 <filename>user@.service</filename> is started automatically during
521 boot, even if the user is not logged in, and that the service is
522 not terminated when the user logs out.</para>
523
524 <para>Enabling lingering allows the user to run processes without being logged in,
525 for example to allow <command>screen</command> to persist after the user logs out,
526 even if the session scope is terminated. In the default configuration, users can
527 enable lingering for themselves:</para>
528
529 <programlisting>$ loginctl enable-linger</programlisting>
530 </example>
7f3614e5
ZJS
531
532 <example>
533 <title>Return value</title>
534
535 <programlisting>$ systemd-run --user --wait true
536$ systemd-run --user --wait -p SuccessExitStatus=11 bash -c 'exit 11'
537$ systemd-run --user --wait -p SuccessExitStatus=SIGUSR1 bash -c 'kill -SIGUSR1 $$$$'</programlisting>
538
539 <para>Those three invocations will succeed, i.e. terminate with an exit code of 0.</para>
540 </example>
c9d954b2
ZJS
541 </refsect1>
542
f09114bc
ZJS
543 <refsect1>
544 <title>See Also</title>
545 <para>
546 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
3803cde4 547 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
f09114bc
ZJS
548 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
549 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
550 <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
d21ed1ea 551 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
df31a6c0
LP
552 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
553 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
4c213d6c 554 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
450442cf 555 <citerefentry><refentrytitle>systemd-mount</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
d21ed1ea 556 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
f09114bc
ZJS
557 </para>
558 </refsect1>
559
560</refentry>