use the html5 backend for asciidoc

[pve-docs.git] / qm.adoc

diff --git a/qm.adoc b/qm.adoc
index f44314c682c38e9bb08ed6497cc5339fd06a8e12..424922cf6ff98c77a0d14c1ea90616f53e301aa4 100644 (file)
--- a/qm.adoc
+++ b/qm.adoc
@@ -1,7 +1,9 @@
+[[chapter_virtual_machines]]
 ifdef::manvolnum[]
-PVE({manvolnum})
-================
+qm(1)
+=====
 include::attributes.txt[]
+:pve-toplevel:
 
 NAME
 ----
@@ -17,11 +19,11 @@ include::qm.1-synopsis.adoc[]
 DESCRIPTION
 -----------
 endif::manvolnum[]
-
 ifndef::manvolnum[]
 Qemu/KVM Virtual Machines
 =========================
 include::attributes.txt[]
+:pve-toplevel:
 endif::manvolnum[]
 
 // deprecates
@@ -88,15 +90,19 @@ measured with `iperf(1)`. footnote:[See this benchmark on the KVM wiki
 http://www.linux-kvm.org/page/Using_VirtIO_NIC]
 
 
+[[qm_virtual_machines_settings]]
 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.
 
 
+[[qm_general_settings]]
 General Settings
 ~~~~~~~~~~~~~~~~
+
 General settings of a VM include
 
 * the *Node* : the physical server on which the VM will run
@@ -105,16 +111,20 @@ General settings of a VM include
 * *Resource Pool*: a logical group of VMs
 
 
+[[qm_os_settings]]
 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.
 
 
+[[qm_hard_disk]]
 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
@@ -182,8 +192,11 @@ 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.
 
+
+[[qm_cpu]]
 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
@@ -238,8 +251,11 @@ 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.
 
+
+[[qm_memory]]
 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. 
@@ -280,8 +296,11 @@ systems.
 When allocating RAMs to your VMs, a good rule of thumb is always to leave 1GB
 of RAM available to the host.
 
+
+[[qm_network_device]]
 Network Device
 ~~~~~~~~~~~~~~
+
 Each VM can have many _Network interface controllers_ (NIC), of four different
 types:
 
@@ -340,8 +359,10 @@ traffic increases. We recommend to set this option only when the VM has to
 process a great number of incoming connections, such as when the VM is running
 as a router, reverse proxy or a busy HTTP server doing long polling.
 
+
 USB Passthrough
 ~~~~~~~~~~~~~~~
+
 There are two different types of USB passthrough devices:
 
 * Host USB passtrough
@@ -374,6 +395,8 @@ if you use a SPICE client which supports it. If you add a SPICE USB port
 to your VM, you can passthrough a USB device from where your SPICE client is,
 directly to the VM (for example an input device or hardware dongle).
 
+
+[[qm_bios_and_uefi]]
 BIOS and UEFI
 ~~~~~~~~~~~~~
 
@@ -405,6 +428,39 @@ 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_startup_and_shutdown]]
+Automatic Start and Shutdown of Virtual Machines
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After creating your VMs, you probably want them to start automatically
+when the host system boots. For this you need to select the option 'Start at
+boot' from the 'Options' Tab of your VM in the web interface, or set it with
+the following command:
+
+ 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/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
+order for shutdown, so a machine with a start order of 1 would be the last to
+be shut down)
+* *Startup delay*: Defines the interval between this VM start and subsequent
+VMs starts . E.g. set it to 240 if you want to wait 240 seconds before starting
+other VMs.
+* *Shutdown timeout*: Defines the duration in seconds {pve} should wait
+for the VM to be offline after issuing a shutdown command.
+By default this value is set to 60, which means that {pve} will issue a
+shutdown request, wait 60s for the machine to be offline, and if after 60s
+the machine is still online will notify that the shutdown action failed.
+
+Please note that machines without a Start/Shutdown order parameter will always
+start after those where the parameter is set, and this parameter only
+makes sense between the machines running locally on a host, and not
+cluster-wide.
 
 Managing Virtual Machines with `qm`
 ------------------------------------
@@ -444,6 +500,7 @@ All configuration files consists of lines in the form
 Configuration files are stored inside the Proxmox cluster file
 system, and can be accessed at `/etc/pve/qemu-server/<VMID>.conf`.
 
+[[qm_options]]
 Options
 ~~~~~~~