X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd-run.xml;h=cc8a68a0227dc369b5f05dfe90ae3c7c40719121;hp=4ced9bfc00b5d1233d560291e97a5793cb751bdd;hb=2614202b517790d1d11319dce830a9bdcca37f00;hpb=f09114bcc7dc9d4699e6ae41150056256bfbabb2;ds=sidebyside

diff --git a/man/systemd-run.xml b/man/systemd-run.xml
index 4ced9bfc0..cc8a68a02 100644
--- a/man/systemd-run.xml
+++ b/man/systemd-run.xml
@@ -44,7 +44,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
   <refnamediv>
     <refname>systemd-run</refname>
-    <refpurpose>Run programs as volatile systemd units</refpurpose>
+    <refpurpose>Run programs in transient scope or service units</refpurpose>
   </refnamediv>
 
   <refsynopsisdiv>
@@ -60,11 +60,26 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
   <refsect1>
     <title>Description</title>
 
-    <para><command>systemd-run</command> may be used
-    create a transient <filename>.service</filename> unit
-    or a <filename>.scope</filename> unit and launch the
-    specified <replaceable>COMMAND</replaceable> as part
-    of this unit.</para>
+    <para><command>systemd-run</command> may be used to create and start
+    a transient <filename>.service</filename> or a
+    <filename>.scope</filename> unit and run the specified
+    <replaceable>COMMAND</replaceable> in it.</para>
+
+    <para>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 <command>systemctl
+    list-units</command> like any other unit. It will run in a clean
+    and detached execution environment. <command>systemd-run</command>
+    will start the service asynchronously in the background and
+    immediately return.</para>
+
+    <para>If a command is run as transient scope unit, it will be
+    started directly by <command>systemd-run</command> 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 <command>systemctl
+    list-units</command>. Execution in this case is synchronous, and
+    execution will return only when the command finishes.</para>
   </refsect1>
 
   <refsect1>
@@ -92,16 +107,37 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
         <term><option>--user</option></term>
 
         <listitem>
-          <para>Talk to the systemd manager of the calling
-          user.</para>
+          <para>Talk to the service manager of the calling user,
+          rather than the service manager of the system.</para>
         </listitem>
       </varlistentry>
 
+      <varlistentry>
+              <term><option>-H</option></term>
+              <term><option>--host=</option></term>
+
+              <listitem><para>Execute operation
+              remotely. Specify a hostname, or
+              username and hostname separated by <literal>@</literal>,
+              to connect to. This will use SSH to
+              talk to the remote machine manager
+              instance.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+              <term><option>-M</option></term>
+              <term><option>--machine=</option></term>
+
+              <listitem><para>Execute operation on a
+              local container. Specify a container
+              name to connect to.</para></listitem>
+      </varlistentry>
+
       <varlistentry>
         <term><option>--scope</option></term>
 
         <listitem>
-          <para>Create a <filename>.scope</filename> unit instead of
+          <para>Create a transient <filename>.scope</filename> unit instead of
           the default transient <filename>.service</filename> unit.
           </para>
         </listitem>
@@ -132,11 +168,37 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
         instead of the <filename>system.slice</filename>.</para>
         </listitem>
       </varlistentry>
+
+      <varlistentry>
+        <term><option>--remain-after-exit</option></term>
+
+        <listitem><para>After the service's 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
+        <varname>RemainAfterExit=</varname> in
+        <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+        </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--send-sighup</option></term>
+
+        <listitem><para>When terminating the scope 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 <varname>SendSIGHUP=</varname> in
+        <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+        </para>
+        </listitem>
+      </varlistentry>
     </variablelist>
 
     <para>All command-line arguments after the first non-option
     argument become part of the commandline of the launched
-    process.</para>
+    process. If a command is run as service unit, its first argument
+    needs to be an absolute binary path.</para>
   </refsect1>
 
   <refsect1>
@@ -146,14 +208,33 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
     code otherwise.</para>
   </refsect1>
 
+  <refsect1>
+    <title>Example</title>
+
+    <para>The following command will log the environment variables
+    provided by systemd to services:</para>
+
+    <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>
+  </refsect1>
+
   <refsect1>
     <title>See Also</title>
     <para>
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+      <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
     </para>
   </refsect1>