On Mon, 7 Nov 2011, Ian Campbell wrote:
> # 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.
I think it would be very useful as a manpage.
If we really want to keep it in markdown rather than pod, we could still
find a way to convert it into a manpage (using ronn, pandoc, etc.).
> 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.
I think builder=[hvm|pv] would make it clearer what the options are. I
know that the idea is that a pv guest doesn't need this key pair but I
think that as it is can be confusing.
[...]
> +
> +## 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.
and it is only relevant for PV guests.
[...]
> + * `tsc_mode=VALUE`: Specifies how the TSC (Time Stamp Counter) should
> + be provided to the guest. XXX ???
see docs/misc/tscmode.txt
_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-devel
|
Home