xl domain config file documentation & other bits

PATCH In review Ian Campbell 4 participants 25 messages Nov 7, 2011 – Nov 11, 2011

lore

Share & tools

lore

Ian Campbell

author

2011-11-07 15:13 UTC #0 lore raw

PATCH 1/1 xl domain config file documentation & other bits

The following contains a document describing the xl configuration file format and the keys therein.

There is also a few incidental bits and bobs relating to documentation.

IanJ, the branch you sent me with the basis for this doc had various other cleanups in it. I have pulled out the one which makes the "name" parameter mandatory but have left the rest.

Ian Campbell

author

2011-11-07 15:13 UTC #1 lore raw

PATCH 1/1 docs: report when we don't build docs due to a missing tool

# HG changeset patch
# User Ian Campbell <[email protected]>
# Date 1320678727 0
# Node ID 7a126dbf62d76d45a10ea55be9c354b1bd4f4bf1 # Parent c0702424afc5f7b972c26c6110f6489305844635
docs: report when we don't build docs due to a missing tool

It's useful if you are wondering why there are no docs..

Signed-off-by Ian Campbell <[email protected]>

docs/Makefile +6 -3

diff -r c0702424afc5 -r 7a126dbf62d7 docs/Makefile
@@ -58,7 +58,8 @@ python-dev-docs:
 .PHONY: man-pages
 man-pages:
 	@if which $(POD2MAN) 1>/dev/null 2>/dev/null; then \
-	$(MAKE) $(DOC_MAN1) $(DOC_MAN5); fi
+	$(MAKE) $(DOC_MAN1) $(DOC_MAN5); else              \
+	echo "pod2man not installed; skipping man-pages."; fi
 
 man1/%.1: man/%.pod.1 Makefile
 	$(INSTALL_DIR) $(@D)

@@ -120,14 +121,16 @@ html/%/index.html: src/%.tex
         echo "Running latex2html to generate $*/index.html ... "; \
 	$(LATEX2HTML) -split 0 -show_section_numbers -toc_depth 3 -nonavigation \
 	-numbered_footnotes -local_icons -noinfo -math -dir $(@D) \
-	$< 1>/dev/null 2>/dev/null ;fi
+	$< 1>/dev/null 2>/dev/null ; else \
+	echo "latex2html not installed; skipping $*."; fi
 
 html/%.html: %.markdown
 	@$(INSTALL_DIR) $(@D)
 	@set -e ; if which $(MARKDOWN) 1>/dev/null 2>/dev/null; then \
 	echo "Running markdown to generate $*.html ... "; \
 	$(MARKDOWN) $< > [email protected] ; \
-	$(call move-if-changed,[email protected],$@) ; fi
+	$(call move-if-changed,[email protected],$@) ; else \
+	echo "markdown not installed; skipping $*.html."; fi
 
 txt/%.txt: %.txt
 	$(INSTALL_DIR) $(@D)

Ian Campbell

author

2011-11-07 15:13 UTC #2 lore raw

PATCH 1/1 README: add markdown to dependency list

In reply to Ian Campbell

# HG changeset patch
# User Ian Campbell <[email protected]> # Date 1320678728 0
# Node ID 705b2e659ff885379fb8b1c4aefbecfb3b8cc1eb # Parent 7a126dbf62d76d45a10ea55be9c354b1bd4f4bf1
README: add markdown to dependency list

although this tool is strictly speaking optional we are providing various user docs in this format so increase the changes that they will install it.

Signed-off-by Ian Campbell <[email protected]>

README +1 -0

diff -r 7a126dbf62d7 -r 705b2e659ff8 README
@@ -55,6 +55,7 @@ provided by your OS distributor:
     * GNU gettext
     * 16-bit x86 assembler, loader and compiler (dev86 rpm or bin86 & bcc debs)
     * ACPI ASL compiler (iasl)
+    * markdown
 
 Second, you need to acquire a suitable kernel for use in domain 0. If
 possible you should use a kernel provided by your OS distributor. If

Ian Campbell

author

2011-11-07 15:13 UTC #3 lore raw

PATCH 1/1 docs: add a document describing the xl cfg file syntax

In reply to Ian Campbell

# HG changeset patch
# User Ian Campbell <[email protected]> # 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 <[email protected]>

docs/Makefile +1 -1

diff -r 705b2e659ff8 -r 291f6cb0d03e docs/Makefile
@@ -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)) \

docs/user/xl-domain-config.markdown new file +554 -0

554 lines not on this page · raw message

Ian Campbell

author

2011-11-09 15:00 UTC #4 lore raw

Re: [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

Quoted 4 lines · Ian Campbell

docs/user/xl-domain-config.markdown new file +3 -0
+### Spice Graphics Support
+
+ * `spice=BOOLEAN`: XXX

docs/user/xl-domain-config.markdown line 484

Quoted 10 lines

docs/user/xl-domain-config.markdown new file +10 -0

+
+ * `spiceport=XXX`: XXX
+
+ * `spicetls_port=XXX`: XXX
+
+ * `spicehost=XXX`: XXX
+
+ * `spicedisable_ticketing=XXX`: XXX
+
+ * `spiceagent_mouse=XXX`: XXX

Hi Zhou,

It seems that you added most of these commands to xl. Can I trouble you to write a few words about what they do?

Thanks,

Ian.

ZhouPeng

2011-11-10 05:18 UTC #5 lore raw

Re: [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

Quoted 2 lines · Ian Campbell

It seems that you added most of these commands to xl. Can I trouble you to write a few words about what they do?

Hi Ian,
This is the doc in line below.
Sorry not sent in a diff patch. I checked but It seems your doc patch has not been committed into the unstable.

Signed-off-by Zhou Peng <[email protected]>

### Spice Graphics Support

The following options control the features of SPICE.

* spice=BOOLEAN: Allow access to the display via the SPICE protocol. This enables the other SPICE-related settings.

* spicehost="ADDRESS": Specify the interface address to listen on if given, otherwise any interface.

* spiceport=NUMBER: Specify the port to listen on by the SPICE server if the SPICE is enabled.

* spicetls_port=NUMBER: Specify the secure port to listen on by the SPICE server if the SPICE is enabled. At least one of the spiceport or spicetls_port must be given if SPICE is enabled. NB. the options depending on spicetls_port have not been supported.

* spicedisable_ticketing=BOOLEAN: Enable client connection without password. The default is false. If it's false (set to 0), spicepasswd must be set.

* spicepasswd="PASSWORD": Specify the ticket password which is used by a client for connection.

* spiceagent_mouse=BOOLEAN: Whether SPICE agent is used for client mouse mode. The default is true (turn on)

Signature · 1 line

Zhou Peng

Ian Campbell

author

2011-11-10 08:04 UTC #6 lore raw

Re: [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

Quoted 9 lines · ZhouPeng

Quoted 2 lines · Ian Campbell
It seems that you added most of these commands to xl. Can I trouble you to write a few words about what they do?
Hi Ian,
This is the doc in line below.
Sorry not sent in a diff patch. I checked but It seems your doc patch has not been committed into the unstable.
Signed-off-by Zhou Peng <[email protected]>

Thanks Zhou, I'll add this to the end of my series and repost it.

Ian.

Quoted 29 lines

### Spice Graphics Support
The following options control the features of SPICE.
* spice=BOOLEAN: Allow access to the display via the SPICE protocol. This enables the other SPICE-related settings.
* spicehost="ADDRESS": Specify the interface address to listen on if given, otherwise any interface.
* spiceport=NUMBER: Specify the port to listen on by the SPICE server if the SPICE is enabled.
* spicetls_port=NUMBER: Specify the secure port to listen on by the SPICE server if the SPICE is enabled. At least one of the spiceport or spicetls_port must be given if SPICE is enabled. NB. the options depending on spicetls_port have not been supported.
* spicedisable_ticketing=BOOLEAN: Enable client connection without password. The default is false. If it's false (set to 0), spicepasswd must be set.
* spicepasswd="PASSWORD": Specify the ticket password which is used by a client for connection.
* spiceagent_mouse=BOOLEAN: Whether SPICE agent is used for client mouse mode. The default is true (turn on)

Ian Campbell

author

2011-11-10 08:10 UTC #7 lore raw

Re: [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

In reply to Ian Campbell

Tim, George:

Is this broadly accurate? In particular the bit about why one would use the shadow_memory option and the suggestion that it also controls the space used by the HAP overhead.

Cheers,
Ian.

Quoted 34 lines · Ian Campbell

docs/user/xl-domain-config.markdown new file +9 -0

+### 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"

docs/user/xl-domain-config.markdown new file +6 -0

+   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.

docs/user/xl-domain-config.markdown new file +11 -0

+   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

docs/user/xl-domain-config.markdown new file +2 -0

+   share address space then increasing this value may improve
+   performance.

Tim Deegan

2011-11-10 09:54 UTC #8 lore raw

Re: [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax\

Quoted 11 lines · Ian Campbell

Tim, George:
Is this broadly accurate? In particular the bit about why one would use the shadow_memory option and the suggestion that it also controls the space used by the HAP overhead.
Cheers,
Ian.
Quoted 1 line · Ian Campbell

Quoted 14 lines

Quoted 12 lines
docs/user/xl-domain-config.markdown new file +9 -0
+### 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"
docs/user/xl-domain-config.markdown line 268
Quoted 2 lines
docs/user/xl-domain-config.markdown new file +2 -0
+   mode where the guest's page table updates and/or TLB flushes
+   etc. will be emulated.  Use of HAP is the default when available.

Yep. Might be worth mentioning that HAP is called EPT and NPT (or RVI) by the hardware vendors.

Quoted 7 lines

docs/user/xl-domain-config.markdown line 275
Quoted 7 lines
+ * oos=BOOLEAN: Turns "out of sync pagetables" on or off. When
(quoted diff) +2 -0
+   running in shadow page table mode, the guest's page table updates
+   may be deferred as specified in the Intel/AMD architecture
manuals.
docs/user/xl-domain-config.markdown new file +3 -0
+   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.

Yep.

Quoted 10 lines

docs/user/xl-domain-config.markdown line 285

Quoted 10 lines

+ * shadow_memory=MBYTES: Number of megabytes to set aside for

docs/user/xl-domain-config.markdown new file +6 -0

+   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

docs/user/xl-domain-config.markdown new file +2 -0

+   share address space then increasing this value may improve
+   performance.

Actually in the bad case the processes _do_ share address space (otherwise the guest would be thrashing for RAM before it rnus out of shadow memory). Maybe 'a very large number of similar processes'?

Cheers,

Tim.

Ian Campbell

author

2011-11-10 09:58 UTC #9 lore raw

Re: [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax\

Quoted 21 lines · Tim Deegan

Quoted 20 lines · Ian Campbell
Tim, George:
Is this broadly accurate? In particular the bit about why one would use the shadow_memory option and the suggestion that it also controls the space used by the HAP overhead.
Cheers,
Ian.
Quoted 10 lines · Ian Campbell
docs/user/xl-domain-config.markdown new file +9 -0
+### 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

Quoted 8 lines

Quoted 5 lines
docs/user/xl-domain-config.markdown line 268
Quoted 5 lines
guests
+ only. If turned off, Xen will run the guest in "shadow page
table"
docs/user/xl-domain-config.markdown new file +2 -0
+   mode where the guest's page table updates and/or TLB flushes
+   etc. will be emulated.  Use of HAP is the default when available.
Yep. Might be worth mentioning that HAP is called EPT and NPT (or RVI) by the hardware vendors.

Good idea. Since I had to look them up:
EPT -- Extended Page Tables (Intel)
NPT -- Nested Page Tables (AMD)
RVI -- Rapid Virtualisation Indexing (vmware's name, I think?)

Quoted 22 lines

Quoted 8 lines
docs/user/xl-domain-config.markdown line 275
Quoted 8 lines
+ * oos=BOOLEAN: Turns "out of sync pagetables" on or off. When
(quoted diff) +2 -0
+   running in shadow page table mode, the guest's page table updates
+   may be deferred as specified in the Intel/AMD architecture
manuals.
docs/user/xl-domain-config.markdown new file +3 -0
+   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.
Yep.
Quoted 10 lines
docs/user/xl-domain-config.markdown line 285
Quoted 10 lines
+ * shadow_memory=MBYTES: Number of megabytes to set aside for
docs/user/xl-domain-config.markdown new file +6 -0
+   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
docs/user/xl-domain-config.markdown new file +2 -0
+   share address space then increasing this value may improve
+   performance. 

Quoted 3 lines

Actually in the bad case the processes _do_ share address space (otherwise the guest would be thrashing for RAM before it rnus out of shadow memory). Maybe 'a very large number of similar processes'?

Sounds fine, thanks!

Quoted 4 lines

Cheers,
Tim.

Tim Deegan

2011-11-10 10:11 UTC #10 lore raw

Re: [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax\

Quoted 7 lines · Ian Campbell

Quoted 2 lines
Yep. Might be worth mentioning that HAP is called EPT and NPT (or RVI) by the hardware vendors.
Good idea. Since I had to look them up:
EPT -- Extended Page Tables (Intel)
NPT -- Nested Page Tables (AMD)
RVI -- Rapid Virtualisation Indexing (vmware's name, I think?)

RVI is AMD's marketing name for NPT, I think, but it never made it into the technical manuals.

VMware doesn't really have a generic name for HAP; they call it 'hardware MMU' in some docs but EPT/RVI in their UI. Microsoft calls it SLAT (?!) for Second-Level Address Translation.

Tim.

Ian Campbell

author

2011-11-10 10:13 UTC #11 lore raw

Re: [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax\

Quoted 11 lines · Tim Deegan

Quoted 7 lines · Ian Campbell
Quoted 2 lines
Yep. Might be worth mentioning that HAP is called EPT and NPT (or RVI) by the hardware vendors.
Good idea. Since I had to look them up:
EPT -- Extended Page Tables (Intel)
NPT -- Nested Page Tables (AMD)
RVI -- Rapid Virtualisation Indexing (vmware's name, I think?)
RVI is AMD's marketing name for NPT, I think, but it never made it into the technical manuals.

Thanks, Google spat out some vmware docs as the first hit. I'll include both names.

Quoted 3 lines

VMware doesn't really have a generic name for HAP; they call it 'hardware MMU' in some docs but EPT/RVI in their UI. Microsoft calls it SLAT (?!) for Second-Level Address Translation.

Nice.

Ian.

Stefano Stabellini

2011-11-10 11:37 UTC #12 lore raw

Re: [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

In reply to Ian Campbell

Quoted 7 lines · Ian Campbell

# HG changeset patch
# User Ian Campbell <[email protected]> # Date 1320678758 0
# Node ID 291f6cb0d03e56e4edbe53c640c96dff85d9bf08 # Parent 705b2e659ff885379fb8b1c4aefbecfb3b8cc1eb
docs: add a document describing the xl cfg file syntax

Quoted 5 lines

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.).

Quoted 67 lines

Signed-off-by Ian Campbell <[email protected]>

diff -r 705b2e659ff8 -r 291f6cb0d03e docs/Makefile

docs/Makefile Mon Nov 07 15:12:38 2011 +0000 renamed from docs/Makefile Mon Nov 07 15:12:08 2011 +0000 +1 -1

@@ -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

docs/user/xl-domain-config.markdown Mon Nov 07 15:12:38 2011 +0000 renamed from dev/null Thu Jan 01 00:00:00 1970 +0000 +49 -0

@@ -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:[email protected]
+[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:

docs/user/xl-domain-config.markdown Mon Nov 07 15:12:38 2011 +0000 line 59

Quoted 10 lines

docs/user/xl-domain-config.markdown Mon Nov 07 15:12:38 2011 +0000 renamed from dev/null Thu Jan 01 00:00:00 1970 +0000 +10 -0

+
+ * `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.

[...]

Quoted 12 lines

docs/user/xl-domain-config.markdown Mon Nov 07 15:12:38 2011 +0000 renamed from dev/null Thu Jan 01 00:00:00 1970 +0000 +12 -0

+
+## 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

docs/user/xl-domain-config.markdown Mon Nov 07 15:12:38 2011 +0000 line 81

Quoted 10 lines

docs/user/xl-domain-config.markdown Mon Nov 07 15:12:38 2011 +0000 renamed from dev/null Thu Jan 01 00:00:00 1970 +0000 +10 -0

+   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.

[...]

docs/user/xl-domain-config.markdown Mon Nov 07 15:12:38 2011 +0000 line 83

Quoted 2 lines

docs/user/xl-domain-config.markdown Mon Nov 07 15:12:38 2011 +0000 renamed from dev/null Thu Jan 01 00:00:00 1970 +0000 +2 -0
+ * `tsc_mode=VALUE`: Specifies how the TSC (Time Stamp Counter) should
+   be provided to the guest.  XXX ???

see docs/misc/tscmode.txt

Ian Campbell

author

2011-11-10 11:42 UTC #13 lore raw

Re: [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

Quoted 10 lines · Stefano Stabellini

Quoted 9 lines · Ian Campbell
# HG changeset patch
# User Ian Campbell <[email protected]> # 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.

Quoted 7 lines

Quoted 3 lines
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.).

If there is a good markdown->man converter I'm all for using it.

Quoted 10 lines

docs/user/xl-domain-config.markdown line 59
Quoted 6 lines
docs/user/xl-domain-config.markdown new file +6 -0
+## 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.

I remember thinking that too, I wonder why I didn't actually make the change. I will do so now.

Quoted 19 lines

[...]

Quoted 16 lines

docs/user/xl-domain-config.markdown new file +16 -0

+
+## 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`.
+

Quoted 8 lines

docs/user/xl-domain-config.markdown line 133
Quoted 6 lines
+ * vfb=[ "VFB_SPEC_STRING", "VFB_SPEC_STRING", ...]: Specifies the
docs/user/xl-domain-config.markdown new file +5 -0
+   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.

Really, I thought that it was possible for a PVHVM to have a PV FB too? Perhaps only in theory?

Quoted 7 lines

[...]
Quoted 2 lines
+ * tsc_mode=VALUE: Specifies how the TSC (Time Stamp Counter) should
+ be provided to the guest. XXX ???
see docs/misc/tscmode.txt

I just posted a patch to update this section. I hadn't noticed this doc so the snarky comment in that patch now seems a little unwarranted...

Ian.

Quoted 1 line

Stefano Stabellini

2011-11-10 11:46 UTC #14 lore raw

Re: [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

Quoted 5 lines · Ian Campbell

Quoted 3 lines
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.).
If there is a good markdown->man converter I'm all for using it.

well, I am not sure if any of them are good, but a badly formatted manpage is still better than no manpage at all

Quoted 25 lines

Quoted 16 lines

docs/user/xl-domain-config.markdown new file +16 -0

+
+## 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`.
+

Quoted 8 lines

docs/user/xl-domain-config.markdown line 133
Quoted 6 lines
+ * vfb=[ "VFB_SPEC_STRING", "VFB_SPEC_STRING", ...]: Specifies the
docs/user/xl-domain-config.markdown new file +5 -0
+   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.

Quoted 2 lines

Really, I thought that it was possible for a PVHVM to have a PV FB too? Perhaps only in theory?

Only in theory, there is no support for it at the moment and I don't think there will be anytime soon.

Stefano Stabellini

2011-11-10 12:23 UTC #15 lore raw

Re: [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

Quoted 9 lines · Stefano Stabellini

Quoted 5 lines · Ian Campbell
Quoted 3 lines
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.).
If there is a good markdown->man converter I'm all for using it.
well, I am not sure if any of them are good, but a badly formatted manpage is still better than no manpage at all

I take it back: manpages generated by pandoc are unreadble but ronn seems to work pretty well

Ian Campbell

author

2011-11-11 13:06 UTC #16 lore raw

Re: [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

Quoted 6 lines · Stefano Stabellini

Quoted 5 lines · Stefano Stabellini
Quoted 4 lines · Ian Campbell
Quoted 3 lines
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.).

Quoted 7 lines

Quoted 4 lines
Quoted 1 line
If there is a good markdown->man converter I'm all for using it.
well, I am not sure if any of them are good, but a badly formatted manpage is still better than no manpage at all
I take it back: manpages generated by pandoc are unreadble but ronn seems to work pretty well

Not widely available though :-(

I can reformat as pod but I'd like to hear from IanJ first since this is based on his first draft which was in markdown.

Ian.

Ian Campbell

author

2011-11-07 15:13 UTC #17 lore raw

PATCH 1/1 docs: fix references from xl man page to xldomain.cfg manpage

In reply to Ian Campbell

# HG changeset patch
# User Ian Campbell <[email protected]>
# Date 1320678761 0
# Node ID 25c3e859855f71cf25a0d607736821d4858d880a
# Parent 291f6cb0d03e56e4edbe53c640c96dff85d9bf08
docs: fix references from xl man page to xldomain.cfg manpage.

They should reference the xl-domain-config document. pod2html (which I will call shortly) doesn't like these and reports: "cannot resolve L<xldomain.cfg> in paragraph" and similar.

Signed-off-by Ian Campbell <[email protected]>

docs/man/xl.pod.1 +14 ~~-13~~

diff -r 291f6cb0d03e -r 25c3e859855f docs/man/xl.pod.1
@@ -54,8 +54,9 @@ previously, most commands take I<domain-
 
 =item B<create> [I<OPTIONS>] I<configfile>
 
-The create subcommand requires a config file: see L<xldomain.cfg> for
-full details of that file format and possible options.
+The create subcommand requires a config file: see
+F<xl-domain-config> for full details of that file format and
+possible options.
 
 I<configfile> can either be an absolute path to a file, or a relative
 path to a file located in /etc/xen.

@@ -232,7 +233,7 @@ FIXME: Why would you ever see this state
 
 The domain has crashed, which is always a violent ending.  Usually
 this state can only occur if the domain has been configured not to
-restart on crash.  See L<xldomain.cfg> for more info.
+restart on crash.  See F<xl-domain-config> for more info.
 
 =item B<d - dying>

@@ -319,8 +320,8 @@ executed the reboot action, which may be
 domain actually reboots.
 
 The behavior of what happens to a domain when it reboots is set by the
-B<on_reboot> parameter of the xldomain.cfg file when the domain was
-created.
+B<on_reboot> parameter of the domain configuration file when the
+domain was created.
 
 =item B<restore> [I<OPTIONS>] [I<ConfigFile>] I<CheckpointFile>

@@ -372,8 +373,8 @@ services must be shutdown in the domain.
 immediately after signally the domain unless that B<-w> flag is used.
 
 The behavior of what happens to a domain when it reboots is set by the
-B<on_shutdown> parameter of the xldomain.cfg file when the domain was
-created.
+B<on_shutdown> parameter of the domain configuration file when the
+domain was created.
 
 B<OPTIONS>

@@ -699,7 +700,7 @@ The domain id of the guest domain that t
 =item I<disc-spec-component>
 
 A disc specification in the same format used for the B<disk> variable in
-the domain config file. See L<xldomain.cfg>.
+the domain config file. See F<xl-disk-configuration>.
 
 =back

@@ -733,9 +734,9 @@ How the device should be presented to th
 
 =item I<be-dev>
 
-the device in the backend domain (usually domain 0) to be exported; it can be a
-path to a file (file://path/to/file.iso). See B<disk> in L<xldomain.cfg> for the
-details.
+the device in the backend domain (usually domain 0) to be exported; it
+can be a path to a file (file://path/to/file.iso). See B<disk> in
+F<xl-domain-config> for the details.
 
 =back

@@ -754,7 +755,7 @@ I<VirtualDevice> is the cdrom device in 
 
 Creates a new network device in the domain specified by I<domain-id>.
 I<network-device> describes the device to attach, using the same format as the
-B<vif> string in the domain config file. See L<xldomain.cfg> for the
+B<vif> string in the domain config file. See F<xl-domain-config> for the
 description.
 
 =item B<network-detach> I<domain-id> I<devid|mac>

@@ -795,7 +796,7 @@ List pass-through pci devices for a doma
 
 =head1 SEE ALSO
 
-B<xldomain.cfg>(5), B<xlcpupool.cfg>(5), B<xentop>(1)
+F<xl-domain-config>, B<xlcpupool.cfg>(5), B<xentop>(1)
 
 =head1 AUTHOR

docs/man/xm.pod.1 +2 -2

diff -r 291f6cb0d03e -r 25c3e859855f docs/man/xm.pod.1
@@ -71,7 +71,7 @@ Use the key combination Ctrl+] to detach
 
 The create subcommand requires a config file and can optionally take a
 series of I<vars> that add to or override variables defined
-in the config file.  See L<xmdomain.cfg> for full details of that file
+in the config file.  See F<xmdomain.cfg> for full details of that file
 format, and possible options used in either the configfile or for I<vars>.
 
 I<configfile> can either be an absolute path to a file, or a relative

@@ -301,7 +301,7 @@ FIXME: Why would you ever see this state
 
 The domain has crashed, which is always a violent ending.  Usually
 this state can only occur if the domain has been configured not to
-restart on crash.  See L<xmdomain.cfg> for more info.
+restart on crash.  See F<xmdomain.cfg> for more info.
 
 =item B<d - dying>

Ian Campbell

author

2011-11-07 15:13 UTC #18 lore raw

PATCH 1/1 docs: install html and txt versions of manpages

In reply to Ian Campbell

# HG changeset patch
# User Ian Campbell <[email protected]> # Date 1320678761 0
# Node ID 2f1fbfd8880858dba3fe18c811e3926293b6030b # Parent 25c3e859855f71cf25a0d607736821d4858d880a
docs: install html and txt versions of manpages

Signed-off-by Ian Campbell <[email protected]>

docs/Docs.mk +2 -0

diff -r 25c3e859855f -r 2f1fbfd88808 docs/Docs.mk
@@ -5,6 +5,8 @@ FIG2DEV		:= fig2dev
 LATEX2HTML	:= latex2html
 DOXYGEN		:= doxygen
 POD2MAN		:= pod2man
+POD2HTML	:= pod2html
+POD2TEXT	:= pod2text
 DOT		:= dot
 NEATO		:= neato
 MARKDOWN	:= markdown

docs/Makefile +28 -3

diff -r 25c3e859855f -r 2f1fbfd88808 docs/Makefile
@@ -15,9 +15,13 @@ DOC_MARKDOWN	:= $(wildcard misc/*.markdo
 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)) \
-		   $(patsubst %.markdown,html/%.html,$(DOC_MARKDOWN))
+		   $(patsubst %.markdown,html/%.html,$(DOC_MARKDOWN)) \
+		   $(patsubst man/%.pod.1,html/man/%.1.html,$(DOC_MAN1SRC)) \
+		   $(patsubst man/%.pod.5,html/man/%.5.html,$(DOC_MAN5SRC))
 DOC_TXT         := $(patsubst %.txt,txt/%.txt,$(wildcard misc/*.txt)) \
-		   $(patsubst %.markdown,txt/%.txt,$(DOC_MARKDOWN))
+		   $(patsubst %.markdown,txt/%.txt,$(DOC_MARKDOWN)) \
+		   $(patsubst man/%.pod.1,txt/man/%.1.txt,$(DOC_MAN1SRC)) \
+		   $(patsubst man/%.pod.5,txt/man/%.5.txt,$(DOC_MAN5SRC))
 
 GFX = $(patsubst %.fig, %.eps, $(wildcard figs/*.fig))

@@ -76,7 +80,7 @@ clean:
 	$(MAKE) -C xen-api clean
 	rm -rf .word_count *.aux *.dvi *.bbl *.blg *.glo *.idx *~ 
 	rm -rf *.ilg *.log *.ind *.toc *.bak core
-	rm -rf $(GFX) ps pdf html
+	rm -rf $(GFX) ps pdf html txt
 	rm -rf api
 	rm -rf man5
 	rm -rf man1

@@ -132,6 +136,16 @@ html/%.html: %.markdown
 	$(call move-if-changed,[email protected],$@) ; else \
 	echo "markdown not installed; skipping $*.html."; fi
 
+html/man/%.1.html: man/%.pod.1 Makefile
+	$(INSTALL_DIR) $(@D)
+	$(POD2HTML) --infile=$< [email protected]
+	$(call move-if-changed,[email protected],$@)
+
+html/man/%.5.html: man/%.pod.5 Makefile
+	$(INSTALL_DIR) $(@D)
+	$(POD2HTML) --infile=$< [email protected]
+	$(call move-if-changed,[email protected],$@)
+
 txt/%.txt: %.txt
 	$(INSTALL_DIR) $(@D)
 	cp $< [email protected]

@@ -141,3 +155,14 @@ txt/%.txt: %.markdown
 	$(INSTALL_DIR) $(@D)
 	cp $< [email protected]
 	$(call move-if-changed,[email protected],$@)
+
+txt/man/%.1.txt: man/%.pod.1 Makefile
+	$(INSTALL_DIR) $(@D)
+	$(POD2TEXT) $< [email protected]
+	$(call move-if-changed,[email protected],$@)
+
+txt/man/%.5.txt: man/%.pod.5 Makefile
+	$(INSTALL_DIR) $(@D)
+	$(POD2TEXT) $< [email protected]
+	$(call move-if-changed,[email protected],$@)
+

Ian Campbell

author

2011-11-07 15:13 UTC #19 lore raw

PATCH 1/1 xl: the name field in a guest config file is mandatory

In reply to Ian Campbell

# HG changeset patch
# User Ian Campbell <[email protected]> # Date 1320678761 0
# Node ID 83c6d49df549f663291dbf032de70d6bab149feb # Parent 2f1fbfd8880858dba3fe18c811e3926293b6030b
xl: the name field in a guest config file is mandatory

Signed-off-by Ian Campbell <[email protected]>

tools/libxl/xl_cmdimpl.c +4 -2

diff -r 2f1fbfd88808 -r 83c6d49df549 tools/libxl/xl_cmdimpl.c
@@ -575,8 +575,10 @@ static void parse_config_data(const char
     if (!xlu_cfg_get_long (config, "hap", &l))
         c_info->hap = l;
 
-    if (xlu_cfg_replace_string (config, "name", &c_info->name))
-        c_info->name = strdup("test");
+    if (xlu_cfg_replace_string (config, "name", &c_info->name)) {
+        fprintf(stderr, "Domain name must be specified.");
+        exit(1);
+    }
 
     if (!xlu_cfg_get_string (config, "uuid", &buf) ) {
         if ( libxl_uuid_from_string(&c_info->uuid, buf) ) {

Ian Campbell

author

2011-11-07 15:13 UTC #20 lore raw

PATCH 1/1 docs: generate docs direct into final filename

In reply to Ian Campbell

# HG changeset patch
# User Ian Campbell <[email protected]> # Date 1320678761 0
# Node ID e97a5f1943e0a3641f9415e15bdeb991cf1c3bdd # Parent 83c6d49df549f663291dbf032de70d6bab149feb
docs: generate docs direct into final filename

Nothing depends on the final document so there is not much point in generating to a tempfile and move-if-changed.

Signed-off-by Ian Campbell <[email protected]>

docs/Makefile +7 ~~-14~~

diff -r 83c6d49df549 -r e97a5f1943e0 docs/Makefile
@@ -132,37 +132,30 @@ html/%.html: %.markdown
 	@$(INSTALL_DIR) $(@D)
 	@set -e ; if which $(MARKDOWN) 1>/dev/null 2>/dev/null; then \
 	echo "Running markdown to generate $*.html ... "; \
-	$(MARKDOWN) $< > [email protected] ; \
-	$(call move-if-changed,[email protected],$@) ; else \
+	$(MARKDOWN) $< > $@ ; else \
 	echo "markdown not installed; skipping $*.html."; fi
 
 html/man/%.1.html: man/%.pod.1 Makefile
 	$(INSTALL_DIR) $(@D)
-	$(POD2HTML) --infile=$< [email protected]
-	$(call move-if-changed,[email protected],$@)
+	$(POD2HTML) --infile=$< --outfile=$@
 
 html/man/%.5.html: man/%.pod.5 Makefile
 	$(INSTALL_DIR) $(@D)
-	$(POD2HTML) --infile=$< [email protected]
-	$(call move-if-changed,[email protected],$@)
+	$(POD2HTML) --infile=$< --outfile=$@
 
 txt/%.txt: %.txt
 	$(INSTALL_DIR) $(@D)
-	cp $< [email protected]
-	$(call move-if-changed,[email protected],$@)
+	cp $< $@
 
 txt/%.txt: %.markdown
 	$(INSTALL_DIR) $(@D)
-	cp $< [email protected]
-	$(call move-if-changed,[email protected],$@)
+	cp $< $@
 
 txt/man/%.1.txt: man/%.pod.1 Makefile
 	$(INSTALL_DIR) $(@D)
-	$(POD2TEXT) $< [email protected]
-	$(call move-if-changed,[email protected],$@)
+	$(POD2TEXT) $< $@
 
 txt/man/%.5.txt: man/%.pod.5 Makefile
 	$(INSTALL_DIR) $(@D)
-	$(POD2TEXT) $< [email protected]
-	$(call move-if-changed,[email protected],$@)
+	$(POD2TEXT) $< $@

Ian Campbell

author

2011-11-07 16:06 UTC #21 lore raw

PATCH 1/1 docs: xlexample.hvm is missing "builder = 'hvm'"

In reply to Ian Campbell

# HG changeset patch
# User Ian Campbell <[email protected]> # Date 1320681787 0
# Node ID e4a5b7b7f9ac739bb350080524279580086e0ad9 # Parent e97a5f1943e0a3641f9415e15bdeb991cf1c3bdd
docs: xlexample.hvm is missing "builder = 'hvm'"

This is rather critical...

Signed-off-by Ian Campbell <[email protected]>

tools/examples/xlexample.hvm +3 -0

diff -r e97a5f1943e0 -r e4a5b7b7f9ac tools/examples/xlexample.hvm
@@ -5,6 +5,9 @@
 # This is a fairly minimal example of what is required for an
 # HVM guest. For a more complete guide see <XXX Document TBD>
 
+# This configures an HVM rather than PV guest
+builder = "hvm"
+
 # Guest name
 name = "example.hvm"

Ian Campbell

author

2011-11-07 16:06 UTC #22 lore raw

PATCH 1/1 docs: xlexample.*: reference xl-domain-config document

In reply to Ian Campbell

# HG changeset patch
# User Ian Campbell <[email protected]> # Date 1320681846 0
# Node ID 30c6d81d3509a35365ac4bd68bdfdc035f768ff3 # Parent e4a5b7b7f9ac739bb350080524279580086e0ad9
docs: xlexample.*: reference xl-domain-config document

Signed-off-by Ian Campbell <[email protected]>

tools/examples/xlexample.hvm +1 -1

diff -r e4a5b7b7f9ac -r 30c6d81d3509 tools/examples/xlexample.hvm
@@ -3,7 +3,7 @@
 # =====================================================================
 #
 # This is a fairly minimal example of what is required for an
-# HVM guest. For a more complete guide see <XXX Document TBD>
+# HVM guest. For a more complete guide see <xl-domain-config>
 
 # This configures an HVM rather than PV guest
 builder = "hvm"

tools/examples/xlexample.pvlinux +1 -1

diff -r e4a5b7b7f9ac -r 30c6d81d3509 tools/examples/xlexample.pvlinux
@@ -3,7 +3,7 @@
 # =====================================================================
 #
 # This is a fairly minimal example of what is required for a
-# Paravirtualised Linux guest. For a more complete guide see <XXX Document TBD>
+# Paravirtualised Linux guest. For a more complete guide see <xl-domain-config>
 
 # Guest name
 name = "example.pvlinux"

Ian Campbell

author

2011-11-07 16:07 UTC #23 lore raw

In reply to Ian Campbell

Quoted 2 lines · Ian Campbell

The following contains a document describing the xl configuration file format and the keys therein.

I just sent 2 additional patches:

[PATCH 8 of 7] docs: xlexample.hvm is missing "builder = 'hvm'" [PATCH 9 of 7] docs: xlexample.*: reference xl-domain-config document

Ian.

Ian Campbell

author

2011-11-10 08:06 UTC #24 lore raw

PATCH 1/1 docs: add spice options to xl domain cfg document

In reply to Ian Campbell

# HG changeset patch
# User Ian Campbell <[email protected]> # Date 1320912366 0
# Node ID ceebf46a339d6c5e1bb2f91abe8a7ed0cc0178bf # Parent 30c6d81d3509a35365ac4bd68bdfdc035f768ff3
docs: add spice options to xl domain cfg document

Signed-off-by Zhou Peng <[email protected]>

Signed-off-by Ian Campbell <[email protected]>

docs/user/xl-domain-config.markdown +20 -6

diff -r 30c6d81d3509 -r ceebf46a339d docs/user/xl-domain-config.markdown
@@ -471,17 +471,31 @@ in the `VFB_SPEC_STRING` for configuring
 
 ### Spice Graphics Support
 
- * `spice=BOOLEAN`: XXX
+The following options control the features of SPICE.
 
- * `spiceport=XXX`: XXX
+ * `spice=BOOLEAN`: Allow access to the display via the SPICE protocol.
+    This enables the other SPICE-related settings.
 
- * `spicetls_port=XXX`: XXX
+ * `spicehost="ADDRESS"`: Specify the interface address to listen on if
+    given, otherwise any interface.
 
- * `spicehost=XXX`: XXX
+ * `spiceport=NUMBER`: Specify the port to listen on by the SPICE server
+    if the SPICE is enabled.
 
- * `spicedisable_ticketing=XXX`: XXX
+ * `spicetls_port=NUMBER`: Specify the secure port to listen on
+    by the SPICE server if the SPICE is enabled. At least one of the
+    spiceport or spicetls_port must be given if SPICE is enabled.
+    NB. the options depending on spicetls_port have not been supported.
 
- * `spiceagent_mouse=XXX`: XXX
+ * `spicedisable_ticketing=BOOLEAN`: Enable client connection
+    without password. The default is false. If it's false (set to 0),
+    spicepasswd must be set.
+
+ * `spicepasswd="PASSWORD"`: Specify the ticket password which is used by
+    a client for connection.
+
+ * `spiceagent_mouse=BOOLEAN`: Whether SPICE agent is used
+    for client mouse mode. The default is true (turn on)
 
 ### Miscellaneous Emulated Hardware