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