From d083d3d384304e74892ad5d6907c8eb9f1444fb8 Mon Sep 17 00:00:00 2001
From: Dietmar Maurer <dietmar@proxmox.com>
Date: Thu, 14 Apr 2016 10:53:46 +0200
Subject: [PATCH] vzdump.adoc: auto-generate configuration options

---
 gen-vzdump.conf.5-opts.pl | 26 +++++++++++++++
 pve-doc-generator.mk      |  1 +
 vzdump.adoc               | 38 +++++++++++++--------
 vzdump.conf.5-opts.adoc   | 69 +++++++++++++++++++++++++++++++++++++++
 4 files changed, 120 insertions(+), 14 deletions(-)
 create mode 100755 gen-vzdump.conf.5-opts.pl
 create mode 100644 vzdump.conf.5-opts.adoc

diff --git a/gen-vzdump.conf.5-opts.pl b/gen-vzdump.conf.5-opts.pl
new file mode 100755
index 0000000..4e013fb
--- /dev/null
+++ b/gen-vzdump.conf.5-opts.pl
@@ -0,0 +1,26 @@
+#!/usr/bin/perl
+
+use lib '.';
+use strict;
+use warnings;
+use PVE::RESTHandler;
+use PVE::VZDump;
+
+my $prop = PVE::VZDump::json_config_properties();
+my $skip = {
+    all => 1,
+    exclude => 1,
+    vmid => 1,
+    node => 1,
+    quiet => 1,
+    size => 1,
+    stop => 1,
+};
+
+my $filterFn = sub {
+    my ($k, $phash) = @_;
+
+    return $skip->{$k} || 0;
+};
+
+print PVE::RESTHandler::dump_properties($prop, 'asciidoc', 'config', $filterFn);
diff --git a/pve-doc-generator.mk b/pve-doc-generator.mk
index 2d77f0e..51e02a8 100644
--- a/pve-doc-generator.mk
+++ b/pve-doc-generator.mk
@@ -41,6 +41,7 @@ PVESM_MAN1_SOURCES=			\
 VZDUMP_MAN1_SOURCES=			\
 	vzdump.adoc 			\
 	vzdump.1-synopsis.adoc		\
+	vzdump.conf.5-opts.adoc		\
 	${PVE_COMMON_DOC_SOURCES}
 
 PVESUBSCRIPTION_MAN1_SOURCES=		\
diff --git a/vzdump.adoc b/vzdump.adoc
index 42383be..d9ccfe6 100644
--- a/vzdump.adoc
+++ b/vzdump.adoc
@@ -56,6 +56,9 @@ A technical overview of the Proxmox VE live backup for QemuServer can
 be found online
 https://git.proxmox.com/?p=pve-qemu-kvm.git;a=blob;f=backup.txt[here].
 
+NOTE: Qemu backup provides snapshots on any storage type. It does
+not require that the underlying storage supports snapshots.
+
 
 .Backup `mode` for Containers:
 
@@ -111,20 +114,27 @@ For details see the corresponding manual pages.
 Configuration
 -------------
 
-Global configuration is stored in '/etc/vzdump.conf'.
-
- tmpdir: DIR
- dumpdir: DIR
- storage: STORAGE_ID
- mode: snapshot|suspend|stop
- bwlimit: KBPS
- ionize: PRI
- lockwait: MINUTES
- stopwait: MINUTES
- size: MB
- maxfiles: N
- script: FILENAME
- exclude-path: PATHLIST
+Global configuration is stored in '/etc/vzdump.conf'. The file uses a
+simple colon separated key/value format. Each line has the following
+format:
+
+ OPTION: value
+
+Blank lines in the file are ignored, and lines starting with a '#'
+character are treated as comments and are also ignored.
+
+We currently support the following options:
+
+include::vzdump.conf.5-opts.adoc[]
+
+
+.Example 'vzdump.conf' Configuration
+----
+tmpdir: /mnt/fast_local_disk
+storage: my_backup_storage
+mode: snapshot
+bwlimit: 10000
+----
 
 Hook Scripts
 ------------
diff --git a/vzdump.conf.5-opts.adoc b/vzdump.conf.5-opts.adoc
new file mode 100644
index 0000000..2e72b23
--- /dev/null
+++ b/vzdump.conf.5-opts.adoc
@@ -0,0 +1,69 @@
+`bwlimit`: `integer (0 - N)` (default=`0`)::
+
+Limit I/O bandwidth (KBytes per second).
+
+`compress`: `(0 | 1 | gzip | lzo)` (default=`0`)::
+
+Compress dump file.
+
+`dumpdir`: `string` ::
+
+Store resulting files to specified directory.
+
+`exclude-path`: `string` ::
+
+Exclude certain files/directories (shell globs).
+
+`ionice`: `integer (0 - 8)` (default=`7`)::
+
+Set CFQ ionice priority.
+
+`lockwait`: `integer (0 - N)` (default=`180`)::
+
+Maximal time to wait for the global lock (minutes).
+
+`mailnotification`: `(always | failure)` (default=`always`)::
+
+Specify when to send an email
+
+`mailto`: `string` ::
+
+no description available
+
+`maxfiles`: `integer (1 - N)` (default=`1`)::
+
+Maximal number of backup files per guest system.
+
+`mode`: `(snapshot | stop | suspend)` (default=`snapshot`)::
+
+Backup mode.
+
+`pigz`: `integer` (default=`0`)::
+
+Use pigz instead of gzip when N>0. N=1 uses half of cores, N>1 uses N as
+thread count.
+
+`remove`: `boolean` (default=`1`)::
+
+Remove old backup files if there are more than 'maxfiles' backup files.
+
+`script`: `string` ::
+
+Use specified hook script.
+
+`stdexcludes`: `boolean` (default=`1`)::
+
+Exclude temporary files and logs.
+
+`stopwait`: `integer (0 - N)` (default=`10`)::
+
+Maximal time to wait until a guest system is stopped (minutes).
+
+`storage`: `string` ::
+
+Store resulting file to this storage.
+
+`tmpdir`: `string` ::
+
+Store temporary files to specified directory.
+
-- 
2.39.2