From 0a29a3ef6a0d128087db842948694c454f7d20eb Mon Sep 17 00:00:00 2001
From: Christian Brauner <christian.brauner@ubuntu.com>
Date: Tue, 19 Sep 2017 12:41:24 +0200
Subject: [PATCH] doc: add lxc-update-config manpage

Closes #1818.

Signed-off-by: Christian Brauner <christian.brauner@ubuntu.com>
---
 configure.ac                  |   1 +
 doc/Makefile.am               |   1 +
 doc/lxc-update-config.sgml.in | 133 ++++++++++++++++++++++++++++++++++
 3 files changed, 135 insertions(+)
 create mode 100644 doc/lxc-update-config.sgml.in

diff --git a/configure.ac b/configure.ac
index e42347b4d..f5d33e9c2 100644
--- 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 b0f811517..ae023e411 100644
--- 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
index 000000000..520a898e8
--- /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:
+-->