include::attributes.txt[]
endif::manvolnum[]
+// deprecates
+// http://pve.proxmox.com/wiki/Container_and_Full_Virtualization
+// http://pve.proxmox.com/wiki/KVM
+// http://pve.proxmox.com/wiki/Qemu_Server
-qm is a script to manage virtual machines with Qemu/Kvm. You can
+Qemu (short form for Quick Emulator) is an opensource hypervisor that emulates a
+physical computer. From the perspective of the host system where Qemu is
+running, Qemu is a user program which has access to a number of local resources
+like partitions, files, network cards which are then passed to an
+emulated computer which sees them as if they were real devices.
+
+A guest operating system running in the emulated computer accesses these
+devices, and runs as it were running on real hardware. For instance you can pass
+an iso image as a parameter to Qemu, and the OS running in the emulated computer
+will see a real CDROM inserted in a CD drive.
+
+Qemu can emulates a great variety of hardware from ARM to Sparc, but {pve} is
+only concerned with 32 and 64 bits PC clone emulation, since it represents the
+overwhelming majority of server hardware. The emulation of PC clones is also one
+of the fastest due to the availability of processor extensions which greatly
+speed up Qemu when the emulated architecture is the same as the host
+architecture.
+
+NOTE: You may sometimes encounter the term _KVM_ (Kernel-based Virtual Machine).
+It means that Qemu is running with the support of the virtualization processor
+extensions, via the Linux kvm module. In the context of {pve} _Qemu_ and
+_KVM_ can be use interchangeably as Qemu in {pve} will always try to load the kvm
+module.
+
+Qemu inside {pve} runs as a root process, since this is required to access block
+and PCI devices.
+
+Emulated devices and paravirtualized devices
+--------------------------------------------
+
+The PC hardware emulated by Qemu includes a mainboard, network controllers,
+scsi, ide and sata controllers, serial ports (the complete list can be seen in
+the `kvm(1)` man page) all of them emulated in software. All these devices
+are the exact software equivalent of existing hardware devices, and if the OS
+running in the guest has the proper drivers it will use the devices as if it
+were running on real hardware. This allows Qemu to runs _unmodified_ operating
+systems.
+
+This however has a performance cost, as running in software what was meant to
+run in hardware involves a lot of extra work for the host CPU. To mitigate this,
+Qemu can present to the guest operating system _paravirtualized devices_, where
+the guest OS recognizes it is running inside Qemu and cooperates with the
+hypervisor.
+
+Qemu relies on the virtio virtualization standard, and is thus able to presente
+paravirtualized virtio devices, which includes a paravirtualized generic disk
+controller, a paravirtualized network card, a paravirtualized serial port,
+a paravirtualized SCSI controller, etc ...
+
+It is highly recommended to use the virtio devices whenever you can, as they
+provide a big performance improvement. Using the virtio generic disk controller
+versus an emulated IDE controller will double the sequential write throughput,
+as measured with `bonnie++(8)`. Using the virtio network interface can deliver
+up to three times the throughput of an emulated Intel E1000 network card, as
+measured with `iperf(1)`. footnote:[See this benchmark on the KVM wiki
+http://www.linux-kvm.org/page/Using_VirtIO_NIC]
+
+Virtual Machines settings
+-------------------------
+Generally speaking {pve} tries to choose sane defaults for virtual machines
+(VM). Make sure you understand the meaning of the settings you change, as it
+could incur a performance slowdown, or putting your data at risk.
+
+General Settings
+~~~~~~~~~~~~~~~~
+General settings of a VM include
+
+* the *Node* : the physical server on which the VM will run
+* the *VM ID*: a unique number in this {pve} installation used to identify your VM
+* *Name*: a free form text string you can use to describe the VM
+* *Resource Pool*: a logical group of VMs
+
+OS Settings
+~~~~~~~~~~~
+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.
+
+Hard Disk
+~~~~~~~~~
+Qemu can emulate a number of storage controllers:
+
+* the *IDE* controller, has a design which goes back to the 1984 PC/AT disk
+controller. Even if this controller has been superseded by more more designs,
+each and every OS you can think has support for it, making it a great choice
+if you want to run an OS released before 2003. You can connect up to 4 devices
+on this controller.
+
+* the *SATA* (Serial ATA) controller, dating from 2003, has a more modern
+design, allowing higher throughput and a greater number of devices to be
+connected. You can connect up to 6 devices on this controller.
+
+* 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.
+
+* The *Virtio* controller is a generic paravirtualized controller, and is the
+recommended setting if you aim for performance. To use this controller, the OS
+need to have special drivers which may be included in your installation ISO or
+not. Linux distributions have support for the Virtio controller since 2010, and
+FreeBSD since 2014. For Windows OSes, you need to provide an extra iso
+containing the Virtio drivers during the installation.
+// see: https://pve.proxmox.com/wiki/Paravirtualized_Block_Drivers_for_Windows#During_windows_installation.
+You can connect up to 16 devices on this controller.
+
+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
+present block devices (LVM, ZFS, Ceph) will require the *raw disk image format*,
+whereas files based storages (Ext4, NFS, GlusterFS) will let you to choose
+either the *raw disk image format* or the *QEMU image format*.
+
+ * the *QEMU image format* is a copy on write format which allows snapshots, and
+ thin provisioning of the disk image.
+ * the *raw disk image* is a bit-to-bit image of a hard disk, similar to what
+ you would get when executing the `dd` command on a block device in Linux. This
+ format do not support thin provisioning or snapshotting by itself, requiring
+ cooperation from the storage layer for these tasks. It is however 10% faster
+ than the *QEMU image format*. footnote:[See this benchmark for details
+ http://events.linuxfoundation.org/sites/events/files/slides/CloudOpen2013_Khoa_Huynh_v3.pdf]
+ * the *VMware image format* only makes sense if you intend to import/export the
+ disk image to other hypervisors.
+
+Setting the *Cache* mode of the hard drive will impact how the host system will
+notify the guest systems of block write completions. The *No cache* default
+means that the guest system will be notified that a write is complete when each
+block reaches the physical storage write queue, ignoring the host page cache.
+This provides a good balance between safety and speed.
+
+If you want the {pve} backup manager to skip a disk when doing a backup of a VM,
+you can set the *No backup* option on that disk.
+
+If your storage supports _thin provisioning_ (see the storage chapter in the
+{pve} guide), and your VM has a *SCSI* controller you can activate the *Discard*
+option on the hard disks connected to that controller. With *Discard* enabled,
+when the filesystem of a VM marks blocks as unused after removing files, the
+emulated SCSI controller will relay this information to the storage, which will
+then shrink the disk image accordingly.
+
+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*.
+With this enabled, Qemu uses one thread per disk, instead of one thread for all,
+so it should increase performance when using multiple disks.
+Note that backups do not currently work with *IO Thread* enabled.
+
+CPU
+~~~
+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. +
+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
+virtual cpus, as for each virtual cpu you add, Qemu will create a new thread of
+execution on the host system. If you're not sure about the workload of your VM,
+it is usually a safe bet to set the number of *Total cores* to 2.
+
+NOTE: It is perfectly safe to set the _overall_ number of total cores in all
+your VMs to be greater than the number of of cores you have on your server (ie.
+4 VMs with each 4 Total cores running in a 8 core machine is OK) In that case
+the host system will balance the Qemu execution threads between your server
+cores just like if you were running a standard multithreaded application.
+However {pve} will prevent you to allocate on a _single_ machine more vcpus than
+physically available, as this will only bring the performance down due to the
+cost of context switches.
+
+Qemu can emulate a number different of *CPU types* from 486 to the latest Xeon
+processors. Each new processor generation adds new features, like hardware
+assisted 3d rendering, random number generation, memory protection, etc ...
+Usually you should select for your VM a processor type which closely matches the
+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. +
+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
+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.
+
+You can also optionally emulate a *NUMA* architecture in your VMs. The basics of
+the NUMA architecture mean that instead of having a global memory pool available
+to all your cores, the memory is spread into local banks close to each socket.
+This can bring speed improvements as the memory bus is not a bottleneck
+anymore. If your system has a NUMA architecture footnote:[if the command
+`numactl --hardware | grep available` returns more than one node, then your host
+system has a NUMA architecture] we recommend to activate the option, as this
+will allow proper distribution of the VM resources on the host system. This
+option is also required in {pve} to allow hotplugging of cores and RAM to 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.
+
+Memory
+~~~~~~
+For each VM you have the option to set a fixed size memory or asking
+{pve} to dynamically allocate memory based on the current RAM usage of the
+host.
+
+When choosing a *fixed size memory* {pve} will simply allocate what you
+specify to your VM.
+
+// 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. +
+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
+done via a special `balloon` kernel driver running inside the guest, which will
+grab or release memory pages from the host.
+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/]
+
+All Linux distributions released after 2010 have the balloon kernel driver
+included. For Windows OSes, the balloon driver needs to be added manually and can
+incur a slowdown of the guest, so we don't recommend using it on critical
+systems.
+// see https://forum.proxmox.com/threads/solved-hyper-threading-vs-no-hyper-threading-fixed-vs-variable-memory.20265/
+
+When allocating RAMs to your VMs, a good rule of thumb is always to leave 1GB
+of RAM available to the host.
+
+Managing Virtual Machines with 'qm'
+------------------------------------
+
+qm is the tool to manage Qemu/Kvm virtual machines on {pve}. You can
create and destroy virtual machines, and control execution
(start/stop/suspend/resume). Besides that, you can use qm to set
parameters in the associated config file. It is also possible to
create and delete virtual disks.
+CLI Usage Examples
+~~~~~~~~~~~~~~~~~~
+
+Create a new VM with 4 GB IDE disk.
+
+ qm create 300 -ide0 4 -net0 e1000 -cdrom proxmox-mailgateway_2.1.iso
+
+Start the new VM
+
+ qm start 300
+
+Send a shutdown request, then wait until the VM is stopped.
+
+ qm shutdown 300 && qm wait 300
+
+Same as above, but only wait for 40 seconds.
+
+ qm shutdown 300 && qm wait 300 -timeout 40
+
Configuration
-------------
PARAMETER: value
Configuration files are stored inside the Proxmox cluster file
-system, and can be access at '/etc/pve/qemu-server/<VMID>.conf'.
+system, and can be accessed at '/etc/pve/qemu-server/<VMID>.conf'.
Options
~~~~~~~
qm unlock <vmid>
-Examples
---------
-
-Create a new VM with 4 GB IDE disk.
-
- qm create 300 -ide0 4 -net0 e1000 -cdrom proxmox-mailgateway_2.1.iso
-
-Start the new VM
-
- qm start 300
-
-Send a shutdown request, then wait until the VM is stopped.
-
- qm shutdown 300 && qm wait 300
-
-Same as above, but only wait for 40 seconds.
-
- qm shutdown 300 && qm wait 300 -timeout 40
-
ifdef::manvolnum[]
include::pve-copyright.adoc[]
projects / pve-docs.git / blobdiff