X-Git-Url: https://git.proxmox.com/?p=pve-docs.git;a=blobdiff_plain;f=qm.adoc;h=81fd39ec06e3d8c55a5f2716deb0b8ec10de9dbd;hp=a15e0fe3cc99f83623ebdc299edbacbe3436bf09;hb=76937e7d831a0be755a3c67b046594997bd0febb;hpb=53cbac409bd5077aae26c22f51d2af3fb0f87ff8 diff --git a/qm.adoc b/qm.adoc index a15e0fe..81fd39e 100644 --- a/qm.adoc +++ b/qm.adoc @@ -117,11 +117,34 @@ OS Settings [thumbnail="screenshot/gui-create-vm-os.png"] -When creating a VM, setting the proper Operating System(OS) allows {pve} to -optimize some low level parameters. For instance Windows OS expect the BIOS -clock to use the local time, while Unix based OS expect the BIOS clock to have -the UTC time. +When creating a virtual machine (VM), setting the proper Operating System(OS) +allows {pve} to optimize some low level parameters. For instance Windows OS +expect the BIOS clock to use the local time, while Unix based OS expect the +BIOS clock to have the UTC time. +[[qm_system_settings]] +System Settings +~~~~~~~~~~~~~~~ + +On VM creation you can change some basic system components of the new VM. You +can specify which xref:qm_display[display type] you want to use. +[thumbnail="screenshot/gui-create-vm-system.png"] +Additionally, the xref:qm_hard_disk[SCSI controller] can be changed. +If you plan to install the QEMU Guest Agent, or if your selected ISO image +already ships and installs it automatically, you may want to tick the 'Qemu +Agent' box, which lets {pve} know that it can use its features to show some +more information, and complete some actions (for example, shutdown or +snapshots) more intelligently. + +{pve} allows to boot VMs with different firmware and machine types, namely +xref:qm_bios_and_uefi[SeaBIOS and OVMF]. In most cases you want to switch from +the default SeabBIOS to OVMF only if you plan to use +xref:qm_pci_passthrough[PCIe pass through]. A VMs 'Machine Type' defines the +hardware layout of the VM's virtual motherboard. You can choose between the +default https://en.wikipedia.org/wiki/Intel_440FX[Intel 440FX] or the +https://ark.intel.com/content/www/us/en/ark/products/31918/intel-82q35-graphics-and-memory-controller.html[Q35] +chipset, which also provides a virtual PCIe bus, and thus may be desired if +one want's to pass through PCIe hardware. [[qm_hard_disk]] Hard Disk @@ -437,7 +460,7 @@ will allow proper distribution of the VM resources on the host system. This option is also required to hot-plug cores or RAM in a VM. If the NUMA option is used, it is recommended to set the number of sockets to -the number of sockets of the host system. +the number of nodes of the host system. vCPU hot-plug ^^^^^^^^^^^^^ @@ -484,7 +507,7 @@ host. .Fixed Memory Allocation [thumbnail="screenshot/gui-create-vm-memory.png"] -When setting memory and minimum memory to the same amount +ghen setting memory and minimum memory to the same amount {pve} will simply allocate what you specify to your VM. Even when using a fixed memory size, the ballooning device gets added to the @@ -676,8 +699,12 @@ BIOS and UEFI ~~~~~~~~~~~~~ In order to properly emulate a computer, QEMU needs to use a firmware. -By default QEMU uses *SeaBIOS* for this, which is an open-source, x86 BIOS -implementation. SeaBIOS is a good choice for most standard setups. +Which, on common PCs often known as BIOS or (U)EFI, is executed as one of the +first steps when booting a VM. It is responsible for doing basic hardware +initialization and for providing an interface to the firmware and hardware for +the operating system. By default QEMU uses *SeaBIOS* for this, which is an +open-source, x86 BIOS implementation. SeaBIOS is a good choice for most +standard setups. There are, however, some scenarios in which a BIOS is not a good firmware to boot from, e.g. if you want to do VGA passthrough. footnote:[Alex Williamson has a very good blog entry about this. @@ -703,6 +730,29 @@ you need to set the client resolution in the OVMF menu(which you can reach with a press of the ESC button during boot), or you have to choose SPICE as the display type. +[[qm_ivshmem]] +Inter-VM shared memory +~~~~~~~~~~~~~~~~~~~~~~ + +You can add an Inter-VM shared memory device (`ivshmem`), which allows one to +share memory between the host and a guest, or also between multiple guests. + +To add such a device, you can use `qm`: + + qm set -ivshmem size=32,name=foo + +Where the size is in MiB. The file will be located under +`/dev/shm/pve-shm-$name` (the default name is the vmid). + +NOTE: Currently the device will get deleted as soon as any VM using it got +shutdown or stopped. Open connections will still persist, but new connections +to the exact same device cannot be made anymore. + +A use case for such a device is the Looking Glass +footnote:[Looking Glass: https://looking-glass.hostfission.com/] project, +which enables high performance, low-latency display mirroring between +host and guest. + [[qm_startup_and_shutdown]] Automatic Start and Shutdown of Virtual Machines ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -829,7 +879,7 @@ migrate a VM to a totally different storage. You can also change the disk image *Format* if the storage driver supports several formats. + -NOTE: A full clone need to read and copy all VM image data. This is +NOTE: A full clone needs to read and copy all VM image data. This is usually much slower than creating a linked clone. + @@ -840,7 +890,7 @@ never includes any additional snapshots from the original VM. Linked Clone:: -Modern storage drivers supports a way to generate fast linked +Modern storage drivers support a way to generate fast linked clones. Such a clone is a writable copy whose initial contents are the same as the original data. Creating a linked clone is nearly instantaneous, and initially consumes no additional space. @@ -857,8 +907,8 @@ can convert any VM into a read-only <>). Such templates can later be used to create linked clones efficiently. + -NOTE: You cannot delete the original template while linked clones -exists. +NOTE: You cannot delete an original template while linked clones +exist. + It is not possible to change the *Target storage* for linked clones, @@ -869,7 +919,7 @@ The *Target node* option allows you to create the new VM on a different node. The only restriction is that the VM is on shared storage, and that storage is also available on the target node. -To avoid resource conflicts, all network interface MAC addresses gets +To avoid resource conflicts, all network interface MAC addresses get randomized, and we generate a new 'UUID' for the VM BIOS (smbios1) setting. @@ -1030,6 +1080,16 @@ ifndef::wiki[] include::qm-pci-passthrough.adoc[] endif::wiki[] +Hookscripts +----------- + +You can add a hook script to VMs with the config property `hookscript`. + + qm set 100 -hookscript local:snippets/hookscript.pl + +It will be called during various phases of the guests lifetime. +For an example and documentation see the example script under +`/usr/share/pve-docs/examples/guest-example-hookscript.pl`. Managing Virtual Machines with `qm` ------------------------------------