From 9a2ec00a0552d1eb6ba9a2787e7042baab876cff Mon Sep 17 00:00:00 2001 From: Daniel Veillard Date: Mon, 20 Feb 2006 23:08:47 +0000 Subject: [PATCH] * src/libvirt.c src/xend_internal.c src/xend_internal.h: move the XML dump function around to make sure all entry points are centralized in libvirt.c and also avoid doc generation troubles. * docs/examples/Makefile.am docs/examples/index.py: fix the makefile a bit. * TODO: updated * docs/format.html: added a description of the XML used for the domains. * docs//*: rebuilt Daniel --- ChangeLog | 12 ++++ TODO | 1 + docs/APIchunk0.html | 22 +++++-- docs/APIchunk1.html | 14 ++++- docs/APIchunk2.html | 13 +++- docs/FAQ.html | 12 ++-- docs/architecture.html | 2 +- docs/bugs.html | 2 +- docs/downloads.html | 5 +- docs/examples/Makefile.am | 4 +- docs/examples/index.py | 5 +- docs/format.html | 68 ++++++++++++++++++++ docs/html/libvirt-libvirt.html | 6 +- docs/index.html | 5 +- docs/intro.html | 10 +-- docs/libvir.html | 111 ++++++++++++++++++++++++++++++--- docs/libvirt-api.xml | 10 +-- docs/libvirt-refs.xml | 71 ++++++++++++++++++--- docs/news.html | 2 +- docs/site.xsl | 8 +-- src/libvirt.c | 25 +++++++- src/xend_internal.c | 16 ++--- src/xend_internal.h | 9 +++ 23 files changed, 358 insertions(+), 75 deletions(-) create mode 100644 docs/format.html diff --git a/ChangeLog b/ChangeLog index 3cbe6a057a..774b83ee53 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,15 @@ +Tue Feb 21 00:06:30 CET 2006 Daniel Veillard + + * src/libvirt.c src/xend_internal.c src/xend_internal.h: move the + XML dump function around to make sure all entry points are centralized + in libvirt.c and also avoid doc generation troubles. + * docs/examples/Makefile.am docs/examples/index.py: fix the makefile + a bit. + * TODO: updated + * docs/format.html: added a description of the XML used for the + domains. + * docs//*: rebuilt + Mon Feb 20 21:48:55 CET 2006 Daniel Veillard * docs/examples/examples.xsl docs/examples/index.html diff --git a/TODO b/TODO index c3c82a2ddd..e812b95869 100644 --- a/TODO +++ b/TODO @@ -10,6 +10,7 @@ TODO: - track change of xend API, XML-RPC, UUID based lookup and naming - API for the Node: extracting informations, selecting scheduling policy - better resources allocation APIs (%CPU, set memory) +- DTD/RNG/XSD schemas for the XML Domain descriptions Probable TODOs: - event on big domain state change (create, crashed, paused, shutdown, destroy) diff --git a/docs/APIchunk0.html b/docs/APIchunk0.html index 7370ed3ff1..ec44579b6e 100644 --- a/docs/APIchunk0.html +++ b/docs/APIchunk0.html @@ -4,7 +4,6 @@ g-r s-z

Letter A:

ABI
_virDomainInfo
-
API
virDomainCreateLinux
APIs
virConnectOpenReadOnly
After
virDomainSave

Letter C:

CPU
virDomainSuspend
@@ -37,6 +36,7 @@ virDomainGetMaxMemory
virDomainGetName
virDomainGetOSType
+virDomainGetXMLDesc
virDomainLookupByID
virDomainLookupByName
virDomainSetMaxMemory
@@ -45,7 +45,8 @@ virDomainShutdown

Letter O:

OUT
virConnectGetVersion
virGetVersion
-

Letter P:

Provides
virConnectNumOfDomains
+

Letter P:

Provide
virDomainGetXMLDesc
+
Provides
virConnectNumOfDomains
virGetVersion

Letter R:

Read-Only
virConnectGetVersion
Resume
virDomainResume
@@ -67,9 +68,11 @@ virDomainSuspend
Try
virDomainLookupByID
virDomainLookupByName
-

Letter U:

Use
virDomainSave
+

Letter U:

UTF-8
virDomainGetXMLDesc
+
Use
virDomainSave
virDomainSuspend

Letter X:

XML
virDomainCreateLinux
+virDomainGetXMLDesc
Xen
virGetVersion

Letter a:

about
virDomainGetInfo
access
_virDomainInfo
@@ -114,7 +117,8 @@
availble
virGetVersion

Letter b:

back
virDomainDestroy
virGetVersion
-
based
virDomainLookupByID
+
based
virDomainCreateLinux
+virDomainLookupByID
virDomainLookupByName
being
virDomainShutdown
below
_virDomainInfo
@@ -128,6 +132,7 @@
called
virConnectClose
virConnectOpen
virConnectOpenReadOnly
+
caller
virDomainGetXMLDesc
calling
virDomainResume
can
_virDomainInfo
virConnectGetVersion
@@ -161,8 +166,8 @@

Letter d:

data
virDomainDestroy
virDomainFree
deallocated
virDomainGetName
-
defined
virDomainCreateLinux
description
virDomainCreateLinux
+virDomainGetXMLDesc
device
_virDomainKernel
disk
virDomainRestore
virDomainSave
@@ -172,7 +177,8 @@ virConnectNumOfDomains
virConnectOpenReadOnly
down
virDomainDestroy
-

Letter e:

error
virConnectClose
+

Letter e:

encoded
virDomainGetXMLDesc
+
error
virConnectClose
virConnectGetType
virConnectGetVersion
virConnectListDomains
@@ -183,11 +189,13 @@ virDomainGetID
virDomainGetMaxMemory
virDomainGetOSType
+virDomainGetXMLDesc
virGetVersion
especially
virConnectClose
extracted
_virDomainInfo
virConnectGetVersion
virDomainGetInfo
+
extraction
virDomainGetXMLDesc

Letter f:

failure
virDomainCreateLinux
virDomainDestroy
virDomainFree
@@ -206,6 +214,7 @@
find
virDomainLookupByID
first
virConnectOpen
virConnectOpenReadOnly
+
flags
virDomainGetXMLDesc
for
_virDomainInfo
virConnectGetVersion
virDomainGetID
@@ -217,6 +226,7 @@
format
virGetVersion
found
virConnectListDomains
virConnectNumOfDomains
+
free
virDomainGetXMLDesc
freed
virDomainDestroy
virDomainFree
from
_virDomainInfo
diff --git a/docs/APIchunk1.html b/docs/APIchunk1.html index 6092e4ab69..2afaba5b4a 100644 --- a/docs/APIchunk1.html +++ b/docs/APIchunk1.html @@ -38,6 +38,7 @@
init
_virDomainKernel
instance
virDomainDestroy
virDomainFree
+virDomainGetXMLDesc
int
virDomainGetID
interaction
virConnectClose
its
virDomainGetName
@@ -49,6 +50,7 @@ virDomainSetMaxMemory
knowing
virDomainShutdown

Letter l:

lack
virConnectGetVersion
+
later
virDomainGetXMLDesc
level
virConnectGetVersion
virDomainSuspend
libbrary
virConnectOpenReadOnly
@@ -68,7 +70,9 @@ virDomainGetMaxMemory
virDomainSetMaxMemory
may
virConnectGetVersion
+virDomainCreateLinux
virDomainDestroy
+virDomainGetXMLDesc
virDomainResume
virDomainSave
virDomainShutdown
@@ -86,6 +90,7 @@ virConnectGetVersion
virGetVersion
monitoring
virConnectClose
+
must
virDomainGetXMLDesc

Letter n:

name
virConnectGetType
virDomainGetName
virDomainLookupByName
@@ -101,6 +106,7 @@ virDomainDestroy
virDomainFree
virDomainGetName
+virDomainGetXMLDesc
virDomainSave
virDomainShutdown
virGetVersion
@@ -116,6 +122,7 @@ virDomainGetMaxMemory
virDomainGetName
virDomainGetOSType
+virDomainGetXMLDesc
virDomainLookupByID
virDomainLookupByName
virDomainResume
@@ -124,6 +131,7 @@ virDomainShutdown
virDomainSuspend
one
_virDomainInfo
+virDomainCreateLinux
only
_virDomainInfo
virConnectGetVersion
virDomainGetInfo
@@ -177,6 +185,7 @@

Letter r:

ramdisk
_virDomainKernel
reactivate
virDomainSuspend
reboot
virDomainShutdown
+
relaunch
virDomainGetXMLDesc
release
virConnectGetVersion
virGetVersion
request
virDomainShutdown
@@ -196,8 +205,11 @@
return
virConnectGetVersion
virDomainDestroy
virGetVersion
-
returned
virGetVersion
+
returned
virDomainCreateLinux
+virDomainGetXMLDesc
+virGetVersion
returns
virConnectGetVersion
+
reused
virDomainGetXMLDesc
root
_virDomainKernel
running
_virDomainInfo
virConnectClose
diff --git a/docs/APIchunk2.html b/docs/APIchunk2.html index ef6756423a..a390d636de 100644 --- a/docs/APIchunk2.html +++ b/docs/APIchunk2.html @@ -10,6 +10,7 @@
set
virConnectOpenReadOnly
virDomainCreateLinux
virDomainGetInfo
+virDomainGetXMLDesc
should
virConnectClose
virConnectOpen
virConnectOpenReadOnly
@@ -17,6 +18,7 @@ virDomainFree
virDomainShutdown
shutdown
virDomainDestroy
+
similar
virDomainCreateLinux
size
virConnectListDomains
virDomainGetMaxMemory
virDomainSetMaxMemory
@@ -52,6 +54,7 @@
system
virDomainGetOSType

Letter t:

term
_virDomainInfo
terminated
virConnectGetType
+virDomainGetXMLDesc
that
virDomainGetInfo
virDomainGetName
virDomainShutdown
@@ -70,8 +73,7 @@
two
virGetVersion
type
virDomainGetOSType
virGetVersion
-

Letter u:

unimplemented
virDomainCreateLinux
-
unknown
virGetVersion
+

Letter u:

unknown
virGetVersion
unsigned
virDomainGetID
unused
virConnectOpen
virConnectOpenReadOnly
@@ -82,16 +84,20 @@ virDomainDestroy
virDomainFree
virDomainGetInfo
+virDomainGetXMLDesc
virDomainSuspend
user
virDomainGetInfo

Letter v:

value
virConnectGetVersion
+virDomainGetXMLDesc
virGetVersion
values
virGetVersion
version
LIBVIR_VERSION_NUMBER
virConnectGetVersion
virGetVersion
+
virDomainCreateLinux
virDomainGetXMLDesc
virDomainFlags
_virDomainInfo
virDomainCreateLinux
+
virDomainGetXMLDesc
virDomainCreateLinux
virDomainInfo
virDomainGetInfo
virDomainRestore
virDomainSave
virDomainResume
virDomainSuspend
@@ -114,11 +120,12 @@
with
_virDomainInfo
virConnectClose
virConnectGetVersion
+virDomainGetXMLDesc
without
virDomainSuspend
work
virConnectGetVersion

Letter x:

xen
virConnectOpen
xenstore
_virDomainInfo
-

Letter y:

yet
virDomainCreateLinux
+

Letter y:

yet
virDomainGetXMLDesc

Letter z:

zero
virConnectGetType

A-f g-r diff --git a/docs/FAQ.html b/docs/FAQ.html index adae05a20b..8718e94e31 100644 --- a/docs/FAQ.html +++ b/docs/FAQ.html @@ -1,14 +1,14 @@ -FAQ

FAQ

Table of Contents:

main menu

related links

Graphics and design by Diana Fong

diff --git a/docs/architecture.html b/docs/architecture.html index 98e729455b..ecf3722c14 100644 --- a/docs/architecture.html +++ b/docs/architecture.html @@ -24,4 +24,4 @@ connect to initialize the library. It will try to open the read-only socket /var/run/xenstored/socket_ro to connect to the Xen Store and also try to use the RPC to the Xen daemon. In this case use of hypervisor calls and write to the Xen Store will not be possible, restraining the amount -of APIs available and slowing down information gathering about domains.

main menu

related links

Graphics and design by Diana Fong

+of APIs available and slowing down information gathering about domains.

main menu

related links

Graphics and design by Diana Fong

diff --git a/docs/bugs.html b/docs/bugs.html index 53923f0fe8..c0eef3e6be 100644 --- a/docs/bugs.html +++ b/docs/bugs.html @@ -7,4 +7,4 @@ page and follow the instructions. Patches with explanations and provided as attachments are really appreciated and will be discussed on the mailing list. If possible generate the patches by using cvs diff -u in a CVS checkout.

We expect to use Red Hat Bugzilla to track bugs for libvirt, though there isn't a libvirt software -module defined yet, in the meantime use the mailing-list, thanks !.

main menu

related links

Graphics and design by Diana Fong

+module defined yet, in the meantime use the mailing-list, thanks !.

main menu

related links

Graphics and design by Diana Fong

diff --git a/docs/downloads.html b/docs/downloads.html index 9ba8db73c9..6701fe0973 100644 --- a/docs/downloads.html +++ b/docs/downloads.html @@ -4,6 +4,7 @@ versions as well as snapshot tarballs updated from CVS head every hour

Anonymous CVS is also available, first register onto the server:

cvs -d :pserver:anoncvs@libvirt.org:2401/data/cvs login

it will request a password, enter anoncvs. Then you can -checkout the development tree with:

cvs -d :pserver:anoncvs@libvirt.org:2401/data/cvs co libvirt

Use ./autogen.sh to configure the local checkout, then make +checkout the development tree with:

cvs -d :pserver:anoncvs@libvirt.org:2401/data/cvs co +libvirt

Use ./autogen.sh to configure the local checkout, then make and make install, as usual. All normal cvs commands are now -available except commiting to the base.

main menu

related links

Graphics and design by Diana Fong

+available except commiting to the base.

main menu

related links

Graphics and design by Diana Fong

diff --git a/docs/examples/Makefile.am b/docs/examples/Makefile.am index 25048b2cac..26844e9142 100644 --- a/docs/examples/Makefile.am +++ b/docs/examples/Makefile.am @@ -8,8 +8,8 @@ rebuild: examples.xml index.html examples.xml: index.py *.c -@($(srcdir)/index.py) -index.html: examples.xml examples.xsl - -@(xsltproc examples.xsl examples.xml && echo "Rebuilt web page" && xmllint --valid --noout index.html) +index.html: examples.xml examples.xsl $(top_srcdir)/docs/site.xsl + -@(if [ -x $(XSLTPROC) ] ; then $(XSLTPROC) examples.xsl examples.xml && echo "Rebuilt web page" && xmllint --valid --noout index.html ; fi) install-data-local: $(mkinstalldirs) $(DESTDIR)$(HTML_DIR) diff --git a/docs/examples/index.py b/docs/examples/index.py index c719556556..91defeb9bf 100755 --- a/docs/examples/index.py +++ b/docs/examples/index.py @@ -230,8 +230,9 @@ rebuild: examples.xml index.html examples.xml: index.py *.c -@($(srcdir)/index.py) -index.html: examples.xml examples.xsl - -@(xsltproc examples.xsl examples.xml && echo "Rebuilt web page" && xmllint --valid --noout index.html) +index.html: examples.xml examples.xsl $(top_srcdir)/docs/site.xsl + -@(if [ -x $(XSLTPROC) ] ; then \ + $(XSLTPROC) examples.xsl examples.xml && echo "Rebuilt web page" && xmllint --valid --noout index.html ; fi) install-data-local: $(mkinstalldirs) $(DESTDIR)$(HTML_DIR) diff --git a/docs/format.html b/docs/format.html new file mode 100644 index 0000000000..fb55d0891d --- /dev/null +++ b/docs/format.html @@ -0,0 +1,68 @@ + + +XML Format

XML Format

The library use an XML format to describe domains, as input to virDomainCreateLinux() +and as the output of virDomainGetXMLDesc(), +the following is an example of the format as returned by the shell command +virsh xmldump fc4 , where fc4 was one of the running domains:

<domain type='xen' id='18'>
+  <name>fc4</name>
+  <os>
+    <type>linux</type>
+    <kernel>/boot/vmlinuz-2.6.15-1.43_FC5guest</kernel>
+    <initrd>/boot/initrd-2.6.15-1.43_FC5guest.img</initrd>
+    <root>/dev/sda1</root>
+    <cmdline> ro selinux=0 3</cmdline>
+  </os>
+  <memory>131072</memory>
+  <vcpu>1</vcpu>
+  <devices>
+    <disk type='file'>
+      <source file='/u/fc4.img'/>
+      <target dev='sda1'/>
+    </disk>
+    <interface type='bridge'>
+      <source bridge='xenbr0'/>
+      <mac address='aa:00:00:00:00:11'/>
+      <script path='/etc/xen/scripts/vif-bridge'/>
+    </interface>
+  </devices>
+</domain>

The root element must be called domain with no namespace, the +type attribute indicates the kind of hypervisor used, 'xen' is +the default value. The id attribute gives the domain id at +runtime (not however that this may change, for example if the domain is saved +to disk and restored). The domain has a few children whose order is not +significant:

  • name: the domain name, preferably ASCII based
    • +
  • memory: the maximum memory allocated to the domain in kilobytes
    • +
  • vcpu: the number of virtual cpu configured for the domain
    • +
  • os: a block describing the Operating System, its content will be + dependant on the OS type +
    • type: indicate the OS type, always linux at this point
      • +
    • kernel: path to the kernel on the Domain 0 filesystem
      • +
    • initrd: an optional path for the init ramdisk on the Domain 0 + filesystem
      • +
    • cmdline: optional command line to the kernel
      • +
    • root: the root filesystem from the guest viewpoint, it may be + passed as part of the cmdline content too
      • +
    • +
  • devices: a list of disk and interface + descriptions in no special order
    • +

The format of the devices and their type may grow over time, but the +following should be sufficient for basic use:

A disk device indicates a block device, it can have two values for the +type attribute either 'file' or 'block' corresponding to the 2 options +availble at the Xen layer. It has two mandatory children, and one optional +one in no specific order:

  • source with a file attribute containing the path in Domain 0 to the + file or a dev attribute if using a block device, containing the device + name ('hda5' or '/dev/hda5')
    • +
  • target indicates in a dev attribute the device where it is mapped in + the guest
    • +
  • readonly an optional empty element indicating the device is + read-only
    • +

An interface element describes a network device mapped on the guest, it +also has a type whose value is currently 'bridge', it also have a number of +children in no specific order:

  • source: indicating the bridge name
    • +
  • mac: the optional mac address provided in the address attribute
    • +
  • ip: the optional IP address provided in the address attribute
    • +
  • script: the script used to bridge the interfcae in the Domain 0
    • +
  • target: and optional target indicating the device name.
    • +

While the format may be extended in various ways as support for more +hypervisor types and features are added, it is expected that this core subset +will remain functional in spite of the evolution of the library.

main menu

related links

Graphics and design by Diana Fong

diff --git a/docs/html/libvirt-libvirt.html b/docs/html/libvirt-libvirt.html index e405aa591e..0d183a85fa 100644 --- a/docs/html/libvirt-libvirt.html +++ b/docs/html/libvirt-libvirt.html @@ -103,7 +103,7 @@ The content of this structure is not made public by the API.
name:optional argument currently unused, pass NULL
Returns:a pointer to the hypervisor connection or NULL in case of error

Function: virConnectOpenReadOnly

virConnectPtr	virConnectOpenReadOnly	(const char * name)

This function should be called first to get a restricted connection to the libbrary functionalities. The set of APIs usable are then restricted on the available methods to control the domains.

name:optional argument currently unused, pass NULL
Returns:a pointer to the hypervisor connection or NULL in case of error

Function: virDomainCreateLinux

virDomainPtr	virDomainCreateLinux	(virConnectPtr conn, 
					 const char * xmlDesc, 
					 unsigned int flags)

-

Launch a new Linux guest domain, unimplemented yet, API to be defined. This function requires priviledged access to the hypervisor.

+

Launch a new Linux guest domain, based on an XML description similar to the one returned by virDomainGetXMLDesc() This function may requires priviledged access to the hypervisor.

conn:pointer to the hypervisor connection
xmlDesc:an XML description of the domain
flags:an optional set of virDomainFlags
Returns:a new domain object or NULL in case of failure

Function: virDomainDestroy

int	virDomainDestroy		(virDomainPtr domain)

Destroy the domain object. The running instance is shutdown if not down already and all resources used by it are given back to the hypervisor. The data structure is freed and should not be used thereafter if the call does not return an error. This function may requires priviledged access

domain:a domain object
Returns:0 in case of success and -1 in case of failure.

Function: virDomainFree

int	virDomainFree			(virDomainPtr domain)

@@ -119,8 +119,8 @@ The content of this structure is not made public by the API.
 
domain:a domain object
Returns:a pointer to the name or NULL, the string need not be deallocated its lifetime will be the same as the domain object.
Function: virDomainGetOSType
char *	virDomainGetOSType		(virDomainPtr domain)

 
Get the type of domain operation system.

 
domain:a domain object
Returns:the new string or NULL in case of error
Function: virDomainGetXMLDesc
char *	virDomainGetXMLDesc		(virDomainPtr domain, 
					 int flags)

-

-
domain:
flags:
Returns:
Function: virDomainLookupByID
virDomainPtr	virDomainLookupByID	(virConnectPtr conn, 
					 int id)

+
Provide an XML description of the domain. The description may be reused later to relaunch the domain with virDomainCreateLinux().

+
domain:a domain object
flags:and OR'ed set of extraction flags, not used yet
Returns:a 0 terminated UTF-8 encoded XML instance, or NULL in case of error. the caller must free() the returned value.
Function: virDomainLookupByID
virDomainPtr	virDomainLookupByID	(virConnectPtr conn, 
					 int id)

 
Try to find a domain based on the hypervisor ID number

 
conn:pointer to the hypervisor connection
id:the domain ID number
Returns:a new domain object or NULL in case of failure
Function: virDomainLookupByName
virDomainPtr	virDomainLookupByName	(virConnectPtr conn, 
					 const char * name)

 
Try to lookup a domain on the given hypervisor based on its name.

diff --git a/docs/index.html b/docs/index.html
index 60cd39615f..82c4169498 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -47,7 +47,10 @@ mechanisms if needed.

               Downloads
             
             
  • 
-              FAQ
+              XML Format
+            
    • 
+            
  • 
+               FAQ
             
    • 
             
  • 
               Reporting bugs and getting help
diff --git a/docs/intro.html b/docs/intro.html
index 2952a66972..5444c1777d 100644
--- a/docs/intro.html
+++ b/docs/intro.html
@@ -22,9 +22,9 @@ generic and stable layer to manage domains on a node.
    This implies the fol
   
  • stability of the API is a big concern, libvirt should isolate
     applications from the frequent changes expected at the lower level of the
     virtualization framework
    • 
-
    So libvirt should be a building block for higher level management tools and
-for applications focusing on virtualization of a single node (the only
+
    So libvirt should be a building block for higher level management tools
+and for applications focusing on virtualization of a single node (the only
 exception being domain migration between node capabilities which may need to
-be added at the libvirt level). Where possible libvirt should be extendable to
-be able to provide the same API for remote nodes, however this is not the
-case at the moment, the code currently handle only local node accesses.
    main menu
    related links
    Graphics and design by Diana Fong
    
+be added at the libvirt level). Where possible libvirt should be extendable
+to be able to provide the same API for remote nodes, however this is not the
+case at the moment, the code currently handle only local node accesses.
    main menu
    related links
    Graphics and design by Diana Fong
    
diff --git a/docs/libvir.html b/docs/libvir.html
index a184e24c95..e8ba435131 100644
--- a/docs/libvir.html
+++ b/docs/libvir.html
@@ -102,11 +102,11 @@ generic and stable layer to manage domains on a node.
    
     virtualization framework
 
 
-
    So libvirt should be a building block for higher level management tools and
-for applications focusing on virtualization of a single node (the only
+
    So libvirt should be a building block for higher level management tools
+and for applications focusing on virtualization of a single node (the only
 exception being domain migration between node capabilities which may need to
-be added at the libvirt level). Where possible libvirt should be extendable to
-be able to provide the same API for remote nodes, however this is not the
+be added at the libvirt level). Where possible libvirt should be extendable
+to be able to provide the same API for remote nodes, however this is not the
 case at the moment, the code currently handle only local node accesses.
    
 
 
    libvirt architecture
    
@@ -166,13 +166,104 @@ available, first register onto the server:
    
 
    it will request a password, enter anoncvs. Then you can
 checkout the development tree with:
    
 
-
    cvs -d :pserver:anoncvs@libvirt.org:2401/data/cvs co libvirt
    
+
    cvs -d :pserver:anoncvs@libvirt.org:2401/data/cvs co
+libvirt
    
 
 
    Use ./autogen.sh to configure the local checkout, then make
 and make install, as usual. All normal cvs commands are now
 available except commiting to the base.
    
 
-
    FAQ
    
+
    XML Format
    
+
+
    The library use an XML format to describe domains, as input to virDomainCreateLinux()
+and as the output of virDomainGetXMLDesc(),
+the following is an example of the format as returned by the shell command
+virsh xmldump fc4 , where fc4 was one of the running domains:
    
+
    <domain type='xen' id='18'>
+  <name>fc4</name>
+  <os>
+    <type>linux</type>
+    <kernel>/boot/vmlinuz-2.6.15-1.43_FC5guest</kernel>
+    <initrd>/boot/initrd-2.6.15-1.43_FC5guest.img</initrd>
+    <root>/dev/sda1</root>
+    <cmdline> ro selinux=0 3</cmdline>
+  </os>
+  <memory>131072</memory>
+  <vcpu>1</vcpu>
+  <devices>
+    <disk type='file'>
+      <source file='/u/fc4.img'/>
+      <target dev='sda1'/>
+    </disk>
+    <interface type='bridge'>
+      <source bridge='xenbr0'/>
+      <mac address='aa:00:00:00:00:11'/>
+      <script path='/etc/xen/scripts/vif-bridge'/>
+    </interface>
+  </devices>
+</domain>
    
+
+
    The root element must be called domain with no namespace, the
+type attribute indicates the kind of hypervisor used, 'xen' is
+the default value. The id attribute gives the domain id at
+runtime (not however that this may change, for example if the domain is saved
+to disk and restored). The domain has a few children whose order is not
+significant:
    
+
      
+  
    • name: the domain name, preferably ASCII based
      • 
+  
    • memory: the maximum memory allocated to the domain in kilobytes
      • 
+  
    • vcpu: the number of virtual cpu configured for the domain
      • 
+  
    • os: a block describing the Operating System, its content will be
+    dependant on the OS type
+    
        
+      
      • type: indicate the OS type, always linux at this point
        • 
+      
      • kernel: path to the kernel on the Domain 0 filesystem
        • 
+      
      • initrd: an optional path for the init ramdisk on the Domain 0
+        filesystem
        • 
+      
      • cmdline: optional command line to the kernel
        • 
+      
      • root: the root filesystem from the guest viewpoint, it may be
+        passed as part of the cmdline content too
        • 
+    
      
+  
      • 
+  
    • devices: a list of disk and interface
+    descriptions in no special order
      • 
+
    
+
+
    The format of the devices and their type may grow over time, but the
+following should be sufficient for basic use:
    
+
+
    A disk device indicates a block device, it can have two values for the
+type attribute either 'file' or 'block' corresponding to the 2 options
+availble at the Xen layer. It has two mandatory children, and one optional
+one in no specific order:
    
+
      
+  
    • source with a file attribute containing the path in Domain 0 to the
+    file or a dev attribute if using a block device, containing the device
+    name ('hda5' or '/dev/hda5')
      • 
+  
    • target indicates in a dev attribute the device where it is mapped in
+    the guest
      • 
+  
    • readonly an optional empty element indicating the device is
+  read-only
      • 
+
    
+
+
    An interface element describes a network device mapped on the guest, it
+also has a type whose value is currently 'bridge', it also have a number of
+children in no specific order:
    
+
      
+  
    • source: indicating the bridge name
      • 
+  
    • mac: the optional mac address provided in the address attribute
      • 
+  
    • ip: the optional IP address provided in the address attribute
      • 
+  
    • script: the script used to bridge the interfcae in the Domain 0
      • 
+  
    • target: and optional target indicating the device name.
      • 
+
    
+
+
    While the format may be extended in various ways as support for more
+hypervisor types and features are added, it is expected that this core subset
+will remain functional in spite of the evolution of the library. 
    
+
+
     FAQ
    
 
 
    Table of Contents:
    
 
      
@@ -188,8 +279,8 @@ available except commiting to the base.
      
     
      libvirt is released under the GNU Lesser
     General Public License, see the file COPYING.LIB in the distribution
-    for the precise wording. The only library that libvirt depends upon is the
-    Xen store access library which is also licenced under the LGPL.
      
+    for the precise wording. The only library that libvirt depends upon is
+    the Xen store access library which is also licenced under the LGPL.
      
   
   
    • Can I embed libvirt in a proprietary application ?
     
      Yes. The LGPL allows you to embed libvirt into a proprietary
@@ -205,8 +296,8 @@ available except commiting to the base.
      
     
      The original distribution comes from ftp://libvirt.org/libvirt/.
      
   
      • 
-  
    • I can't install the libvirt/libvirt-devel RPM packages due to failed
-    dependencies
+  
    • I can't install the libvirt/libvirt-devel RPM packages due to
+    failed dependencies
     
      The most generic solution is to re-fetch the latest src.rpm , and
     rebuild it locally with
      
     
      rpm --rebuild libvirt-xxx.src.rpm.
      
diff --git a/docs/libvirt-api.xml b/docs/libvirt-api.xml
index 4cabaa949a..b4873fa31b 100644
--- a/docs/libvirt-api.xml
+++ b/docs/libvirt-api.xml
@@ -159,7 +159,7 @@
       
     
     
-      Launch a new Linux guest domain, unimplemented yet, API to be defined. This function requires priviledged access to the hypervisor.
+      Launch a new Linux guest domain, based on an XML description similar to the one returned by virDomainGetXMLDesc() This function may requires priviledged access to the hypervisor.
       
       
       
@@ -202,10 +202,10 @@
       
     
     
-      
-      
-      
-      
+      Provide an XML description of the domain. The description may be reused later to relaunch the domain with virDomainCreateLinux().
+      
+      
+      
     
     
       Try to find a domain based on the hypervisor ID number
diff --git a/docs/libvirt-refs.xml b/docs/libvirt-refs.xml
index db8dcb2122..0dc7cd6f29 100644
--- a/docs/libvirt-refs.xml
+++ b/docs/libvirt-refs.xml
@@ -251,9 +251,6 @@
         
           
         
-        
-          
-        
         
           
         
@@ -343,6 +340,7 @@
           
           
           
+          
           
           
           
@@ -360,6 +358,9 @@
         
       
       
+        
+          
+        
         
           
           
@@ -408,6 +409,9 @@
         
       
       
+        
+          
+        
         
           
           
@@ -416,6 +420,7 @@
       
         
           
+          
         
         
           
@@ -510,6 +515,7 @@
           
         
         
+          
           
           
         
@@ -539,6 +545,9 @@
           
           
         
+        
+          
+        
         
           
         
@@ -608,11 +617,9 @@
         
           
         
-        
-          
-        
         
           
+          
         
         
           
@@ -637,6 +644,9 @@
         
       
       
+        
+          
+        
         
           
           
@@ -649,6 +659,7 @@
           
           
           
+          
           
         
         
@@ -659,6 +670,9 @@
           
           
         
+        
+          
+        
       
       
         
@@ -689,6 +703,9 @@
           
           
         
+        
+          
+        
         
           
           
@@ -706,6 +723,9 @@
           
           
         
+        
+          
+        
         
           
           
@@ -804,6 +824,7 @@
         
           
           
+          
         
         
           
@@ -836,6 +857,9 @@
         
           
         
+        
+          
+        
         
           
           
@@ -882,7 +906,9 @@
         
         
           
+          
           
+          
           
           
           
@@ -913,6 +939,9 @@
         
           
         
+        
+          
+        
       
       
         
@@ -939,6 +968,7 @@
           
           
           
+          
           
           
           
@@ -960,6 +990,7 @@
           
           
           
+          
           
           
           
@@ -970,6 +1001,7 @@
         
         
           
+          
         
         
           
@@ -1078,6 +1110,9 @@
         
           
         
+        
+          
+        
         
           
           
@@ -1116,11 +1151,16 @@
           
         
         
+          
+          
           
         
         
           
         
+        
+          
+        
         
           
         
@@ -1156,6 +1196,7 @@
           
           
           
+          
         
         
           
@@ -1168,6 +1209,9 @@
         
           
         
+        
+          
+        
         
           
           
@@ -1238,6 +1282,7 @@
         
         
           
+          
         
         
           
@@ -1275,9 +1320,6 @@
         
       
       
-        
-          
-        
         
           
         
@@ -1298,6 +1340,7 @@
           
           
           
+          
           
         
         
@@ -1307,6 +1350,7 @@
       
         
           
+          
           
         
         
@@ -1317,10 +1361,16 @@
           
           
         
+        
+          
+        
         
           
           
         
+        
+          
+        
         
           
         
@@ -1368,6 +1418,7 @@
           
           
           
+          
         
         
           
@@ -1386,7 +1437,7 @@
       
       
         
-          
+          
         
       
       
diff --git a/docs/news.html b/docs/news.html
index 5687e90e3a..1c7280a4aa 100644
--- a/docs/news.html
+++ b/docs/news.html
@@ -16,4 +16,4 @@ and check the ChangeLog to gauge progresses.
      0.0.1: Dec 19 2005
      • First release
        • 
   
      • Basic management of existing Xen domains
        • 
   
      • Minimal autogenerated Python bindings
        • 
-
      main menu
      related links
      Graphics and design by Diana Fong
      
+
    main menu
    related links
    Graphics and design by Diana Fong
    
diff --git a/docs/site.xsl b/docs/site.xsl
index 2b7a7e9095..453fdaedff 100644
--- a/docs/site.xsl
+++ b/docs/site.xsl
@@ -36,8 +36,8 @@
       
         contribs.html
       
-      
-        xsltproc2.html
+      
+        format.html
       
       
         
@@ -134,8 +134,8 @@
       
         contribs.html
       
-      
-        xsltproc2.html
+      
+        format.html
       
       
         
diff --git a/src/libvirt.c b/src/libvirt.c
index 55506ae064..85468e8d5f 100644
--- a/src/libvirt.c
+++ b/src/libvirt.c
@@ -399,8 +399,9 @@ virConnectNumOfDomains(virConnectPtr conn) {
  * @xmlDesc: an XML description of the domain
  * @flags: an optional set of virDomainFlags
  *
- * Launch a new Linux guest domain, unimplemented yet, API to be defined.
- * This function requires priviledged access to the hypervisor.
+ * Launch a new Linux guest domain, based on an XML description similar
+ * to the one returned by virDomainGetXMLDesc()
+ * This function may requires priviledged access to the hypervisor.
  * 
  * Returns a new domain object or NULL in case of failure
  */
@@ -1238,3 +1239,23 @@ xend_info:
     return(0);
 }
 
+/**
+ * virDomainGetXMLDesc:
+ * @domain: a domain object
+ * @flags: and OR'ed set of extraction flags, not used yet
+ *
+ * Provide an XML description of the domain. The description may be reused
+ * later to relaunch the domain with virDomainCreateLinux().
+ *
+ * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error.
+ *         the caller must free() the returned value.
+ */
+char *
+virDomainGetXMLDesc(virDomainPtr domain, int flags) {
+    if (!VIR_IS_DOMAIN(domain))
+	return(NULL);
+    if (flags != 0)
+	return(NULL);
+
+    return(xend_get_domain_xml(domain));
+}
diff --git a/src/xend_internal.c b/src/xend_internal.c
index caa04a7d93..2fba8a57ce 100644
--- a/src/xend_internal.c
+++ b/src/xend_internal.c
@@ -2105,7 +2105,7 @@ xend_log(virConnectPtr xend, char *buffer, size_t n_buffer)
 }
 
 /**
- * virDomainParseSExprDesc:
+ * xend_parse_sexp_desc:
  * @root: the root of the parsed S-Expression
  * @name: output name of the domain
  *
@@ -2116,7 +2116,7 @@ xend_log(virConnectPtr xend, char *buffer, size_t n_buffer)
  *         the caller must free() the returned value.
  */
 static char *
-virDomainParseSExprDesc(struct sexpr *root) {
+xend_parse_sexp_desc(struct sexpr *root) {
     char *ret;
     struct sexpr *cur, *node;
     const char *tmp;
@@ -2252,31 +2252,27 @@ error:
 }
 
 /**
- * virDomainGetXMLDesc:
+ * xend_get_domain_xml:
  * @domain: a domain object
- * @flags: and OR'ed set of extraction flags, not used yet
  *
- * Provide an XML description of the domain. NOTE: this API is subject
- * to changes.
+ * Provide an XML description of the domain.
  *
  * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error.
  *         the caller must free() the returned value.
  */
 char *
-virDomainGetXMLDesc(virDomainPtr domain, int flags) {
+xend_get_domain_xml(virDomainPtr domain) {
     char *ret = NULL;
     struct sexpr *root;
 
     if (!VIR_IS_DOMAIN(domain))
 	return(NULL);
-    if (flags != 0)
-	return(NULL);
 
     root = sexpr_get(domain->conn, "/xend/domain/%s?detail=1", domain->name);
     if (root == NULL)
         return(NULL);
 
-    ret = virDomainParseSExprDesc(root);
+    ret = xend_parse_sexp_desc(root);
     sexpr_free(root);
 
     return(ret);
diff --git a/src/xend_internal.h b/src/xend_internal.h
index 5f7266a62f..3a24d48f88 100644
--- a/src/xend_internal.h
+++ b/src/xend_internal.h
@@ -846,6 +846,15 @@ int xend_log(virConnectPtr xend,
 	     char *buffer,
 	     size_t n_buffer);
 
+/**
+ * \brief Provide an XML description of the domain.
+ * \param domain a xend domain object
+ * \return a 0 terminated UTF-8 encoded XML instance, or NULL in case of error.
+ *         the caller must free() the returned value.
+ *
+ * Provide an XML description of the domain.
+ */
+char *xend_get_domain_xml(virDomainPtr domain);
 #ifdef __cplusplus
 }
 #endif
-- 
2.47.3