ifdef::manvolnum[]
qm(1)
=====
-include::attributes.txt[]
:pve-toplevel:
NAME
ifndef::manvolnum[]
Qemu/KVM Virtual Machines
=========================
-include::attributes.txt[]
:pve-toplevel:
endif::manvolnum[]
[[qm_virtual_machines_settings]]
-Virtual Machines settings
+Virtual Machines Settings
-------------------------
Generally speaking {pve} tries to choose sane defaults for virtual machines
General Settings
~~~~~~~~~~~~~~~~
+[thumbnail="gui-create-vm-general.png"]
+
General settings of a VM include
* the *Node* : the physical server on which the VM will run
OS Settings
~~~~~~~~~~~
+[thumbnail="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 *SCSI* controller, designed in 1985, is commonly found on server grade
hardware, and can connect up to 14 storage devices. {pve} emulates by default a
-LSI 53C895A controller. +
-A SCSI controller of type _Virtio_ is the recommended setting if you aim for
+LSI 53C895A controller.
++
+A SCSI controller of type _VirtIO SCSI_ is the recommended setting if you aim for
performance and is automatically selected for newly created Linux VMs since
{pve} 4.3. Linux distributions have support for this controller since 2012, and
FreeBSD since 2014. For Windows OSes, you need to provide an extra iso
containing the drivers during the installation.
// https://pve.proxmox.com/wiki/Paravirtualized_Block_Drivers_for_Windows#During_windows_installation.
+If you aim at maximum performance, you can select a SCSI controller of type
+_VirtIO SCSI single_ which will allow you to select the *IO Thread* option.
+When selecting _VirtIO SCSI single_ Qemu will create a new controller for
+each disk, instead of adding all disks to the same controller.
* The *Virtio* controller, also called virtio-blk to distinguish from
-the Virtio SCSI controller, is an older type of paravirtualized controller
+the VirtIO SCSI controller, is an older type of paravirtualized controller
which has been superseded in features by the Virtio SCSI Controller.
+[thumbnail="gui-create-vm-hard-disk.png"]
On each controller you attach a number of emulated hard disks, which are backed
by a file or a block device residing in the configured storage. The choice of
a storage type will determine the format of the hard disk image. Storages which
then shrink the disk image accordingly.
.IO Thread
-The option *IO Thread* can only be enabled when using a disk with the *VirtIO* controller,
-or with the *SCSI* controller, when the emulated controller type is *VirtIO SCSI*.
-With this enabled, Qemu uses one thread per disk, instead of one thread for all,
-so it should increase performance when using multiple disks.
+The option *IO Thread* can only be used when using a disk with the
+*VirtIO* controller, or with the *SCSI* controller, when the emulated controller
+ type is *VirtIO SCSI single*.
+With this enabled, Qemu creates one I/O thread per storage controller,
+instead of a single thread for all I/O, so it increases performance when
+multiple disks are used and each disk has its own storage controller.
Note that backups do not currently work with *IO Thread* enabled.
CPU
~~~
+[thumbnail="gui-create-vm-cpu.png"]
+
A *CPU socket* is a physical slot on a PC motherboard where you can plug a CPU.
This CPU can then contain one or many *cores*, which are independent
processing units. Whether you have a single CPU socket with 4 cores, or two CPU
sockets with two cores is mostly irrelevant from a performance point of view.
However some software is licensed depending on the number of sockets you have in
your machine, in that case it makes sense to set the number of of sockets to
-what the license allows you, and increase the number of cores. +
+what the license allows you, and increase the number of cores.
+
Increasing the number of virtual cpus (cores and sockets) will usually provide a
performance improvement though that is heavily dependent on the use of the VM.
Multithreaded applications will of course benefit from a large number of
CPU of the host system, as it means that the host CPU features (also called _CPU
flags_ ) will be available in your VMs. If you want an exact match, you can set
the CPU type to *host* in which case the VM will have exactly the same CPU flags
-as your host system. +
+as your host system.
+
This has a downside though. If you want to do a live migration of VMs between
different hosts, your VM might end up on a new system with a different CPU type.
If the CPU flags passed to the guest are missing, the qemu process will stop. To
remedy this Qemu has also its own CPU type *kvm64*, that {pve} uses by defaults.
kvm64 is a Pentium 4 look a like CPU type, which has a reduced CPU flags set,
-but is guaranteed to work everywhere. +
- In short, if you care about live migration and moving VMs between nodes, leave
+but is guaranteed to work everywhere.
+
+In short, if you care about live migration and moving VMs between nodes, leave
the kvm64 default. If you don’t care about live migration, set the CPU type to
host, as in theory this will give your guests maximum performance.
{pve} to dynamically allocate memory based on the current RAM usage of the
host.
+.Fixed Memory Allocation
+[thumbnail="gui-create-vm-memory-fixed.png"]
+
When choosing a *fixed size memory* {pve} will simply allocate what you
specify to your VM.
+Even when using a fixed memory size, the ballooning device gets added to the
+VM, because it delivers useful information such as how much memory the guest
+really uses.
+In general, you should leave *ballooning* enabled, but if you want to disable
+it (e.g. for debugging purposes), simply uncheck
+*Ballooning* or set
+
+ balloon: 0
+
+in the configuration.
+
+.Automatic Memory Allocation
+[thumbnail="gui-create-vm-memory-dynamic.png", float="left"]
+
// see autoballoon() in pvestatd.pm
When choosing to *automatically allocate memory*, {pve} will make sure that the
minimum amount you specified is always available to the VM, and if RAM usage on
the host is below 80%, will dynamically add memory to the guest up to the
-maximum memory specified. +
+maximum memory specified.
+
When the host is becoming short on RAM, the VM will then release some memory
back to the host, swapping running processes if needed and starting the oom
killer in last resort. The passing around of memory between host and guest is
Network Device
~~~~~~~~~~~~~~
+[thumbnail="gui-create-vm-network.png"]
+
Each VM can have many _Network interface controllers_ (NIC), of four different
types:
but the device is not present in the host, the VM can boot without problems.
As soon as the device/port ist available in the host, it gets passed through.
-WARNING: Using this kind of USB passthrough, means that you cannot move
+WARNING: Using this kind of USB passthrough means that you cannot move
a VM online to another host, since the hardware is only available
on the host the VM is currently residing.
qm set <vmid> -onboot 1
-In some case you want to be able to fine tune the boot order of your VMs, for
-instance if one of your VM is providing firewalling or DHCP to other guest
-systems.
-For this you can use the following parameters:
+.Start and Shutdown Order
+
+[thumbnail="gui-qemu-edit-start-order.png"]
+
+In some case you want to be able to fine tune the boot order of your
+VMs, for instance if one of your VM is providing firewalling or DHCP
+to other guest systems. For this you can use the following
+parameters:
* *Start/Shutdown order*: Defines the start order priority. E.g. set it to 1 if
you want the VM to be the first to be started. (We use the reverse startup
makes sense between the machines running locally on a host, and not
cluster-wide.
+
+[[qm_migration]]
+Migration
+---------
+
+[thumbnail="gui-qemu-migrate.png"]
+
+If you have a cluster, you can migrate your VM to another host with
+
+ qm migrate <vmid> <target>
+
+There are generally two mechanisms for this
+
+* Online Migration (aka Live Migration)
+* Offline Migration
+
+Online Migration
+~~~~~~~~~~~~~~~~
+
+When your VM is running and it has no local resources defined (such as disks
+on local storage, passed through devices, etc.) you can initiate a live
+migration with the -online flag.
+
+How it works
+^^^^^^^^^^^^
+
+This starts a Qemu Process on the target host with the 'incoming' flag, which
+means that the process starts and waits for the memory data and device states
+from the source Virtual Machine (since all other resources, e.g. disks,
+are shared, the memory content and device state are the only things left
+to transmit).
+
+Once this connection is established, the source begins to send the memory
+content asynchronously to the target. If the memory on the source changes,
+those sections are marked dirty and there will be another pass of sending data.
+This happens until the amount of data to send is so small that it can
+pause the VM on the source, send the remaining data to the target and start
+the VM on the target in under a second.
+
+Requirements
+^^^^^^^^^^^^
+
+For Live Migration to work, there are some things required:
+
+* The VM has no local resources (e.g. passed through devices, local disks, etc.)
+* The hosts are in the same {pve} cluster.
+* The hosts have a working (and reliable) network connection.
+* The target host must have the same or higher versions of the
+ {pve} packages. (It *might* work the other way, but this is never guaranteed)
+
+Offline Migration
+~~~~~~~~~~~~~~~~~
+
+If you have local resources, you can still offline migrate your VMs,
+as long as all disk are on storages, which are defined on both hosts.
+Then the migration will copy the disk over the network to the target host.
+
+[[qm_copy_and_clone]]
+Copies and Clones
+-----------------
+
+[thumbnail="gui-qemu-full-clone.png"]
+
+VM installation is usually done using an installation media (CD-ROM)
+from the operation system vendor. Depending on the OS, this can be a
+time consuming task one might want to avoid.
+
+An easy way to deploy many VMs of the same type is to copy an existing
+VM. We use the term 'clone' for such copies, and distinguish between
+'linked' and 'full' clones.
+
+Full Clone::
+
+The result of such copy is an independent VM. The
+new VM does not share any storage resources with the original.
++
+
+It is possible to select a *Target Storage*, so one can use this to
+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
+usually much slower than creating a linked clone.
++
+
+Some storage types allows to copy a specific *Snapshot*, which
+defaults to the 'current' VM data. This also means that the final copy
+never includes any additional snapshots from the original VM.
+
+
+Linked Clone::
+
+Modern storage drivers supports 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.
++
+
+They are called 'linked' because the new image still refers to the
+original. Unmodified data blocks are read from the original image, but
+modification are written (and afterwards read) from a new
+location. This technique is called 'Copy-on-write'.
++
+
+This requires that the original volume is read-only. With {pve} one
+can convert any VM into a read-only <<qm_templates, Template>>). Such
+templates can later be used to create linked clones efficiently.
++
+
+NOTE: You cannot delete the original template while linked clones
+exists.
++
+
+It is not possible to change the *Target storage* for linked clones,
+because this is a storage internal feature.
+
+
+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
+randomized, and we generate a new 'UUID' for the VM BIOS (smbios1)
+setting.
+
+
+[[qm_templates]]
+Virtual Machine Templates
+-------------------------
+
+One can convert a VM into a Template. Such templates are read-only,
+and you can use them to create linked clones.
+
+NOTE: It is not possible to start templates, because this would modify
+the disk images. If you want to change the template, create a linked
+clone and modify that.
+
+
Managing Virtual Machines with `qm`
------------------------------------
qm shutdown 300 && qm wait 300 -timeout 40
+
+[[qm_configuration]]
Configuration
-------------
-All configuration files consists of lines in the form
+VM configuration files are stored inside the Proxmox cluster file
+system, and can be accessed at `/etc/pve/qemu-server/<VMID>.conf`.
+Like other files stored inside `/etc/pve/`, they get automatically
+replicated to all other cluster nodes.
- PARAMETER: value
+NOTE: VMIDs < 100 are reserved for internal purposes, and VMIDs need to be
+unique cluster wide.
+
+.Example VM Configuration
+----
+cores: 1
+sockets: 1
+memory: 512
+name: webmail
+ostype: l26
+bootdisk: virtio0
+net0: e1000=EE:D2:28:5F:B6:3E,bridge=vmbr0
+virtio0: local:vm-100-disk-1,size=32G
+----
+
+Those configuration files are simple text files, and you can edit them
+using a normal text editor (`vi`, `nano`, ...). This is sometimes
+useful to do small corrections, but keep in mind that you need to
+restart the VM to apply such changes.
+
+For that reason, it is usually better to use the `qm` command to
+generate and modify those files, or do the whole thing using the GUI.
+Our toolkit is smart enough to instantaneously apply most changes to
+running VM. This feature is called "hot plug", and there is no
+need to restart the VM in that case.
+
+
+File Format
+~~~~~~~~~~~
+
+VM configuration files use a simple colon separated key/value
+format. Each line has the following format:
+
+-----
+# this is a comment
+OPTION: value
+-----
+
+Blank lines in those files are ignored, and lines starting with a `#`
+character are treated as comments and are also ignored.
+
+
+[[qm_snapshots]]
+Snapshots
+~~~~~~~~~
+
+When you create a snapshot, `qm` stores the configuration at snapshot
+time into a separate snapshot section within the same configuration
+file. For example, after creating a snapshot called ``testsnapshot'',
+your configuration file will look like this:
+
+.VM configuration with snapshot
+----
+memory: 512
+swap: 512
+parent: testsnaphot
+...
+
+[testsnaphot]
+memory: 512
+swap: 512
+snaptime: 1457170803
+...
+----
+
+There are a few snapshot related properties like `parent` and
+`snaptime`. The `parent` property is used to store the parent/child
+relationship between snapshots. `snaptime` is the snapshot creation
+time stamp (Unix epoch).
-Configuration files are stored inside the Proxmox cluster file
-system, and can be accessed at `/etc/pve/qemu-server/<VMID>.conf`.
[[qm_options]]
Options
Locks
-----
-Online migrations and backups (`vzdump`) set a lock to prevent incompatible
-concurrent actions on the affected VMs. Sometimes you need to remove such a
-lock manually (e.g., after a power failure).
+Online migrations, snapshots and backups (`vzdump`) set a lock to
+prevent incompatible concurrent actions on the affected VMs. Sometimes
+you need to remove such a lock manually (e.g., after a power failure).
qm unlock <vmid>
+CAUTION: Only do that if you are sure the action which set the lock is
+no longer running.
+
ifdef::manvolnum[]
+
+Files
+------
+
+`/etc/pve/qemu-server/<VMID>.conf`::
+
+Configuration file for the VM '<VMID>'.
+
+
include::pve-copyright.adoc[]
endif::manvolnum[]
projects / pve-docs.git / blobdiff