update lxc-checkpoint / lxc-restart man

Add documentation for checkpoint / restart CLI.

Signed-off-by: Daniel Lezcano <dlezcano@fr.ibm.com>

diff --git a/configure.ac b/configure.ac
index 53702708212e48cc0bbe1ad8bdaf179ad0203a9d..e91f69e07e03f4798659dc045f788056850ab810 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -105,6 +105,8 @@ AC_CONFIG_FILES([
        doc/lxc-destroy.sgml
        doc/lxc-execute.sgml
        doc/lxc-start.sgml
+       doc/lxc-checkpoint.sgml
+       doc/lxc-restart.sgml
        doc/lxc-stop.sgml
        doc/lxc-console.sgml
        doc/lxc-freeze.sgml

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 2ac522590c3f4ad2f3fcd03488cbeb15936238b4..8530ee9956e5256005c89fdcd10ce82af422b26e 100644 (file)
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -12,6 +12,8 @@ man_MANS = \
        lxc-execute.1 \
        lxc-start.1 \
        lxc-stop.1 \
+       lxc-checkpoint.1 \
+       lxc-restart.1 \
        lxc-console.1 \
        lxc-freeze.1 \
        lxc-unfreeze.1 \

diff --git a/doc/lxc-checkpoint.sgml.in b/doc/lxc-checkpoint.sgml.in
new file mode 100644 (file)
index 0000000..94befe6
--- /dev/null
+++ b/doc/lxc-checkpoint.sgml.in
@@ -0,0 +1,191 @@
+<!--
+
+lxc: linux Container library
+
+(C) Copyright IBM Corp. 2007, 2008
+
+Authors:
+Daniel Lezcano <dlezcano at fr.ibm.com>
+
+This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+-->
+
+<!DOCTYPE refentry PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
+
+<!ENTITY commonoptions SYSTEM "@builddir@/common_options.sgml">
+<!ENTITY seealso SYSTEM "@builddir@/see_also.sgml">
+]>
+
+<refentry>
+
+  <docinfo><date>@LXC_GENERATE_DATE@</date></docinfo>
+
+  <refmeta>
+    <refentrytitle>lxc-checkpoint</refentrytitle>
+    <manvolnum>1</manvolnum>
+    <refmiscinfo>IBM</refmiscinfo>
+  </refmeta>
+
+  <refnamediv>
+    <refname>lxc-checkpoint</refname>
+
+    <refpurpose>
+      checkpoint a running container
+    </refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>lxc-checkpoint
+       --statefile=<replaceable>FILE</replaceable>
+       --statefd=<replaceable>FD</replaceable>
+       --name=<replaceable>NAME</replaceable> </command>
+      <arg><option>-k</option>|<option>-p</option></arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>
+      <command>lxc-checkpoint</command> is a command
+      to checkpoint the specified container
+      <replaceable>NAME</replaceable> and dumps its state into the file
+      <replaceable>FILE</replaceable>. If the
+      option <option>--kill</option> is specified, the application
+      running in the container will terminate after the checkpoint
+      just before resuming its execution. If the
+      option <option>--pause</option> is specified, the application
+      will be stopped after the checkpoint just before resuming
+      execution. The command <command>lxc-unfreeze</command> will
+      resume its execution.
+    </para>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Checkpoint Options</title>
+
+    <variablelist>
+
+      <varlistentry>
+       <term><option>-S, --statefile=<replaceable>FILE</replaceable></option></term>
+       <listitem>
+         <para>
+           write the state of the container in this
+           <replaceable>FILE</replaceable>.
+           This option is exclusive with <option>--statefd</option> below.
+         </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term><option>-d, --statefd=<replaceable>FD</replaceable></option></term>
+       <listitem>
+         <para>
+           write the state of the container in this
+           <replaceable>FD</replaceable> file descriptor.
+           This option is exclusive with above <option>--statefile</option>.
+         </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term><option>-k,--kill</option></term>
+       <listitem>
+         <para>
+           Kill container processes after checkpoint. the processes are sent
+           a <literal>SIGKILL</literal> signal.
+         </para>
+         <para>
+           This option is mutually exclusive with the following
+           <option>--pause</option> option.
+         </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term><option>-p,--pause</option></term>
+       <listitem>
+         <para>
+           Pause container processes after checkpoint. The container
+           will be stopped until you resume it. This option is
+           mutually exclusive with previously mentionned
+           <option>--kill</option> option.
+         </para>
+       </listitem>
+      </varlistentry>
+
+    </variablelist>
+
+  </refsect1>
+
+  &commonoptions;
+
+  <refsect1>
+    <title>Examples</title>
+    <para>
+      To start a new container <literal>123</literal> computing decimals of pi
+    </para>
+    <programlisting>
+      lxc-execute -n 123 -- pi1 -d 500000
+      lxc-execute --name=123 -- pi1 -d 500000
+    </programlisting>
+
+    <para>
+      to checkpoint the same container in <emphasis>dump-death</emphasis>
+      mode
+    </para>
+    <programlisting>
+      lxc-checkpoint -n 123 -S /share/123/chkpt1 -k
+      lxc-checkpoint --name=123 -S /share/123/chkpt1 -k
+    </programlisting>
+
+    <para>
+      to checkpoint the same container and <emphasis>pause</emphasis> it
+    </para>
+    <programlisting>
+      lxc-checkpoint -n 123 -S /share/123/chkpt1 -p
+      lxc-checkpoint --name=123 -S /share/123/chkpt1 -p
+    </programlisting>
+
+  </refsect1>
+
+  &seealso;
+
+  <refsect1>
+    <title>Author</title>
+    <para>Daniel Lezcano <email>daniel.lezcano@free.fr</email></para>
+  </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:2
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:nil
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+-->

diff --git a/doc/lxc-kill.sgml.in b/doc/lxc-kill.sgml.in
index 2b06ab866cb9b30dad592e7a72b3c777185c8cca..5bec922471d22441ef913a7da45a5e5ba9be21bd 100644 (file)
--- a/doc/lxc-kill.sgml.in
+++ b/doc/lxc-kill.sgml.in
@@ -1,13 +1,32 @@
+<!--
+
+lxc: linux Container library
+
+(C) Copyright IBM Corp. 2007, 2008
+
+Authors:
+Daniel Lezcano <dlezcano at fr.ibm.com>
+
+This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+-->
+
 <!DOCTYPE refentry PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
 
-<!ENTITY copyrights SYSTEM "@builddir@/copyrights.sgml">
 <!ENTITY commonoptions SYSTEM "@builddir@/common_options.sgml">
 <!ENTITY seealso SYSTEM "@builddir@/see_also.sgml">
-
-<!ENTITY mcr "<citerefentry>
-<refentrytitle><command>mcr</command></refentrytitle>
-<manvolnum/1/</citerefentry>">
-
 ]>
 
 <refentry>
@@ -41,10 +60,9 @@
       <command>lxc-kill</command> send
       the <replaceable>SIGNUM</replaceable> signal to the first process of the container.
     </para>
-
     <para>
-      The <replaceable>SIGNUM</replaceable> is a numeric value,
-      the signal name is not supported.
+       The <replaceable>SIGNUM</replaceable> is a numeric value,
+       the signal name is not supported.
     </para>
     <para>
        If this command is used on an application container ran by
@@ -73,10 +91,13 @@
 
   </refsect1>
 
-  &copyrights;
-
   &seealso;
 
+  <refsect1>
+    <title>Author</title>
+    <para>Daniel Lezcano <email>daniel.lezcano@free.fr</email></para>
+  </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file

diff --git a/doc/lxc-restart.sgml.in b/doc/lxc-restart.sgml.in
new file mode 100644 (file)
index 0000000..8e95441
--- /dev/null
+++ b/doc/lxc-restart.sgml.in
@@ -0,0 +1,203 @@
+<!--
+
+lxc: linux Container library
+
+(C) Copyright IBM Corp. 2007, 2008
+
+Authors:
+Daniel Lezcano <dlezcano at fr.ibm.com>
+
+This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+-->
+
+<!DOCTYPE refentry PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
+
+<!ENTITY commonoptions SYSTEM "@builddir@/common_options.sgml">
+<!ENTITY seealso SYSTEM "@builddir@/see_also.sgml">
+]>
+
+<refentry>
+
+  <docinfo><date>@LXC_GENERATE_DATE@</date></docinfo>
+
+  <refmeta>
+    <refentrytitle>lxc-restart</refentrytitle>
+    <manvolnum>1</manvolnum>
+    <refmiscinfo>IBM</refmiscinfo>
+  </refmeta>
+
+  <refnamediv>
+    <refname>lxc-restart</refname>
+
+    <refpurpose>
+      restart a container from a file
+    </refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>lxc-restart <optional>-f
+       config_file</optional><optional>-s KEY=VAL</optional>
+       --statefile=<replaceable>FILE</replaceable>
+       --statefd=<replaceable>FD</replaceable></command>
+      <arg choice=req><option>--name=<replaceable>NAME</replaceable></option></arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>
+      <command>lxc-restart</command> is a command
+      to restart an application from the state read in the specified
+      <replaceable>FILE</replaceable>, in a container with the
+      identifier <replaceable>NAME</replaceable>.
+      If the option <option>--pause</option>
+      is specified, the application will be stopped after the
+      restart just before resuming execution. The command
+      <command>lxc-unfreeze</command> will be needed to resume its
+      execution.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Restart Options</title>
+
+    <variablelist>
+      <varlistentry>
+       <term><option>-S, --statefile=<replaceable>FILE</replaceable></option></term>
+       <listitem>
+         <para>
+           read the state of the container in this
+           <replaceable>FILE</replaceable>.
+           This option is exclusive with <option>--statefd</option> below.
+         </para>
+       </listitem>
+      </varlistentry>
+
+       <varlistentry>
+       <term><option>-d, --statefd=<replaceable>FD</replaceable></option></term>
+       <listitem>
+         <para>
+           read the state of the container in this
+           <replaceable>FD</replaceable> file descriptor.
+           This option is exclusive with above <option>--statefile</option>.
+         </para>
+       </listitem>
+       </varlistentry>
+
+       <varlistentry>
+       <term><option>-p</option></term>
+       <listitem>
+         <para>
+           Pause container processes after restart. The container will be
+           stopped until you resume it with the lxc-unfreeze command.
+         </para>
+       </listitem>
+       </varlistentry>
+
+       <varlistentry>
+       <term><option>-f, --rcfile=<replaceable>config_file</replaceable></option></term>
+       <listitem>
+         <para>
+           Specify the configuration file to configure the
+           virtualization and isolation functionalities for the
+           container. This parameter should be specified if it was
+           specified for the <command>lxc-execute</command>
+           or <command>lxc-start</command> commands or if the
+           container configuration has to be changed at restart. The
+           latter may fail if the needed resources are not available
+           for the restart. If the container was created and
+           configured with <command>lxc-create</command>, this option
+           is not needed, the configuration will be automatically
+           found.
+         </para>
+       </listitem>
+       </varlistentry>
+
+       <varlistentry>
+       <term>
+         <option>-s <replaceable>KEY=VAL</replaceable></option>
+       </term>
+       <listitem>
+         <para>
+           Assign value <replaceable>VAL</replaceable> to configuration
+           variable <replaceable>KEY</replaceable>. This overrides any
+           assignment done in <replaceable>config_file</replaceable>.
+         </para>
+       </listitem>
+      </varlistentry>
+
+    </variablelist>
+
+  </refsect1>
+
+  &commonoptions;
+
+  <refsect1>
+    <title>Examples</title>
+    <para>
+      To start a new container <literal>123</literal> computing decimals of pi
+    </para>
+    <programlisting>
+      lxc-execute -n 123 -- pi1 -d 500000
+      lxc-execute --name=123 -- pi1 -d 500000
+    </programlisting>
+
+    <para>
+      to checkpoint the same container in <emphasis>dump-death</emphasis>
+      mode
+    </para>
+    <programlisting>
+      lxc-checkpoint -n 123 -S /share/123/chkpt1 -k
+      lxc-checkpoint --name=123 --statefile=/share/123/chkpt1 -k
+    </programlisting>
+
+    <para>
+      and to restart the same container with a different id
+    </para>
+    <programlisting>
+      lxc-restart -n 200 -S /share/123/chkpt1
+      lxc-restart --name=200 --statefile=/share/123/chkpt1
+    </programlisting>
+
+   </refsect1>
+
+  &seealso;
+
+  <refsect1>
+    <title>Author</title>
+    <para>Daniel Lezcano <email>daniel.lezcano@free.fr</email></para>
+  </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:2
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:nil
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+-->