pct - Tool to manage Linux Containers (LXC) on Proxmox VE
-SYNOPSYS
+SYNOPSIS
--------
include::pct.1-synopsis.adoc[]
AppArmor, CGroups and PID and user namespaces, which makes containers
usage quite secure. We distinguish two types of containers:
-Privileged containers
+
+Privileged Containers
~~~~~~~~~~~~~~~~~~~~~
Security is done by dropping capabilities, using mandatory access
trusted environment, or when no untrusted task is running as root in
the container.
-Unprivileged containers
+
+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
+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
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
+-----
+# 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.
Those settings are directly passed to the LXC low-level tools.
+
Snapshots
~~~~~~~~~
file. For example, after creating a snapshot called ``testsnapshot'',
your configuration file will look like this:
-.Container Configuration with Snapshot
+.Container configuration with snapshot
----
memory: 512
swap: 512
NOTE: Container start fails if the configured `ostype` differs from the auto
detected type.
+
Options
~~~~~~~
pct create 999 local:vztmpl/debian-8.0-standard_8.0-1_amd64.tar.gz
-Proxmox itself ships a set of basic templates for most common
+{pve} itself ships a set of basic templates for most common
operating systems, and you can download them using the `pveam` (short
for {pve} Appliance Manager) command line utility. You can also
download https://www.turnkeylinux.org/[TurnKey Linux] containers using
The above command shows you the full {pve} volume identifiers. They include
the storage name, and most other {pve} commands can use them. For
-examply you can delete that image later with:
+example you can delete that image later with:
pveam remove local:vztmpl/debian-8.0-standard_8.0-1_amd64.tar.gz
Currently there are basically three types of mount points: storage backed
mount points, bind mounts and device mounts.
-.Typical Container `rootfs` configuration
+.Typical container `rootfs` configuration
----
rootfs: thin1:base-100-disk-1,size=8G
----
-Storage backed mount points
+Storage Backed Mount Points
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Storage backed mount points are managed by the {pve} storage subsystem and come
in three different flavors:
-- Image based: These are raw images containing a single ext4 formatted file
+- Image based: these are raw images containing a single ext4 formatted file
system.
-- ZFS Subvolumes: These are technically bind mounts, but with managed storage,
+- ZFS subvolumes: these are technically bind mounts, but with managed storage,
and thus allow resizing and snapshotting.
- 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
achieve the same result.
-Device mount points
+Device Mount Points
^^^^^^^^^^^^^^^^^^^
Device mount points allow to mount block devices of the host directly into the
NOTE: The contents of device mount points are not backed up when using `vzdump`.
-FUSE mounts
+FUSE Mounts
~~~~~~~~~~~
WARNING: Because of existing issues in the Linux kernel's freezer
and use a bind mount point to make it accessible inside the container.
-Using quotas inside containers
+Using Quotas Inside Containers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Quotas allow to set limits inside a container for the amount of disk
the mount point's path instead of just `/`.
-Using ACLs inside containers
+Using ACLs Inside Containers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The standard Posix Access Control Lists are also available 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.
Backup and Restore
------------------
+
Container Backup
~~~~~~~~~~~~~~~~
...). You can use pct to set parameters in the associated config file,
like network configuration or memory limits.
+
CLI Usage Examples
~~~~~~~~~~~~~~~~~~
Create a container based on a Debian template (provided you have
-already downloaded the template via the webgui)
+already downloaded the template via the web interface)
pct create 100 /var/lib/vz/template/cache/debian-8.0-standard_8.0-1_amd64.tar.gz
pct set 100 -memory 512
+Obtaining Debugging Logs
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+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):
+
+ 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.
+
+The collected debug log is written to `/tmp/lxc-ID.log`.
+
+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`.
+
+
Files
------
Technology Overview
-------------------
-- Integrated into {pve} graphical user interface (GUI)
-
-- LXC (https://linuxcontainers.org/)
+* Integrated into {pve} graphical user interface (GUI)
-- cgmanager for cgroup management
+* LXC (https://linuxcontainers.org/)
-- lxcfs to provive containerized /proc file system
+* lxcfs to provide containerized /proc file system
-- apparmor
+* AppArmor
-- CRIU: for live migration (planned)
+* CRIU: for live migration (planned)
-- We use latest available kernels (4.4.X)
+* We use latest available kernels (4.4.X)
-- Image based deployment (templates)
+* Image based deployment (templates)
-- Container setup from host (Network, DNS, Storage, ...)
+* Container setup from host (network, DNS, storage, ...)
ifdef::manvolnum[]