[pve-devel] [PATCH docs 2/3] add mountpoint restore documentation

[Fabian Grünbichler]

---
 pct.adoc | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/pct.adoc b/pct.adoc
index 014e48d..38d5507 100644
--- a/pct.adoc
+++ b/pct.adoc
@@ -452,6 +452,45 @@ and destroy containers, and control execution (start, stop, migrate,
 ...). You can use pct to set parameters in the associated config file,
 like network configuration or memory limits.
 
+Restoring vzdump container backup archives with 'pct restore'
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When restoring container backup archives created with vzdump, the `pct
+restore` command will - by default - restore as much of the configuration as
+possible. It is possible to selectively override the backed up configuration
+values or add completely new options on the command line (e.g., if you provide
+the `-memory 1024` option to pct restore, the restored container will be
+configured to use 1024Mb of memory).
+
+For the set of mountpoint options (i.e., `rootfs` and `mp0` to `mp9`), there is
+a distinction between two different restore modes:
+
+.Recovering mountpoint configuration
+
+By default (if no mountpoint option is overridden on the command line), `pct
+restore` will recreate volume mountpoints that are found in the backed up
+configuration. All recovered mountpoints will be created on the same storage
+(provided via `-storage`, defaulting to `local`), with the size and other
+options copied from the backed up configuration.
+
+.Manual mountpoint configuration
+
+If `-rootfs` and optionally any of `-mp0` to `-mp9` are set on the command line,
+`pct restore` will ignore the mountpoint configuration in the backup archive,
+and instead set up the mountpoints according to the provided parameters. This
+advanced mode allows very flexible reconfiguration of mountpoints, e.g. it is
+possible to restore different mountpoints to different storages or completely
+change the mountpoint targets and other options.
+
+NOTE: In both modes, bind and device mounts are configured after the backed up
+files were already extracted from the backup archive.
+
+NOTE: The configuration file stored in a backup archive can be displayed with
+`pvesm extractconfig`.
+
+NOTE: the read-only option (`ro`) is temporarily disabled while restoring files
+from a backup archive.
+
 CLI Usage Examples
 ~~~~~~~~~~~~~~~~~~
 
@@ -460,6 +499,20 @@ already downloaded the template via the webgui)
 
  pct create 100 /var/lib/vz/template/cache/debian-8.0-standard_8.0-1_amd64.tar.gz
 
+Restore vzdump backup, recover mountpoint configuration from backup archive and
+change memory limit
+
+ pct restore 100 /var/lib/vz/template/dump/vzdump-lxc-100-2016-01-01-12-00-00.tar -memory 1024
+
+Restore vzdump backup to non-default storage, recover mountpoint configuration
+
+ pct restore 100 /var/lib/vz/template/dump/vzdump-lxc-100-2016-01-01-12-00-00.tar -storage otherstorage
+
+Restore vzdump backup, manually configure 5Gb `rootfs` on local and read-only
+2Gb `mp1` on otherstorage instead of recovering mountpoint configuration
+
+ pct restore 100 /var/lib/vz/template/dump/vzdump-lxc-100-2016-01-01-12-00-00.tar -rootfs local:5 -mp1 otherstorage:2,mp=/mnt/target,ro=1
+
 Start container 100
 
  pct start 100
-- 
2.1.4