doc: add lxc-update-config manpage

Closes #1818.

Signed-off-by: Christian Brauner <christian.brauner@ubuntu.com>

diff --git a/configure.ac b/configure.ac
index 35fe7964057e198debb99b30349d52cf119cd624..fcfec39cdeacdc466337cf15a0ebd5f57cc27faa 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -785,6 +785,7 @@ AC_CONFIG_FILES([
        doc/lxc-top.sgml
        doc/lxc-unfreeze.sgml
        doc/lxc-unshare.sgml
+       doc/lxc-update-config.sgml
        doc/lxc-user-nic.sgml
        doc/lxc-usernsexec.sgml
        doc/lxc-wait.sgml

diff --git a/doc/Makefile.am b/doc/Makefile.am
index b0f81151761492330fc6fca39ae66368fbafed61..ae023e4114e5b29dab7e10f9f796cfbc136b378e 100644 (file)
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -38,6 +38,7 @@ man_MANS = \
        lxc-top.1 \
        lxc-unfreeze.1 \
        lxc-unshare.1 \
+       lxc-update-config.1 \
        lxc-user-nic.1 \
        lxc-usernsexec.1 \
        lxc-wait.1 \

diff --git a/doc/lxc-update-config.sgml.in b/doc/lxc-update-config.sgml.in
new file mode 100644 (file)
index 0000000..520a898
--- /dev/null
+++ b/doc/lxc-update-config.sgml.in
@@ -0,0 +1,133 @@
+<!--
+
+lxc-update-config
+
+(C) Copyright 2017 Canonical Ltd.
+
+Authors:
+Christian Brauner <christian.brauner@ubuntu.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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+
+-->
+
+<!DOCTYPE refentry PUBLIC @docdtd@ [
+    <!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-update-config</refentrytitle>
+        <manvolnum>1</manvolnum>
+    </refmeta>
+
+    <refnamediv>
+        <refname>lxc-update-config</refname>
+
+        <refpurpose>
+            update a legacy pre LXC 2.1 configuration file
+        </refpurpose>
+    </refnamediv>
+
+    <refsynopsisdiv>
+        <cmdsynopsis>
+            <command>lxc-update-config</command>
+            <arg choice="req">-c <replaceable>config</replaceable></arg>
+        </cmdsynopsis>
+    </refsynopsisdiv>
+
+    <refsect1>
+        <title>Description</title>
+
+        <para>
+           <command>lxc-update-config</command> detects any legacy
+           configuration keys in the given <replaceable>config</replaceable>
+           file and will replace them with the appropriate new configuration
+           keys.
+        </para>
+       <para>
+           <command>lxc-update-config</command> will first create a backup of
+           the old <replaceable>config</replaceable> file in the same directory
+           and name it <replaceable>config.backup</replaceable> and then update
+           the original <replaceable>config</replaceable> file in place. In
+           case the update fails to apply or leads to an invalid
+           <replaceable>config</replaceable> file that cannot be used to start
+           a container users can either compare
+           <replaceable>config</replaceable> with
+           <replaceable>config.backup</replaceable> and try to manually repair
+           any the invalid configuration keys or simply rollback to the legacy
+           configuration file by copying
+           <replaceable>config.backup</replaceable> to
+           <replaceable>config</replaceable>.
+        </para>
+       <para>
+           Any failures for <command>lxc-update-config</command> to generate a
+           useable <replaceable>config</replaceable> file are a bug and should
+           be reported upstream.
+        </para>
+    </refsect1>
+
+    <refsect1>
+        <title>Options</title>
+        <variablelist>
+            <varlistentry>
+                <term>
+                    <option>-c, --config</option>
+                </term>
+                <listitem>
+                    <para>
+                       Path to the configuration file to update.
+                    </para>
+                </listitem>
+            </varlistentry>
+
+            <varlistentry>
+                <term>
+                    <option>-h, --help</option>
+                </term>
+                <listitem>
+                    <para>
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsect1>
+
+    &seealso;
+
+    <refsect1>
+        <title>Author</title>
+        <para>Christian Brauner <email>christian.brauner@ubuntu.com</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:
+-->