|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax
# HG changeset patch # User Ian Campbell <ian.campbell@xxxxxxxxxx> # Date 1320678758 0 # Node ID 291f6cb0d03e56e4edbe53c640c96dff85d9bf08 # Parent 705b2e659ff885379fb8b1c4aefbecfb3b8cc1eb docs: add a document describing the xl cfg file syntax Based on an initial version by Ian Jackson. I believe that all keys are now present in the document although there are are various omissions in the actual documentation of them. Hopefully however this covers the majority of the most interesting keys. Signed-off-by: Ian Campbell <ian.campbell@xxxxxxxxxx> diff -r 705b2e659ff8 -r 291f6cb0d03e docs/Makefile --- a/docs/Makefile Mon Nov 07 15:12:08 2011 +0000 +++ b/docs/Makefile Mon Nov 07 15:12:38 2011 +0000 @@ -11,7 +11,7 @@ DOC_MAN1SRC := $(wildcard man/*.pod.1) DOC_MAN1 := $(patsubst man/%.pod.1,man1/%.1,$(DOC_MAN1SRC)) DOC_MAN5 := $(patsubst man/%.pod.5,man5/%.5,$(DOC_MAN5SRC)) DOC_TEX := src/user.tex src/interface.tex -DOC_MARKDOWN := $(wildcard misc/*.markdown) +DOC_MARKDOWN := $(wildcard misc/*.markdown) $(wildcard user/*.markdown) DOC_PS := $(patsubst src/%.tex,ps/%.ps,$(DOC_TEX)) DOC_PDF := $(patsubst src/%.tex,pdf/%.pdf,$(DOC_TEX)) DOC_HTML := $(patsubst src/%.tex,html/%/index.html,$(DOC_TEX)) \ diff -r 705b2e659ff8 -r 291f6cb0d03e docs/user/xl-domain-config.markdown --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/user/xl-domain-config.markdown Mon Nov 07 15:12:38 2011 +0000 @@ -0,0 +1,554 @@ + # xl Domain Configuration + +To create a VM (a domain in Xen terminology, sometimes called a guest) +with xl requires the provision of a domain config file. Typically +these live in `/etc/xen/DOMAIN.cfg` where DOMAIN is the name of the +domain. + +## Work In Progress + +This document is a work in progress and contains items which require +further documentation and which are generally incomplete (marked with +XXX). However all options are included here whether or not they are +fully documented. + +Patches to improve incomplete items (or any other item) would be +greatfully received on the [xen-devel][] mailing list. Please see +[SubmittingXenPatches][] wiki page for information on how to submit a +patch to Xen. + +[xen-devel]: mailto:xen-devel@xxxxxxxxxxxxxxxxxxx +[SubmittingXenPatches]: http://wiki.xen.org/xenwiki/SubmittingXenPatches + +---------------------------------------- + +## Syntax + +A domain config file consists of a series of `KEY=VALUE` pairs. + +Some `KEY`s are mandatory, others are global options which apply to +any guest type while others relate only to specific guest types +(e.g. PV or HVM guests). + +A value `VALUE` is one of: + + * `"STRING"`: A string, surrounded by either single or double quotes. + * `NUMBER`: A number, in either decimal, octal (using a `0 prefix`) + or hexadecimal (using an `0x` prefix`). + * `BOOLEAN`: A `NUMBER` interpreted as `False` (`0`) or `True` (any + other value). + * `[ VALUE, VALUE, ... ]`: A list of `VALUES` of the above + types. Lists are homogeneous and are not nested. + +The semantics of each `KEY` defines which form of `VALUE` is required. + +---------------------------------------- + +## Mandatory Configuration Items + +The following key is mandatory for any guest type: + + * `name="NAME"`: Specifies the name of the domain. Names of domains + existing on a single host must be unique. + +## Selecting Guest Type + + * `builder=hvm`: Specifies that this is to be an HVM domain. That + is, a fully virtualised computer with emulated BIOS, disk and + network peripherals, etc. The default is a PV domain, suitable for + hosting Xen-aware guest operating systems. + +## Global Options + +The following options apply to guests of any type. + + * `uuid="UUID"`: Specifies the UUID of the domain. If not specified, + a fresh unique UUID will be generated. + + * `pool="CPUPOOLNAME"`: Put the guest's vcpus into the named cpu + pool. + + * `vcpus=N`: Start the guest with N vcpus initially online. + + * `maxvcpus=M`: Allow the guest to bring up a maximum of M vcpus. At + start of day if `vcpus=N` is less than `maxvcpus=M` then the first + `N` vcpus will be created online and the remainder will be offline. + + * `memory=MBYTES`: Start the guest with MBYTES megabytes of RAM. + + * `on_poweroff=ACTION`: Specifies what should be done with the domain + if it shuts itself down. The options are: + + * `destroy`: destroy the domain; + + * `restart`: destroy the domain and immediately create a new + domain with the same configuration; + + * `rename-restart`: rename the domain which terminated, and then + immediately create a new domain with the same configuration as + the original; + + * `preserve`: keep the domain. It can be examined, and later + destroyed with `xl destroy`. + + * `coredump-destroy`: write a "coredump" of the domain to + `/var/xen/dump/NAME` and then destroy the domain. + + * `coredump-restart`: write a "coredump" of the domain to + `/var/xen/dump/NAME` and then restart the domain. + + The default for `on_poweroff` is `destroy`. + + * `on_reboot=ACTION`: Action to take if the domain shuts down with a + reason code requesting a reboot. Default is `restart`. + + * `on_watchdog=ACTION`: Action to take if the domain shuts down due + to a Xen watchdog timeout. Default is `destroy`. + + * `on_crash=ACTION`: Action to take if the domain crashes. Default + is `destroy`. + + * `seclabel=LABEL`: Assign an XSM security label to this domain. + +## Devices + +The following options define the paravirtual, emulated and physical +devices which the guest will contain. + + * `disk=[ "DISK_SPEC_STRING", "DISK_SPEC_STRING", ...]`: Specifies + the disks (both emulated disks and Xen virtual block devices) which + are to be provided to the guest, and what objects on the they + should map to. See `docs/misc/xl-disk-configuration.txt`. + + * `vif=[ "NET_SPEC_STRING", "NET_SPEC_STRING", ...]`: Specifies the + networking provision (both emulated network adapters, and Xen + virtual interfaces) to provided to the guest. See + `docs/misc/xl-network-configuration.markdown`. + + * `vfb=[ "VFB_SPEC_STRING", "VFB_SPEC_STRING", ...]`: Specifies the + paravirtual framebuffer devices which should be supplied to the domain. + + This options does not control the emulated graphics card presented + to an HVM guest. See "Emulated VGA Graphics Device" below for how + to configure the emulated device. + + Each `VFB_SPEC_STRING` is a comma-separated list of `KEY=VALUE` + settings, from the following list: + + * `vnc=BOOLEAN`: Allow access to the display via the VNC + protocol. This enables the other VNC-related settings. + The default is to enable this. + + * `vnclisten="ADDRESS[:DISPLAYNUM]"`: Specifies the IP address, + and optionally VNC display number, to use. + + * `vncdisplay=DISPLAYNUM`: Specifies the VNC display number to + use. The actual TCP port number will be DISPLAYNUM+5900. + + * `vncunused=BOOLEAN`: Requests that the VNC display setup search + for a free TCP port to use. The actual display used can be + accessed with `xl vncviewer`. + + * `vncpasswd="PASSWORD"`: Specifies the password for the VNC + server. + + * `sdl=BOOLEAN`: Specifies that the display should be presented + via an X window (using Simple DirectMedia Layer). The default + is to not enable this mode + + * `opengl=BOOLEAN`: Enable OpenGL acceleration of the SDL + display. Only effects machines using + `device_model_version="qemu-xen-traditonal"` and only if the + device-model was compiled with OpenGL support. Disabled by default. + + * `keymap="LANG"`: Configure the keymap to use for the keyboard + associated with this display. If the input method does not + easily support raw keycodes (e.g. this is often the case when + using VNC) then this allows us to correctly map the input keys + into keycodes seen by the guest. The specific values which are + accepted are defined by the version of the device-model which + you are using. See "Keymaps" below of consult the `qemu(1)` + manpage. The default is `en-us`. + + * `display=XXX`: XXX written to xenstore backend for vfb but does not + appear to be used anywhere? + + * `authority=XXX`: XXX written to xenstore backend for vfb but does not + appear to be used anywhere? + + * `pci=[ "PCI_SPEC_STRING", "PCI_SPEC_STRING", ... ]`: Specifies the + host PCI devices to passthrough to this guest. Each `PCI_SPEC_STRING` + has the form `[DDDD:]BB:DD.F[@VSLOT],KEY=VALUE,KEY=VALUE,...` where: + + `DDDD:BB:DD.F` identifies the PCI device from the host perspective + in domain (`DDDD`), Bus (`BB`), Device (`DD`) and Function (`F`) + syntax. This is the same scheme as used in the output of `lspci` + for the device in question. Note: By default `lspci` will omit the + domain (`DDDD`) if it is zero and it is optional here also. You may + specify the function ('F') as '*' to indicate all functions. + + `@VSLOT` specifies the virtual device where the guest will see this + device. This is equivalent to the `DD` which the guest sees. In a + guest `DDDD` and `BB` are 0000:00. XXX how does this really work? + + Possible `KEY`s are: + + * `msitranslate=BOOLEAN`: XXX + * `power_mgmt=BOOLEAN`: XXX + +## Paravirtualised (PV) Guest Specific Options + +The following options apply only to Paravirtual guests. + + * `kernel="PATHNAME"`: Load the specified file as the kernel image (for + PV guests only). Either `kernel` or `bootloader` must be specified + for PV guests. + + * `ramdisk="PATHNAME"`: Load the specified file as the ramdisk (for PV + guests only). + + * `bootloader="PROGRAM"`: Run PROGRAM to find the kernel image and + ramdisk to use (for PV guests only). Normally PROGRAM would be + `pygrub`, which is an emulation of grub/grub2/syslinux. + + * `bootloader_args=STRING`: Append STRING (split into words at + whitespace) to the arguments to the `bootloader` program. XXX this + should be a list of strings. + + * `root="STRING"`: Append `root="STRING"` to the kernel command line + (Note: it is guest specific what meaning this has). + + * `extra="STRING"`: Append "STRING" to the kernel command line. + (Note: it is guest specific what meaning this has). + + * `e820_host=BOOLEAN`: Selects whether to expose the host e820 + (memory map) to the guest via the virtual e820. When this option is + false the guest psuedo-physical address space consists of a single + contiguous RAM region. When this option is specified the virtual + e820 instead reflects the host e820 and contains the same PCI + holes. The total amount of RAM represented by the memory map is + always the same, this option configures only how it is layed out. + + Exposing the host e820 to the guest gives the guest kernel the + opportunity to set aside the required part of its pseudo-physical + address space in order to provide address space to map + passedthrough PCI devices. It is guest Operaring System dependant + whether this option is required, specifically it is required when + using a mainline Linux ("pvops") kernel. This option defaults to + true if any PCI passthrough devices are configued and false + otherwise. If you do not configure any passthrough devices at + domain creation time but expect to hotplug devices later then you + should set this option. Conversely if your particular guest kernel + does not require this behaviour then it is safe to allow this to be + enabled but you may wish to disable it anyway. + +## Fully-virtualised (HVM) Guest Specific Options + +The following options apply only to HVM guests. + +### Boot Device + + * `boot=[c|d|n]`: Selects the emulated virtual device to boot + from. Options are hard disk (`c`), cd-rom (`d`) or network/PXE + (`n`). Multiple options can be given and will be attempted in the + order they are given. e.g. to boot from cd-rom but fallback to the + hard disk you can give `dc`. The default is `cd`. + +### Paging + +The following options control the mechanisms used to virtualise guest +memory. The defaults are selected to give the best results for the +common case and so you should normally leave these options +unspecified. + + * `hap=BOOLEAN`: Turns "hardware assisted paging" (the use of the + hardware' nested page table feature) on or off. Affects HVM guests + only. If turned off, Xen will run the guest in "shadow page table" + mode where the guest's page table updates and/or TLB flushes + etc. will be emulated. Use of HAP is the default when available. + + * `oos=BOOLEAN`: Turns "out of sync pagetables" on or off. When + running in shadow page table mode, the guest's page table updates + may be deferred as specified in the Intel/AMD architecture manuals. + However this may expose unexpected bugs in the guest, or find bugs + in Xen, so it is possible to disable this feature. Use of out of + sync page tables, when Xen thinks it appropriate, is the default. + + * `shadow_memory=MBYTES`: Number of megabytes to set aside for + shadowing guest pagetable pages (effectively acting as a cache of + translated pages) or to use for HAP state. By default this is 1MB + per guest vcpu plus 8KB per MB of guest RAM. You should not + normally need to adjust this value. However if you are not using + hardware assisted paging (i.e. you are using shadow mode) and your + guest workload consists of a large number of processes which do not + share address space then increasing this value may improve + performance. + +### Processor and Platform Features + +The following options allow various processor and platform level +features to be hidden or exposed from the guest's point of view. This +can be useful when running older guest Operating Systems which may +misbehave when faced with more modern features. In general you should +accept the defaults for these options wherever possible. + + * `pae=BOOLEAN`: Hide or expose the IA32 Physical Address + Extensions. These extensions make it possible for a 32 bit guest + Operating System to access more than 4GB of RAM. Enabling PAE also + enabled other features such as NX. PAE is required if you wish to + run a 64-bit guest Operating System. In general you should leave + this enabled and allow the guest Operating System to choose whether + or not to use PAE. (X86 only) + + * `acpi=BOOLEAN`: Expose ACPI (Advanced Configuration and Power + Interface) tables from the virtual firmware to the guest Operating + System. ACPI is required by most modern guest Operating + Systems. This option is enabled by default and usually you should + omit it. However it may be necessary to disable ACPI for + compatibility with some guest Operating Systems. + + * `apic=BOOLEAN`: Include information regarding APIC (Advanced + Programmable Interrupt Controller) in the firmware/BIOS tables on a + single processor guest. This causes the MP (multiprocessor) and PIR + (PCI Interrupt Routing) tables to be exported by the virtual + firmware. This option has no effect on a guest with multiple + virtual CPUS as they must always include these tables. This option + is enabled by default and you should usually omit it but it may be + necessary to disable these firmware tables when using certain older + guest Operating Systems. These tables have been superceded by newer + constructs within the ACPI tables. (X86 only) + + * `nx=BOOLEAN`: Hides or exposes the No-eXecute capability. This allows + a guest Operating system to map pages such that they cannot be + executed which can enhance security. This options requires that PAE + also be enabled. (X86 only) + + * `hpet=BOOLEAN`: Enables or disables HPET (High Precision Event + Timer). This option is enabled by default and you should usually + omit it. It may be necessary to disable the HPET in order to + improve compatibility with guest Operating Systems (X86 only) + + * `nestedhvm=BOOLEAN`: Enable or disables guest access to hardware + virtualisation features, e.g. it allows a guest Operating System to + also function as a hypervisor. This option is disabled by + default. You may want this option if you want to run another + hypervisor (including another copy of Xen) within a Xen guest or to + support a guest Operating System which uses hardware virtualisation + extensions (e.g. Windows XP compatibility mode on more modern + Windows OS). + +### Support for Paravirtualisation of HVM Guests + +The following options allow Paravirtualised features (such as devices) +to be exposed to the guest Operating System in an HVM guest. +Utilising these features requires specific guest support but when +available they will result in improved performance. + + * `xen_platform_pci=BOOLEAN`: Enable or disable the Xen platform PCI + device. The presence of this virtual device enables a guest + Operating System (subject to the availability of suitable drivers) + to make use of paravirtualisation features such as disk and network + devices etc. Enabling these drivers improves performance and is + strongly recommended when available. PV drivers are available for + various Operating Systems including [HVM + Linux][XenLinuxPVonHVMdrivers] and [Microsoft + Windows][XenWindowsGplPv]. + + [XenLinuxPVonHVMdrivers]: http://wiki.xen.org/xenwiki/XenLinuxPVonHVMdrivers + [XenWindowsGplPv]: http://wiki.xen.org/xenwiki/XenWindowsGplPv + + * `viridian=BOOLEAN`: Turns on or off the exposure of MicroSoft + Hyper-V (AKA viridian) compatible enlightenments to the guest. + These can improve performance of Microsoft Windows guests (XXX + which versions of Windows benefit?) + +### Device-Model Options + +The following options control the selection of the device-model. This +is the component which provides emulation of the virtual devices to an +HVM guest. For a PV guest a device-model is sometimes used to provide +backends for certain PV devices (most usually a virtual framebuffer +device). + + * `device_model_version="DEVICE-MODEL"`: Selects which variant of the + device-model should be used for this guest. Valid values are: + + * `qemu-xen-traditional`: Use the device-model based upon the + historical Xen fork of Qemu. This device-model is currently + the default. + + * `qemu-xen`: use the device-model merged into the upstream Qemu + project. This device-model will become the default in a future + version of Xen. + + It is recommended to accept the default value for new guests. If + you have existing guests then, dpeending on the nature of the guest + Operating System, you may wish to force them to use the device + model which they were installed with. + + * `device_model_override="PATH"`: Override the path to the binary to + be used as the device-model. The binary provided here MUST be + consistent with the `device_model_version` which you have + specified. You should not normally need to specify this option. + + * `device_model_stubdomain_override=BOOLEAN`: Override the use of + stubdomain based device-model. Normally this will be automatically + selected based upon the other features and options you have + selected. + + * `device_model_args=[ "ARG", "ARG", ...]`: Pass additional arbitrary + options on the devide-model command line. Each element in the list + is passed as an option to the device-model. + + * `device_model_args_pv=[ "ARG", "ARG", ...]`: Pass additional + arbitrary options on the devide-model command line for a PV device + model only. Each element in the list is passed as an option to the + device-model. + + * `device_model_args_hvm=[ "ARG", "ARG", ...]`: Pass additional + arbitrary options on the devide-model command line for an HVM + device model only. Each element in the list is passed as an option + to the device-model. + +### Emulated VGA Graphics Device + +The following options control the features of the emulated graphics +device. Many of these options behave similarly to the equivalent key +in the `VFB_SPEC_STRING` for configuring virtual frame buffer devices +(see above). + + * `videoram=MBYTES`: Sets the amount of RAM which the emulated video + card will contain, which in turn limits the resolutions and bit + depths which will be available. This option is only available when + using the `stdvga` option (see below). The default is 8MB which is + sufficient for e.g. 1600x1200 at 32bpp. When not using the `stdvga` + option the amount of video ram is fixed at 4MB which is sufficient + for 1024x768 at 32 bpp. + + * `stdvga=BOOLEAN`: Select a standard VGA card with VBE (VESA BIOS + Extensions) as the emulated graphics device. The default is false + which means to emulate a Cirrus Logic GD5446 VGA card. If your + guest supports VBE 2.0 or later (e.g. Windows XP onwards) then you + should enable this. + + * `vnc=BOOLEAN`: Allow access to the display via the VNC protocol. + This enables the other VNC-related settings. The default is to + enable this. + + * `vnclisten="ADDRESS[:DISPLAYNUM]": Specifies the IP address, and + optionally VNC display number, to use. + + * `vncdisplay=DISPLAYNUM`: Specifies the VNC display number to use. + The actual TCP port number will be DISPLAYNUM+5900. + + * `vncunused=BOOLEAN`: Requests that the VNC display setup search for + a free TCP port to use. The actual display used can be accessed + with `xl vncviewer`. + + * `vncpasswd="PASSWORD"`: Specifies the password for the VNC server. + + * `keymap="LANG"`: Configure the keymap to use for the keyboard + associated with this display. If the input method does not easily + support raw keycodes (e.g. this is often the case when using VNC) + then this allows us to correctly map the input keys into keycodes + seen by the guest. The specific values which are accepted are + defined by the version of the device-model which you are using. See + "Keymaps" below of consult the `qemu(1)` manpage. The default is + `en-us`. + + * `sdl=BOOLEAN`: Specifies that the display should be presented via + an X window (using Simple DirectMedia Layer). The default is not to + enable this mode. + + * `opengl=BOOLEAN`: Enable OpenGL acceleration of the SDL + display. Only effects machines using + `device_model_version="qemu-xen-traditonal"` and only if the + device-model was compiled with OpenGL support. Disabled by default. + + * `nographic=BOOLEAN`: Enable or disable the virtual graphics device. + The default is to provide a VGA graphics device but this option can + be used to disable it. + +### Spice Graphics Support + + * `spice=BOOLEAN`: XXX + + * `spiceport=XXX`: XXX + + * `spicetls_port=XXX`: XXX + + * `spicehost=XXX`: XXX + + * `spicedisable_ticketing=XXX`: XXX + + * `spiceagent_mouse=XXX`: XXX + +### Miscellaneous Emulated Hardware + + * `serial=DEVICE`: Redirect the virtual serial port to + `DEVICE`. Please see the `-serial` option in the `qemu(1)` manpage + for details of the valid `DEVICE` options. Default is `vc` when in + graphical mode and `stdio` if `nographics=1` is used. + + * `soundhw=DEVICE`: Select the virtual sound card to expose to the + guest. The valid devices are defined by the device model + configuration, please see the `qemu(1)` manpage for details. The + default is not to export any sound device. + + * `usb=BOOLEAN`: Enables or disables a USB bus in the guest. + + * `usbdevice=DEVICE`: Adds `DEVICE` to the USB bus. The USB bus must + also be enabled using `usb=1`. The most common use for this option + is `usbdevice=table` which adds pointer device using absolute + coordinates. Such devices function better than relative coordinate + devices (such as a standard mouse) since many methods of exporting + guest graphics (such as VNC) work better in this mode. Note that + this is independent of the actual pointer device you are using on + the host/client side. XXX should/could be a list of devices. + +### Unclassified HVM Specific Options + +These HVM specific options have not yet been documented or +classified. They almost certainly belong in a more appropriate +section. + + * `vpt_align=BOOLEAN`: Align the Virtual Platform Timer ??? XXX + Reduces interrupts? + + * `timer_mode=NUMBER`: Set mode for Virtual Timers XXX ??? should be + an enum of particular values. See HVM_PARAM_TIMER_MODE in + xen/include/public/hvm/params.h + +## Unclassified General Options + +These have not yet been fully documented or classified. They almost +certainly belong in a more appropriate section. + + * `gfx_passthrough=BOOLEAN`: Enable graphics device PCI passthrough. + XXX which device is passed through ? + + * `nomigrate=BOOLEAN`: Disable migration of this domain. This + enables certain other features which are incompatible with + migration (currently certain TSC modes XXX ?). + + * `tsc_mode=VALUE`: Specifies how the TSC (Time Stamp Counter) should + be provided to the guest. XXX ??? + + * `pci_msitranslate=BOOLEAN`: XXX + + * `pci_power_mgmt=BOOLEAN`: XXX + + * `cpuid=XXX`: XXX + +# Keymaps + +The keymaps available are defined by the device-model which you are +using. Commonly this includes: + + ar de-ch es fo fr-ca hu ja mk no pt-br sv + da en-gb et fr fr-ch is lt nl pl ru th + de en-us fi fr-be hr it lv nl-be pt sl tr + +The default is "en-us". + +See `qemu(1)` for more information. _______________________________________________ Xen-devel mailing list Xen-devel@xxxxxxxxxxxxxxxxxxx http://lists.xensource.com/xen-devel
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |