pct: add section about configuration format
[pve-docs.git] / pct.adoc
CommitLineData
0c6b782f
DM
1ifdef::manvolnum[]
2PVE({manvolnum})
3================
38fd0958 4include::attributes.txt[]
0c6b782f
DM
5
6NAME
7----
8
9pct - Tool to manage Linux Containers (LXC) on Proxmox VE
10
11
12SYNOPSYS
13--------
14
15include::pct.1-synopsis.adoc[]
16
17DESCRIPTION
18-----------
19endif::manvolnum[]
20
21ifndef::manvolnum[]
22Proxmox Container Toolkit
23=========================
38fd0958 24include::attributes.txt[]
0c6b782f
DM
25endif::manvolnum[]
26
4a2ae9ed
DM
27
28Containers are a lightweight alternative to fully virtualized
29VMs. Instead of emulating a complete Operating System (OS), containers
30simply use the OS of the host they run on. This implies that all
31containers use the same kernel, and that they can access resources
32from the host directly.
33
34This is great because containers do not waste CPU power nor memory due
35to kernel emulation. Container run-time costs are close to zero and
36usually negligible. But there are also some drawbacks you need to
37consider:
38
39* You can only run Linux based OS inside containers, i.e. it is not
40 possible to run Free BSD or MS Windows inside.
41
42* For security reasons, access to host resources need to be
43 restricted. This is done with AppArmor, SecComp filters and other
44 kernel feature. Be prepared that some syscalls are not allowed
45 inside containers.
46
47{pve} uses https://linuxcontainers.org/[LXC] as underlying container
48technology. We consider LXC as low-level library, which provides
49countless options. It would be to difficult to use those tools
50directly. Instead, we provide a small wrapper called `pct`, the
51"Proxmox Container Toolkit".
52
53The toolkit it tightly coupled with {pve}. That means that it is aware
54of the cluster setup, and it can use the same network and storage
55resources as fully virtualized VMs. You can even use the {pve}
56firewall, or manage containers using the HA framework.
57
58Our primary goal is to offer an environment as one would get from a
59VM, but without the additional overhead. We call this "System
60Containers".
61
70a42028
DM
62NOTE: If you want to run micro-containers (with docker, rct, ...), it
63is best to run them inside a VM.
4a2ae9ed
DM
64
65
66Security Considerations
67-----------------------
68
69Containers use the same kernel as the host, so there is a big attack
70surface for malicious users. You should consider this fact if you
71provide containers to totally untrusted people. In general, fully
72virtualized VM provides better isolation.
73
74The good news is that LXC uses many kernel security features like
75AppArmor, CGroups and PID and user namespaces, which makes containers
76usage quite secure. We distinguish two types of containers:
77
78Privileged containers
79~~~~~~~~~~~~~~~~~~~~~
80
81Security is done by dropping capabilities, using mandatory access
82control (AppArmor), SecComp filters and namespaces. The LXC team
83considers this kind of container as unsafe, and they will not consider
84new container escape exploits to be security issues worthy of a CVE
85and quick fix. So you should use this kind of containers only inside a
86trusted environment, or when no untrusted task is running as root in
87the container.
88
89Unprivileged containers
90~~~~~~~~~~~~~~~~~~~~~~~
91
92This kind of containers use a new kernel feature, called user
93namespaces. The root uid 0 inside the container is mapped to an
94unprivileged user outside the container. This means that most security
95issues (container escape, resource abuse, ...) in those containers
96will affect a random unprivileged user, and so would be a generic
97kernel security bug rather than a LXC issue. LXC people think
98unprivileged containers are safe by design.
99
7fc230db
DM
100
101Configuration
102-------------
103
104The '/etc/pve/lxc/<CTID>.conf' files stores container configuration,
105where '<CTID>' is the numeric ID of the given container. Note that
106CTIDs < 100 are reserved for internal purposes. CTIDs need to be
107unique - cluster wide. Files are stored inside '/etc/pve/', so they get
108automatically replicated to all other cluster nodes.
109
110Those configuration files are simple text files, and you can edit them
111using a normal text editor ('vi', 'nano', ...). But one can also use
112the 'pct' command to generate and modify those files, or do the whole
113thing using the GUI.
114
115
116File Format
117~~~~~~~~~~~
118
119Container configuration files use a simple colon separated key/value
120format. Each line has the following format:
121
122 # this is a comment
123 OPTION: value
124
125Blank lines in those files are ignored, and lines starting with a '#'
126character are treated as comments and are also ignored.
127
128It is possible to add low-level, LXC style configuration directly, for
129example:
130
131 lxc.init_cmd: /sbin/my_own_init
132
133or
134
135 lxc.init_cmd = /sbin/my_own_init
136
137Those settings are directly passed to the LXC low-level tools.
138
139
70a42028
DM
140Container Storage
141-----------------
142
143Traditional containers use a very simple storage model, only allowing
144a single mount point, the root file system. This was further
145restricted to specific file system types like 'ext4' and 'nfs'.
146Additional mounts are often done by user provided scripts. This turend
147out to be complex and error prone, so we trie to avoid that now.
148
149Our new LXC based container model is more flexible regarding
150storage. First, you can have more than a single mount point. This
151allows you to choose a suitable storage for each application. For
152example, you can use a relatively slow (and thus cheap) storage for
153the container root file system. Then you can use a second mount point
154to mount a very fast, distributed storage for your database
155application.
156
157The second big improvement is that you can use any storage type
158supported by the {pve} storage library. That means that you can store
159your containers on local 'lvmthin' or 'zfs', shared 'iSCSI' storage,
160or even on distributed storage systems like 'ceph'. And it enables us
161to use advanced storage features like snapshots and clones. 'vzdump'
162can also use the snapshots feature to provide consistent container
163backups.
164
165Last but not least, you can also mount local devices directly, or
166mount local directories using bind mounts. That way you can access
167local storage inside containers with zero overhead. Such bind mounts
168also provides an easy way to share data between different containers.
169
4a2ae9ed
DM
170
171Managing Containers with 'pct'
172------------------------------
173
0c6b782f
DM
174'pct' is a tool to manages Linux Containers (LXC). You can create and
175destroy containers, and control execution
176(start/stop/suspend/resume). Besides that, you can use pct to set
177parameters in the associated config file, like network configuration
178or memory.
179
180CLI Usage Examples
181------------------
182
183Create a container based on a Debian template (provided you downloaded
184the template via the webgui before)
185
186 pct create 100 /var/lib/vz/template/cache/debian-8.0-standard_8.0-1_amd64.tar.gz
187
188Start container 100
189
190 pct start 100
191
192Start a login session via getty
193
194 pct console 100
195
196Enter the LXC namespace and run a shell as root user
197
198 pct enter 100
199
200Display the configuration
201
202 pct config 100
203
204Add a network interface called eth0, bridged to the host bridge vmbr0,
205set the address and gateway, while it's running
206
207 pct set 100 -net0 name=eth0,bridge=vmbr0,ip=192.168.15.147/24,gw=192.168.15.1
208
209Reduce the memory of the container to 512MB
210
211 pct set -memory 512 100
212
213Files
214------
215
216'/etc/pve/lxc/<vmid>.conf'::
217
218Configuration file for the container <vmid>
219
220
221Container Advantages
222--------------------
223
224- Simple, and fully integrated into {pve}. Setup looks similar to a normal
225 VM setup.
226
227 * Storage (ZFS, LVM, NFS, Ceph, ...)
228
229 * Network
230
231 * Authentification
232
233 * Cluster
234
235- Fast: minimal overhead, as fast as bare metal
236
237- High density (perfect for idle workloads)
238
239- REST API
240
241- Direct hardware access
242
243
244Technology Overview
245-------------------
246
247- Integrated into {pve} graphical user interface (GUI)
248
249- LXC (https://linuxcontainers.org/)
250
251- cgmanager for cgroup management
252
253- lxcfs to provive containerized /proc file system
254
255- apparmor
256
257- CRIU: for live migration (planned)
258
259- We use latest available kernels (4.2.X)
260
261- image based deployment (templates)
262
263- Container setup from host (Network, DNS, Storage, ...)
264
265
266ifdef::manvolnum[]
267include::pve-copyright.adoc[]
268endif::manvolnum[]
269
270
271
272
273
274
275