]>
Commit | Line | Data |
---|---|---|
80c0adcb | 1 | [[chapter_virtual_machines]] |
f69cfd23 | 2 | ifdef::manvolnum[] |
b2f242ab DM |
3 | qm(1) |
4 | ===== | |
5f09af76 DM |
5 | :pve-toplevel: |
6 | ||
f69cfd23 DM |
7 | NAME |
8 | ---- | |
9 | ||
10 | qm - Qemu/KVM Virtual Machine Manager | |
11 | ||
12 | ||
49a5e11c | 13 | SYNOPSIS |
f69cfd23 DM |
14 | -------- |
15 | ||
16 | include::qm.1-synopsis.adoc[] | |
17 | ||
18 | DESCRIPTION | |
19 | ----------- | |
20 | endif::manvolnum[] | |
f69cfd23 DM |
21 | ifndef::manvolnum[] |
22 | Qemu/KVM Virtual Machines | |
23 | ========================= | |
5f09af76 | 24 | :pve-toplevel: |
194d2f29 | 25 | endif::manvolnum[] |
5f09af76 | 26 | |
c4cba5d7 EK |
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 | ||
5eba0743 | 32 | Qemu (short form for Quick Emulator) is an open source hypervisor that emulates a |
c4cba5d7 EK |
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 | |
189d3661 | 36 | emulated computer which sees them as if they were real devices. |
c4cba5d7 EK |
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 | |
189d3661 | 41 | will see a real CDROM inserted in a CD drive. |
c4cba5d7 | 42 | |
189d3661 | 43 | Qemu can emulates a great variety of hardware from ARM to Sparc, but {pve} is |
c4cba5d7 EK |
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 | |
9c63b5d9 EK |
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 | ||
c4cba5d7 EK |
56 | Qemu inside {pve} runs as a root process, since this is required to access block |
57 | and PCI devices. | |
58 | ||
5eba0743 | 59 | |
c4cba5d7 EK |
60 | Emulated devices and paravirtualized devices |
61 | -------------------------------------------- | |
62 | ||
189d3661 DC |
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 | |
c4cba5d7 EK |
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 | |
189d3661 DC |
78 | paravirtualized virtio devices, which includes a paravirtualized generic disk |
79 | controller, a paravirtualized network card, a paravirtualized serial port, | |
c4cba5d7 EK |
80 | a paravirtualized SCSI controller, etc ... |
81 | ||
189d3661 DC |
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 | |
c4cba5d7 | 86 | up to three times the throughput of an emulated Intel E1000 network card, as |
189d3661 | 87 | measured with `iperf(1)`. footnote:[See this benchmark on the KVM wiki |
c4cba5d7 EK |
88 | http://www.linux-kvm.org/page/Using_VirtIO_NIC] |
89 | ||
5eba0743 | 90 | |
80c0adcb | 91 | [[qm_virtual_machines_settings]] |
5274ad28 | 92 | Virtual Machines Settings |
c4cba5d7 | 93 | ------------------------- |
80c0adcb | 94 | |
c4cba5d7 EK |
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 | ||
5eba0743 | 99 | |
80c0adcb | 100 | [[qm_general_settings]] |
c4cba5d7 EK |
101 | General Settings |
102 | ~~~~~~~~~~~~~~~~ | |
80c0adcb | 103 | |
b473f999 | 104 | [thumbnail="gui-create-vm-general.png"] |
b16d767f | 105 | |
c4cba5d7 EK |
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 | ||
5eba0743 | 113 | |
80c0adcb | 114 | [[qm_os_settings]] |
c4cba5d7 EK |
115 | OS Settings |
116 | ~~~~~~~~~~~ | |
80c0adcb | 117 | |
b473f999 | 118 | [thumbnail="gui-create-vm-os.png"] |
200114a7 | 119 | |
c4cba5d7 EK |
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 | ||
5eba0743 | 125 | |
80c0adcb | 126 | [[qm_hard_disk]] |
c4cba5d7 EK |
127 | Hard Disk |
128 | ~~~~~~~~~ | |
80c0adcb | 129 | |
2ec49380 | 130 | Qemu can emulate a number of storage controllers: |
c4cba5d7 EK |
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 | ||
b0b6802b EK |
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 | |
f4bfd701 DM |
144 | LSI 53C895A controller. |
145 | + | |
b0b6802b EK |
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 | |
c4cba5d7 | 149 | FreeBSD since 2014. For Windows OSes, you need to provide an extra iso |
b0b6802b EK |
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. | |
c4cba5d7 | 156 | |
b473f999 | 157 | [thumbnail="gui-create-vm-hard-disk.png"] |
c4cba5d7 EK |
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. | |
189d3661 DC |
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 | |
c4cba5d7 | 172 | http://events.linuxfoundation.org/sites/events/files/slides/CloudOpen2013_Khoa_Huynh_v3.pdf] |
189d3661 | 173 | * the *VMware image format* only makes sense if you intend to import/export the |
c4cba5d7 EK |
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 | ||
af9c6de1 | 192 | .IO Thread |
2b6e4b66 EK |
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*. | |
c564fc52 DC |
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 | ||
80c0adcb DM |
199 | |
200 | [[qm_cpu]] | |
34e541c5 EK |
201 | CPU |
202 | ~~~ | |
80c0adcb | 203 | |
b473f999 | 204 | [thumbnail="gui-create-vm-cpu.png"] |
397c74c3 | 205 | |
34e541c5 EK |
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 | |
f4bfd701 DM |
212 | what the license allows you, and increase the number of cores. |
213 | ||
34e541c5 EK |
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 | |
f4bfd701 DM |
237 | as your host system. |
238 | ||
34e541c5 EK |
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, | |
f4bfd701 DM |
244 | but is guaranteed to work everywhere. |
245 | ||
246 | In short, if you care about live migration and moving VMs between nodes, leave | |
34e541c5 EK |
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 | ||
80c0adcb DM |
263 | |
264 | [[qm_memory]] | |
34e541c5 EK |
265 | Memory |
266 | ~~~~~~ | |
80c0adcb | 267 | |
34e541c5 EK |
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 | ||
96124d0f | 272 | .Fixed Memory Allocation |
b473f999 | 273 | [thumbnail="gui-create-vm-memory-fixed.png"] |
96124d0f | 274 | |
34e541c5 EK |
275 | When choosing a *fixed size memory* {pve} will simply allocate what you |
276 | specify to your VM. | |
277 | ||
96124d0f | 278 | .Automatic Memory Allocation |
b473f999 | 279 | [thumbnail="gui-create-vm-memory-dynamic.png", float="left"] |
96124d0f | 280 | |
34e541c5 EK |
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 | |
f4bfd701 DM |
285 | maximum memory specified. |
286 | ||
34e541c5 EK |
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 | ||
c9f6e1a4 EK |
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 | ||
34e541c5 EK |
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 | ||
80c0adcb DM |
315 | |
316 | [[qm_network_device]] | |
1ff7835b EK |
317 | Network Device |
318 | ~~~~~~~~~~~~~~ | |
80c0adcb | 319 | |
b473f999 | 320 | [thumbnail="gui-create-vm-network.png"] |
c24ddb0a | 321 | |
1ff7835b EK |
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 | ||
af9c6de1 EK |
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 | |
1ff7835b | 353 | If you are using the VirtIO driver, you can optionally activate the |
af9c6de1 | 354 | *Multiqueue* option. This option allows the guest OS to process networking |
1ff7835b EK |
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 | |
af9c6de1 | 365 | When using Multiqueue, it is recommended to set it to a value equal |
1ff7835b EK |
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 | ||
af9c6de1 | 374 | You should note that setting the Multiqueue parameter to a value greater |
1ff7835b EK |
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 | ||
80c0adcb | 380 | |
685cc8e0 DC |
381 | USB Passthrough |
382 | ~~~~~~~~~~~~~~~ | |
80c0adcb | 383 | |
685cc8e0 DC |
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 | ||
80c0adcb DM |
416 | |
417 | [[qm_bios_and_uefi]] | |
076d60ae DC |
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 | ||
288e3f46 EK |
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 | ||
4dbeb548 DM |
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: | |
288e3f46 EK |
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. | |
076d60ae | 486 | |
c73c190f DM |
487 | |
488 | [[qm_migration]] | |
489 | Migration | |
490 | --------- | |
491 | ||
e4bcef0a DM |
492 | [thumbnail="gui-qemu-migrate.png"] |
493 | ||
c73c190f DM |
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 | ||
8c1189b6 | 507 | Managing Virtual Machines with `qm` |
dd042288 | 508 | ------------------------------------ |
f69cfd23 | 509 | |
dd042288 | 510 | qm is the tool to manage Qemu/Kvm virtual machines on {pve}. You can |
f69cfd23 DM |
511 | create and destroy virtual machines, and control execution |
512 | (start/stop/suspend/resume). Besides that, you can use qm to set | |
513 | parameters in the associated config file. It is also possible to | |
514 | create and delete virtual disks. | |
515 | ||
dd042288 EK |
516 | CLI Usage Examples |
517 | ~~~~~~~~~~~~~~~~~~ | |
518 | ||
519 | Create a new VM with 4 GB IDE disk. | |
520 | ||
521 | qm create 300 -ide0 4 -net0 e1000 -cdrom proxmox-mailgateway_2.1.iso | |
522 | ||
523 | Start the new VM | |
524 | ||
525 | qm start 300 | |
526 | ||
527 | Send a shutdown request, then wait until the VM is stopped. | |
528 | ||
529 | qm shutdown 300 && qm wait 300 | |
530 | ||
531 | Same as above, but only wait for 40 seconds. | |
532 | ||
533 | qm shutdown 300 && qm wait 300 -timeout 40 | |
534 | ||
f0a8ab95 DM |
535 | |
536 | [[qm_configuration]] | |
f69cfd23 DM |
537 | Configuration |
538 | ------------- | |
539 | ||
f0a8ab95 DM |
540 | VM configuration files are stored inside the Proxmox cluster file |
541 | system, and can be accessed at `/etc/pve/qemu-server/<VMID>.conf`. | |
542 | Like other files stored inside `/etc/pve/`, they get automatically | |
543 | replicated to all other cluster nodes. | |
f69cfd23 | 544 | |
f0a8ab95 DM |
545 | NOTE: VMIDs < 100 are reserved for internal purposes, and VMIDs need to be |
546 | unique cluster wide. | |
547 | ||
548 | .Example VM Configuration | |
549 | ---- | |
550 | cores: 1 | |
551 | sockets: 1 | |
552 | memory: 512 | |
553 | name: webmail | |
554 | ostype: l26 | |
555 | bootdisk: virtio0 | |
556 | net0: e1000=EE:D2:28:5F:B6:3E,bridge=vmbr0 | |
557 | virtio0: local:vm-100-disk-1,size=32G | |
558 | ---- | |
559 | ||
560 | Those configuration files are simple text files, and you can edit them | |
561 | using a normal text editor (`vi`, `nano`, ...). This is sometimes | |
562 | useful to do small corrections, but keep in mind that you need to | |
563 | restart the VM to apply such changes. | |
564 | ||
565 | For that reason, it is usually better to use the `qm` command to | |
566 | generate and modify those files, or do the whole thing using the GUI. | |
567 | Our toolkit is smart enough to instantaneously apply most changes to | |
568 | running VM. This feature is called "hot plug", and there is no | |
569 | need to restart the VM in that case. | |
570 | ||
571 | ||
572 | File Format | |
573 | ~~~~~~~~~~~ | |
574 | ||
575 | VM configuration files use a simple colon separated key/value | |
576 | format. Each line has the following format: | |
577 | ||
578 | ----- | |
579 | # this is a comment | |
580 | OPTION: value | |
581 | ----- | |
582 | ||
583 | Blank lines in those files are ignored, and lines starting with a `#` | |
584 | character are treated as comments and are also ignored. | |
585 | ||
586 | ||
587 | [[qm_snapshots]] | |
588 | Snapshots | |
589 | ~~~~~~~~~ | |
590 | ||
591 | When you create a snapshot, `qm` stores the configuration at snapshot | |
592 | time into a separate snapshot section within the same configuration | |
593 | file. For example, after creating a snapshot called ``testsnapshot'', | |
594 | your configuration file will look like this: | |
595 | ||
596 | .VM configuration with snapshot | |
597 | ---- | |
598 | memory: 512 | |
599 | swap: 512 | |
600 | parent: testsnaphot | |
601 | ... | |
602 | ||
603 | [testsnaphot] | |
604 | memory: 512 | |
605 | swap: 512 | |
606 | snaptime: 1457170803 | |
607 | ... | |
608 | ---- | |
609 | ||
610 | There are a few snapshot related properties like `parent` and | |
611 | `snaptime`. The `parent` property is used to store the parent/child | |
612 | relationship between snapshots. `snaptime` is the snapshot creation | |
613 | time stamp (Unix epoch). | |
f69cfd23 | 614 | |
f69cfd23 | 615 | |
80c0adcb | 616 | [[qm_options]] |
a7f36905 DM |
617 | Options |
618 | ~~~~~~~ | |
619 | ||
620 | include::qm.conf.5-opts.adoc[] | |
621 | ||
f69cfd23 DM |
622 | |
623 | Locks | |
624 | ----- | |
625 | ||
0bcc62dd DM |
626 | Online migrations, snapshots and backups (`vzdump`) set a lock to |
627 | prevent incompatible concurrent actions on the affected VMs. Sometimes | |
628 | you need to remove such a lock manually (e.g., after a power failure). | |
f69cfd23 DM |
629 | |
630 | qm unlock <vmid> | |
631 | ||
0bcc62dd DM |
632 | CAUTION: Only do that if you are sure the action which set the lock is |
633 | no longer running. | |
634 | ||
f69cfd23 DM |
635 | |
636 | ifdef::manvolnum[] | |
704f19fb DM |
637 | |
638 | Files | |
639 | ------ | |
640 | ||
641 | `/etc/pve/qemu-server/<VMID>.conf`:: | |
642 | ||
643 | Configuration file for the VM '<VMID>'. | |
644 | ||
645 | ||
f69cfd23 DM |
646 | include::pve-copyright.adoc[] |
647 | endif::manvolnum[] |