You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

pct.adoc 28KB

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