diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/systemd-nspawn.xml | 72 | ||||
| -rw-r--r-- | man/systemd.nspawn.xml | 32 | ||||
| -rw-r--r-- | man/systemd.service.xml | 42 |
3 files changed, 120 insertions, 26 deletions
diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index 28b91dee24..86cdb4e124 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -249,15 +249,75 @@ </varlistentry> <varlistentry> + <term><option>-a</option></term> + <term><option>--as-pid2</option></term> + + <listitem><para>Invoke the shell or specified program as process ID (PID) 2 instead of PID 1 (init). By + default, if neither this option nor <option>--boot</option> is used, the selected binary is run as process with + PID 1, a mode only suitable for programs that are aware of the special semantics that the process with PID 1 + has on UNIX. For example, it needs to reap all processes reparented to it, and should implement + <command>sysvinit</command> compatible signal handling (specifically: it needs to reboot on SIGINT, reexecute + on SIGTERM, reload configuration on SIGHUP, and so on). With <option>--as-pid2</option> a minimal stub init + process is run as PID 1 and the selected binary is executed as PID 2 (and hence does not need to implement any + special semantics). The stub init process will reap processes as necessary and react appropriately to + signals. It is recommended to use this mode to invoke arbitrary commands in containers, unless they have been + modified to run correctly as PID 1. Or in other words: this switch should be used for pretty much all commands, + except when the command refers to an init or shell implementation, as these are generally capable of running + correctly as PID 1). This option may not be combined with <option>--boot</option> or + <option>--share-system</option>.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>-b</option></term> <term><option>--boot</option></term> - <listitem><para>Automatically search for an init binary and - invoke it instead of a shell or a user supplied program. If - this option is used, arguments specified on the command line - are used as arguments for the init binary. This option may not - be combined with <option>--share-system</option>. - </para></listitem> + <listitem><para>Automatically search for an init binary and invoke it as PID 1, instead of a shell or a user + supplied program. If this option is used, arguments specified on the command line are used as arguments for the + init binary. This option may not be combined with <option>--as-pid2</option> or + <option>--share-system</option>.</para> + + <para>The following table explains the different modes of invocation and relationship to + <option>--as-pid2</option> (see above):</para> + + <table> + <title>Invocation Mode</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname="switch" /> + <colspec colname="explanation" /> + <thead> + <row> + <entry>Switch</entry> + <entry>Explanation</entry> + </row> + </thead> + <tbody> + <row> + <entry>Neither <option>--as-pid2</option> nor <option>--boot</option> specified</entry> + <entry>The passed parameters are interpreted as command line, which is executed as PID 1 in the container.</entry> + </row> + + <row> + <entry><option>--as-pid2</option> specified</entry> + <entry>The passed parameters are interpreted as command line, which are executed as PID 2 in the container. A stub init process is run as PID 1.</entry> + </row> + + <row> + <entry><option>--boot</option> specified</entry> + <entry>An init binary as automatically searched and run as PID 1 in the container. The passed parameters are used as invocation parameters for this process.</entry> + </row> + + </tbody> + </tgroup> + </table> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--chdir=</option></term> + + <listitem><para>Change to the specified working directory before invoking the process in the container. Expects + an absolute path in the container's file system namespace.</para></listitem> </varlistentry> <varlistentry> diff --git a/man/systemd.nspawn.xml b/man/systemd.nspawn.xml index f39e1ad42c..c07a4b0243 100644 --- a/man/systemd.nspawn.xml +++ b/man/systemd.nspawn.xml @@ -141,15 +141,21 @@ <varlistentry> <term><varname>Boot=</varname></term> - <listitem><para>Takes a boolean argument, which defaults to off. If - enabled, <command>systemd-nspawn</command> will automatically - search for an <filename>init</filename> executable and invoke - it. In this case, the specified parameters using - <varname>Parameters=</varname> are passed as additional - arguments to the <filename>init</filename> process. This - setting corresponds to the <option>--boot</option> switch on - the <command>systemd-nspawn</command> command - line. </para></listitem> + <listitem><para>Takes a boolean argument, which defaults to off. If enabled, <command>systemd-nspawn</command> + will automatically search for an <filename>init</filename> executable and invoke it. In this case, the + specified parameters using <varname>Parameters=</varname> are passed as additional arguments to the + <filename>init</filename> process. This setting corresponds to the <option>--boot</option> switch on the + <command>systemd-nspawn</command> command line. This option may not be combined with + <varname>ProcessTwo=yes</varname>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ProcessTwo=</varname></term> + + <listitem><para>Takes a boolean argument, which defaults to off. If enabled, the specified program is run as + PID 2. A stub init process is run as PID 1. This setting corresponds to the <option>--as-pid2</option> switch + on the <command>systemd-nspawn</command> command line. This option may not be combined with + <varname>Boot=yes</varname>.</para></listitem> </varlistentry> <varlistentry> @@ -187,6 +193,14 @@ </varlistentry> <varlistentry> + <term><varname>WorkingDirectory=</varname></term> + + <listitem><para>Selects the working directory for the process invoked in the container. Expects an absolute + path in the container's file system namespace. This corresponds to the <option>--chdir=</option> command line + switch.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>Capability=</varname></term> <term><varname>DropCapability=</varname></term> diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 14f6cd6adc..4cd36ac70e 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -383,6 +383,11 @@ used to start long-running processes. All processes forked off by processes invoked via <varname>ExecStartPre=</varname> will be killed before the next service process is run.</para> + + <para>Note that if any of the commands specified in <varname>ExecStartPre=</varname>, + <varname>ExecStart=</varname>, or <varname>ExecStartPost=</varname> fail (and are not prefixed with + <literal>-</literal>, see above) or time out before the service is fully up, execution continues with commands + specified in <varname>ExecStopPost=</varname>, the commands in <varname>ExecStop=</varname> are skipped.</para> </listitem> </varlistentry> @@ -438,21 +443,36 @@ <constant>SIGKILL</constant> immediately after the command exited, this would not result in a clean stop. The specified command should hence be a synchronous operation, not an - asynchronous one.</para></listitem> + asynchronous one.</para> + + <para>Note that the commands specified in <varname>ExecStop=</varname> are only executed when the service + started successfuly first. They are not invoked if the service was never started at all, or in case its + start-up failed, for example because any of the commands specified in <varname>ExecStart=</varname>, + <varname>ExecStartPre=</varname> or <varname>ExecStartPost=</varname> failed (and weren't prefixed with + <literal>-</literal>, see above) or timed out. Use <varname>ExecStopPost=</varname> to invoke commands when a + service failed to start up correctly and is shut down again.</para> + + <para>It is recommended to use this setting for commands that communicate with the service requesting clean + termination. When the commands specified with this option are executed it should be assumed that the service is + still fully up and is able to react correctly to all commands. For post-mortem clean-up steps use + <varname>ExecStopPost=</varname> instead.</para></listitem> </varlistentry> <varlistentry> <term><varname>ExecStopPost=</varname></term> - <listitem><para>Additional commands that are executed after - the service was stopped. This includes cases where the - commands configured in <varname>ExecStop=</varname> were used, - where the service does not have any - <varname>ExecStop=</varname> defined, or where the service - exited unexpectedly. This argument takes multiple command - lines, following the same scheme as described for - <varname>ExecStart=</varname>. Use of these settings is - optional. Specifier and environment variable substitution is - supported.</para></listitem> + <listitem><para>Additional commands that are executed after the service is stopped. This includes cases where + the commands configured in <varname>ExecStop=</varname> were used, where the service does not have any + <varname>ExecStop=</varname> defined, or where the service exited unexpectedly. This argument takes multiple + command lines, following the same scheme as described for <varname>ExecStart=</varname>. Use of these settings + is optional. Specifier and environment variable substitution is supported. Note that – unlike + <varname>ExecStop=</varname> – commands specified with this setting are invoked when a service failed to start + up correctly and is shut down again.</para> + + <para>It is recommended to use this setting for clean-up operations that shall be executed even when the + service failed to start up correctly. Commands configured with this setting need to be able to operate even if + the service failed starting up half-way and left incompletely initialized data around. As the service's + processes have been terminated already when the commands specified with this setting are executed they should + not attempt to communicate with them.</para></listitem> </varlistentry> <varlistentry> |