From 7b2c36ae8185fd6c8855e6abcc86c6fcf090ed28 Mon Sep 17 00:00:00 2001 From: Dietmar Maurer Date: Wed, 23 Mar 2016 10:31:15 +0100 Subject: [PATCH] add vm.conf man page --- Makefile | 13 +- gen-vm-conf-opts-adoc.pl | 10 ++ index.adoc | 3 +- pve-admin-guide.adoc | 2 + vm.conf.5-opts.adoc | 330 +++++++++++++++++++++++++++++++++++++++ vm.conf.adoc | 55 +++++++ 6 files changed, 408 insertions(+), 5 deletions(-) create mode 100755 gen-vm-conf-opts-adoc.pl create mode 100644 vm.conf.5-opts.adoc create mode 100644 vm.conf.adoc diff --git a/Makefile b/Makefile index fb2ca10..9e3b064 100644 --- 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 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 8d5c06e..00ef8f2 100644 --- 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/.conf' | link:vm.conf.5.html[vm.conf.5] |=========================================================== diff --git a/pve-admin-guide.adoc b/pve-admin-guide.adoc index 64b9f47..08f09cd 100644 --- 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 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=] [,aio=] [,backup=] [,bps=] [,bps_rd=] [,bps_wr=] [,cache=] [,cyls=] [,discard=] [,format=] [,heads=] [,iops=] [,iops_max=] [,iops_rd=] [,iops_rd_max=] [,iops_wr=] [,iops_wr_max=] [,mbps=] [,mbps_max=] [,mbps_rd=] [,mbps_rd_max=] [,mbps_wr=] [,mbps_wr_max=] [,media=] [,model=] [,rerror=] [,secs=] [,serial=] [,snapshot=] [,trans=] [,werror=]` :: + +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=][,queues=][,rate=] [,tag=][,trunks=][,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=[[,hostnodes=] [,policy=]]` :: + +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=] [,aio=] [,backup=] [,bps=] [,bps_rd=] [,bps_wr=] [,cache=] [,cyls=] [,discard=] [,format=] [,heads=] [,iops=] [,iops_max=] [,iops_rd=] [,iops_rd_max=] [,iops_wr=] [,iops_wr_max=] [,mbps=] [,mbps_max=] [,mbps_rd=] [,mbps_rd_max=] [,mbps_wr=] [,mbps_wr_max=] [,media=] [,rerror=] [,secs=] [,serial=] [,snapshot=] [,trans=] [,werror=]` :: + +Use volume as SATA hard disk or CD-ROM (n is 0 to 5). + +`scsi[n]`: `[file=] [,aio=] [,backup=] [,bps=] [,bps_rd=] [,bps_wr=] [,cache=] [,cyls=] [,discard=] [,format=] [,heads=] [,iops=] [,iops_max=] [,iops_rd=] [,iops_rd_max=] [,iops_wr=] [,iops_wr_max=] [,iothread=] [,mbps=] [,mbps_max=] [,mbps_rd=] [,mbps_rd_max=] [,mbps_wr=] [,mbps_wr_max=] [,media=] [,queues=] [,secs=] [,serial=] [,snapshot=] [,trans=] [,werror=]` :: + +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=] [,manufacturer=] [,product=] [,serial=] [,sku=] [,uuid=] [,version=]` :: + +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=] [,usb3=]` :: + +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=] [,aio=] [,backup=] [,bps=] [,bps_rd=] [,bps_wr=] [,cache=] [,cyls=] [,discard=] [,format=] [,heads=] [,iops=] [,iops_max=] [,iops_rd=] [,iops_rd_max=] [,iops_wr=] [,iops_wr_max=] [,iothread=] [,mbps=] [,mbps_max=] [,mbps_rd=] [,mbps_rd_max=] [,mbps_wr=] [,mbps_wr_max=] [,media=] [,rerror=] [,secs=] [,serial=] [,snapshot=] [,trans=] [,werror=]` :: + +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 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/.conf' + + +DESCRIPTION +----------- +endif::manvolnum[] + +ifndef::manvolnum[] + Virtual Machine Configuration +============================== +include::attributes.txt[] +endif::manvolnum[] + +The '/etc/pve/qemu-server/.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[] -- 2.39.2