buildsys: switch upload dist over to buster
[pve-docs.git] / pct.adoc
index 56d6310..2cb4bbe 100644 (file)
--- a/pct.adoc
+++ b/pct.adoc
@@ -2,7 +2,6 @@
 ifdef::manvolnum[]
 pct(1)
 ======
-include::attributes.txt[]
 :pve-toplevel:
 
 NAME
@@ -23,7 +22,6 @@ endif::manvolnum[]
 ifndef::manvolnum[]
 Proxmox Container Toolkit
 =========================
-include::attributes.txt[]
 :pve-toplevel:
 endif::manvolnum[]
 ifdef::wiki[]
@@ -85,7 +83,7 @@ Technology Overview
 
 * CRIU: for live migration (planned)
 
-* Use latest available kernels (4.4.X)
+* Runs on modern Linux kernels
 
 * Image based deployment (templates)
 
@@ -104,32 +102,7 @@ virtualized VMs provide better isolation.
 
 The good news is that LXC uses many kernel security features like
 AppArmor, CGroups and PID and user namespaces, which makes containers
-usage quite secure. We distinguish two types of containers:
-
-
-Privileged Containers
-~~~~~~~~~~~~~~~~~~~~~
-
-Security is done by dropping capabilities, using mandatory access
-control (AppArmor), SecComp filters and namespaces. The LXC team
-considers this kind of container as unsafe, and they will not consider
-new container escape exploits to be security issues worthy of a CVE
-and quick fix. So you should use this kind of containers only inside a
-trusted environment, or when no untrusted task is running as root in
-the container.
-
-
-Unprivileged Containers
-~~~~~~~~~~~~~~~~~~~~~~~
-
-This kind of containers use a new kernel feature called user
-namespaces. The root UID 0 inside the container is mapped to an
-unprivileged user outside the container. This means that most security
-issues (container escape, resource abuse, ...) in those containers
-will affect a random unprivileged user, and so would be a generic
-kernel security bug rather than an LXC issue. The LXC team thinks
-unprivileged containers are safe by design.
-
+usage quite secure.
 
 Guest Operating System Configuration
 ------------------------------------
@@ -170,7 +143,7 @@ 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:
+simple empty file created via:
 
  # touch /etc/.pve-ignore.hosts
 
@@ -347,15 +320,81 @@ ACLs allow you to set more detailed file ownership than the traditional user/
 group/others model.
 
 
-[[pct_setting]]
+Backup of Containers mount points
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default additional mount points besides the Root Disk mount point are not
+included in backups. You can reverse this default behavior by setting the
+*Backup* option on a mount point.
+// see PVE::VZDump::LXC::prepare()
+
+Replication of Containers mount points
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default additional mount points are replicated when the Root Disk
+is replicated. If you want the {pve} storage replication mechanism to skip a
+ mount point when starting  a replication job, you can set the
+*Skip replication* option on that mount point. +
+As of {pve} 5.0, replication requires a storage of type `zfspool`, so adding a
+ mount point to a different type of storage when the container has replication
+ configured requires to *Skip replication* for that mount point.
+
+
+[[pct_settings]]
 Container Settings
 ------------------
 
-[[pct_cpu]]
+[[pct_general]]
+General Settings
+~~~~~~~~~~~~~~~~
+
+[thumbnail="screenshot/gui-create-ct-general.png"]
+
+General settings of a container include
+
+* the *Node* : the physical server on which the container will run
+* the *CT ID*: a unique number in this {pve} installation used to identify your container
+* *Hostname*: the hostname of the container
+* *Resource Pool*: a logical group of containers and VMs
+* *Password*: the root password of the container
+* *SSH Public Key*: a public key for connecting to the root account over SSH
+* *Unprivileged container*: this option allows to choose at creation time
+if you want to create a privileged or unprivileged container.
+
+
+Privileged Containers
+^^^^^^^^^^^^^^^^^^^^^
+
+Security is done by dropping capabilities, using mandatory access
+control (AppArmor), SecComp filters and namespaces. The LXC team
+considers this kind of container as unsafe, and they will not consider
+new container escape exploits to be security issues worthy of a CVE
+and quick fix. So you should use this kind of containers only inside a
+trusted environment, or when no untrusted task is running as root in
+the container.
+
+
+Unprivileged Containers
+^^^^^^^^^^^^^^^^^^^^^^^
+
+This kind of containers use a new kernel feature called user
+namespaces. The root UID 0 inside the container is mapped to an
+unprivileged user outside the container. This means that most security
+issues (container escape, resource abuse, ...) in those containers
+will affect a random unprivileged user, and so would be a generic
+kernel security bug rather than an LXC issue. The LXC team thinks
+unprivileged containers are safe by design.
+
+NOTE: If the container uses systemd as an init system, please be
+aware the systemd version running inside the container should be equal
+or greater than 220.
 
+[[pct_cpu]]
 CPU
 ~~~
 
+[thumbnail="screenshot/gui-create-ct-cpu.png"]
+
 You can restrict the number of visible CPUs inside the container using
 the `cores` option. This is implemented using the Linux 'cpuset'
 cgroup (**c**ontrol *group*). A special task inside `pvestatd` tries
@@ -399,6 +438,8 @@ prioritize some containers.
 Memory
 ~~~~~~
 
+[thumbnail="screenshot/gui-create-ct-memory.png"]
+
 Container memory is controlled using the cgroup memory controller.
 
 [horizontal]
@@ -416,6 +457,8 @@ swap`).
 Mount Points
 ~~~~~~~~~~~~
 
+[thumbnail="screenshot/gui-create-ct-root-disk.png"]
+
 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:
@@ -444,6 +487,13 @@ in three different flavors:
 - Directories: passing `size=0` triggers a special case where instead of a raw
   image a directory is created.
 
+NOTE: The special option syntax `STORAGE_ID:SIZE_IN_GB` for storage backed
+mount point volumes will automatically allocate a volume of the specified size
+on the specified storage. E.g., calling
+`pct set 100 -mp0 thin1:10,mp=/path/in/container` will allocate a 10GB volume
+on the storage `thin1` and replace the volume ID place holder `10` with the
+allocated volume ID.
+
 
 Bind Mount Points
 ^^^^^^^^^^^^^^^^^
@@ -495,6 +545,8 @@ NOTE: The contents of device mount points are not backed up when using `vzdump`.
 Network
 ~~~~~~~
 
+[thumbnail="screenshot/gui-create-ct-network.png"]
+
 You can configure up to 10 network interfaces for a single
 container. The corresponding options are called `net0` to `net9`, and
 they can contain the following setting:
@@ -502,6 +554,53 @@ they can contain the following setting:
 include::pct-network-opts.adoc[]
 
 
+[[pct_startup_and_shutdown]]
+Automatic Start and Shutdown of Containers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After creating your containers, you probably want them to start automatically
+when the host system boots. For this you need to select the option 'Start at
+boot' from the 'Options' Tab of your container in the web interface, or set it with
+the following command:
+
+ pct set <ctid> -onboot 1
+
+.Start and Shutdown Order
+// use the screenshot from qemu - its the same
+[thumbnail="screenshot/gui-qemu-edit-start-order.png"]
+
+If you want to fine tune the boot order of your containers, you can use the following
+parameters :
+
+* *Start/Shutdown order*: Defines the start order priority. E.g. set it to 1 if
+you want the CT to be the first to be started. (We use the reverse startup
+order for shutdown, so a container with a start order of 1 would be the last to
+be shut down)
+* *Startup delay*: Defines the interval between this container start and subsequent
+containers starts . E.g. set it to 240 if you want to wait 240 seconds before starting
+other containers.
+* *Shutdown timeout*: Defines the duration in seconds {pve} should wait
+for the container to be offline after issuing a shutdown command.
+By default this value is set to 60, which means that {pve} will issue a
+shutdown request, wait 60s for the machine to be offline, and if after 60s
+the machine is still online will notify that the shutdown action failed.
+
+Please note that containers without a Start/Shutdown order parameter will always
+start after those where the parameter is set, and this parameter only
+makes sense between the machines running locally on a host, and not
+cluster-wide.
+
+Hookscripts
+~~~~~~~~~~~
+
+You can add a hook script to CTs with the config property `hookscript`.
+
+ pct set 100 -hookscript local:snippets/hookscript.pl
+
+It will be called during various phases of the guests lifetime.
+For an example and documentation see the example script under
+`/usr/share/pve-docs/examples/guest-example-hookscript.pl`.
+
 Backup and Restore
 ------------------
 
@@ -630,6 +729,26 @@ NOTE: If you have changed the container's configuration since the last start
 attempt with `pct start`, you need to run `pct start` at least once to also
 update the configuration used by `lxc-start`.
 
+[[pct_migration]]
+Migration
+---------
+
+If you have a cluster, you can migrate your Containers with
+
+ pct migrate <vmid> <target>
+
+This works as long as your Container is offline. If it has local volumes or
+mountpoints defined, the migration will copy the content over the network to
+the target host if there is the same storage defined.
+
+If you want to migrate online Containers, the only way is to use
+restart migration. This can be initiated with the -restart flag and the optional
+-timeout parameter.
+
+A restart migration will shut down the Container and kill it after the specified
+timeout (the default is 180 seconds). Then it will migrate the Container
+like an offline migration and when finished, it starts the Container on the
+target node.
 
 [[pct_configuration]]
 Configuration