]>
Commit | Line | Data |
---|---|---|
0c6b782f DM |
1 | ifdef::manvolnum[] |
2 | PVE({manvolnum}) | |
3 | ================ | |
38fd0958 | 4 | include::attributes.txt[] |
0c6b782f DM |
5 | |
6 | NAME | |
7 | ---- | |
8 | ||
9 | pct - Tool to manage Linux Containers (LXC) on Proxmox VE | |
10 | ||
11 | ||
12 | SYNOPSYS | |
13 | -------- | |
14 | ||
15 | include::pct.1-synopsis.adoc[] | |
16 | ||
17 | DESCRIPTION | |
18 | ----------- | |
19 | endif::manvolnum[] | |
20 | ||
21 | ifndef::manvolnum[] | |
22 | Proxmox Container Toolkit | |
23 | ========================= | |
38fd0958 | 24 | include::attributes.txt[] |
0c6b782f DM |
25 | endif::manvolnum[] |
26 | ||
4a2ae9ed DM |
27 | |
28 | Containers are a lightweight alternative to fully virtualized | |
29 | VMs. Instead of emulating a complete Operating System (OS), containers | |
30 | simply use the OS of the host they run on. This implies that all | |
31 | containers use the same kernel, and that they can access resources | |
32 | from the host directly. | |
33 | ||
34 | This is great because containers do not waste CPU power nor memory due | |
35 | to kernel emulation. Container run-time costs are close to zero and | |
36 | usually negligible. But there are also some drawbacks you need to | |
37 | consider: | |
38 | ||
39 | * You can only run Linux based OS inside containers, i.e. it is not | |
a8e99754 | 40 | possible to run FreeBSD or MS Windows inside. |
4a2ae9ed | 41 | |
a8e99754 | 42 | * For security reasons, access to host resources needs to be |
4a2ae9ed | 43 | restricted. This is done with AppArmor, SecComp filters and other |
a8e99754 | 44 | kernel features. Be prepared that some syscalls are not allowed |
4a2ae9ed DM |
45 | inside containers. |
46 | ||
47 | {pve} uses https://linuxcontainers.org/[LXC] as underlying container | |
48 | technology. We consider LXC as low-level library, which provides | |
a8e99754 | 49 | countless options. It would be too difficult to use those tools |
4a2ae9ed DM |
50 | directly. Instead, we provide a small wrapper called `pct`, the |
51 | "Proxmox Container Toolkit". | |
52 | ||
a8e99754 | 53 | The toolkit is tightly coupled with {pve}. That means that it is aware |
4a2ae9ed DM |
54 | of the cluster setup, and it can use the same network and storage |
55 | resources as fully virtualized VMs. You can even use the {pve} | |
56 | firewall, or manage containers using the HA framework. | |
57 | ||
58 | Our primary goal is to offer an environment as one would get from a | |
59 | VM, but without the additional overhead. We call this "System | |
60 | Containers". | |
61 | ||
70a42028 DM |
62 | NOTE: If you want to run micro-containers (with docker, rct, ...), it |
63 | is best to run them inside a VM. | |
4a2ae9ed DM |
64 | |
65 | ||
66 | Security Considerations | |
67 | ----------------------- | |
68 | ||
69 | Containers use the same kernel as the host, so there is a big attack | |
70 | surface for malicious users. You should consider this fact if you | |
71 | provide containers to totally untrusted people. In general, fully | |
a8e99754 | 72 | virtualized VMs provide better isolation. |
4a2ae9ed DM |
73 | |
74 | The good news is that LXC uses many kernel security features like | |
75 | AppArmor, CGroups and PID and user namespaces, which makes containers | |
76 | usage quite secure. We distinguish two types of containers: | |
77 | ||
78 | Privileged containers | |
79 | ~~~~~~~~~~~~~~~~~~~~~ | |
80 | ||
81 | Security is done by dropping capabilities, using mandatory access | |
82 | control (AppArmor), SecComp filters and namespaces. The LXC team | |
83 | considers this kind of container as unsafe, and they will not consider | |
84 | new container escape exploits to be security issues worthy of a CVE | |
85 | and quick fix. So you should use this kind of containers only inside a | |
86 | trusted environment, or when no untrusted task is running as root in | |
87 | the container. | |
88 | ||
89 | Unprivileged containers | |
90 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
91 | ||
a8e99754 | 92 | This kind of containers use a new kernel feature called user |
4a2ae9ed DM |
93 | namespaces. The root uid 0 inside the container is mapped to an |
94 | unprivileged user outside the container. This means that most security | |
95 | issues (container escape, resource abuse, ...) in those containers | |
96 | will affect a random unprivileged user, and so would be a generic | |
a8e99754 | 97 | kernel security bug rather than an LXC issue. The LXC team thinks |
4a2ae9ed DM |
98 | unprivileged containers are safe by design. |
99 | ||
7fc230db DM |
100 | |
101 | Configuration | |
102 | ------------- | |
103 | ||
104 | The '/etc/pve/lxc/<CTID>.conf' files stores container configuration, | |
105 | where '<CTID>' is the numeric ID of the given container. Note that | |
105bc8f1 | 106 | CTIDs < 100 are reserved for internal purposes, and CTIDs need to be |
a8e99754 | 107 | unique cluster wide. Files are stored inside '/etc/pve/', so they get |
7fc230db DM |
108 | automatically replicated to all other cluster nodes. |
109 | ||
105bc8f1 DM |
110 | .Example Container Configuration |
111 | ---- | |
112 | ostype: debian | |
113 | arch: amd64 | |
114 | hostname: www | |
115 | memory: 512 | |
116 | swap: 512 | |
117 | net0: bridge=vmbr0,hwaddr=66:64:66:64:64:36,ip=dhcp,name=eth0,type=veth | |
118 | rootfs: local:107/vm-107-disk-1.raw,size=7G | |
119 | ---- | |
120 | ||
7fc230db | 121 | Those configuration files are simple text files, and you can edit them |
55fb2a21 DM |
122 | using a normal text editor ('vi', 'nano', ...). This is sometimes |
123 | useful to do small corrections, but keep in mind that you need to | |
124 | restart the container to apply such changes. | |
125 | ||
126 | For that reason, it is usually better to use the 'pct' command to | |
127 | generate and modify those files, or do the whole thing using the GUI. | |
128 | Our toolkit is smart enough to instantaneously apply most changes to | |
105bc8f1 DM |
129 | running containers. This feature is called "hot plug", and there is no |
130 | need to restart the container in that case. | |
7fc230db DM |
131 | |
132 | File Format | |
133 | ~~~~~~~~~~~ | |
134 | ||
135 | Container configuration files use a simple colon separated key/value | |
136 | format. Each line has the following format: | |
137 | ||
138 | # this is a comment | |
139 | OPTION: value | |
140 | ||
141 | Blank lines in those files are ignored, and lines starting with a '#' | |
142 | character are treated as comments and are also ignored. | |
143 | ||
144 | It is possible to add low-level, LXC style configuration directly, for | |
145 | example: | |
146 | ||
147 | lxc.init_cmd: /sbin/my_own_init | |
148 | ||
149 | or | |
150 | ||
151 | lxc.init_cmd = /sbin/my_own_init | |
152 | ||
153 | Those settings are directly passed to the LXC low-level tools. | |
154 | ||
105bc8f1 DM |
155 | Snapshots |
156 | ~~~~~~~~~ | |
157 | ||
158 | When you create a snapshot, 'pct' stores the configuration at snapshot | |
159 | time into a separate snapshot section within the same configuration | |
160 | file. For example, after creating a snapshot called 'testsnapshot', | |
161 | your configuration file will look like this: | |
162 | ||
163 | .Container Configuration with Snapshot | |
164 | ---- | |
165 | memory: 512 | |
166 | swap: 512 | |
167 | parent: testsnaphot | |
168 | ... | |
169 | ||
170 | [testsnaphot] | |
171 | memory: 512 | |
172 | swap: 512 | |
173 | snaptime: 1457170803 | |
174 | ... | |
175 | ---- | |
176 | ||
a8e99754 FG |
177 | There are a few snapshot related properties like 'parent' and |
178 | 'snaptime'. The 'parent' property is used to store the parent/child | |
105bc8f1 DM |
179 | relationship between snapshots. 'snaptime' is the snapshot creation |
180 | time stamp (unix epoch). | |
7fc230db | 181 | |
3f13c1c3 DM |
182 | Guest Operating System Configuration |
183 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
184 | ||
185 | We normally try to detect the operating system type inside the | |
186 | container, and then modify some files inside the container to make | |
187 | them work as expected. Here is a short list of things we do at | |
188 | container startup: | |
189 | ||
190 | set /etc/hostname:: to set the container name | |
191 | ||
a8e99754 | 192 | modify /etc/hosts:: to allow lookup of the local hostname |
3f13c1c3 DM |
193 | |
194 | network setup:: pass the complete network setup to the container | |
195 | ||
196 | configure DNS:: pass information about DNS servers | |
197 | ||
a8e99754 | 198 | adapt the init system:: for example, fix the number of spawned getty processes |
3f13c1c3 DM |
199 | |
200 | set the root password:: when creating a new container | |
201 | ||
202 | rewrite ssh_host_keys:: so that each container has unique keys | |
203 | ||
a8e99754 | 204 | randomize crontab:: so that cron does not start at the same time on all containers |
3f13c1c3 | 205 | |
a8e99754 | 206 | The above task depends on the OS type, so the implementation is different |
3f13c1c3 DM |
207 | for each OS type. You can also disable any modifications by manually |
208 | setting the 'ostype' to 'unmanaged'. | |
209 | ||
210 | OS type detection is done by testing for certain files inside the | |
211 | container: | |
212 | ||
213 | Ubuntu:: inspect /etc/lsb-release ('DISTRIB_ID=Ubuntu') | |
214 | ||
215 | Debian:: test /etc/debian_version | |
216 | ||
217 | Fedora:: test /etc/fedora-release | |
218 | ||
219 | RedHat or CentOS:: test /etc/redhat-release | |
220 | ||
221 | ArchLinux:: test /etc/arch-release | |
222 | ||
223 | Alpine:: test /etc/alpine-release | |
224 | ||
a8e99754 | 225 | NOTE: Container start fails if the configured 'ostype' differs from the auto |
3f13c1c3 DM |
226 | detected type. |
227 | ||
d61bab51 DM |
228 | |
229 | Container Images | |
230 | ---------------- | |
231 | ||
a8e99754 FG |
232 | Container Images, sometimes also referred to as "templates" or |
233 | "appliances", are 'tar' archives which contain everything to run a | |
d61bab51 DM |
234 | container. You can think of it as a tidy container backup. Like most |
235 | modern container toolkits, 'pct' uses those images when you create a | |
236 | new container, for example: | |
237 | ||
238 | pct create 999 local:vztmpl/debian-8.0-standard_8.0-1_amd64.tar.gz | |
239 | ||
240 | Proxmox itself ships a set of basic templates for most common | |
241 | operating systems, and you can download them using the 'pveam' (short | |
242 | for {pve} Appliance Manager) command line utility. You can also | |
243 | download https://www.turnkeylinux.org/[TurnKey Linux] containers using | |
244 | that tool (or the graphical user interface). | |
245 | ||
3a6fa247 DM |
246 | Our image repositories contain a list of available images, and there |
247 | is a cron job run each day to download that list. You can trigger that | |
248 | update manually with: | |
249 | ||
250 | pveam update | |
251 | ||
252 | After that you can view the list of available images using: | |
253 | ||
254 | pveam available | |
255 | ||
256 | You can restrict this large list by specifying the 'section' you are | |
257 | interested in, for example basic 'system' images: | |
258 | ||
259 | .List available system images | |
260 | ---- | |
261 | # pveam available --section system | |
262 | system archlinux-base_2015-24-29-1_x86_64.tar.gz | |
263 | system centos-7-default_20160205_amd64.tar.xz | |
264 | system debian-6.0-standard_6.0-7_amd64.tar.gz | |
265 | system debian-7.0-standard_7.0-3_amd64.tar.gz | |
266 | system debian-8.0-standard_8.0-1_amd64.tar.gz | |
267 | system ubuntu-12.04-standard_12.04-1_amd64.tar.gz | |
268 | system ubuntu-14.04-standard_14.04-1_amd64.tar.gz | |
269 | system ubuntu-15.04-standard_15.04-1_amd64.tar.gz | |
270 | system ubuntu-15.10-standard_15.10-1_amd64.tar.gz | |
271 | ---- | |
272 | ||
a8e99754 | 273 | Before you can use such a template, you need to download them into one |
3a6fa247 DM |
274 | of your storages. You can simply use storage 'local' for that |
275 | purpose. For clustered installations, it is preferred to use a shared | |
276 | storage so that all nodes can access those images. | |
277 | ||
278 | pveam download local debian-8.0-standard_8.0-1_amd64.tar.gz | |
279 | ||
24f73a63 DM |
280 | You are now ready to create containers using that image, and you can |
281 | list all downloaded images on storage 'local' with: | |
282 | ||
283 | ---- | |
284 | # pveam list local | |
285 | local:vztmpl/debian-8.0-standard_8.0-1_amd64.tar.gz 190.20MB | |
286 | ---- | |
287 | ||
a8e99754 | 288 | The above command shows you the full {pve} volume identifiers. They include |
24f73a63 DM |
289 | the storage name, and most other {pve} commands can use them. For |
290 | examply you can delete that image later with: | |
291 | ||
292 | pveam remove local:vztmpl/debian-8.0-standard_8.0-1_amd64.tar.gz | |
3a6fa247 | 293 | |
d61bab51 | 294 | |
70a42028 DM |
295 | Container Storage |
296 | ----------------- | |
297 | ||
298 | Traditional containers use a very simple storage model, only allowing | |
299 | a single mount point, the root file system. This was further | |
300 | restricted to specific file system types like 'ext4' and 'nfs'. | |
301 | Additional mounts are often done by user provided scripts. This turend | |
a8e99754 | 302 | out to be complex and error prone, so we try to avoid that now. |
70a42028 DM |
303 | |
304 | Our new LXC based container model is more flexible regarding | |
305 | storage. First, you can have more than a single mount point. This | |
306 | allows you to choose a suitable storage for each application. For | |
307 | example, you can use a relatively slow (and thus cheap) storage for | |
308 | the container root file system. Then you can use a second mount point | |
309 | to mount a very fast, distributed storage for your database | |
310 | application. | |
311 | ||
312 | The second big improvement is that you can use any storage type | |
313 | supported by the {pve} storage library. That means that you can store | |
314 | your containers on local 'lvmthin' or 'zfs', shared 'iSCSI' storage, | |
a8e99754 | 315 | or even on distributed storage systems like 'ceph'. It also enables us |
70a42028 | 316 | to use advanced storage features like snapshots and clones. 'vzdump' |
a8e99754 | 317 | can also use the snapshot feature to provide consistent container |
70a42028 DM |
318 | backups. |
319 | ||
320 | Last but not least, you can also mount local devices directly, or | |
321 | mount local directories using bind mounts. That way you can access | |
322 | local storage inside containers with zero overhead. Such bind mounts | |
a8e99754 | 323 | also provide an easy way to share data between different containers. |
70a42028 | 324 | |
4a2ae9ed DM |
325 | |
326 | Managing Containers with 'pct' | |
327 | ------------------------------ | |
328 | ||
9dfe82f1 DM |
329 | 'pct' is the tool to manage Linux Containers on {pve}. You can create |
330 | and destroy containers, and control execution (start, stop, migrate, | |
331 | ...). You can use pct to set parameters in the associated config file, | |
a8e99754 | 332 | like network configuration or memory limits. |
0c6b782f DM |
333 | |
334 | CLI Usage Examples | |
335 | ------------------ | |
336 | ||
a8e99754 FG |
337 | Create a container based on a Debian template (provided you have |
338 | already downloaded the template via the webgui) | |
0c6b782f DM |
339 | |
340 | pct create 100 /var/lib/vz/template/cache/debian-8.0-standard_8.0-1_amd64.tar.gz | |
341 | ||
342 | Start container 100 | |
343 | ||
344 | pct start 100 | |
345 | ||
346 | Start a login session via getty | |
347 | ||
348 | pct console 100 | |
349 | ||
350 | Enter the LXC namespace and run a shell as root user | |
351 | ||
352 | pct enter 100 | |
353 | ||
354 | Display the configuration | |
355 | ||
356 | pct config 100 | |
357 | ||
358 | Add a network interface called eth0, bridged to the host bridge vmbr0, | |
359 | set the address and gateway, while it's running | |
360 | ||
361 | pct set 100 -net0 name=eth0,bridge=vmbr0,ip=192.168.15.147/24,gw=192.168.15.1 | |
362 | ||
363 | Reduce the memory of the container to 512MB | |
364 | ||
365 | pct set -memory 512 100 | |
366 | ||
367 | Files | |
368 | ------ | |
369 | ||
9dfe82f1 | 370 | '/etc/pve/lxc/<CTID>.conf':: |
0c6b782f | 371 | |
9dfe82f1 | 372 | Configuration file for the container '<CTID>'. |
0c6b782f DM |
373 | |
374 | ||
eeecce95 WB |
375 | Container Mountpoints |
376 | --------------------- | |
377 | ||
378 | Beside the root directory the container can also have additional mountpoints. | |
379 | Currently there are basically three types of mountpoints: storage backed | |
380 | mountpoints, bind mounts and device mounts. | |
381 | ||
382 | Storage backed mountpoints are managed by the {pve} storage subsystem and come | |
383 | in three different flavors: | |
384 | ||
385 | - Image based: These are raw images containing a single ext4 formatted file | |
386 | system. | |
387 | - ZFS Subvolumes: These are technically bind mounts, but with managed storage, | |
388 | and thus allow resizing and snapshotting. | |
389 | - Directories: passing `size=0` triggers a special case where instead of a raw | |
390 | image a directory is created. | |
391 | ||
392 | Bind mounts are considered to not be managed by the storage subsystem, so you | |
393 | cannot make snapshots or deal with quotas from inside the container, and with | |
394 | unprivileged containers you might run into permission problems caused by the | |
395 | user mapping, and cannot use ACLs from inside an unprivileged container. | |
396 | ||
397 | Similarly device mounts are not managed by the storage, but for these the | |
398 | `quota` and `acl` options will be honored. | |
399 | ||
400 | ||
d6ed3622 WB |
401 | Using quotas inside containers |
402 | ------------------------------ | |
403 | ||
6c60aebf EK |
404 | Quotas allow to set limits inside a container for the amount of disk space |
405 | that each user can use. | |
d6ed3622 WB |
406 | This only works on ext4 image based storage types and currently does not work |
407 | with unprivileged containers. | |
408 | ||
409 | Activating the `quota` option causes the following mount options to be used for | |
410 | a mountpoint: `usrjquota=aquota.user,grpjquota=aquota.group,jqfmt=vfsv0` | |
411 | ||
412 | This allows quotas to be used like you would on any other system. You can | |
413 | initialize the `/aquota.user` and `/aquota.group` files by running | |
414 | ||
415 | quotacheck -cmug / | |
416 | quotaon / | |
417 | ||
418 | And edit the quotas via the `edquota` command. (Note that you need to do this | |
419 | for every mountpoint by passing the mountpoint's path instead of just `/`.) Best | |
420 | see the documentation specific to the distributiont running inside the | |
421 | container. | |
422 | ||
6c60aebf EK |
423 | Using ACLs inside containers |
424 | ---------------------------- | |
425 | ||
426 | The standard Posix Access Control Lists are also available inside containers. | |
427 | ACLs allow you to set more detailed file ownership than the traditional user/ | |
428 | group/others model. | |
d6ed3622 | 429 | |
0c6b782f DM |
430 | Container Advantages |
431 | -------------------- | |
432 | ||
433 | - Simple, and fully integrated into {pve}. Setup looks similar to a normal | |
434 | VM setup. | |
435 | ||
436 | * Storage (ZFS, LVM, NFS, Ceph, ...) | |
437 | ||
438 | * Network | |
439 | ||
440 | * Authentification | |
441 | ||
442 | * Cluster | |
443 | ||
444 | - Fast: minimal overhead, as fast as bare metal | |
445 | ||
446 | - High density (perfect for idle workloads) | |
447 | ||
448 | - REST API | |
449 | ||
450 | - Direct hardware access | |
451 | ||
452 | ||
453 | Technology Overview | |
454 | ------------------- | |
455 | ||
456 | - Integrated into {pve} graphical user interface (GUI) | |
457 | ||
458 | - LXC (https://linuxcontainers.org/) | |
459 | ||
460 | - cgmanager for cgroup management | |
461 | ||
462 | - lxcfs to provive containerized /proc file system | |
463 | ||
464 | - apparmor | |
465 | ||
466 | - CRIU: for live migration (planned) | |
467 | ||
468 | - We use latest available kernels (4.2.X) | |
469 | ||
a8e99754 | 470 | - Image based deployment (templates) |
0c6b782f DM |
471 | |
472 | - Container setup from host (Network, DNS, Storage, ...) | |
473 | ||
474 | ||
475 | ifdef::manvolnum[] | |
476 | include::pve-copyright.adoc[] | |
477 | endif::manvolnum[] | |
478 | ||
479 | ||
480 | ||
481 | ||
482 | ||
483 | ||
484 |