qm.adoc: rework clone/template sections
[pve-docs.git] / qm.adoc
1 [[chapter_virtual_machines]]
2 ifdef::manvolnum[]
3 qm(1)
4 =====
5 :pve-toplevel:
6
7 NAME
8 ----
9
10 qm - Qemu/KVM Virtual Machine Manager
11
12
13 SYNOPSIS
14 --------
15
16 include::qm.1-synopsis.adoc[]
17
18 DESCRIPTION
19 -----------
20 endif::manvolnum[]
21 ifndef::manvolnum[]
22 Qemu/KVM Virtual Machines
23 =========================
24 :pve-toplevel:
25 endif::manvolnum[]
26
27 // deprecates
28 // http://pve.proxmox.com/wiki/Container_and_Full_Virtualization
29 // http://pve.proxmox.com/wiki/KVM
30 // http://pve.proxmox.com/wiki/Qemu_Server
31
32 Qemu (short form for Quick Emulator) is an open source hypervisor that emulates a
33 physical computer. From the perspective of the host system where Qemu is
34 running, Qemu is a user program which has access to a number of local resources
35 like partitions, files, network cards which are then passed to an
36 emulated computer which sees them as if they were real devices.
37
38 A guest operating system running in the emulated computer accesses these
39 devices, and runs as it were running on real hardware. For instance you can pass
40 an iso image as a parameter to Qemu, and the OS running in the emulated computer
41 will see a real CDROM inserted in a CD drive.
42
43 Qemu can emulates a great variety of hardware from ARM to Sparc, but {pve} is
44 only concerned with 32 and 64 bits PC clone emulation, since it represents the
45 overwhelming majority of server hardware. The emulation of PC clones is also one
46 of the fastest due to the availability of processor extensions which greatly
47 speed up Qemu when the emulated architecture is the same as the host
48 architecture.
49
50 NOTE: You may sometimes encounter the term _KVM_ (Kernel-based Virtual Machine).
51 It means that Qemu is running with the support of the virtualization processor
52 extensions, via the Linux kvm module. In the context of {pve} _Qemu_ and
53 _KVM_ can be use interchangeably as Qemu in {pve} will always try to load the kvm
54 module.
55
56 Qemu inside {pve} runs as a root process, since this is required to access block
57 and PCI devices.
58
59
60 Emulated devices and paravirtualized devices
61 --------------------------------------------
62
63 The PC hardware emulated by Qemu includes a mainboard, network controllers,
64 scsi, ide and sata controllers, serial ports (the complete list can be seen in
65 the `kvm(1)` man page) all of them emulated in software. All these devices
66 are the exact software equivalent of existing hardware devices, and if the OS
67 running in the guest has the proper drivers it will use the devices as if it
68 were running on real hardware. This allows Qemu to runs _unmodified_ operating
69 systems.
70
71 This however has a performance cost, as running in software what was meant to
72 run in hardware involves a lot of extra work for the host CPU. To mitigate this,
73 Qemu can present to the guest operating system _paravirtualized devices_, where
74 the guest OS recognizes it is running inside Qemu and cooperates with the
75 hypervisor.
76
77 Qemu relies on the virtio virtualization standard, and is thus able to presente
78 paravirtualized virtio devices, which includes a paravirtualized generic disk
79 controller, a paravirtualized network card, a paravirtualized serial port,
80 a paravirtualized SCSI controller, etc ...
81
82 It is highly recommended to use the virtio devices whenever you can, as they
83 provide a big performance improvement. Using  the virtio generic disk controller
84 versus an emulated IDE controller will double the sequential write throughput,
85 as measured with `bonnie++(8)`. Using the virtio network interface can deliver
86 up to three times the throughput of an emulated Intel E1000 network card, as
87 measured with `iperf(1)`. footnote:[See this benchmark on the KVM wiki
88 http://www.linux-kvm.org/page/Using_VirtIO_NIC]
89
90
91 [[qm_virtual_machines_settings]]
92 Virtual Machines Settings
93 -------------------------
94
95 Generally speaking {pve} tries to choose sane defaults for virtual machines
96 (VM). Make sure you understand the meaning of the settings you change, as it
97 could incur a performance slowdown, or putting your data at risk.
98
99
100 [[qm_general_settings]]
101 General Settings
102 ~~~~~~~~~~~~~~~~
103
104 [thumbnail="gui-create-vm-general.png"]
105
106 General settings of a VM include
107
108 * the *Node* : the physical server on which the VM will run
109 * the *VM ID*: a unique number in this {pve} installation used to identify your VM
110 * *Name*: a free form text string you can use to describe the VM
111 * *Resource Pool*: a logical group of VMs
112
113
114 [[qm_os_settings]]
115 OS Settings
116 ~~~~~~~~~~~
117
118 [thumbnail="gui-create-vm-os.png"]
119
120 When creating a VM, setting the proper Operating System(OS) allows {pve} to
121 optimize some low level parameters. For instance Windows OS expect the BIOS
122 clock to use the local time, while Unix based OS expect the BIOS clock to have
123 the UTC time.
124
125
126 [[qm_hard_disk]]
127 Hard Disk
128 ~~~~~~~~~
129
130 Qemu can emulate a number of storage controllers:
131
132 * the *IDE* controller, has a design which goes back to the 1984 PC/AT disk
133 controller. Even if this controller has been superseded by more more designs,
134 each and every OS you can think has support for it, making it a great choice
135 if you want to run an OS released before 2003. You can connect up to 4 devices
136 on this controller.
137
138 * the *SATA* (Serial ATA) controller, dating from 2003, has a more modern
139 design, allowing higher throughput and a greater number of devices to be
140 connected. You can connect up to 6 devices on this controller.
141
142 * the *SCSI* controller, designed in 1985, is commonly found on server grade
143 hardware, and can connect up to 14 storage devices. {pve} emulates by default a
144 LSI 53C895A controller.
145 +
146 A SCSI controller of type _Virtio_ is the recommended setting if you aim for
147 performance and is automatically selected for newly created Linux VMs since
148 {pve} 4.3. Linux distributions have support for this controller since 2012, and
149 FreeBSD since 2014. For Windows OSes, you need to provide an extra iso
150 containing the drivers during the installation.
151 // https://pve.proxmox.com/wiki/Paravirtualized_Block_Drivers_for_Windows#During_windows_installation.
152
153 * The *Virtio* controller, also called virtio-blk to distinguish from
154 the Virtio SCSI controller, is an older type of paravirtualized controller
155 which has been superseded in features by the Virtio SCSI Controller.
156
157 [thumbnail="gui-create-vm-hard-disk.png"]
158 On each controller you attach a number of emulated hard disks, which are backed
159 by a file or a block device residing in the configured storage. The choice of
160 a storage type will determine the format of the hard disk image. Storages which
161 present block devices (LVM, ZFS, Ceph) will require the *raw disk image format*,
162 whereas files based storages (Ext4, NFS, GlusterFS) will let you to choose
163 either the *raw disk image format* or the *QEMU image format*.
164
165  * the *QEMU image format* is a copy on write format which allows snapshots, and
166   thin provisioning of the disk image.
167  * the *raw disk image* is a bit-to-bit image of a hard disk, similar to what
168  you would get when executing the `dd` command on a block device in Linux. This
169  format do not support thin provisioning or snapshotting by itself, requiring
170  cooperation from the storage layer for these tasks. It is however 10% faster
171   than the *QEMU image format*. footnote:[See this benchmark for details
172  http://events.linuxfoundation.org/sites/events/files/slides/CloudOpen2013_Khoa_Huynh_v3.pdf]
173  * the *VMware image format* only makes sense if you intend to import/export the
174  disk image to other hypervisors.
175
176 Setting the *Cache* mode of the hard drive will impact how the host system will
177 notify the guest systems of block write completions. The *No cache* default
178 means that the guest system will be notified that a write is complete when each
179 block reaches the physical storage write queue, ignoring the host page cache.
180 This provides a good balance between safety and speed.
181
182 If you want the {pve} backup manager to skip a disk when doing a backup of a VM,
183 you can set the *No backup* option on that disk.
184
185 If your storage supports _thin provisioning_ (see the storage chapter in the
186 {pve} guide), and your VM has a *SCSI* controller you can activate the *Discard*
187 option on the hard disks connected to that controller. With *Discard* enabled,
188 when the filesystem of a VM marks blocks as unused after removing files, the
189 emulated SCSI controller will relay this information to the storage, which will
190 then shrink the disk image accordingly.
191
192 .IO Thread
193 The option *IO Thread* can only be enabled when using a disk with the *VirtIO* controller,
194 or with the *SCSI* controller, when the emulated controller type is  *VirtIO SCSI*.
195 With this enabled, Qemu uses one thread per disk, instead of one thread for all,
196 so it should increase performance when using multiple disks.
197 Note that backups do not currently work with *IO Thread* enabled.
198
199
200 [[qm_cpu]]
201 CPU
202 ~~~
203
204 [thumbnail="gui-create-vm-cpu.png"]
205
206 A *CPU socket* is a physical slot on a PC motherboard where you can plug a CPU.
207 This CPU can then contain one or many *cores*, which are independent
208 processing units. Whether you have a single CPU socket with 4 cores, or two CPU
209 sockets with two cores is mostly irrelevant from a performance point of view.
210 However some software is licensed depending on the number of sockets you have in
211 your machine, in that case it makes sense to set the number of of sockets to
212 what the license allows you, and increase the number of cores.
213
214 Increasing the number of virtual cpus (cores and sockets) will usually provide a
215 performance improvement though that is heavily dependent on the use of the VM.
216 Multithreaded applications will of course benefit from a large number of
217 virtual cpus, as for each virtual cpu you add, Qemu will create a new thread of
218 execution on the host system. If you're not sure about the workload of your VM,
219 it is usually a safe bet to set the number of *Total cores* to 2.
220
221 NOTE: It is perfectly safe to set the _overall_ number of total cores in all
222 your VMs to be greater than the number of of cores you have on your server (ie.
223 4 VMs with each 4 Total cores running in a 8 core machine is OK) In that case
224 the host system will balance the Qemu execution threads between your server
225 cores just like if you were running a standard multithreaded application.
226 However {pve} will prevent you to allocate on a _single_ machine more vcpus than
227 physically available, as this will only bring the performance down due to the
228 cost of context switches.
229
230 Qemu can emulate a number different of *CPU types* from 486 to the latest Xeon
231 processors. Each new processor generation adds new features, like hardware
232 assisted 3d rendering, random number generation, memory protection, etc ...
233 Usually you should select for your VM a processor type which closely matches the
234 CPU of the host system, as it means that the host CPU features (also called _CPU
235 flags_ ) will be available in your VMs. If you want an exact match, you can set
236 the CPU type to *host* in which case the VM will have exactly the same CPU flags
237 as your host system.
238
239 This has a downside though. If you want to do a live migration of VMs between
240 different hosts, your VM might end up on a new system with a different CPU type.
241 If the CPU flags passed to the guest are missing, the qemu process will stop. To
242 remedy this Qemu has also its own CPU type *kvm64*, that {pve} uses by defaults.
243 kvm64 is a Pentium 4 look a like CPU type, which has a reduced CPU flags set,
244 but is guaranteed to work everywhere.
245
246 In short, if you care about live migration and moving VMs between nodes, leave
247 the kvm64 default. If you don’t care about live migration, set the CPU type to
248 host, as in theory this will give your guests maximum performance.
249
250 You can also optionally emulate a *NUMA* architecture in your VMs. The basics of
251 the NUMA architecture mean that instead of having a global memory pool available
252 to all your cores, the memory is spread into local banks close to each socket.
253 This can bring speed improvements as the memory bus is not a bottleneck
254 anymore. If your system has a NUMA architecture footnote:[if the command
255 `numactl --hardware | grep available` returns more than one node, then your host
256 system has a NUMA architecture] we recommend to activate the option, as this
257 will allow proper distribution of the VM resources on the host system. This
258 option is also required in {pve} to allow hotplugging of cores and RAM to a VM.
259
260 If the NUMA option is used, it is recommended to set the number of sockets to
261 the number of sockets of the host system.
262
263
264 [[qm_memory]]
265 Memory
266 ~~~~~~
267
268 For each VM you have the option to set a fixed size memory or asking
269 {pve} to dynamically allocate memory based on the current RAM usage of the
270 host. 
271
272 .Fixed Memory Allocation
273 [thumbnail="gui-create-vm-memory-fixed.png"]
274
275 When choosing a *fixed size memory* {pve} will simply allocate what you
276 specify to your VM.
277
278 .Automatic Memory Allocation
279 [thumbnail="gui-create-vm-memory-dynamic.png", float="left"]
280
281 // see autoballoon() in pvestatd.pm
282 When choosing to *automatically allocate memory*, {pve} will make sure that the
283 minimum amount you specified is always available to the VM, and if RAM usage on
284 the host is below 80%, will dynamically add memory to the guest up to the
285 maximum memory specified.
286
287 When the host is becoming short on RAM, the VM will then release some memory
288 back to the host, swapping running processes if needed and starting the oom
289 killer in last resort. The passing around of memory between host and guest is
290 done via a special `balloon` kernel driver running inside the guest, which will
291 grab or release memory pages from the host.
292 footnote:[A good explanation of the inner workings of the balloon driver can be found here https://rwmj.wordpress.com/2010/07/17/virtio-balloon/]
293
294 When multiple VMs use the autoallocate facility, it is possible to set a
295 *Shares* coefficient which indicates the relative amount of the free host memory
296 that each VM shoud take. Suppose for instance you have four VMs, three of them
297 running a HTTP server and the last one is a database server. To cache more
298 database blocks in the database server RAM, you would like to prioritize the
299 database VM when spare RAM is available. For this you assign a Shares property
300 of 3000 to the database VM, leaving the other VMs to the Shares default setting
301 of 1000. The host server has 32GB of RAM, and is curring using 16GB, leaving 32
302 * 80/100 - 16 = 9GB RAM to be allocated to the VMs. The database VM will get 9 *
303 3000 / (3000 + 1000 + 1000 + 1000) = 4.5 GB extra RAM and each HTTP server will
304 get 1/5 GB.
305
306 All Linux distributions released after 2010 have the balloon kernel driver
307 included. For Windows OSes, the balloon driver needs to be added manually and can
308 incur a slowdown of the guest, so we don't recommend using it on critical
309 systems. 
310 // see https://forum.proxmox.com/threads/solved-hyper-threading-vs-no-hyper-threading-fixed-vs-variable-memory.20265/
311
312 When allocating RAMs to your VMs, a good rule of thumb is always to leave 1GB
313 of RAM available to the host.
314
315
316 [[qm_network_device]]
317 Network Device
318 ~~~~~~~~~~~~~~
319
320 [thumbnail="gui-create-vm-network.png"]
321
322 Each VM can have many _Network interface controllers_ (NIC), of four different
323 types:
324
325  * *Intel E1000* is the default, and emulates an Intel Gigabit network card.
326  * the *VirtIO* paravirtualized NIC should be used if you aim for maximum
327 performance. Like all VirtIO devices, the guest OS should have the proper driver
328 installed.
329  * the *Realtek 8139* emulates an older 100 MB/s network card, and should
330 only be used when emulating older operating systems ( released before 2002 ) 
331  * the *vmxnet3* is another paravirtualized device, which should only be used
332 when importing a VM from another hypervisor.
333
334 {pve} will generate for each NIC a random *MAC address*, so that your VM is
335 addressable on Ethernet networks.
336
337 The NIC you added to the VM can follow one of two differents models:
338
339  * in the default *Bridged mode* each virtual NIC is backed on the host by a
340 _tap device_, ( a software loopback device simulating an Ethernet NIC ). This
341 tap device is added to a bridge, by default vmbr0 in {pve}. In this mode, VMs
342 have direct access to the Ethernet LAN on which the host is located.
343  * in the alternative *NAT mode*, each virtual NIC will only communicate with
344 the Qemu user networking stack, where a builting router and DHCP server can
345 provide network access. This built-in DHCP will serve adresses in the private
346 10.0.2.0/24 range. The NAT mode is much slower than the bridged mode, and
347 should only be used for testing.
348
349 You can also skip adding a network device when creating a VM by selecting *No
350 network device*.
351
352 .Multiqueue
353 If you are using the VirtIO driver, you can optionally activate the
354 *Multiqueue* option. This option allows the guest OS to process networking
355 packets using multiple virtual CPUs, providing an increase in the total number
356 of packets transfered.
357
358 //http://blog.vmsplice.net/2011/09/qemu-internals-vhost-architecture.html
359 When using the VirtIO driver with {pve}, each NIC network queue is passed to the
360 host kernel, where the queue will be processed by a kernel thread spawn by the
361 vhost driver. With this option activated, it is possible to pass _multiple_
362 network queues to the host kernel for each NIC.
363
364 //https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Virtualization_Tuning_and_Optimization_Guide/sect-Virtualization_Tuning_Optimization_Guide-Networking-Techniques.html#sect-Virtualization_Tuning_Optimization_Guide-Networking-Multi-queue_virtio-net
365 When using Multiqueue, it is recommended to set it to a value equal
366 to the number of Total Cores of your guest. You also need to set in
367 the VM the number of multi-purpose channels on each VirtIO NIC with the ethtool
368 command: 
369
370 `ethtool -L eth0 combined X`
371
372 where X is the number of the number of vcpus of the VM.
373
374 You should note that setting the Multiqueue parameter to a value greater
375 than one will increase the CPU load on the host and guest systems as the
376 traffic increases. We recommend to set this option only when the VM has to
377 process a great number of incoming connections, such as when the VM is running
378 as a router, reverse proxy or a busy HTTP server doing long polling.
379
380
381 USB Passthrough
382 ~~~~~~~~~~~~~~~
383
384 There are two different types of USB passthrough devices:
385
386 * Host USB passtrough
387 * SPICE USB passthrough
388
389 Host USB passthrough works by giving a VM a USB device of the host.
390 This can either be done via the vendor- and product-id, or
391 via the host bus and port.
392
393 The vendor/product-id looks like this: *0123:abcd*,
394 where *0123* is the id of the vendor, and *abcd* is the id
395 of the product, meaning two pieces of the same usb device
396 have the same id.
397
398 The bus/port looks like this: *1-2.3.4*, where *1* is the bus
399 and *2.3.4* is the port path. This represents the physical
400 ports of your host (depending of the internal order of the
401 usb controllers).
402
403 If a device is present in a VM configuration when the VM starts up,
404 but the device is not present in the host, the VM can boot without problems.
405 As soon as the device/port ist available in the host, it gets passed through.
406
407 WARNING: Using this kind of USB passthrough, means that you cannot move
408 a VM online to another host, since the hardware is only available
409 on the host the VM is currently residing.
410
411 The second type of passthrough is SPICE USB passthrough. This is useful
412 if you use a SPICE client which supports it. If you add a SPICE USB port
413 to your VM, you can passthrough a USB device from where your SPICE client is,
414 directly to the VM (for example an input device or hardware dongle).
415
416
417 [[qm_bios_and_uefi]]
418 BIOS and UEFI
419 ~~~~~~~~~~~~~
420
421 In order to properly emulate a computer, QEMU needs to use a firmware.
422 By default QEMU uses *SeaBIOS* for this, which is an open-source, x86 BIOS
423 implementation. SeaBIOS is a good choice for most standard setups.
424
425 There are, however, some scenarios in which a BIOS is not a good firmware
426 to boot from, e.g. if you want to do VGA passthrough. footnote:[Alex Williamson has a very good blog entry about this.
427 http://vfio.blogspot.co.at/2014/08/primary-graphics-assignment-without-vga.html]
428 In such cases, you should rather use *OVMF*, which is an open-source UEFI implemenation. footnote:[See the OVMF Project http://www.tianocore.org/ovmf/]
429
430 If you want to use OVMF, there are several things to consider:
431
432 In order to save things like the *boot order*, there needs to be an EFI Disk.
433 This disk will be included in backups and snapshots, and there can only be one.
434
435 You can create such a disk with the following command:
436
437  qm set <vmid> -efidisk0 <storage>:1,format=<format>
438
439 Where *<storage>* is the storage where you want to have the disk, and
440 *<format>* is a format which the storage supports. Alternatively, you can
441 create such a disk through the web interface with 'Add' -> 'EFI Disk' in the
442 hardware section of a VM.
443
444 When using OVMF with a virtual display (without VGA passthrough),
445 you need to set the client resolution in the OVMF menu(which you can reach
446 with a press of the ESC button during boot), or you have to choose
447 SPICE as the display type.
448
449 [[qm_startup_and_shutdown]]
450 Automatic Start and Shutdown of Virtual Machines
451 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
452
453 After creating your VMs, you probably want them to start automatically
454 when the host system boots. For this you need to select the option 'Start at
455 boot' from the 'Options' Tab of your VM in the web interface, or set it with
456 the following command:
457
458  qm set <vmid> -onboot 1
459
460 .Start and Shutdown Order
461
462 [thumbnail="gui-qemu-edit-start-order.png"]
463
464 In some case you want to be able to fine tune the boot order of your
465 VMs, for instance if one of your VM is providing firewalling or DHCP
466 to other guest systems.  For this you can use the following
467 parameters:
468
469 * *Start/Shutdown order*: Defines the start order priority. E.g. set it to 1 if
470 you want the VM to be the first to be started. (We use the reverse startup
471 order for shutdown, so a machine with a start order of 1 would be the last to
472 be shut down)
473 * *Startup delay*: Defines the interval between this VM start and subsequent
474 VMs starts . E.g. set it to 240 if you want to wait 240 seconds before starting
475 other VMs.
476 * *Shutdown timeout*: Defines the duration in seconds {pve} should wait
477 for the VM to be offline after issuing a shutdown command.
478 By default this value is set to 60, which means that {pve} will issue a
479 shutdown request, wait 60s for the machine to be offline, and if after 60s
480 the machine is still online will notify that the shutdown action failed.
481
482 Please note that machines without a Start/Shutdown order parameter will always
483 start after those where the parameter is set, and this parameter only
484 makes sense between the machines running locally on a host, and not
485 cluster-wide.
486
487
488 [[qm_migration]]
489 Migration
490 ---------
491
492 [thumbnail="gui-qemu-migrate.png"]
493
494 If you have a cluster, you can migrate your VM to another host with
495
496  qm migrate <vmid> <target>
497
498 When your VM is running and it has no local resources defined (such as disks
499 on local storage, passed through devices, etc.) you can initiate a live
500 migration with the -online flag.
501
502 If you have local resources, you can still offline migrate your VMs,
503 as long as all disk are on storages, which are defined on both hosts.
504 Then the migration will copy the disk over the network to the target host.
505
506
507 VM Templates, Copies and Clones
508 -------------------------------
509
510 [thumbnail="gui-qemu-full-clone.png"]
511
512 VM installation is usually done using an installation media (CD-ROM)
513 from the operation system vendor. Depending on the OS, this can be a
514 time consuming task one might want to avoid.
515
516 An easy way to deploy many VMs of the same type is to copy an existing
517 VM. We use the term 'clone' for such copies, and distinguish between
518 'linked' and 'full' clones.
519
520 Full Clone::
521
522 The result of such copy is an independent VM. The
523 new VM does not share any storage resources with the original.
524 +
525
526 It is possible to select a *Target Storage*, so one can use this to
527 migrate a VM to a totally different storage. You can also change the
528 disk image *Format* if the storage driver supports several formats.
529 +
530
531 NOTE: A full clone need to read and copy all VM image data. This is
532 usually much slower than creating a linked clone.
533 +
534
535 Some storage types allows to copy a specific *Snapshot*, which
536 defaults to the 'current' VM data. This also means that the final copy
537 never includes any additional snapshots from the original VM.
538
539
540 Linked Clone::
541
542 Modern storage drivers supports a way to generate fast linked
543 clones. Such a clone is a writable copy whose initial contents are the
544 same as the original data. Creating a linked clone is nearly
545 instantaneous, and initially consumes no additional space.
546 +
547
548 They are called 'linked' because the new image still refers to the
549 original. Unmodified data blocks are read from the original image, but
550 modification are written (and afterwards read) from a new
551 location. This technique is called 'Copy-on-write'.
552 +
553
554 This requires that the original volume is read-only. With {pve} one
555 can convert any VM into a read-only <<qm_templates, Template>>). Such
556 templates can later be used to create linked clones efficiently.
557 +
558
559 NOTE: You cannot delete the original template while linked clones
560 exists.
561 +
562
563 It is not possible to change the *Target storage* for linked clones,
564 because this is a storage internal feature.
565
566
567 The *Target node* option allows you to create the new VM on a
568 different node. The only restriction is that the VM is on shared
569 storage, and that storage is also available on the target node.
570
571 To avoid resource conflicts, all network interface MAC addresses gets
572 randomized, and we generate a new 'UUID' for the VM BIOS (smbios1)
573 setting.
574
575
576 [[qm_templates]]
577 Virtual Machine Templates
578 -------------------------
579
580 One can convert a VM into a Template. Such templates are read-only,
581 and you can use them to create linked clones.
582
583 NOTE: It is not possible to start templates, because this would modify
584 the disk images. If you want to change the template, create a linked
585 clone and modify that.
586
587
588 Managing Virtual Machines with `qm`
589 ------------------------------------
590
591 qm is the tool to manage Qemu/Kvm virtual machines on {pve}. You can
592 create and destroy virtual machines, and control execution
593 (start/stop/suspend/resume). Besides that, you can use qm to set
594 parameters in the associated config file. It is also possible to
595 create and delete virtual disks.
596
597 CLI Usage Examples
598 ~~~~~~~~~~~~~~~~~~
599
600 Create a new VM with 4 GB IDE disk.
601
602  qm create 300 -ide0 4 -net0 e1000 -cdrom proxmox-mailgateway_2.1.iso
603
604 Start the new VM
605
606  qm start 300
607
608 Send a shutdown request, then wait until the VM is stopped.
609
610  qm shutdown 300 && qm wait 300
611
612 Same as above, but only wait for 40 seconds.
613
614  qm shutdown 300 && qm wait 300 -timeout 40
615
616
617 [[qm_configuration]]
618 Configuration
619 -------------
620
621 VM configuration files are stored inside the Proxmox cluster file
622 system, and can be accessed at `/etc/pve/qemu-server/<VMID>.conf`.
623 Like other files stored inside `/etc/pve/`, they get automatically
624 replicated to all other cluster nodes.
625
626 NOTE: VMIDs < 100 are reserved for internal purposes, and VMIDs need to be
627 unique cluster wide.
628
629 .Example VM Configuration
630 ----
631 cores: 1
632 sockets: 1
633 memory: 512
634 name: webmail
635 ostype: l26
636 bootdisk: virtio0
637 net0: e1000=EE:D2:28:5F:B6:3E,bridge=vmbr0
638 virtio0: local:vm-100-disk-1,size=32G
639 ----
640
641 Those configuration files are simple text files, and you can edit them
642 using a normal text editor (`vi`, `nano`, ...). This is sometimes
643 useful to do small corrections, but keep in mind that you need to
644 restart the VM to apply such changes.
645
646 For that reason, it is usually better to use the `qm` command to
647 generate and modify those files, or do the whole thing using the GUI.
648 Our toolkit is smart enough to instantaneously apply most changes to
649 running VM. This feature is called "hot plug", and there is no
650 need to restart the VM in that case.
651
652
653 File Format
654 ~~~~~~~~~~~
655
656 VM configuration files use a simple colon separated key/value
657 format. Each line has the following format:
658
659 -----
660 # this is a comment
661 OPTION: value
662 -----
663
664 Blank lines in those files are ignored, and lines starting with a `#`
665 character are treated as comments and are also ignored.
666
667
668 [[qm_snapshots]]
669 Snapshots
670 ~~~~~~~~~
671
672 When you create a snapshot, `qm` stores the configuration at snapshot
673 time into a separate snapshot section within the same configuration
674 file. For example, after creating a snapshot called ``testsnapshot'',
675 your configuration file will look like this:
676
677 .VM configuration with snapshot
678 ----
679 memory: 512
680 swap: 512
681 parent: testsnaphot
682 ...
683
684 [testsnaphot]
685 memory: 512
686 swap: 512
687 snaptime: 1457170803
688 ...
689 ----
690
691 There are a few snapshot related properties like `parent` and
692 `snaptime`. The `parent` property is used to store the parent/child
693 relationship between snapshots. `snaptime` is the snapshot creation
694 time stamp (Unix epoch).
695
696
697 [[qm_options]]
698 Options
699 ~~~~~~~
700
701 include::qm.conf.5-opts.adoc[]
702
703
704 Locks
705 -----
706
707 Online migrations, snapshots and backups (`vzdump`) set a lock to
708 prevent incompatible concurrent actions on the affected VMs. Sometimes
709 you need to remove such a lock manually (e.g., after a power failure).
710
711  qm unlock <vmid>
712
713 CAUTION: Only do that if you are sure the action which set the lock is
714 no longer running.
715
716
717 ifdef::manvolnum[]
718
719 Files
720 ------
721
722 `/etc/pve/qemu-server/<VMID>.conf`::
723
724 Configuration file for the VM '<VMID>'.
725
726
727 include::pve-copyright.adoc[]
728 endif::manvolnum[]