ia64/xen-unstable

changeset 1520:466fcde21922

find changesets by author, revision, files, or words in the commit message
bitkeeper revision 1.990.2.2 (40d6ccbfylHHyK831DLP8wwqRjrX4w)

Documentation for xen SXP config format.
author mjw@wray-m-3.hpl.hp.com
date Mon Jun 21 11:55:43 2004 +0000 (2004-06-21)
parents 3862329b4861
children e1ea789b5c8c
files .rootkeys docs/xen_config.html
line diff
     1.1 --- a/.rootkeys	Mon Jun 21 10:06:22 2004 +0000
     1.2 +++ b/.rootkeys	Mon Jun 21 11:55:43 2004 +0000
     1.3 @@ -16,6 +16,7 @@ 3f9e7d60PWZJeVh5xdnk0nLUdxlqEA docs/eps/
     1.4  3f9e7d63lTwQbp2fnx7yY93epWS-eQ docs/figs/dummy
     1.5  3f9e7d564bWFB-Czjv1qdmE6o0GqNg docs/interface.tex
     1.6  3f9e7d58t7N6hjjBMxSn-NMxBphchA docs/style.tex
     1.7 +40d6ccbfKKBq8jE0ula4eHEzBiQuDA docs/xen_config.html
     1.8  3f9e7d5bz8BwYkNuwyiPVu7JJG441A docs/xenstyle.cls
     1.9  3f815144d1vI2777JI-dO4wk49Iw7g extras/mini-os/Makefile
    1.10  3f815144zTnCV5591ulIJQrpe5b-5Q extras/mini-os/README

     2.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.2 +++ b/docs/xen_config.html	Mon Jun 21 11:55:43 2004 +0000
     2.3 @@ -0,0 +1,192 @@
     2.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
     2.5 +<html>
     2.6 +<head>
     2.7 +  <meta http-equiv="content-type"
     2.8 + content="text/html; charset=ISO-8859-1">
     2.9 +  <title>Xen Configuration Syntax</title>
    2.10 +</head>
    2.11 +<body>
    2.12 +<center>
    2.13 +<h1>Xen Configuration Syntax</h1>
    2.14 +<br>
    2.15 +Version 0.1<br>2004 June 21<br>
    2.16 +</center>
    2.17 +
    2.18 +<h1>Xen Configuration</h1>
    2.19 +The Xen virtual machine creation tools provide command-line interfaces and
    2.20 +HTTP interfaces to creating virtual machines. Underneath all these interfaces
    2.21 +virtual machine configuration data is represented in a common configuration syntax
    2.22 +called SXP.
    2.23 +
    2.24 +The SXP syntax is s-expressions (sxprs), a simple bracketed abstract syntax.
    2.25 +Python lists are used to represent its parsed form, with a support
    2.26 +api providing  access to fields and values (class xenmgr.sxp).
    2.27 +
    2.28 +<h1>SXP syntax</h1>
    2.29 +<p>A general s-expression has the syntax:
    2.30 +<code><pre>
    2.31 +s-exp = '(' s-exp* ')' | atom | string
    2.32 +</pre></code>
    2.33 +Where an <code>atom</code> is an unquoted string, such as fred or /domain/0.
    2.34 +A <code>string</code> is a quoted string, supporting the usual escape sequences.
    2.35 +Strings support single or double quotes: 'fred 1' or "fred 2" are both accepted.
    2.36 +The characters ()[]&lt;&gt{} are separators.
    2.37 +
    2.38 +<p>An <code>element</code> is an s-expression representing data similar to XML.
    2.39 +It has the form:
    2.40 +<code><pre>
    2.41 +element    = '(' name attributes? value* ')'
    2.42 +name       = atom
    2.43 +attributes = '(' '@' attribute* ')'
    2.44 +attribute  = '(' attrname attrval ')'
    2.45 +attrname   = atom
    2.46 +attrval    = atom | string
    2.47 +value      = element | atom | string
    2.48 +</pre></code>
    2.49 +The <code>name</code> is the element name (roughly indentifying its type).
    2.50 +The <code>attributes</code> is a list of attribute-values.
    2.51 +We usually prefer to avoid using attributes, and use sub-elements instead.
    2.52 +As in XML, any element may have the attribute <code>id</code> to give it an identifier
    2.53 +for later reference.
    2.54 +
    2.55 +<h1>VM configuration</h1>
    2.56 +A vm configuration is a single SXP vm element, with subelements for
    2.57 +vm parameters and devices. The supported elements and their fields
    2.58 +are listed below.
    2.59 +
    2.60 +<h2>(vm) element</h2>
    2.61 +The top-level element, a virtual machine configuration.
    2.62 +<ul>
    2.63 +    <li>name: string, required. Domain name.
    2.64 +    <li>id: int, optional, default generated. Domain unique id.
    2.65 +    <li>memory: int, optional, default 128. Domain memory in MB.
    2.66 +    <li>image: linux | netbsd | ..., required. Domain image (OS-specific element).
    2.67 +    <li>controller: any device controller type, optional, default none.
    2.68 +    <li>device: any device type, optional, repeats. Device.
    2.69 +    <li>auto-restart: bool, optional, default false. Auto-restart flag.
    2.70 +</ul>
    2.71 +
    2.72 +<h2>(image (linux)) element</h2>
    2.73 +Defines a linux kernel image and its command-line parameters.
    2.74 +<ul>
    2.75 +    <li>kernel: string, required. Kernel image file (absolute path).
    2.76 +    <li>root: string, optional. Root device.
    2.77 +    <li>ip: string, optional. IP address specifier.
    2.78 +    <li>ramdisk: string, optional, default none. Ramdisk file (absolute path).
    2.79 +    <li>args: string, optional. Extra kernel args.
    2.80 +</ul>
    2.81 +
    2.82 +<h2>(image (netbsd)) element</h2>
    2.83 +Defines a netbsd kernel image and its command-line parameters.
    2.84 +<ul>
    2.85 +    <li>kernel: string, required. Kernel image file.
    2.86 +    <li>root: string, optional. Root device.
    2.87 +    <li>ip: string, optional. IP address specifier.
    2.88 +    <li>ramdisk: string, optional, default none. Ramdisk file.
    2.89 +    <li>args: string, optional. Extra kernel args.
    2.90 +</ul>
    2.91 +
    2.92 +<h2>(controller (block)) element</h2>
    2.93 +Define that the vm is a block device controller backend.
    2.94 +The vm can have pci devices configured, but no virtual
    2.95 +block devices.
    2.96 +
    2.97 +<h2>(controller (net)) element</h2>
    2.98 +Define that the vm is a net device controller backend.
    2.99 +The domain may not have virtual network interfaces (vifs) configured.
   2.100 +
   2.101 +<h2>(device (vif)) element</h2>
   2.102 +Defines a virtual network interface.
   2.103 +<ul>
   2.104 +    <li>mac: string, optional, default generated. Interface MAC address.
   2.105 +    <li>quota info: optional. Subelements bytes and usecs.
   2.106 +    <li>bridge: string, optional, default system-dependent. Bridge to connect to.
   2.107 +</ul>
   2.108 +A random MAC is assined is not specified.
   2.109 +The interface is connected to the system default bridge if no bridge
   2.110 +is specified.
   2.111 +
   2.112 +<h2>(device (vbd)) element</h2>
   2.113 +Defines a virtual block device.
   2.114 +<ul>
   2.115 +    <li>uname: string, required. Virtual block device id, e.g phys:hda1.
   2.116 +    <li>dev: string, required. Device file name in domain, e.g. xda1.
   2.117 +    <li>mode: string, optional, default r. Read-write mode: r | rw | w.
   2.118 +</ul>
   2.119 +The uname field defines the device being exported from the block device
   2.120 +controller. The dev field defines the device name the vm will see.
   2.121 +The device is read-only unless the mode contains w.
   2.122 +
   2.123 +<h2>(device (pci)) element</h2>
   2.124 +Defines a pci device. 
   2.125 +<ul>
   2.126 +    <li>bus: int, required. PCI bus id.
   2.127 +    <li>dev: int, required. PCI dev id.
   2.128 +    <li>func: int, required. PCI func id.
   2.129 +</ul>
   2.130 +The bus, dev or func may be given in hex,
   2.131 +e.g. 0xff. With no leading 0x they are interpreted as decimal.
   2.132 +
   2.133 +<h2>(vnet) element</h2>
   2.134 +Defines the virtual networks associated with vifs (may go away soon).
   2.135 +Contains a list of vif elements:
   2.136 +<ul>
   2.137 +  <li>id: id of the vif being configured.
   2.138 +  <li>vnet: id of vnet the vif is assigned to.
   2.139 +</ul>
   2.140 +
   2.141 +<h2>(vfr) element</h2>
   2.142 +Defines the ip addresses for vifs (may go away soon).
   2.143 +Contains a list of vif elements:
   2.144 +<ul>
   2.145 +  <li>id: vif index
   2.146 +  <li>ip: vif ip address
   2.147 +</ul>
   2.148 +
   2.149 +<h1>Examples</h1>
   2.150 +<p> A vm  with 64 MB memory, root on /dev/xda1 (mapped from /dev/hda1),
   2.151 +one vif with default MAC.
   2.152 +<code><pre>
   2.153 +(vm
   2.154 +    (name xendom1)
   2.155 +    (memory 64)
   2.156 +    (image
   2.157 +        (linux
   2.158 +            (kernel /boot/vmlinuz-2.4.26-xen)
   2.159 +            (ip ::::xendom1:eth0:dhcp)
   2.160 +            (root /dev/xda1)
   2.161 +            (args 'rw fastboot 4')
   2.162 +        )
   2.163 +    )
   2.164 +    (device (vif))
   2.165 +    (device (vbd (uname phy:hda1) (dev xda1) (mode w)))
   2.166 +)
   2.167 +</pre></code>
   2.168 +
   2.169 +<p>A vm with 64 MB memory, NFS root, and 2 vifs on separate vnets.
   2.170 +<code><pre>
   2.171 +(vm 
   2.172 +   (name xendom2)
   2.173 +   (memory 64)
   2.174 +    # Define a linux image.
   2.175 +    (image
   2.176 +        (linux 
   2.177 +            (kernel "/boot/vmlinuz-2.4.26-xen")
   2.178 +            (ip     "::::xendom2:eth0:dhcp")
   2.179 +            (root   "/dev/nfs")
   2.180 +            (args   "rw fastboot nfsroot=15.144.25.79:/opt/xen/xendom2 4")
   2.181 +         )
   2.182 +    )
   2.183 +    # Define some vifs, with ids for use later.
   2.184 +    (device (vif (@ (id vif1)) (mac aa:00:00:00:00:12)))
   2.185 +    (device (vif (@ (id vif2)) (mac aa:00:00:00:10:12)))
   2.186 +
   2.187 +     # Configure vnets. Refer to vifs by id.
   2.188 +     (vnet (vif (id vif1) (vnet 1))
   2.189 +           (vif (id vif2) (vnet 2)))
   2.190 +
   2.191 +)
   2.192 +</pre></code>
   2.193 +
   2.194 +</body>
   2.195 +</html>