add vm.conf man page

diff --git a/Makefile b/Makefile
index fb2ca100e73ddb6e53a27364945a29a49145ad21..9e3b064a34ff2dfa75ed5d705a1bd33139b07760 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -19,6 +19,8 @@ SYSADMIN_SOURCES=                     \
 PVE_ADMIN_GUIDE_SOURCES=               \
        datacenter.cfg.adoc             \
        datacenter.cfg.5-opts.adoc      \
+       vm.conf.adoc                    \
+       vm.conf.5-opts.adoc             \
        ${SYSADMIN_SOURCES}             \
        pve-admin-guide.adoc            \
        pve-intro.adoc                  \
@@ -45,6 +47,8 @@ ADOC_MAN8_HTML_ARGS=-a "manvolnum=8" ${ADOC_STDARG} -a "revnumber=${RELEASE}"
 
 BROWSER?=xdg-open
 
+all: pve-admin-guide.html
+
 %-nwdiag.svg: %.nwdiag
        nwdiag -T svg $*.nwdiag -o $@;
 
@@ -77,6 +81,10 @@ datacenter.cfg.5-opts.adoc:
        ./gen-datacenter-cfg-opts-adoc.pl >$@.tmp
        mv $@.tmp $@
 
+vm.conf.5-opts.adoc:
+       ./gen-vm-conf-opts-adoc.pl >$@.tmp
+       mv $@.tmp $@
+
 %.5: %.adoc %.5-opts.adoc docinfo.xml
        a2x -a docinfo1 -a "manvolnum=5" -a "manversion=Release ${RELEASE}" -f manpage $*.adoc
        test -z "$${NOVIEW}" && man -l $@
@@ -85,12 +93,9 @@ datacenter.cfg.5-opts.adoc:
        asciidoc ${ADOC_MAN5_HTML_ARGS} -o $@ $*.adoc
        test -z "$${NOVIEW}" && $(BROWSER) $@ &
 
-
-all: pve-admin-guide.html
-
 index.html: index.adoc ${PVE_ADMIN_GUIDE_SOURCES}
        $(MAKE) NOVIEW=1 pve-admin-guide.pdf pve-admin-guide.html pve-admin-guide.epub
-       $(MAKE) NOVIEW=1 qm.1.html pct.1.html pveam.1.html pvesm.1.html pveum.1.html vzdump.1.html pve-firewall.8.html ha-manager.1.html datacenter.cfg.5.html
+       $(MAKE) NOVIEW=1 qm.1.html pct.1.html pveam.1.html pvesm.1.html pveum.1.html vzdump.1.html pve-firewall.8.html ha-manager.1.html datacenter.cfg.5.html vm.conf.5.html
        asciidoc -a "date=$(shell date)" -a "revnumber=${RELEASE}" index.adoc
        $(BROWSER) index.html &
 

diff --git a/gen-vm-conf-opts-adoc.pl b/gen-vm-conf-opts-adoc.pl
new file mode 100755 (executable)
index 0000000..8aadf92
--- /dev/null
+++ b/gen-vm-conf-opts-adoc.pl
@@ -0,0 +1,10 @@
+#!/usr/bin/perl
+
+use strict;
+use warnings;
+use PVE::RESTHandler;
+use PVE::QemuServer;
+
+my $prop = PVE::QemuServer::json_config_properties();
+
+print PVE::RESTHandler::dump_properties($prop);

diff --git a/index.adoc b/index.adoc
index 8d5c06ecb9bfc52f0fea1e684d64826077856755..00ef8f2235c8bbdfee97da8b4898c8b9ecb74b99 100644 (file)
--- a/index.adoc
+++ b/index.adoc
@@ -29,7 +29,8 @@ include::attributes.txt[]
 | vzdump       | link:vzdump.1.html[vzdump.1]
 | ha-manager   | link:ha-manager.1.html[ha-manager.1]
 | pve-firewall | link:pve-firewall.8.html[pve-firewall.8]
-| '/etc/pve/datacenter.cfg' | link:datacenter.cfg.5.html[datacenter.cfg.5]
+| '/etc/pve/datacenter.cfg'          | link:datacenter.cfg.5.html[datacenter.cfg.5]
+| '/etc/pve/qemu-server/<VMID>.conf' | link:vm.conf.5.html[vm.conf.5]
 |===========================================================
 
 

diff --git a/pve-admin-guide.adoc b/pve-admin-guide.adoc
index 64b9f47e43be7addc5bfda2310b7b32d6775ff4c..08f09cd63b69dcf2763e74def9cd36955e340b20 100644 (file)
--- a/pve-admin-guide.adoc
+++ b/pve-admin-guide.adoc
@@ -110,6 +110,8 @@ Configuration Files
 :leveloffset: 2
 include::datacenter.cfg.adoc[]
 
+include::vm.conf.adoc[]
+
 :leveloffset: 0
 
 

diff --git a/vm.conf.5-opts.adoc b/vm.conf.5-opts.adoc
new file mode 100644 (file)
index 0000000..97968df
--- /dev/null
+++ b/vm.conf.5-opts.adoc
@@ -0,0 +1,330 @@
+`acpi`: `boolean` (default=`1`)::
+
+Enable/disable ACPI.
+
+`agent`: `boolean` (default=`0`)::
+
+Enable/disable Qemu GuestAgent.
+
+`args`: `string` ::
+
+NOTE: this option is for experts only. It allows you to pass arbitrary
+arguments to kvm, for example:
++
+args: -no-reboot -no-hpet
+
+`autostart`: `boolean` (default=`0`)::
+
+Automatic restart after crash (currently ignored).
+
+`balloon`: `integer (0 - N)` ::
+
+Amount of target RAM for the VM in MB. Using zero disables the ballon
+driver.
+
+`bios`: `(ovmf | seabios)` (default=`seabios`)::
+
+Select BIOS implementation.
+
+`boot`: `[acdn]{1,4}` (default=`cdn`)::
+
+Boot on floppy (a), hard disk (c), CD-ROM (d), or network (n).
+
+`bootdisk`: `(ide|sata|scsi|virtio)\d+` ::
+
+Enable booting from specified disk.
+
+`cdrom`: `volume` ::
+
+This is an alias for option -ide2
+
+`cores`: `integer (1 - N)` (default=`1`)::
+
+The number of cores per socket.
+
+`cpu`: ::
+
+Emulated CPU type.
+
+`cpulimit`: `number (0 - 128)` (default=`0`)::
+
+Limit of CPU usage.
++
+NOTE: If the computer has 2 CPUs, it has total of '2' CPU time. Value '0'
+indicates no CPU limit.
+
+`cpuunits`: `integer (0 - 500000)` (default=`1000`)::
+
+CPU weight for a VM. Argument is used in the kernel fair scheduler. The
+larger the number is, the more CPU time this VM gets. Number is relative to
+weights of all the other running VMs.
++
+NOTE: You can disable fair-scheduler configuration by setting this to 0.
+
+`description`: `string` ::
+
+Description for the VM. Only used on the configuration web interface. This
+is saved as comment inside the configuration file.
+
+`freeze`: `boolean` ::
+
+Freeze CPU at startup (use 'c' monitor command to start execution).
+
+`hostpci[n]`: `[host=]HOSTPCIDEVICE [,rombar=on|off] [,pcie=0|1] [,x-vga=on|off]` ::
+
+Map host pci devices. HOSTPCIDEVICE syntax is:
++
+'bus:dev.func' (hexadecimal numbers)
++
+You can us the 'lspci' command to list existing pci devices.
++
+The 'rombar' option determines whether or not the device's ROM will be
+visible in the guest's memory map (default is 'on').
++
+NOTE: This option allows direct access to host hardware. So it is no longer
+possible to migrate such machines - use with special care.
++
+Experimental: user reported problems with this option.
+
+`hotplug`: `string` (default=`network,disk,usb`)::
+
+Selectively enable hotplug features. This is a comma separated list of
+hotplug features: 'network', 'disk', 'cpu', 'memory' and 'usb'. Use '0' to
+disable hotplug completely. Value '1' is an alias for the default
+'network,disk,usb'.
+
+`ide[n]`: `[file=]<volume> [,aio=<native|threads>] [,backup=<on|off>] [,bps=<bps>] [,bps_rd=<bps>] [,bps_wr=<bps>] [,cache=<none|writethrough|writeback|unsafe|directsync>] [,cyls=<count>] [,discard=<ignore|on>] [,format=<drive format>] [,heads=<count>] [,iops=<iops>] [,iops_max=<iops>] [,iops_rd=<iops>] [,iops_rd_max=<iops>] [,iops_wr=<iops>] [,iops_wr_max=<iops>] [,mbps=<mbps>] [,mbps_max=<mbps>] [,mbps_rd=<mbps>] [,mbps_rd_max=<mbps>] [,mbps_wr=<mbps>] [,mbps_wr_max=<mbps>] [,media=<cdrom|disk>] [,model=<model>] [,rerror=<ignore|report|stop>] [,secs=<count>] [,serial=<serial>] [,snapshot=<on|off>] [,trans=<none|lba|auto>] [,werror=<enospc|ignore|report|stop>]` ::
+
+Use volume as IDE hard disk or CD-ROM (n is 0 to 3).
+
+`keyboard`: `(da | de | de-ch | en-gb | en-us | es | fi | fr | fr-be | fr-ca | fr-ch | hu | is | it | ja | lt | mk | nl | no | pl | pt | pt-br | sl | sv | tr)` (default=`en-us`)::
+
+Keybord layout for vnc server. Default is read from the datacenter
+configuration file.
+
+`kvm`: `boolean` (default=`1`)::
+
+Enable/disable KVM hardware virtualization.
+
+`localtime`: `boolean` ::
+
+Set the real time clock to local time. This is enabled by default if ostype
+indicates a Microsoft OS.
+
+`lock`: `(backup | migrate | rollback | snapshot)` ::
+
+Lock/unlock the VM.
+
+`machine`: `(pc|pc(-i440fx)?-\d+\.\d+(\.pxe)?|q35|pc-q35-\d+\.\d+(\.pxe)?)` ::
+
+Specific the Qemu machine type.
+
+`memory`: `integer (16 - N)` (default=`512`)::
+
+Amount of RAM for the VM in MB. This is the maximum available memory when
+you use the balloon device.
+
+`migrate_downtime`: `number (0 - N)` (default=`0.1`)::
+
+Set maximum tolerated downtime (in seconds) for migrations.
+
+`migrate_speed`: `integer (0 - N)` (default=`0`)::
+
+Set maximum speed (in MB/s) for migrations. Value 0 is no limit.
+
+`name`: `string` ::
+
+Set a name for the VM. Only used on the configuration web interface.
+
+`net[n]`: `MODEL=XX:XX:XX:XX:XX:XX [,bridge=<dev>][,queues=<nbqueues>][,rate=<mbps>] [,tag=<vlanid>][,trunks=<vlanid[;vlanid]>][,firewall=0|1],link_down=0|1]` ::
+
+Specify network devices.
++
+MODEL is one of: e1000 e1000-82540em e1000-82544gc e1000-82545em i82551
+i82557b i82559er ne2k_isa ne2k_pci pcnet rtl8139 virtio vmxnet3
++
+XX:XX:XX:XX:XX:XX should be an unique MAC address. This is
+automatically generated if not specified.
++
+The bridge parameter can be used to automatically add the interface to a
+bridge device. The Proxmox VE standard bridge is called 'vmbr0'.
++
+Option 'rate' is used to limit traffic bandwidth from and to this
+interface. It is specified as floating point number, unit is 'Megabytes per
+second'.
++
+If you specify no bridge, we create a kvm 'user' (NATed) network device,
+which provides DHCP and DNS services. The following addresses are used:
++
+10.0.2.2   Gateway
+10.0.2.3   DNS Server
+10.0.2.4   SMB Server
++
+The DHCP server assign addresses to the guest starting from 10.0.2.15.
+
+`numa`: `boolean` (default=`0`)::
+
+Enable/disable NUMA.
+
+`numa[n]`: `cpus=<id[-id],memory=<mb>[[,hostnodes=<id[-id]>] [,policy=<preferred|bind|interleave>]]` ::
+
+numa topology
+
+`onboot`: `boolean` (default=`0`)::
+
+Specifies whether a VM will be started during system bootup.
+
+`ostype`: `(l24 | l26 | other | solaris | w2k | w2k3 | w2k8 | win7 | win8 | wvista | wxp)` ::
+
+Used to enable special optimization/features for specific
+operating systems:
++
+other  => unspecified OS
+wxp    => Microsoft Windows XP
+w2k    => Microsoft Windows 2000
+w2k3   => Microsoft Windows 2003
+w2k8   => Microsoft Windows 2008
+wvista => Microsoft Windows Vista
+win7   => Microsoft Windows 7
+win8   => Microsoft Windows 8/2012
+l24    => Linux 2.4 Kernel
+l26    => Linux 2.6/3.X Kernel
+solaris => solaris/opensolaris/openindiania kernel
++
+other|l24|l26|solaris                      ... no special behaviour
+wxp|w2k|w2k3|w2k8|wvista|win7|win8  ... use --localtime switch
+
+`parallel[n]`: `/dev/parport\d+|/dev/usb/lp\d+` ::
+
+Map host parallel devices (n is 0 to 2).
++
+NOTE: This option allows direct access to host hardware. So it is no longer
+possible to migrate such machines - use with special care.
++
+Experimental: user reported problems with this option.
+
+`protection`: `boolean` (default=`0`)::
+
+Sets the protection flag of the VM. This will prevent the remove operation.
+
+`reboot`: `boolean` (default=`1`)::
+
+Allow reboot. If set to '0' the VM exit on reboot.
+
+`sata[n]`: `[file=]<volume> [,aio=<native|threads>] [,backup=<on|off>] [,bps=<bps>] [,bps_rd=<bps>] [,bps_wr=<bps>] [,cache=<none|writethrough|writeback|unsafe|directsync>] [,cyls=<count>] [,discard=<ignore|on>] [,format=<drive format>] [,heads=<count>] [,iops=<iops>] [,iops_max=<iops>] [,iops_rd=<iops>] [,iops_rd_max=<iops>] [,iops_wr=<iops>] [,iops_wr_max=<iops>] [,mbps=<mbps>] [,mbps_max=<mbps>] [,mbps_rd=<mbps>] [,mbps_rd_max=<mbps>] [,mbps_wr=<mbps>] [,mbps_wr_max=<mbps>] [,media=<cdrom|disk>] [,rerror=<ignore|report|stop>] [,secs=<count>] [,serial=<serial>] [,snapshot=<on|off>] [,trans=<none|lba|auto>] [,werror=<enospc|ignore|report|stop>]` ::
+
+Use volume as SATA hard disk or CD-ROM (n is 0 to 5).
+
+`scsi[n]`: `[file=]<volume> [,aio=<native|threads>] [,backup=<on|off>] [,bps=<bps>] [,bps_rd=<bps>] [,bps_wr=<bps>] [,cache=<none|writethrough|writeback|unsafe|directsync>] [,cyls=<count>] [,discard=<ignore|on>] [,format=<drive format>] [,heads=<count>] [,iops=<iops>] [,iops_max=<iops>] [,iops_rd=<iops>] [,iops_rd_max=<iops>] [,iops_wr=<iops>] [,iops_wr_max=<iops>] [,iothread=<off|on>] [,mbps=<mbps>] [,mbps_max=<mbps>] [,mbps_rd=<mbps>] [,mbps_rd_max=<mbps>] [,mbps_wr=<mbps>] [,mbps_wr_max=<mbps>] [,media=<cdrom|disk>] [,queues=<nbqueues>] [,secs=<count>] [,serial=<serial>] [,snapshot=<on|off>] [,trans=<none|lba|auto>] [,werror=<enospc|ignore|report|stop>]` ::
+
+Use volume as SCSI hard disk or CD-ROM (n is 0 to 13).
+
+`scsihw`: `(lsi | lsi53c810 | megasas | pvscsi | virtio-scsi-pci | virtio-scsi-single)` (default=`lsi`)::
+
+scsi controller model
+
+`serial[n]`: `(/dev/.+|socket)` ::
+
+Create a serial device inside the VM (n is 0 to 3), and pass through a host
+serial device (i.e. /dev/ttyS0), or create a unix socket on the host side
+(use 'qm terminal' to open a terminal connection).
++
+NOTE: If you pass through a host serial device, it is no longer possible to
+migrate such machines - use with special care.
++
+Experimental: user reported problems with this option.
+
+`shares`: `integer (0 - 50000)` (default=`1000`)::
+
+Amount of memory shares for auto-ballooning. The larger the number is, the
+more memory this VM gets. Number is relative to weights of all other
+running VMs. Using zero disables auto-ballooning
+
+`smbios[n]`: `[family=<str>] [,manufacturer=<name>] [,product=<name>] [,serial=<str>] [,sku=<str>] [,uuid=<UUID>] [,version=<str>]` ::
+
+Specify SMBIOS type 1 fields.
+
+`smp`: `integer (1 - N)` (default=`1`)::
+
+The number of CPUs. Please use option -sockets instead.
+
+`sockets`: `integer (1 - N)` (default=`1`)::
+
+The number of CPU sockets.
+
+`startdate`: `(now | YYYY-MM-DD | YYYY-MM-DDTHH:MM:SS)` (default=`now`)::
+
+Set the initial date of the real time clock. Valid format for date are:
+'now' or '2006-06-17T16:01:21' or '2006-06-17'.
+
+`startup`: `[[order=]\d+] [,up=\d+] [,down=\d+] ` ::
+
+Startup and shutdown behavior. Order is a non-negative number defining the
+general startup order. Shutdown in done with reverse ordering. Additionally
+you can set the 'up' or 'down' delay in seconds, which specifies a delay to
+wait before the next VM is started or stopped.
+
+`tablet`: `boolean` (default=`1`)::
+
+Enable/disable the USB tablet device. This device is usually needed to
+allow absolute mouse positioning with VNC. Else the mouse runs out of sync
+with normal VNC clients. If you're running lots of console-only guests on
+one host, you may consider disabling this to save some context switches.
+This is turned off by default if you use spice (-vga=qxl).
+
+`tdf`: `boolean` (default=`0`)::
+
+Enable/disable time drift fix.
+
+`template`: `boolean` (default=`0`)::
+
+Enable/disable Template.
+
+`unused[n]`: `string` ::
+
+Reference to unused volumes.
+
+`usb[n]`: `[host=]<HOSTUSBDEVICE|spice> [,usb3=<yes|no>]` ::
+
+Configure an USB device (n is 0 to 4). This can be used to
+pass-through usb devices to the guest. HOSTUSBDEVICE syntax is:
++
+'bus-port(.port)*' (decimal numbers) or
+'vendor_id:product_id' (hexadeciaml numbers) or
+'spice'
++
+You can use the 'lsusb -t' command to list existing usb devices.
++
+NOTE: This option allows direct access to host hardware. So it is no longer
+possible to migrate such machines - use with special care.
++
+The value 'spice' can be used to add a usb redirection devices for spice.
++
+The 'usb3' option determines whether the device is a USB3 device or not
+(this does currently not work reliably with spice redirection and is then
+ignored).
+
+`vcpus`: `integer (1 - N)` (default=`0`)::
+
+Number of hotplugged vcpus.
+
+`vga`: `(cirrus | qxl | qxl2 | qxl3 | qxl4 | serial0 | serial1 | serial2 | serial3 | std | vmware)` ::
+
+Select the VGA type. If you want to use high resolution modes (>=
+1280x1024x16) then you should use the options 'std' or 'vmware'. Default is
+'std' for win8/win7/w2k8, and 'cirrus' for other OS types. The 'qxl' option
+enables the SPICE display sever. For win* OS you can select how many
+independent displays you want, Linux guests can add displays them self. You
+can also run without any graphic card, using a serial device as terminal.
+
+`virtio[n]`: `[file=]<volume> [,aio=<native|threads>] [,backup=<on|off>] [,bps=<bps>] [,bps_rd=<bps>] [,bps_wr=<bps>] [,cache=<none|writethrough|writeback|unsafe|directsync>] [,cyls=<count>] [,discard=<ignore|on>] [,format=<drive format>] [,heads=<count>] [,iops=<iops>] [,iops_max=<iops>] [,iops_rd=<iops>] [,iops_rd_max=<iops>] [,iops_wr=<iops>] [,iops_wr_max=<iops>] [,iothread=<off|on>] [,mbps=<mbps>] [,mbps_max=<mbps>] [,mbps_rd=<mbps>] [,mbps_rd_max=<mbps>] [,mbps_wr=<mbps>] [,mbps_wr_max=<mbps>] [,media=<cdrom|disk>] [,rerror=<ignore|report|stop>] [,secs=<count>] [,serial=<serial>] [,snapshot=<on|off>] [,trans=<none|lba|auto>] [,werror=<enospc|ignore|report|stop>]` ::
+
+Use volume as VIRTIO hard disk (n is 0 to 15).
+
+`watchdog`: `[[model=]i6300esb|ib700] [,[action=]reset|shutdown|poweroff|pause|debug|none]` ::
+
+Create a virtual hardware watchdog device. Once enabled (by a guest
+action), the watchdog must be periodically polled by an agent inside the
+guest or else the watchdog will reset the guest (or execute the respective
+action specified)
+

diff --git a/vm.conf.adoc b/vm.conf.adoc
new file mode 100644 (file)
index 0000000..a6ebaaf
--- /dev/null
+++ b/vm.conf.adoc
@@ -0,0 +1,55 @@
+ifdef::manvolnum[]
+PVE({manvolnum})
+================
+include::attributes.txt[]
+
+NAME
+----
+
+vm.conf - Proxmox VE  Virtual Machine Configuration
+
+
+SYNOPSYS
+--------
+
+'/etc/pve/qemu-server/<VMID>.conf'
+
+
+DESCRIPTION
+-----------
+endif::manvolnum[]
+
+ifndef::manvolnum[]
+ Virtual Machine Configuration
+==============================
+include::attributes.txt[]
+endif::manvolnum[]
+
+The '/etc/pve/qemu-server/<VMID>.conf' files stores VM configuration,
+where "VMID" is the numeric ID of the given VM. Note that IDs <=
+100 are reserved for internal purposes.
+
+
+File Format
+-----------
+
+The file uses a simple colon separated key/value format. Each line has
+the following format:
+
+ OPTION: value
+
+Blank lines in the file are ignored, and lines starting with a '#'
+character are treated as comments and are also ignored.
+
+One can use the 'qm' command to generate and modify those files.
+
+
+Options
+-------
+
+include::vm.conf.5-opts.adoc[]
+
+
+ifdef::manvolnum[]
+include::pve-copyright.adoc[]
+endif::manvolnum[]