man/systemd-run-generator.xml

   1 <?xml version="1.0"?>
   2 <!--*-nxml-*-->
   3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!--
   5   SPDX-License-Identifier: LGPL-2.1+
   6 -->
   7 <refentry id="systemd-run-generator">
   8
   9   <refentryinfo>
  10     <title>systemd-run-generator</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>systemd-run-generator</refentrytitle>
  16     <manvolnum>8</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>systemd-run-generator</refname>
  21     <refpurpose>Generator for invoking commands specified on the kernel command line as system service</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <para><filename>/usr/lib/systemd/system-generators/systemd-run-generator</filename></para>
  26   </refsynopsisdiv>
  27
  28   <refsect1>
  29     <title>Description</title>
  30
  31     <para><filename>systemd-run-generator</filename> is a generator
  32     that reads the kernel command line and understands three
  33     options:</para>
  34
  35     <para>If the <option>systemd.run=</option> option is specified and followed by a command line, a unit named
  36     <filename>kernel-command-line.service</filename> is generated for it and booted into. The service has
  37     <varname>Type=oneshot</varname> set, and has <varname>SuccessAction=exit</varname> and
  38     <varname>FailureAction=exit</varname> configured by default, thus ensuring that the system is shut down as soon as
  39     the command completes. The exit status of the command line is propagated to the invoking container manager, if
  40     this applies (which might propagate this further, to the calling shell — e.g.
  41     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>7</manvolnum></citerefentry> does this). If
  42     this option is used multiple times the unit file will contain multiple <varname>ExecStart=</varname> lines, to
  43     execute all commands in order. The command is started as regular service, i.e. with
  44     <varname>DefaultDependencies=</varname> on. </para>
  45
  46     <para>Use <option>systemd.run_success_action=</option> and <option>systemd.run_failure_action=</option> to tweak
  47     how to react to the process completing. In particular assigning <literal>none</literal> will leave the system
  48     running after the command completes. For further details on supported arguments, see
  49     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
  50
  51     <para><filename>systemd-run-generator</filename> implements
  52     <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
  53   </refsect1>
  54
  55   <refsect1>
  56     <title>Example</title>
  57
  58     <para>Use a command like the following to add a user to the user database inside a container run with
  59     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>7</manvolnum></citerefentry>:</para>
  60
  61     <programlisting># systemd-nspawn -D mycontainer -b systemd.run='"adduser test"'</programlisting>
  62     <para>(Note the requirement for double quoting in the command line above. The first level of quoting ('') is
  63     processed and removed by the command shell used to invoke <command>systemd-nspawn</command>. The second level of
  64     quoting ("") is propagated to the kernel command line of the container and processed and removed by
  65     <command>systemd-run-generator</command>. Both together make sure both words of the specified command line
  66     <command>adduser test</command> end up in the generated unit file together and are neither split apart by the
  67     command shell nor by the generator.)</para>
  68   </refsect1>
  69
  70   <refsect1>
  71     <title>See Also</title>
  72     <para>
  73       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
  74       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
  75       <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
  76       <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
  77       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  78       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  79     </para>
  80   </refsect1>
  81
  82 </refentry>