X-Git-Url: https://git.proxmox.com/?p=pve-docs.git;a=blobdiff_plain;f=pct.adoc;h=67abec1784f6cfb220402fe4c8bea3c14d14dbda;hp=6a81b14c5ac30a0491474375f8e224990f4c61d0;hb=097aa949df2f5a3a8b3b21e1a146113762905815;hpb=26ca7ff55309331b9b11b10b64fab2d819454909 diff --git a/pct.adoc b/pct.adoc index 6a81b14..67abec1 100644 --- a/pct.adoc +++ b/pct.adoc @@ -1,7 +1,8 @@ +[[chapter_pct]] ifdef::manvolnum[] -PVE({manvolnum}) -================ -include::attributes.txt[] +pct(1) +====== +:pve-toplevel: NAME ---- @@ -9,7 +10,7 @@ NAME pct - Tool to manage Linux Containers (LXC) on Proxmox VE -SYNOPSYS +SYNOPSIS -------- include::pct.1-synopsis.adoc[] @@ -21,9 +22,11 @@ endif::manvolnum[] ifndef::manvolnum[] Proxmox Container Toolkit ========================= -include::attributes.txt[] +:pve-toplevel: endif::manvolnum[] - +ifdef::wiki[] +:title: Linux Container +endif::wiki[] Containers are a lightweight alternative to fully virtualized VMs. Instead of emulating a complete Operating System (OS), containers @@ -63,6 +66,32 @@ NOTE: If you want to run micro-containers (with docker, rkt, ...), it is best to run them inside a VM. +Technology Overview +------------------- + +* LXC (https://linuxcontainers.org/) + +* Integrated into {pve} graphical user interface (GUI) + +* Easy to use command line tool `pct` + +* Access via {pve} REST API + +* lxcfs to provide containerized /proc file system + +* AppArmor/Seccomp to improve security + +* CRIU: for live migration (planned) + +* Use latest available kernels (4.4.X) + +* Image based deployment (templates) + +* Use {pve} storage library + +* Container setup from host (network, DNS, storage, ...) + + Security Considerations ----------------------- @@ -100,96 +129,8 @@ kernel security bug rather than an LXC issue. The LXC team thinks unprivileged containers are safe by design. -Configuration -------------- - -The `/etc/pve/lxc/.conf` file stores container configuration, -where `` is the numeric ID of the given container. Like all -other files stored inside `/etc/pve/`, they get automatically -replicated to all other cluster nodes. - -NOTE: CTIDs < 100 are reserved for internal purposes, and CTIDs need to be -unique cluster wide. - -.Example Container Configuration ----- -ostype: debian -arch: amd64 -hostname: www -memory: 512 -swap: 512 -net0: bridge=vmbr0,hwaddr=66:64:66:64:64:36,ip=dhcp,name=eth0,type=veth -rootfs: local:107/vm-107-disk-1.raw,size=7G ----- - -Those configuration files are simple text files, and you can edit them -using a normal text editor (`vi`, `nano`, ...). This is sometimes -useful to do small corrections, but keep in mind that you need to -restart the container to apply such changes. - -For that reason, it is usually better to use the `pct` command to -generate and modify those files, or do the whole thing using the GUI. -Our toolkit is smart enough to instantaneously apply most changes to -running containers. This feature is called "hot plug", and there is no -need to restart the container in that case. - - -File Format -~~~~~~~~~~~ - -Container configuration files use a simple colon separated key/value -format. Each line has the following format: - ------ -# this is a comment -OPTION: value ------ - -Blank lines in those files are ignored, and lines starting with a `#` -character are treated as comments and are also ignored. - -It is possible to add low-level, LXC style configuration directly, for -example: - - lxc.init_cmd: /sbin/my_own_init - -or - - lxc.init_cmd = /sbin/my_own_init - -Those settings are directly passed to the LXC low-level tools. - - -Snapshots -~~~~~~~~~ - -When you create a snapshot, `pct` stores the configuration at snapshot -time into a separate snapshot section within the same configuration -file. For example, after creating a snapshot called ``testsnapshot'', -your configuration file will look like this: - -.Container configuration with snapshot ----- -memory: 512 -swap: 512 -parent: testsnaphot -... - -[testsnaphot] -memory: 512 -swap: 512 -snaptime: 1457170803 -... ----- - -There are a few snapshot related properties like `parent` and -`snaptime`. The `parent` property is used to store the parent/child -relationship between snapshots. `snaptime` is the snapshot creation -time stamp (Unix epoch). - - Guest Operating System Configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------ We normally try to detect the operating system type inside the container, and then modify some files inside the container to make @@ -256,12 +197,7 @@ NOTE: Container start fails if the configured `ostype` differs from the auto detected type. -Options -~~~~~~~ - -include::pct.conf.5-opts.adoc[] - - +[[pct_container_images]] Container Images ---------------- @@ -328,6 +264,7 @@ example you can delete that image later with: pveam remove local:vztmpl/debian-8.0-standard_8.0-1_amd64.tar.gz +[[pct_container_storage]] Container Storage ----------------- @@ -343,7 +280,8 @@ allows you to choose a suitable storage for each application. For example, you can use a relatively slow (and thus cheap) storage for the container root file system. Then you can use a second mount point to mount a very fast, distributed storage for your database -application. +application. See section <> for further +details. The second big improvement is that you can use any storage type supported by the {pve} storage library. That means that you can store @@ -359,9 +297,128 @@ local storage inside containers with zero overhead. Such bind mounts also provide an easy way to share data between different containers. +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 +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. + + +Using Quotas Inside Containers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Quotas allow to set limits inside a container for the amount of disk +space that each user can use. This only works on ext4 image based +storage types and currently does not work with unprivileged +containers. + +Activating the `quota` option causes the following mount options to be +used for a mount point: +`usrjquota=aquota.user,grpjquota=aquota.group,jqfmt=vfsv0` + +This allows quotas to be used like you would on any other system. You +can initialize the `/aquota.user` and `/aquota.group` files by running + +---- +quotacheck -cmug / +quotaon / +---- + +and edit the quotas via the `edquota` command. Refer to the documentation +of the distribution running inside the container for details. + +NOTE: You need to run the above commands for every mount point by passing +the mount point's path instead of just `/`. + + +Using ACLs Inside Containers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The standard Posix **A**ccess **C**ontrol **L**ists are also available inside containers. +ACLs allow you to set more detailed file ownership than the traditional user/ +group/others model. + + +[[pct_settings]] +Container Settings +------------------ + +[[pct_cpu]] +CPU +~~~ + +[thumbnail="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 +to distribute running containers among available CPUs. You can view +the assigned CPUs using the following command: + +---- +# pct cpusets + --------------------- + 102: 6 7 + 105: 2 3 4 5 + 108: 0 1 + --------------------- +---- + +Containers use the host kernel directly, so all task inside a +container are handled by the host CPU scheduler. {pve} uses the Linux +'CFS' (**C**ompletely **F**air **S**cheduler) scheduler by default, +which has additional bandwidth control options. + +[horizontal] + +`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. ++ +---- +cores: 2 +cpulimit: 0.5 +---- + +`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 +prioritize some containers. + + +[[pct_memory]] +Memory +~~~~~~ + +[thumbnail="gui-create-ct-memory.png"] + +Container memory is controlled using the cgroup memory controller. + +[horizontal] + +`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 +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`). + + +[[pct_mount_points]] Mount Points ~~~~~~~~~~~~ +[thumbnail="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: @@ -437,56 +494,11 @@ 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 -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. - - -Using Quotas Inside Containers -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Quotas allow to set limits inside a container for the amount of disk -space that each user can use. This only works on ext4 image based -storage types and currently does not work with unprivileged -containers. - -Activating the `quota` option causes the following mount options to be -used for a mount point: -`usrjquota=aquota.user,grpjquota=aquota.group,jqfmt=vfsv0` - -This allows quotas to be used like you would on any other system. You -can initialize the `/aquota.user` and `/aquota.group` files by running - ----- -quotacheck -cmug / -quotaon / ----- - -and edit the quotas via the `edquota` command. Refer to the documentation -of the distribution running inside the container for details. - -NOTE: You need to run the above commands for every mount point by passing -the mount point's path instead of just `/`. - - -Using ACLs Inside Containers -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The standard Posix **A**ccess **C**ontrol **L**ists are also available inside containers. -ACLs allow you to set more detailed file ownership than the traditional user/ -group/others model. - +[[pct_container_network]] +Network +~~~~~~~ -Container Network ------------------ +[thumbnail="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 @@ -606,58 +618,144 @@ Reduce the memory of the container to 512MB pct set 100 -memory 512 -Files ------- +Obtaining Debugging Logs +~~~~~~~~~~~~~~~~~~~~~~~~ -`/etc/pve/lxc/.conf`:: +In case `pct start` is unable to start a specific container, it might be +helpful to collect debugging output by running `lxc-start` (replace `ID` with +the container's ID): -Configuration file for the container ''. + lxc-start -n ID -F -l DEBUG -o /tmp/lxc-ID.log +This command will attempt to start the container in foreground mode, to stop the container run `pct shutdown ID` or `pct stop ID` in a second terminal. -Container Advantages --------------------- +The collected debug log is written to `/tmp/lxc-ID.log`. -* Simple, and fully integrated into {pve}. Setup looks similar to a normal - VM setup. +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`. -** Storage (ZFS, LVM, NFS, Ceph, ...) -** Network +[[pct_configuration]] +Configuration +------------- -** Authentication +The `/etc/pve/lxc/.conf` file stores container configuration, +where `` is the numeric ID of the given container. Like all +other files stored inside `/etc/pve/`, they get automatically +replicated to all other cluster nodes. -** Cluster +NOTE: CTIDs < 100 are reserved for internal purposes, and CTIDs need to be +unique cluster wide. -* Fast: minimal overhead, as fast as bare metal +.Example Container Configuration +---- +ostype: debian +arch: amd64 +hostname: www +memory: 512 +swap: 512 +net0: bridge=vmbr0,hwaddr=66:64:66:64:64:36,ip=dhcp,name=eth0,type=veth +rootfs: local:107/vm-107-disk-1.raw,size=7G +---- -* High density (perfect for idle workloads) +Those configuration files are simple text files, and you can edit them +using a normal text editor (`vi`, `nano`, ...). This is sometimes +useful to do small corrections, but keep in mind that you need to +restart the container to apply such changes. -* REST API +For that reason, it is usually better to use the `pct` command to +generate and modify those files, or do the whole thing using the GUI. +Our toolkit is smart enough to instantaneously apply most changes to +running containers. This feature is called "hot plug", and there is no +need to restart the container in that case. -* Direct hardware access +File Format +~~~~~~~~~~~ -Technology Overview -------------------- +Container configuration files use a simple colon separated key/value +format. Each line has the following format: -* Integrated into {pve} graphical user interface (GUI) +----- +# this is a comment +OPTION: value +----- -* LXC (https://linuxcontainers.org/) +Blank lines in those files are ignored, and lines starting with a `#` +character are treated as comments and are also ignored. -* lxcfs to provide containerized /proc file system +It is possible to add low-level, LXC style configuration directly, for +example: -* AppArmor + lxc.init_cmd: /sbin/my_own_init -* CRIU: for live migration (planned) +or -* We use latest available kernels (4.4.X) + lxc.init_cmd = /sbin/my_own_init -* Image based deployment (templates) +Those settings are directly passed to the LXC low-level tools. -* Container setup from host (network, DNS, storage, ...) + +[[pct_snapshots]] +Snapshots +~~~~~~~~~ + +When you create a snapshot, `pct` stores the configuration at snapshot +time into a separate snapshot section within the same configuration +file. For example, after creating a snapshot called ``testsnapshot'', +your configuration file will look like this: + +.Container configuration with snapshot +---- +memory: 512 +swap: 512 +parent: testsnaphot +... + +[testsnaphot] +memory: 512 +swap: 512 +snaptime: 1457170803 +... +---- + +There are a few snapshot related properties like `parent` and +`snaptime`. The `parent` property is used to store the parent/child +relationship between snapshots. `snaptime` is the snapshot creation +time stamp (Unix epoch). + + +[[pct_options]] +Options +~~~~~~~ + +include::pct.conf.5-opts.adoc[] + + +Locks +----- + +Container migrations, snapshots and backups (`vzdump`) set a lock to +prevent incompatible concurrent actions on the affected container. Sometimes +you need to remove such a lock manually (e.g., after a power failure). + + pct unlock + +CAUTION: Only do that if you are sure the action which set the lock is +no longer running. ifdef::manvolnum[] + +Files +------ + +`/etc/pve/lxc/.conf`:: + +Configuration file for the container ''. + + include::pve-copyright.adoc[] endif::manvolnum[]