make dinstall: skip mediawiki deb for now
[pve-docs.git] / pct.adoc
index efd4303..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
@@ -377,7 +416,8 @@ container are handled by the host CPU scheduler. {pve} uses the Linux
 which has additional bandwidth control options.
 
 [horizontal]
-cpulimit: :: You can use this option to further limit assigned CPU
+
+`cpulimit`: :: You can use this option to further limit assigned CPU
 time. Please note that this is a floating point number, so it is
 perfectly valid to assign two cores to a container, but restrict
 overall CPU consumption to half a core.
@@ -387,7 +427,7 @@ cores: 2
 cpulimit: 0.5
 ----
 
-cpuunits: :: This is a relative weight passed to the kernel
+`cpuunits`: :: This is a relative weight passed to the kernel
 scheduler. The larger the number is, the more CPU time this container
 gets. Number is relative to the weights of all the other running
 containers. The default is 1024. You can use this setting to
@@ -398,14 +438,16 @@ prioritize some containers.
 Memory
 ~~~~~~
 
+[thumbnail="screenshot/gui-create-ct-memory.png"]
+
 Container memory is controlled using the cgroup memory controller.
 
 [horizontal]
 
-memory: :: Limit overall memory usage. This corresponds
+`memory`: :: Limit overall memory usage. This corresponds
 to the `memory.limit_in_bytes` cgroup setting.
 
-swap: :: Allows the container to use additional swap memory from the
+`swap`: :: Allows the container to use additional swap memory from the
 host swap space. This corresponds to the `memory.memsw.limit_in_bytes`
 cgroup setting, which is set to the sum of both value (`memory +
 swap`).
@@ -415,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:
@@ -443,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
 ^^^^^^^^^^^^^^^^^
@@ -494,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:
@@ -501,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
 ------------------
 
@@ -629,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