]>
Commit | Line | Data |
---|---|---|
80c0adcb | 1 | [[chapter_pct]] |
0c6b782f | 2 | ifdef::manvolnum[] |
b2f242ab | 3 | pct(1) |
7e2fdb3d | 4 | ====== |
5f09af76 DM |
5 | :pve-toplevel: |
6 | ||
0c6b782f DM |
7 | NAME |
8 | ---- | |
9 | ||
10 | pct - Tool to manage Linux Containers (LXC) on Proxmox VE | |
11 | ||
12 | ||
49a5e11c | 13 | SYNOPSIS |
0c6b782f DM |
14 | -------- |
15 | ||
16 | include::pct.1-synopsis.adoc[] | |
17 | ||
18 | DESCRIPTION | |
19 | ----------- | |
20 | endif::manvolnum[] | |
21 | ||
22 | ifndef::manvolnum[] | |
23 | Proxmox Container Toolkit | |
24 | ========================= | |
194d2f29 | 25 | :pve-toplevel: |
0c6b782f | 26 | endif::manvolnum[] |
5f09af76 | 27 | ifdef::wiki[] |
cb84ed18 | 28 | :title: Linux Container |
5f09af76 | 29 | endif::wiki[] |
4a2ae9ed DM |
30 | |
31 | Containers are a lightweight alternative to fully virtualized | |
32 | VMs. Instead of emulating a complete Operating System (OS), containers | |
33 | simply use the OS of the host they run on. This implies that all | |
34 | containers use the same kernel, and that they can access resources | |
35 | from the host directly. | |
36 | ||
37 | This is great because containers do not waste CPU power nor memory due | |
38 | to kernel emulation. Container run-time costs are close to zero and | |
39 | usually negligible. But there are also some drawbacks you need to | |
40 | consider: | |
41 | ||
42 | * You can only run Linux based OS inside containers, i.e. it is not | |
a8e99754 | 43 | possible to run FreeBSD or MS Windows inside. |
4a2ae9ed | 44 | |
a8e99754 | 45 | * For security reasons, access to host resources needs to be |
4a2ae9ed | 46 | restricted. This is done with AppArmor, SecComp filters and other |
a8e99754 | 47 | kernel features. Be prepared that some syscalls are not allowed |
4a2ae9ed DM |
48 | inside containers. |
49 | ||
50 | {pve} uses https://linuxcontainers.org/[LXC] as underlying container | |
51 | technology. We consider LXC as low-level library, which provides | |
a8e99754 | 52 | countless options. It would be too difficult to use those tools |
4a2ae9ed DM |
53 | directly. Instead, we provide a small wrapper called `pct`, the |
54 | "Proxmox Container Toolkit". | |
55 | ||
a8e99754 | 56 | The toolkit is tightly coupled with {pve}. That means that it is aware |
4a2ae9ed DM |
57 | of the cluster setup, and it can use the same network and storage |
58 | resources as fully virtualized VMs. You can even use the {pve} | |
59 | firewall, or manage containers using the HA framework. | |
60 | ||
61 | Our primary goal is to offer an environment as one would get from a | |
62 | VM, but without the additional overhead. We call this "System | |
63 | Containers". | |
64 | ||
99d2e25b | 65 | NOTE: If you want to run micro-containers (with docker, rkt, ...), it |
70a42028 | 66 | is best to run them inside a VM. |
4a2ae9ed DM |
67 | |
68 | ||
99f6ae1a DM |
69 | Technology Overview |
70 | ------------------- | |
71 | ||
72 | * LXC (https://linuxcontainers.org/) | |
73 | ||
74 | * Integrated into {pve} graphical user interface (GUI) | |
75 | ||
76 | * Easy to use command line tool `pct` | |
77 | ||
78 | * Access via {pve} REST API | |
79 | ||
80 | * lxcfs to provide containerized /proc file system | |
81 | ||
82 | * AppArmor/Seccomp to improve security | |
83 | ||
84 | * CRIU: for live migration (planned) | |
85 | ||
86 | * Use latest available kernels (4.4.X) | |
87 | ||
88 | * Image based deployment (templates) | |
89 | ||
90 | * Use {pve} storage library | |
91 | ||
92 | * Container setup from host (network, DNS, storage, ...) | |
93 | ||
94 | ||
4a2ae9ed DM |
95 | Security Considerations |
96 | ----------------------- | |
97 | ||
98 | Containers use the same kernel as the host, so there is a big attack | |
99 | surface for malicious users. You should consider this fact if you | |
100 | provide containers to totally untrusted people. In general, fully | |
a8e99754 | 101 | virtualized VMs provide better isolation. |
4a2ae9ed DM |
102 | |
103 | The good news is that LXC uses many kernel security features like | |
104 | AppArmor, CGroups and PID and user namespaces, which makes containers | |
304eb5a9 | 105 | usage quite secure. |
3bd9d0cf | 106 | |
53e3cd6f DM |
107 | Guest Operating System Configuration |
108 | ------------------------------------ | |
109 | ||
110 | We normally try to detect the operating system type inside the | |
111 | container, and then modify some files inside the container to make | |
112 | them work as expected. Here is a short list of things we do at | |
113 | container startup: | |
114 | ||
115 | set /etc/hostname:: to set the container name | |
116 | ||
117 | modify /etc/hosts:: to allow lookup of the local hostname | |
118 | ||
119 | network setup:: pass the complete network setup to the container | |
120 | ||
121 | configure DNS:: pass information about DNS servers | |
122 | ||
123 | adapt the init system:: for example, fix the number of spawned getty processes | |
124 | ||
125 | set the root password:: when creating a new container | |
126 | ||
127 | rewrite ssh_host_keys:: so that each container has unique keys | |
128 | ||
129 | randomize crontab:: so that cron does not start at the same time on all containers | |
130 | ||
131 | Changes made by {PVE} are enclosed by comment markers: | |
132 | ||
133 | ---- | |
134 | # --- BEGIN PVE --- | |
135 | <data> | |
136 | # --- END PVE --- | |
137 | ---- | |
138 | ||
139 | Those markers will be inserted at a reasonable location in the | |
140 | file. If such a section already exists, it will be updated in place | |
141 | and will not be moved. | |
142 | ||
143 | Modification of a file can be prevented by adding a `.pve-ignore.` | |
144 | file for it. For instance, if the file `/etc/.pve-ignore.hosts` | |
145 | exists then the `/etc/hosts` file will not be touched. This can be a | |
470d4313 | 146 | simple empty file created via: |
53e3cd6f DM |
147 | |
148 | # touch /etc/.pve-ignore.hosts | |
149 | ||
150 | Most modifications are OS dependent, so they differ between different | |
151 | distributions and versions. You can completely disable modifications | |
152 | by manually setting the `ostype` to `unmanaged`. | |
153 | ||
154 | OS type detection is done by testing for certain files inside the | |
155 | container: | |
156 | ||
157 | Ubuntu:: inspect /etc/lsb-release (`DISTRIB_ID=Ubuntu`) | |
158 | ||
159 | Debian:: test /etc/debian_version | |
160 | ||
161 | Fedora:: test /etc/fedora-release | |
162 | ||
163 | RedHat or CentOS:: test /etc/redhat-release | |
164 | ||
165 | ArchLinux:: test /etc/arch-release | |
166 | ||
167 | Alpine:: test /etc/alpine-release | |
168 | ||
169 | Gentoo:: test /etc/gentoo-release | |
170 | ||
171 | NOTE: Container start fails if the configured `ostype` differs from the auto | |
172 | detected type. | |
173 | ||
174 | ||
80c0adcb | 175 | [[pct_container_images]] |
d61bab51 DM |
176 | Container Images |
177 | ---------------- | |
178 | ||
8c1189b6 FG |
179 | Container images, sometimes also referred to as ``templates'' or |
180 | ``appliances'', are `tar` archives which contain everything to run a | |
d61bab51 | 181 | container. You can think of it as a tidy container backup. Like most |
8c1189b6 | 182 | modern container toolkits, `pct` uses those images when you create a |
d61bab51 DM |
183 | new container, for example: |
184 | ||
185 | pct create 999 local:vztmpl/debian-8.0-standard_8.0-1_amd64.tar.gz | |
186 | ||
26ca7ff5 | 187 | {pve} itself ships a set of basic templates for most common |
8c1189b6 | 188 | operating systems, and you can download them using the `pveam` (short |
d61bab51 DM |
189 | for {pve} Appliance Manager) command line utility. You can also |
190 | download https://www.turnkeylinux.org/[TurnKey Linux] containers using | |
191 | that tool (or the graphical user interface). | |
192 | ||
3a6fa247 DM |
193 | Our image repositories contain a list of available images, and there |
194 | is a cron job run each day to download that list. You can trigger that | |
195 | update manually with: | |
196 | ||
197 | pveam update | |
198 | ||
199 | After that you can view the list of available images using: | |
200 | ||
201 | pveam available | |
202 | ||
8c1189b6 FG |
203 | You can restrict this large list by specifying the `section` you are |
204 | interested in, for example basic `system` images: | |
3a6fa247 DM |
205 | |
206 | .List available system images | |
207 | ---- | |
208 | # pveam available --section system | |
209 | system archlinux-base_2015-24-29-1_x86_64.tar.gz | |
210 | system centos-7-default_20160205_amd64.tar.xz | |
211 | system debian-6.0-standard_6.0-7_amd64.tar.gz | |
212 | system debian-7.0-standard_7.0-3_amd64.tar.gz | |
213 | system debian-8.0-standard_8.0-1_amd64.tar.gz | |
214 | system ubuntu-12.04-standard_12.04-1_amd64.tar.gz | |
215 | system ubuntu-14.04-standard_14.04-1_amd64.tar.gz | |
216 | system ubuntu-15.04-standard_15.04-1_amd64.tar.gz | |
217 | system ubuntu-15.10-standard_15.10-1_amd64.tar.gz | |
218 | ---- | |
219 | ||
a8e99754 | 220 | Before you can use such a template, you need to download them into one |
8c1189b6 | 221 | of your storages. You can simply use storage `local` for that |
3a6fa247 DM |
222 | purpose. For clustered installations, it is preferred to use a shared |
223 | storage so that all nodes can access those images. | |
224 | ||
225 | pveam download local debian-8.0-standard_8.0-1_amd64.tar.gz | |
226 | ||
24f73a63 | 227 | You are now ready to create containers using that image, and you can |
8c1189b6 | 228 | list all downloaded images on storage `local` with: |
24f73a63 DM |
229 | |
230 | ---- | |
231 | # pveam list local | |
232 | local:vztmpl/debian-8.0-standard_8.0-1_amd64.tar.gz 190.20MB | |
233 | ---- | |
234 | ||
a8e99754 | 235 | The above command shows you the full {pve} volume identifiers. They include |
24f73a63 | 236 | the storage name, and most other {pve} commands can use them. For |
5eba0743 | 237 | example you can delete that image later with: |
24f73a63 DM |
238 | |
239 | pveam remove local:vztmpl/debian-8.0-standard_8.0-1_amd64.tar.gz | |
3a6fa247 | 240 | |
d61bab51 | 241 | |
80c0adcb | 242 | [[pct_container_storage]] |
70a42028 DM |
243 | Container Storage |
244 | ----------------- | |
245 | ||
246 | Traditional containers use a very simple storage model, only allowing | |
247 | a single mount point, the root file system. This was further | |
8c1189b6 FG |
248 | restricted to specific file system types like `ext4` and `nfs`. |
249 | Additional mounts are often done by user provided scripts. This turned | |
a8e99754 | 250 | out to be complex and error prone, so we try to avoid that now. |
70a42028 DM |
251 | |
252 | Our new LXC based container model is more flexible regarding | |
253 | storage. First, you can have more than a single mount point. This | |
254 | allows you to choose a suitable storage for each application. For | |
255 | example, you can use a relatively slow (and thus cheap) storage for | |
256 | the container root file system. Then you can use a second mount point | |
257 | to mount a very fast, distributed storage for your database | |
4f785ca7 DM |
258 | application. See section <<pct_mount_points,Mount Points>> for further |
259 | details. | |
70a42028 DM |
260 | |
261 | The second big improvement is that you can use any storage type | |
262 | supported by the {pve} storage library. That means that you can store | |
8c1189b6 FG |
263 | your containers on local `lvmthin` or `zfs`, shared `iSCSI` storage, |
264 | or even on distributed storage systems like `ceph`. It also enables us | |
265 | to use advanced storage features like snapshots and clones. `vzdump` | |
a8e99754 | 266 | can also use the snapshot feature to provide consistent container |
70a42028 DM |
267 | backups. |
268 | ||
269 | Last but not least, you can also mount local devices directly, or | |
270 | mount local directories using bind mounts. That way you can access | |
271 | local storage inside containers with zero overhead. Such bind mounts | |
a8e99754 | 272 | also provide an easy way to share data between different containers. |
70a42028 | 273 | |
eeecce95 | 274 | |
4f785ca7 DM |
275 | FUSE Mounts |
276 | ~~~~~~~~~~~ | |
277 | ||
278 | WARNING: Because of existing issues in the Linux kernel's freezer | |
279 | subsystem the usage of FUSE mounts inside a container is strongly | |
280 | advised against, as containers need to be frozen for suspend or | |
281 | snapshot mode backups. | |
282 | ||
283 | If FUSE mounts cannot be replaced by other mounting mechanisms or storage | |
284 | technologies, it is possible to establish the FUSE mount on the Proxmox host | |
285 | and use a bind mount point to make it accessible inside the container. | |
286 | ||
287 | ||
288 | Using Quotas Inside Containers | |
289 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
290 | ||
291 | Quotas allow to set limits inside a container for the amount of disk | |
292 | space that each user can use. This only works on ext4 image based | |
293 | storage types and currently does not work with unprivileged | |
294 | containers. | |
295 | ||
296 | Activating the `quota` option causes the following mount options to be | |
297 | used for a mount point: | |
298 | `usrjquota=aquota.user,grpjquota=aquota.group,jqfmt=vfsv0` | |
299 | ||
300 | This allows quotas to be used like you would on any other system. You | |
301 | can initialize the `/aquota.user` and `/aquota.group` files by running | |
302 | ||
303 | ---- | |
304 | quotacheck -cmug / | |
305 | quotaon / | |
306 | ---- | |
307 | ||
308 | and edit the quotas via the `edquota` command. Refer to the documentation | |
309 | of the distribution running inside the container for details. | |
310 | ||
311 | NOTE: You need to run the above commands for every mount point by passing | |
312 | the mount point's path instead of just `/`. | |
313 | ||
314 | ||
315 | Using ACLs Inside Containers | |
316 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
317 | ||
318 | The standard Posix **A**ccess **C**ontrol **L**ists are also available inside containers. | |
319 | ACLs allow you to set more detailed file ownership than the traditional user/ | |
320 | group/others model. | |
321 | ||
322 | ||
690cd737 EK |
323 | Backup of Containers mount points |
324 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
325 | ||
470d4313 DC |
326 | By default additional mount points besides the Root Disk mount point are not |
327 | included in backups. You can reverse this default behavior by setting the | |
563159b1 | 328 | *Backup* option on a mount point. |
690cd737 EK |
329 | // see PVE::VZDump::LXC::prepare() |
330 | ||
331 | Replication of Containers mount points | |
332 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
333 | ||
470d4313 | 334 | By default additional mount points are replicated when the Root Disk |
690cd737 | 335 | is replicated. If you want the {pve} storage replication mechanism to skip a |
470d4313 | 336 | mount point when starting a replication job, you can set the |
690cd737 EK |
337 | *Skip replication* option on that mount point. + |
338 | As of {pve} 5.0, replication requires a storage of type `zfspool`, so adding a | |
339 | mount point to a different type of storage when the container has replication | |
340 | configured requires to *Skip replication* for that mount point. | |
341 | ||
342 | ||
f3afbb70 | 343 | [[pct_settings]] |
4f785ca7 DM |
344 | Container Settings |
345 | ------------------ | |
346 | ||
304eb5a9 EK |
347 | [[pct_general]] |
348 | General Settings | |
349 | ~~~~~~~~~~~~~~~~ | |
350 | ||
2225402c DM |
351 | [thumbnail="gui-create-ct-general.png"] |
352 | ||
304eb5a9 EK |
353 | General settings of a container include |
354 | ||
355 | * the *Node* : the physical server on which the container will run | |
356 | * the *CT ID*: a unique number in this {pve} installation used to identify your container | |
357 | * *Hostname*: the hostname of the container | |
358 | * *Resource Pool*: a logical group of containers and VMs | |
359 | * *Password*: the root password of the container | |
360 | * *SSH Public Key*: a public key for connecting to the root account over SSH | |
361 | * *Unprivileged container*: this option allows to choose at creation time | |
362 | if you want to create a privileged or unprivileged container. | |
363 | ||
364 | ||
365 | Privileged Containers | |
366 | ^^^^^^^^^^^^^^^^^^^^^ | |
367 | ||
368 | Security is done by dropping capabilities, using mandatory access | |
369 | control (AppArmor), SecComp filters and namespaces. The LXC team | |
370 | considers this kind of container as unsafe, and they will not consider | |
371 | new container escape exploits to be security issues worthy of a CVE | |
372 | and quick fix. So you should use this kind of containers only inside a | |
373 | trusted environment, or when no untrusted task is running as root in | |
374 | the container. | |
375 | ||
376 | ||
377 | Unprivileged Containers | |
378 | ^^^^^^^^^^^^^^^^^^^^^^^ | |
379 | ||
380 | This kind of containers use a new kernel feature called user | |
381 | namespaces. The root UID 0 inside the container is mapped to an | |
382 | unprivileged user outside the container. This means that most security | |
383 | issues (container escape, resource abuse, ...) in those containers | |
384 | will affect a random unprivileged user, and so would be a generic | |
385 | kernel security bug rather than an LXC issue. The LXC team thinks | |
386 | unprivileged containers are safe by design. | |
387 | ||
388 | NOTE: If the container uses systemd as an init system, please be | |
389 | aware the systemd version running inside the container should be equal | |
390 | or greater than 220. | |
391 | ||
9a5e9443 | 392 | [[pct_cpu]] |
9a5e9443 DM |
393 | CPU |
394 | ~~~ | |
395 | ||
097aa949 DM |
396 | [thumbnail="gui-create-ct-cpu.png"] |
397 | ||
9a5e9443 DM |
398 | You can restrict the number of visible CPUs inside the container using |
399 | the `cores` option. This is implemented using the Linux 'cpuset' | |
400 | cgroup (**c**ontrol *group*). A special task inside `pvestatd` tries | |
401 | to distribute running containers among available CPUs. You can view | |
402 | the assigned CPUs using the following command: | |
403 | ||
404 | ---- | |
405 | # pct cpusets | |
406 | --------------------- | |
407 | 102: 6 7 | |
408 | 105: 2 3 4 5 | |
409 | 108: 0 1 | |
410 | --------------------- | |
411 | ---- | |
412 | ||
413 | Containers use the host kernel directly, so all task inside a | |
414 | container are handled by the host CPU scheduler. {pve} uses the Linux | |
415 | 'CFS' (**C**ompletely **F**air **S**cheduler) scheduler by default, | |
416 | which has additional bandwidth control options. | |
417 | ||
418 | [horizontal] | |
0725e3c6 DM |
419 | |
420 | `cpulimit`: :: You can use this option to further limit assigned CPU | |
9a5e9443 DM |
421 | time. Please note that this is a floating point number, so it is |
422 | perfectly valid to assign two cores to a container, but restrict | |
423 | overall CPU consumption to half a core. | |
424 | + | |
425 | ---- | |
426 | cores: 2 | |
427 | cpulimit: 0.5 | |
428 | ---- | |
429 | ||
0725e3c6 | 430 | `cpuunits`: :: This is a relative weight passed to the kernel |
9a5e9443 DM |
431 | scheduler. The larger the number is, the more CPU time this container |
432 | gets. Number is relative to the weights of all the other running | |
433 | containers. The default is 1024. You can use this setting to | |
434 | prioritize some containers. | |
435 | ||
436 | ||
437 | [[pct_memory]] | |
438 | Memory | |
439 | ~~~~~~ | |
440 | ||
097aa949 DM |
441 | [thumbnail="gui-create-ct-memory.png"] |
442 | ||
9a5e9443 DM |
443 | Container memory is controlled using the cgroup memory controller. |
444 | ||
445 | [horizontal] | |
446 | ||
0725e3c6 | 447 | `memory`: :: Limit overall memory usage. This corresponds |
9a5e9443 DM |
448 | to the `memory.limit_in_bytes` cgroup setting. |
449 | ||
0725e3c6 | 450 | `swap`: :: Allows the container to use additional swap memory from the |
9a5e9443 DM |
451 | host swap space. This corresponds to the `memory.memsw.limit_in_bytes` |
452 | cgroup setting, which is set to the sum of both value (`memory + | |
453 | swap`). | |
454 | ||
4f785ca7 DM |
455 | |
456 | [[pct_mount_points]] | |
9e44e493 DM |
457 | Mount Points |
458 | ~~~~~~~~~~~~ | |
eeecce95 | 459 | |
097aa949 DM |
460 | [thumbnail="gui-create-ct-root-disk.png"] |
461 | ||
01639994 FG |
462 | The root mount point is configured with the `rootfs` property, and you can |
463 | configure up to 10 additional mount points. The corresponding options | |
464 | are called `mp0` to `mp9`, and they can contain the following setting: | |
465 | ||
466 | include::pct-mountpoint-opts.adoc[] | |
467 | ||
9e44e493 DM |
468 | Currently there are basically three types of mount points: storage backed |
469 | mount points, bind mounts and device mounts. | |
470 | ||
5eba0743 | 471 | .Typical container `rootfs` configuration |
4c3b5c77 DM |
472 | ---- |
473 | rootfs: thin1:base-100-disk-1,size=8G | |
474 | ---- | |
475 | ||
476 | ||
5eba0743 | 477 | Storage Backed Mount Points |
4c3b5c77 | 478 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
01639994 | 479 | |
9e44e493 | 480 | Storage backed mount points are managed by the {pve} storage subsystem and come |
eeecce95 WB |
481 | in three different flavors: |
482 | ||
5eba0743 | 483 | - Image based: these are raw images containing a single ext4 formatted file |
eeecce95 | 484 | system. |
5eba0743 | 485 | - ZFS subvolumes: these are technically bind mounts, but with managed storage, |
eeecce95 WB |
486 | and thus allow resizing and snapshotting. |
487 | - Directories: passing `size=0` triggers a special case where instead of a raw | |
488 | image a directory is created. | |
489 | ||
03782251 FG |
490 | NOTE: The special option syntax `STORAGE_ID:SIZE_IN_GB` for storage backed |
491 | mount point volumes will automatically allocate a volume of the specified size | |
492 | on the specified storage. E.g., calling | |
493 | `pct set 100 -mp0 thin1:10,mp=/path/in/container` will allocate a 10GB volume | |
494 | on the storage `thin1` and replace the volume ID place holder `10` with the | |
495 | allocated volume ID. | |
496 | ||
4c3b5c77 | 497 | |
5eba0743 | 498 | Bind Mount Points |
4c3b5c77 | 499 | ^^^^^^^^^^^^^^^^^ |
01639994 | 500 | |
9baca183 FG |
501 | Bind mounts allow you to access arbitrary directories from your Proxmox VE host |
502 | inside a container. Some potential use cases are: | |
503 | ||
504 | - Accessing your home directory in the guest | |
505 | - Accessing an USB device directory in the guest | |
acccc49b | 506 | - Accessing an NFS mount from the host in the guest |
9baca183 | 507 | |
eeecce95 | 508 | Bind mounts are considered to not be managed by the storage subsystem, so you |
9baca183 | 509 | cannot make snapshots or deal with quotas from inside the container. With |
eeecce95 | 510 | unprivileged containers you might run into permission problems caused by the |
9baca183 FG |
511 | user mapping and cannot use ACLs. |
512 | ||
8c1189b6 | 513 | NOTE: The contents of bind mount points are not backed up when using `vzdump`. |
eeecce95 | 514 | |
6b707f2c FG |
515 | WARNING: For security reasons, bind mounts should only be established |
516 | using source directories especially reserved for this purpose, e.g., a | |
517 | directory hierarchy under `/mnt/bindmounts`. Never bind mount system | |
518 | directories like `/`, `/var` or `/etc` into a container - this poses a | |
9baca183 FG |
519 | great security risk. |
520 | ||
521 | NOTE: The bind mount source path must not contain any symlinks. | |
522 | ||
523 | For example, to make the directory `/mnt/bindmounts/shared` accessible in the | |
524 | container with ID `100` under the path `/shared`, use a configuration line like | |
8c1189b6 FG |
525 | `mp0: /mnt/bindmounts/shared,mp=/shared` in `/etc/pve/lxc/100.conf`. |
526 | Alternatively, use `pct set 100 -mp0 /mnt/bindmounts/shared,mp=/shared` to | |
9baca183 | 527 | achieve the same result. |
6b707f2c | 528 | |
4c3b5c77 | 529 | |
5eba0743 | 530 | Device Mount Points |
4c3b5c77 | 531 | ^^^^^^^^^^^^^^^^^^^ |
fe154a4f | 532 | |
7432d78e FG |
533 | Device mount points allow to mount block devices of the host directly into the |
534 | container. Similar to bind mounts, device mounts are not managed by {PVE}'s | |
535 | storage subsystem, but the `quota` and `acl` options will be honored. | |
536 | ||
537 | NOTE: Device mount points should only be used under special circumstances. In | |
538 | most cases a storage backed mount point offers the same performance and a lot | |
539 | more features. | |
540 | ||
8c1189b6 | 541 | NOTE: The contents of device mount points are not backed up when using `vzdump`. |
01639994 | 542 | |
4c3b5c77 | 543 | |
80c0adcb | 544 | [[pct_container_network]] |
f5c351f0 DM |
545 | Network |
546 | ~~~~~~~ | |
04c569f6 | 547 | |
097aa949 DM |
548 | [thumbnail="gui-create-ct-network.png"] |
549 | ||
bac8c385 | 550 | You can configure up to 10 network interfaces for a single |
8c1189b6 | 551 | container. The corresponding options are called `net0` to `net9`, and |
bac8c385 DM |
552 | they can contain the following setting: |
553 | ||
554 | include::pct-network-opts.adoc[] | |
04c569f6 DM |
555 | |
556 | ||
139a9019 DM |
557 | [[pct_startup_and_shutdown]] |
558 | Automatic Start and Shutdown of Containers | |
559 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
560 | ||
561 | After creating your containers, you probably want them to start automatically | |
562 | when the host system boots. For this you need to select the option 'Start at | |
563 | boot' from the 'Options' Tab of your container in the web interface, or set it with | |
564 | the following command: | |
565 | ||
566 | pct set <ctid> -onboot 1 | |
567 | ||
4dbeb548 DM |
568 | .Start and Shutdown Order |
569 | // use the screenshot from qemu - its the same | |
570 | [thumbnail="gui-qemu-edit-start-order.png"] | |
571 | ||
139a9019 DM |
572 | If you want to fine tune the boot order of your containers, you can use the following |
573 | parameters : | |
574 | ||
575 | * *Start/Shutdown order*: Defines the start order priority. E.g. set it to 1 if | |
576 | you want the CT to be the first to be started. (We use the reverse startup | |
577 | order for shutdown, so a container with a start order of 1 would be the last to | |
578 | be shut down) | |
579 | * *Startup delay*: Defines the interval between this container start and subsequent | |
580 | containers starts . E.g. set it to 240 if you want to wait 240 seconds before starting | |
581 | other containers. | |
582 | * *Shutdown timeout*: Defines the duration in seconds {pve} should wait | |
583 | for the container to be offline after issuing a shutdown command. | |
584 | By default this value is set to 60, which means that {pve} will issue a | |
585 | shutdown request, wait 60s for the machine to be offline, and if after 60s | |
586 | the machine is still online will notify that the shutdown action failed. | |
587 | ||
588 | Please note that containers without a Start/Shutdown order parameter will always | |
589 | start after those where the parameter is set, and this parameter only | |
590 | makes sense between the machines running locally on a host, and not | |
591 | cluster-wide. | |
592 | ||
593 | ||
51e33128 FG |
594 | Backup and Restore |
595 | ------------------ | |
596 | ||
5eba0743 | 597 | |
2175e37b FG |
598 | Container Backup |
599 | ~~~~~~~~~~~~~~~~ | |
600 | ||
8c1189b6 FG |
601 | It is possible to use the `vzdump` tool for container backup. Please |
602 | refer to the `vzdump` manual page for details. | |
603 | ||
51e33128 | 604 | |
2175e37b FG |
605 | Restoring Container Backups |
606 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
607 | ||
8c1189b6 FG |
608 | Restoring container backups made with `vzdump` is possible using the |
609 | `pct restore` command. By default, `pct restore` will attempt to restore as much | |
2175e37b FG |
610 | of the backed up container configuration as possible. It is possible to override |
611 | the backed up configuration by manually setting container options on the command | |
8c1189b6 | 612 | line (see the `pct` manual page for details). |
2175e37b | 613 | |
8c1189b6 | 614 | NOTE: `pvesm extractconfig` can be used to view the backed up configuration |
2175e37b FG |
615 | contained in a vzdump archive. |
616 | ||
617 | There are two basic restore modes, only differing by their handling of mount | |
618 | points: | |
619 | ||
4c3b5c77 | 620 | |
8c1189b6 FG |
621 | ``Simple'' Restore Mode |
622 | ^^^^^^^^^^^^^^^^^^^^^^^ | |
2175e37b FG |
623 | |
624 | If neither the `rootfs` parameter nor any of the optional `mpX` parameters | |
625 | are explicitly set, the mount point configuration from the backed up | |
626 | configuration file is restored using the following steps: | |
627 | ||
628 | . Extract mount points and their options from backup | |
629 | . Create volumes for storage backed mount points (on storage provided with the | |
630 | `storage` parameter, or default local storage if unset) | |
631 | . Extract files from backup archive | |
632 | . Add bind and device mount points to restored configuration (limited to root user) | |
633 | ||
634 | NOTE: Since bind and device mount points are never backed up, no files are | |
635 | restored in the last step, but only the configuration options. The assumption | |
636 | is that such mount points are either backed up with another mechanism (e.g., | |
637 | NFS space that is bind mounted into many containers), or not intended to be | |
638 | backed up at all. | |
639 | ||
640 | This simple mode is also used by the container restore operations in the web | |
641 | interface. | |
642 | ||
4c3b5c77 | 643 | |
8c1189b6 FG |
644 | ``Advanced'' Restore Mode |
645 | ^^^^^^^^^^^^^^^^^^^^^^^^^ | |
2175e37b FG |
646 | |
647 | By setting the `rootfs` parameter (and optionally, any combination of `mpX` | |
8c1189b6 | 648 | parameters), the `pct restore` command is automatically switched into an |
2175e37b FG |
649 | advanced mode. This advanced mode completely ignores the `rootfs` and `mpX` |
650 | configuration options contained in the backup archive, and instead only | |
651 | uses the options explicitly provided as parameters. | |
652 | ||
653 | This mode allows flexible configuration of mount point settings at restore time, | |
654 | for example: | |
655 | ||
656 | * Set target storages, volume sizes and other options for each mount point | |
657 | individually | |
658 | * Redistribute backed up files according to new mount point scheme | |
659 | * Restore to device and/or bind mount points (limited to root user) | |
660 | ||
51e33128 | 661 | |
8c1189b6 | 662 | Managing Containers with `pct` |
04c569f6 DM |
663 | ------------------------------ |
664 | ||
8c1189b6 | 665 | `pct` is the tool to manage Linux Containers on {pve}. You can create |
04c569f6 DM |
666 | and destroy containers, and control execution (start, stop, migrate, |
667 | ...). You can use pct to set parameters in the associated config file, | |
668 | like network configuration or memory limits. | |
669 | ||
5eba0743 | 670 | |
04c569f6 DM |
671 | CLI Usage Examples |
672 | ~~~~~~~~~~~~~~~~~~ | |
673 | ||
674 | Create a container based on a Debian template (provided you have | |
5eba0743 | 675 | already downloaded the template via the web interface) |
04c569f6 DM |
676 | |
677 | pct create 100 /var/lib/vz/template/cache/debian-8.0-standard_8.0-1_amd64.tar.gz | |
678 | ||
679 | Start container 100 | |
680 | ||
681 | pct start 100 | |
682 | ||
683 | Start a login session via getty | |
684 | ||
685 | pct console 100 | |
686 | ||
687 | Enter the LXC namespace and run a shell as root user | |
688 | ||
689 | pct enter 100 | |
690 | ||
691 | Display the configuration | |
692 | ||
693 | pct config 100 | |
694 | ||
8c1189b6 | 695 | Add a network interface called `eth0`, bridged to the host bridge `vmbr0`, |
04c569f6 DM |
696 | set the address and gateway, while it's running |
697 | ||
698 | pct set 100 -net0 name=eth0,bridge=vmbr0,ip=192.168.15.147/24,gw=192.168.15.1 | |
699 | ||
700 | Reduce the memory of the container to 512MB | |
701 | ||
0585f29a DM |
702 | pct set 100 -memory 512 |
703 | ||
04c569f6 | 704 | |
fe57a420 FG |
705 | Obtaining Debugging Logs |
706 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
707 | ||
708 | In case `pct start` is unable to start a specific container, it might be | |
709 | helpful to collect debugging output by running `lxc-start` (replace `ID` with | |
710 | the container's ID): | |
711 | ||
712 | lxc-start -n ID -F -l DEBUG -o /tmp/lxc-ID.log | |
713 | ||
714 | 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. | |
715 | ||
716 | The collected debug log is written to `/tmp/lxc-ID.log`. | |
717 | ||
718 | NOTE: If you have changed the container's configuration since the last start | |
719 | attempt with `pct start`, you need to run `pct start` at least once to also | |
720 | update the configuration used by `lxc-start`. | |
721 | ||
33f50e04 DC |
722 | [[pct_migration]] |
723 | Migration | |
724 | --------- | |
725 | ||
726 | If you have a cluster, you can migrate your Containers with | |
727 | ||
728 | pct migrate <vmid> <target> | |
729 | ||
730 | This works as long as your Container is offline. If it has local volumes or | |
731 | mountpoints defined, the migration will copy the content over the network to | |
732 | the target host if there is the same storage defined. | |
733 | ||
734 | If you want to migrate online Containers, the only way is to use | |
735 | restart migration. This can be initiated with the -restart flag and the optional | |
736 | -timeout parameter. | |
737 | ||
738 | A restart migration will shut down the Container and kill it after the specified | |
739 | timeout (the default is 180 seconds). Then it will migrate the Container | |
740 | like an offline migration and when finished, it starts the Container on the | |
741 | target node. | |
c7bc47af DM |
742 | |
743 | [[pct_configuration]] | |
744 | Configuration | |
745 | ------------- | |
746 | ||
747 | The `/etc/pve/lxc/<CTID>.conf` file stores container configuration, | |
748 | where `<CTID>` is the numeric ID of the given container. Like all | |
749 | other files stored inside `/etc/pve/`, they get automatically | |
750 | replicated to all other cluster nodes. | |
751 | ||
752 | NOTE: CTIDs < 100 are reserved for internal purposes, and CTIDs need to be | |
753 | unique cluster wide. | |
754 | ||
755 | .Example Container Configuration | |
756 | ---- | |
757 | ostype: debian | |
758 | arch: amd64 | |
759 | hostname: www | |
760 | memory: 512 | |
761 | swap: 512 | |
762 | net0: bridge=vmbr0,hwaddr=66:64:66:64:64:36,ip=dhcp,name=eth0,type=veth | |
763 | rootfs: local:107/vm-107-disk-1.raw,size=7G | |
764 | ---- | |
765 | ||
766 | Those configuration files are simple text files, and you can edit them | |
767 | using a normal text editor (`vi`, `nano`, ...). This is sometimes | |
768 | useful to do small corrections, but keep in mind that you need to | |
769 | restart the container to apply such changes. | |
770 | ||
771 | For that reason, it is usually better to use the `pct` command to | |
772 | generate and modify those files, or do the whole thing using the GUI. | |
773 | Our toolkit is smart enough to instantaneously apply most changes to | |
774 | running containers. This feature is called "hot plug", and there is no | |
775 | need to restart the container in that case. | |
776 | ||
777 | ||
778 | File Format | |
779 | ~~~~~~~~~~~ | |
780 | ||
781 | Container configuration files use a simple colon separated key/value | |
782 | format. Each line has the following format: | |
783 | ||
784 | ----- | |
785 | # this is a comment | |
786 | OPTION: value | |
787 | ----- | |
788 | ||
789 | Blank lines in those files are ignored, and lines starting with a `#` | |
790 | character are treated as comments and are also ignored. | |
791 | ||
792 | It is possible to add low-level, LXC style configuration directly, for | |
793 | example: | |
794 | ||
795 | lxc.init_cmd: /sbin/my_own_init | |
796 | ||
797 | or | |
798 | ||
799 | lxc.init_cmd = /sbin/my_own_init | |
800 | ||
801 | Those settings are directly passed to the LXC low-level tools. | |
802 | ||
803 | ||
804 | [[pct_snapshots]] | |
805 | Snapshots | |
806 | ~~~~~~~~~ | |
807 | ||
808 | When you create a snapshot, `pct` stores the configuration at snapshot | |
809 | time into a separate snapshot section within the same configuration | |
810 | file. For example, after creating a snapshot called ``testsnapshot'', | |
811 | your configuration file will look like this: | |
812 | ||
813 | .Container configuration with snapshot | |
814 | ---- | |
815 | memory: 512 | |
816 | swap: 512 | |
817 | parent: testsnaphot | |
818 | ... | |
819 | ||
820 | [testsnaphot] | |
821 | memory: 512 | |
822 | swap: 512 | |
823 | snaptime: 1457170803 | |
824 | ... | |
825 | ---- | |
826 | ||
827 | There are a few snapshot related properties like `parent` and | |
828 | `snaptime`. The `parent` property is used to store the parent/child | |
829 | relationship between snapshots. `snaptime` is the snapshot creation | |
830 | time stamp (Unix epoch). | |
831 | ||
832 | ||
833 | [[pct_options]] | |
834 | Options | |
835 | ~~~~~~~ | |
836 | ||
837 | include::pct.conf.5-opts.adoc[] | |
838 | ||
839 | ||
2a11aa70 DM |
840 | Locks |
841 | ----- | |
842 | ||
843 | Container migrations, snapshots and backups (`vzdump`) set a lock to | |
844 | prevent incompatible concurrent actions on the affected container. Sometimes | |
845 | you need to remove such a lock manually (e.g., after a power failure). | |
846 | ||
847 | pct unlock <CTID> | |
848 | ||
849 | CAUTION: Only do that if you are sure the action which set the lock is | |
850 | no longer running. | |
851 | ||
fe57a420 | 852 | |
0c6b782f | 853 | ifdef::manvolnum[] |
3bd9d0cf DM |
854 | |
855 | Files | |
856 | ------ | |
857 | ||
858 | `/etc/pve/lxc/<CTID>.conf`:: | |
859 | ||
860 | Configuration file for the container '<CTID>'. | |
861 | ||
862 | ||
0c6b782f DM |
863 | include::pve-copyright.adoc[] |
864 | endif::manvolnum[] | |
865 | ||
866 | ||
867 | ||
868 | ||
869 | ||
870 | ||
871 |