summaryrefslogtreecommitdiff
path: root/man/systemd-run.xml
diff options
context:
space:
mode:
Diffstat (limited to 'man/systemd-run.xml')
-rw-r--r--man/systemd-run.xml107
1 files changed, 81 insertions, 26 deletions
diff --git a/man/systemd-run.xml b/man/systemd-run.xml
index 414e1c8335..9c1a29218e 100644
--- a/man/systemd-run.xml
+++ b/man/systemd-run.xml
@@ -226,11 +226,11 @@
</varlistentry>
<varlistentry>
- <term><option>--setenv=</option></term>
+ <term><option>-E <replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term>
+ <term><option>--setenv=<replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term>
- <listitem><para>Runs the service process with the specified
- environment variables set. Also see
- <varname>Environment=</varname> in
+ <listitem><para>Runs the service process with the specified environment variable set.
+ Also see <varname>Environment=</varname> in
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
</listitem>
</varlistentry>
@@ -341,33 +341,41 @@
<refsect1>
<title>Examples</title>
- <para>The following command will log the environment variables
- provided by systemd to services:</para>
+ <example>
+ <title>Logging environment variables provided by systemd to services</title>
- <programlisting># systemd-run env
-Running as unit run-19945.service.
+ <programlisting># systemd-run env
+Running as unit: run-19945.service
# journalctl -u run-19945.service
Sep 08 07:37:21 bupkis systemd[1]: Starting /usr/bin/env...
Sep 08 07:37:21 bupkis systemd[1]: Started /usr/bin/env.
Sep 08 07:37:21 bupkis env[19948]: PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin
Sep 08 07:37:21 bupkis env[19948]: LANG=en_US.UTF-8
Sep 08 07:37:21 bupkis env[19948]: BOOT_IMAGE=/vmlinuz-3.11.0-0.rc5.git6.2.fc20.x86_64</programlisting>
+ </example>
+
+ <example>
+ <title>Limiting resources available to a command</title>
+
+ <programlisting># systemd-run -p BlockIOWeight=10 updatedb</programlisting>
- <para>The following command invokes the
- <citerefentry project='man-pages'><refentrytitle>updatedb</refentrytitle><manvolnum>8</manvolnum></citerefentry>
- tool, but lowers the block I/O weight for it to 10. See
- <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for more information on the <varname>BlockIOWeight=</varname>
- property.</para>
+ <para>This command invokes the
+ <citerefentry project='man-pages'><refentrytitle>updatedb</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ tool, but lowers the block I/O weight for it to 10. See
+ <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for more information on the <varname>BlockIOWeight=</varname>
+ property.</para>
+ </example>
- <programlisting># systemd-run -p BlockIOWeight=10 updatedb</programlisting>
+ <example>
+ <title>Running commands at a specified time</title>
- <para>The following command will touch a file after 30 seconds.</para>
+ <para>The following command will touch a file after 30 seconds.</para>
- <programlisting># date; systemd-run --on-active=30 --timer-property=AccuracySec=100ms /bin/touch /tmp/foo
+ <programlisting># date; systemd-run --on-active=30 --timer-property=AccuracySec=100ms /bin/touch /tmp/foo
Mon Dec 8 20:44:24 KST 2014
-Running as unit run-71.timer.
-Will run as unit run-71.service.
+Running as unit: run-71.timer
+Will run service as unit: run-71.service
# journalctl -b -u run-71.timer
-- Logs begin at Fri 2014-12-05 19:09:21 KST, end at Mon 2014-12-08 20:44:54 KST. --
Dec 08 20:44:38 container systemd[1]: Starting /bin/touch /tmp/foo.
@@ -376,13 +384,60 @@ Dec 08 20:44:38 container systemd[1]: Started /bin/touch /tmp/foo.
-- Logs begin at Fri 2014-12-05 19:09:21 KST, end at Mon 2014-12-08 20:44:54 KST. --
Dec 08 20:44:48 container systemd[1]: Starting /bin/touch /tmp/foo...
Dec 08 20:44:48 container systemd[1]: Started /bin/touch /tmp/foo.</programlisting>
-
- <para>The following command invokes <filename>/bin/bash</filename>
- as a service passing its standard input, output and error to
- the calling TTY.</para>
-
- <programlisting># systemd-run -t --send-sighup /bin/bash</programlisting>
-
+ </example>
+
+ <example>
+ <title>Allowing access to the tty</title>
+
+ <para>The following command invokes <filename>/bin/bash</filename> as a service
+ passing its standard input, output and error to the calling TTY.</para>
+
+ <programlisting># systemd-run -t --send-sighup /bin/bash</programlisting>
+ </example>
+
+ <example>
+ <title>Start <command>screen</command> as a user service</title>
+
+ <programlisting>$ systemd-run --scope --user screen
+Running scope as unit run-r14b0047ab6df45bfb45e7786cc839e76.scope.
+
+$ screen -ls
+There is a screen on:
+ 492..laptop (Detached)
+1 Socket in /var/run/screen/S-fatima.
+</programlisting>
+
+ <para>This starts the <command>screen</command> process as a child of the
+ <command>systemd --user</command> process that was started by
+ <filename>user@.service</filename>, in a scope unit. A
+ <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ unit is used instead of a
+ <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ unit, because <command>screen</command> will exit when detaching from the terminal,
+ and a service unit would be terminated. Running <command>screen</command>
+ as a user unit has the advantage that it is not part of the session scope.
+ If <varname>KillUserProcesses=yes</varname> is configured in
+ <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ the default, the session scope will be terminated when the user logs
+ out of that session.</para>
+
+ <para>The <filename>user@.service</filename> is started automatically
+ when the user first logs in, and stays around as long as at least one
+ login session is open. After the user logs out of the last session,
+ <filename>user@.service</filename> and all services underneath it
+ are terminated. This behaviour is the default, when "lingering" is
+ not enabled for that user. Enabling lingering means that
+ <filename>user@.service</filename> is started automatically during
+ boot, even if the user is not logged in, and that the service is
+ not terminated when the user logs out.</para>
+
+ <para>Enabling lingering allows the user to run processes without being logged in,
+ for example to allow <command>screen</command> to persist after the user logs out,
+ even if the session scope is terminated. In the default configuration, users can
+ enable lingering for themselves:</para>
+
+ <programlisting>$ loginctl enable-linger</programlisting>
+ </example>
</refsect1>
<refsect1>