pct: merge wiki content about bind mounts

[pve-docs.git] / pct.adoc

diff --git a/pct.adoc b/pct.adoc
index 40028b70f4b0796933ad342cc2bf186a7cd5aba5..14e2d3781b577ab3f3b26ff5966baa1cd24f9b13 100644 (file)
--- a/pct.adoc
+++ b/pct.adoc
@@ -363,7 +363,14 @@ include::pct-mountpoint-opts.adoc[]
 Currently there are basically three types of mount points: storage backed
 mount points, bind mounts and device mounts.
 
 Currently there are basically three types of mount points: storage backed
 mount points, bind mounts and device mounts.
 

-.Storage backed mount points
+.Typical Container `rootfs` configuration
+----
+rootfs: thin1:base-100-disk-1,size=8G
+----
+
+
+Storage backed mount points
+^^^^^^^^^^^^^^^^^^^^^^^^^^^

 
 Storage backed mount points are managed by the {pve} storage subsystem and come
 in three different flavors:
 
 Storage backed mount points are managed by the {pve} storage subsystem and come
 in three different flavors:


@@ -375,25 +382,48 @@ in three different flavors:
 - Directories: passing `size=0` triggers a special case where instead of a raw
   image a directory is created.
 
 - Directories: passing `size=0` triggers a special case where instead of a raw
   image a directory is created.
 

-.Bind mount points
+
+Bind mount points
+^^^^^^^^^^^^^^^^^
+
+Bind mounts allow you to access arbitrary directories from your Proxmox VE host
+inside a container. Some potential use cases are:
+
+- Accessing your home directory in the guest
+- Accessing an USB device directory in the guest
+- Accessing an NFS mount from in the host in the guest

 
 Bind mounts are considered to not be managed by the storage subsystem, so you
 
 Bind mounts are considered to not be managed by the storage subsystem, so you

-cannot make snapshots or deal with quotas from inside the container, and with
+cannot make snapshots or deal with quotas from inside the container. With

 unprivileged containers you might run into permission problems caused by the
 unprivileged containers you might run into permission problems caused by the

-user mapping, and cannot use ACLs from inside an unprivileged container.
+user mapping and cannot use ACLs.
+
+NOTE: The contents of bind mount points are not backed up when using 'vzdump'.

 
 WARNING: For security reasons, bind mounts should only be established
 using source directories especially reserved for this purpose, e.g., a
 directory hierarchy under `/mnt/bindmounts`. Never bind mount system
 directories like `/`, `/var` or `/etc` into a container - this poses a
 
 WARNING: For security reasons, bind mounts should only be established
 using source directories especially reserved for this purpose, e.g., a
 directory hierarchy under `/mnt/bindmounts`. Never bind mount system
 directories like `/`, `/var` or `/etc` into a container - this poses a

-great security risk. The bind mount source path must not contain any symlinks.
+great security risk.
+
+NOTE: The bind mount source path must not contain any symlinks.
+
+For example, to make the directory `/mnt/bindmounts/shared` accessible in the
+container with ID `100` under the path `/shared`, use a configuration line like
+'mp0: /mnt/bindmounts/shared,mp=/shared' in '/etc/pve/lxc/100.conf'.
+Alternatively, use 'pct set 100 -mp0 /mnt/bindmounts/shared,mp=/shared' to
+achieve the same result.

 
 

-.Device mount points
+
+Device mount points
+^^^^^^^^^^^^^^^^^^^

 
 Similar to bind mounts, device mounts are not managed by the storage, but for
 these the `quota` and `acl` options will be honored.
 
 
 Similar to bind mounts, device mounts are not managed by the storage, but for
 these the `quota` and `acl` options will be honored.
 

-.FUSE mounts
+
+FUSE mounts
+~~~~~~~~~~~

 
 WARNING: Because of existing issues in the Linux kernel's freezer
 subsystem the usage of FUSE mounts inside a container is strongly
 
 WARNING: Because of existing issues in the Linux kernel's freezer
 subsystem the usage of FUSE mounts inside a container is strongly


@@ -404,11 +434,6 @@ If FUSE mounts cannot be replaced by other mounting mechanisms or storage
 technologies, it is possible to establish the FUSE mount on the Proxmox host
 and use a bind mount point to make it accessible inside the container.
 
 technologies, it is possible to establish the FUSE mount on the Proxmox host
 and use a bind mount point to make it accessible inside the container.
 

-.Typical Container `rootfs` configuration
-----
-rootfs: thin1:base-100-disk-1,size=8G
-----
-

 
 Using quotas inside containers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Using quotas inside containers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


@@ -458,9 +483,68 @@ include::pct-network-opts.adoc[]
 Backup and Restore
 ------------------
 
 Backup and Restore
 ------------------
 

+Container Backup
+~~~~~~~~~~~~~~~~
+

 It is possible to use the 'vzdump' tool for container backup. Please
 refer to the 'vzdump' manual page for details.
 
 It is possible to use the 'vzdump' tool for container backup. Please
 refer to the 'vzdump' manual page for details.
 

+Restoring Container Backups
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Restoring container backups made with 'vzdump' is possible using the
+'pct restore' command. By default, 'pct restore' will attempt to restore as much
+of the backed up container configuration as possible. It is possible to override
+the backed up configuration by manually setting container options on the command
+line (see the 'pct' manual page for details).
+
+NOTE: 'pvesm extractconfig' can be used to view the backed up configuration
+contained in a vzdump archive.
+
+There are two basic restore modes, only differing by their handling of mount
+points:
+
+
+"Simple" restore mode
+^^^^^^^^^^^^^^^^^^^^^
+
+If neither the `rootfs` parameter nor any of the optional `mpX` parameters
+are explicitly set, the mount point configuration from the backed up
+configuration file is restored using the following steps:
+
+. Extract mount points and their options from backup
+. Create volumes for storage backed mount points (on storage provided with the
+`storage` parameter, or default local storage if unset)
+. Extract files from backup archive
+. Add bind and device mount points to restored configuration (limited to root user)
+
+NOTE: Since bind and device mount points are never backed up, no files are
+restored in the last step, but only the configuration options. The assumption
+is that such mount points are either backed up with another mechanism (e.g.,
+NFS space that is bind mounted into many containers), or not intended to be
+backed up at all.
+
+This simple mode is also used by the container restore operations in the web
+interface.
+
+
+"Advanced" restore mode
+^^^^^^^^^^^^^^^^^^^^^^^
+
+By setting the `rootfs` parameter (and optionally, any combination of `mpX`
+parameters), the 'pct restore' command is automatically switched into an
+advanced mode. This advanced mode completely ignores the `rootfs` and `mpX`
+configuration options contained in the backup archive, and instead only
+uses the options explicitly provided as parameters.
+
+This mode allows flexible configuration of mount point settings at restore time,
+for example:
+
+* Set target storages, volume sizes and other options for each mount point
+individually
+* Redistribute backed up files according to new mount point scheme
+* Restore to device and/or bind mount points (limited to root user)
+

 
 Managing Containers with 'pct'
 ------------------------------
 
 Managing Containers with 'pct'
 ------------------------------