fix sentence

[pve-docs.git] / pct.adoc

diff --git a/pct.adoc b/pct.adoc
index 95856da31bc5196ff32af9d787d2abe5f12bb3d9..9983ba8e03544ed2823100dce28b220438b968c2 100644 (file)
--- a/pct.adoc
+++ b/pct.adoc
@@ -59,7 +59,7 @@ Our primary goal is to offer an environment as one would get from a
 VM, but without the additional overhead. We call this "System
 Containers".
 
 VM, but without the additional overhead. We call this "System
 Containers".
 

-NOTE: If you want to run micro-containers (with docker, rct, ...), it
+NOTE: If you want to run micro-containers (with docker, rkt, ...), it

 is best to run them inside a VM.
 
 
 is best to run them inside a VM.
 
 


@@ -205,9 +205,28 @@ rewrite ssh_host_keys:: so that each container has unique keys
 
 randomize crontab:: so that cron does not start at the same time on all containers
 
 
 randomize crontab:: so that cron does not start at the same time on all containers
 

-The above task depends on the OS type, so the implementation is different
-for each OS type. You can also disable any modifications by manually
-setting the 'ostype' to 'unmanaged'.
+Changes made by {PVE} are enclosed by comment markers:
+
+----
+# --- BEGIN PVE ---
+<data>
+# --- END PVE ---
+----
+
+Those markers will be inserted at a reasonable location in the
+file. If such a section already exists, it will be updated in place
+and will not be moved.
+
+Modification of a file can be prevented by adding a `.pve-ignore.`
+file for it.  For instance, if the file `/etc/.pve-ignore.hosts`
+exists then the `/etc/hosts` file will not be touched. This can be a
+simple empty file creatd via:
+
+ # touch /etc/.pve-ignore.hosts
+
+Most modifications are OS dependent, so they differ between different
+distributions and versions. You can completely disable modifications
+by manually setting the 'ostype' to 'unmanaged'.

 
 OS type detection is done by testing for certain files inside the
 container:
 
 OS type detection is done by testing for certain files inside the
 container:


@@ -224,9 +243,16 @@ ArchLinux:: test /etc/arch-release
 
 Alpine:: test /etc/alpine-release
 
 
 Alpine:: test /etc/alpine-release
 

+Gentoo:: test /etc/gentoo-release
+

 NOTE: Container start fails if the configured 'ostype' differs from the auto
 detected type.
 
 NOTE: Container start fails if the configured 'ostype' differs from the auto
 detected type.
 

+Options
+~~~~~~~
+
+include::pct.conf.5-opts.adoc[]
+

 
 Container Images
 ----------------
 
 Container Images
 ----------------


@@ -328,10 +354,24 @@ also provide an easy way to share data between different containers.
 Mount Points
 ~~~~~~~~~~~~
 
 Mount Points
 ~~~~~~~~~~~~
 

-Beside the root directory the container can also have additional mount points.
+The root mount point is configured with the `rootfs` property, and you can
+configure up to 10 additional mount points. The corresponding options
+are called `mp0` to `mp9`, and they can contain the following setting:
+
+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.
 

+.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:
 


@@ -342,32 +382,65 @@ 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 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 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
+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
+^^^^^^^^^^^^^^^^^^^

 
 

-Similarly device mounts are not managed by the storage, but for these the
-`quota` and `acl` options will be honored.
+Device mount points allow to mount block devices of the host directly into the
+container. Similar to bind mounts, device mounts are not managed by {PVE}'s
+storage subsystem, but the `quota` and `acl` options will be honored.
+
+NOTE: Device mount points should only be used under special circumstances. In
+most cases a storage backed mount point offers the same performance and a lot
+more features.
+
+NOTE: The contents of device mount points are not backed up when using 'vzdump'.
+
+
+FUSE mounts
+~~~~~~~~~~~

 
 WARNING: Because of existing issues in the Linux kernel's freezer
 subsystem the usage of FUSE mounts inside a container is strongly
 advised against, as containers need to be frozen for suspend or
 
 WARNING: Because of existing issues in the Linux kernel's freezer
 subsystem the usage of FUSE mounts inside a container is strongly
 advised against, as containers need to be frozen for suspend or

-snapshot mode backups. 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.
+snapshot mode backups.

 
 

-The root mount point is configured with the 'rootfs' property, and you can
-configure up to 10 additional mount points. The corresponding options
-are called 'mp0' to 'mp9', and they can contain the following setting:
+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.

 
 

-include::pct-mountpoint-opts.adoc[]
-
-.Typical Container 'rootfs' configuration
-----
-rootfs: thin1:base-100-disk-1,size=8G
-----

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


@@ -414,6 +487,72 @@ they can contain the following setting:
 include::pct-network-opts.adoc[]
 
 
 include::pct-network-opts.adoc[]
 
 

+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.
+
+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'
 ------------------------------