Added network XML docs

diff --git a/ChangeLog b/ChangeLog
index 808c5a2b14604edb82b2ca5c63f13a29d746d1c1..507323b8e3565ea633af5697b036791218e50730 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+Tue Apr 29 10:06:00 EST 2008 Daniel P. Berrange <berrange@redhat.com>
+
+       * docs/formatnetwork.html, docs/formatnetwork.html.in: Added
+       docs on XML format for networks
+
 Tue Apr 29 09:46:00 EST 2008 Daniel P. Berrange <berrange@redhat.com>
 
        * src/hash.c: remove bogus test code accidentally added in

diff --git a/docs/formatnetwork.html b/docs/formatnetwork.html
index 42584de88a421a11ea68392d6060d8965f4ebb2f..e951cd788583ff66b87d2bdb3469163f7dd1c2ee 100644 (file)
--- a/docs/formatnetwork.html
+++ b/docs/formatnetwork.html
@@ -114,8 +114,104 @@
       </div>
       <div id="content">
         <h1>Network XML format</h1>
+        <p>
+      This page provides an introduction to the network XML format. For background
+      information on the concepts referred to here, consult the <a href="archnetwork.html">network driver architecture</a>
+      page.
+    </p>
+        <h2>Element and attribute overview</h2>
+        <p>
+      The root element required for all virtual networks is
+      named <code>network</code> and has no attributes.
+    </p>
+        <h3>General metadata</h3>
+        <p>
+      The first elements provide basic metadata about the virtual
+      network.
+    </p>
+        <pre>
+      &lt;network&gt;
+        &lt;name&gt;default&lt;/name&gt;
+        &lt;uuid&gt;3e3fce45-4f53-4fa7-bb32-11f34168b82b&lt;/uuid&gt;
+        ...</pre>
+        <dl><dt><code>name</code></dt><dd>The content of the <code>name</code> element provides
+       a short name for the virtual network. This name should
+       consist only of alpha-numeric characters and is required
+       to be unique within the scope of a single host. It is
+       used to form the filename for storing the persistent
+       configuration file.</dd><dt><code>uuid</code></dt><dd>The content of the <code>uuid</code> element provides
+       a globally unique identifier for the virtual network.
+       The format must be RFC 4122 compliant, eg <code>3e3fce45-4f53-4fa7-bb32-11f34168b82b</code>.
+       If omitted when defining/creating a new network, a random
+       UUID is generated.</dd></dl>
+        <h3>Connectivity</h3>
+        <p>
+      The next set of elements control how a virtual network is
+      provided connectivity to the physical LAN (if at all).
+    </p>
+        <pre>
+        ...
+        &lt;bridge name="virbr0" /&gt;
+       &lt;forward type="nat"/&gt;
+       ...</pre>
+        <dl><dt><code>bridge</code></dt><dd>The <code>name</code> attribute on the <code>bridge</code> element
+       defines the name of a bridge device which will be used to construct
+       the virtual network. The virtual machines will be connected to this
+       bridge device allowing them to talk to each other. The bridge device
+       may also be connected to the LAN. It is recommended that bridge
+       device names started with the prefix <code>vir</code>, but the name
+       <code>virbr0</code> is reserved for the "default" virtual network.
+       This element should always be provided when defining a new network
+      </dd><dt><code>forward</code></dt><dd>Inclusion of the <code>forward</code> element indicates that
+       the virtual network is to be connected to the physical LAN. If
+       no attributes are set, NAT forwarding will be used for connectivity.
+       Firewall rules will allow forwarding to any other network device whether
+       ethernet, wireless, dialup, or VPN. If the <code>dev</code> attribute
+       is set, the firewall rules will restrict forwarding to the named
+       device only. If the <code>type</code> attribute is set to <code>route</code>
+       then the traffic will not have NAT applied. This presumes that the
+       local LAN router has suitable routing table entries to return traffic
+       to this host.</dd></dl>
+        <h3>Addressing</h3>
+        <p>
+      The final set of elements define the IPv4 address range available,
+      and optionally enable DHCP sevices.
+    </p>
+        <pre>
+        ...
+       &lt;ip address="192.168.122.1" netmask="255.255.255.0"&gt;
+         &lt;dhcp&gt;
+           &lt;range start="192.168.122.2" end="192.168.122.254" /&gt;
+         &lt;/dhcp&gt;
+       &lt;/ip&gt;
+      &lt;/network&gt;</pre>
+        <dl><dt><code>ip</code></dt><dd>The <code>address</code> attribute defines an IPv4 address in
+       dotted-decimal format, that will be configured on the bridge
+       device associated with the virtual network. To the guests this
+       address will be their default route. The <code>netmask</code>
+       attribute defines the significant bits of the network address,
+       again specified in dotted-decimal format.
+      </dd><dt><code>dhcp</code></dt><dd>Immediately within the <code>ip</code> element there is an
+       optional <code>dhcp</code> element. The presence of this element
+       enables DHCP services on the virtual network. It will further
+       contain one or more <code>range</code> elements.
+      </dd><dt><code>range</code></dt><dd>The <code>start</code> and <code>end</code> attributes on the
+       <code>range</code> element specify the boundaries of a pool of
+       IPv4 addresses to be provided to DHCP clients. These two addresses
+       must lie within the scope of the network defined on the parent
+       <code>ip</code> element.
+      </dd></dl>
         <h2>Example configuration</h2>
         <h3>NAT based network</h3>
+        <p>
+      This example is the so called "default" virtual network. It is
+      provided and enabled out-of-the-box for all libvirt installations.
+      This is a configuration that allows guest OS to get outbound
+      connectivity regardless of whether the host uses ethernet, wireless,
+      dialup, or VPN networking without requiring any specific admin
+      configuration. In the absence of host networking, it at least allows
+      guests to talk directly to each other.
+    </p>
         <pre>
       &lt;network&gt;
        &lt;name&gt;default&lt;/name&gt;
@@ -128,6 +224,14 @@
        &lt;/ip&gt;
       &lt;/network&gt;</pre>
         <h3>Routed network config</h3>
+        <p>
+      This is a variant on the default network which routes traffic
+      from the virtual network to the LAN without applying any NAT.
+      It requires that the IP address range be pre-configured in the
+      routing tables of the router on the host network. This example
+      further specifies that guest traffic may only go out via the
+      <code>eth1</code> host network device.
+    </p>
         <pre>
       &lt;network&gt;
        &lt;name&gt;local&lt;/name&gt;
@@ -140,6 +244,13 @@
        &lt;/ip&gt;
       &lt;/network&gt;</pre>
         <h3>Isolated network config</h3>
+        <p>
+      This variant provides a completely isolated private network
+      for guests. The guests can talk to each other, and the host
+      OS, but cannot reach any other machines on the LAN, due to
+      the omission of the <code>forward</code> element in the XML
+      description.
+    </p>
         <pre>
       &lt;network&gt;
        &lt;name&gt;private&lt;/name&gt;

diff --git a/docs/formatnetwork.html.in b/docs/formatnetwork.html.in
index 1932bf061ff31b6ca33b043bba6dd86dd321be2a..d3da0003218b1f64570247076a1d78c640d14a63 100644 (file)
--- a/docs/formatnetwork.html.in
+++ b/docs/formatnetwork.html.in
@@ -2,11 +2,139 @@
   <body>
     <h1>Network XML format</h1>
 
+    <p>
+      This page provides an introduction to the network XML format. For background
+      information on the concepts referred to here, consult the <a href="archnetwork.html">network driver architecture</a>
+      page.
+    </p>
+
+    <h2>Element and attribute overview</h2>
+
+    <p>
+      The root element required for all virtual networks is
+      named <code>network</code> and has no attributes.
+    </p>
+
+    <h3>General metadata</h3>
+
+    <p>
+      The first elements provide basic metadata about the virtual
+      network.
+    </p>
+
+    <pre>
+      &lt;network&gt;
+        &lt;name&gt;default&lt;/name&gt;
+        &lt;uuid&gt;3e3fce45-4f53-4fa7-bb32-11f34168b82b&lt;/uuid&gt;
+        ...</pre>
+
+    <dl>
+      <dt><code>name</code></dt>
+      <dd>The content of the <code>name</code> element provides
+       a short name for the virtual network. This name should
+       consist only of alpha-numeric characters and is required
+       to be unique within the scope of a single host. It is
+       used to form the filename for storing the persistent
+       configuration file.</dd>
+      <dt><code>uuid</code></dt>
+      <dd>The content of the <code>uuid</code> element provides
+       a globally unique identifier for the virtual network.
+       The format must be RFC 4122 compliant, eg <code>3e3fce45-4f53-4fa7-bb32-11f34168b82b</code>.
+       If omitted when defining/creating a new network, a random
+       UUID is generated.</dd>
+    </dl>
+
+    <h3>Connectivity</h3>
+
+    <p>
+      The next set of elements control how a virtual network is
+      provided connectivity to the physical LAN (if at all).
+    </p>
+
+    <pre>
+        ...
+        &lt;bridge name="virbr0" /&gt;
+       &lt;forward type="nat"/&gt;
+       ...</pre>
+
+    <dl>
+      <dt><code>bridge</code></dt>
+      <dd>The <code>name</code> attribute on the <code>bridge</code> element
+       defines the name of a bridge device which will be used to construct
+       the virtual network. The virtual machines will be connected to this
+       bridge device allowing them to talk to each other. The bridge device
+       may also be connected to the LAN. It is recommended that bridge
+       device names started with the prefix <code>vir</code>, but the name
+       <code>virbr0</code> is reserved for the "default" virtual network.
+       This element should always be provided when defining a new network
+      </dd>
+      <dt><code>forward</code></dt>
+      <dd>Inclusion of the <code>forward</code> element indicates that
+       the virtual network is to be connected to the physical LAN. If
+       no attributes are set, NAT forwarding will be used for connectivity.
+       Firewall rules will allow forwarding to any other network device whether
+       ethernet, wireless, dialup, or VPN. If the <code>dev</code> attribute
+       is set, the firewall rules will restrict forwarding to the named
+       device only. If the <code>type</code> attribute is set to <code>route</code>
+       then the traffic will not have NAT applied. This presumes that the
+       local LAN router has suitable routing table entries to return traffic
+       to this host.</dd>
+    </dl>
+
+    <h3>Addressing</h3>
+
+    <p>
+      The final set of elements define the IPv4 address range available,
+      and optionally enable DHCP sevices.
+    </p>
+
+    <pre>
+        ...
+       &lt;ip address="192.168.122.1" netmask="255.255.255.0"&gt;
+         &lt;dhcp&gt;
+           &lt;range start="192.168.122.2" end="192.168.122.254" /&gt;
+         &lt;/dhcp&gt;
+       &lt;/ip&gt;
+      &lt;/network&gt;</pre>
+
+    <dl>
+      <dt><code>ip</code></dt>
+      <dd>The <code>address</code> attribute defines an IPv4 address in
+       dotted-decimal format, that will be configured on the bridge
+       device associated with the virtual network. To the guests this
+       address will be their default route. The <code>netmask</code>
+       attribute defines the significant bits of the network address,
+       again specified in dotted-decimal format.
+      </dd>
+      <dt><code>dhcp</code></dt>
+      <dd>Immediately within the <code>ip</code> element there is an
+       optional <code>dhcp</code> element. The presence of this element
+       enables DHCP services on the virtual network. It will further
+       contain one or more <code>range</code> elements.
+      </dd>
+      <dt><code>range</code></dt>
+      <dd>The <code>start</code> and <code>end</code> attributes on the
+       <code>range</code> element specify the boundaries of a pool of
+       IPv4 addresses to be provided to DHCP clients. These two addresses
+       must lie within the scope of the network defined on the parent
+       <code>ip</code> element.
+      </dd>
+    </dl>
 
     <h2>Example configuration</h2>
 
     <h3>NAT based network</h3>
 
+    <p>
+      This example is the so called "default" virtual network. It is
+      provided and enabled out-of-the-box for all libvirt installations.
+      This is a configuration that allows guest OS to get outbound
+      connectivity regardless of whether the host uses ethernet, wireless,
+      dialup, or VPN networking without requiring any specific admin
+      configuration. In the absence of host networking, it at least allows
+      guests to talk directly to each other.
+    </p>
+
     <pre>
       &lt;network&gt;
        &lt;name&gt;default&lt;/name&gt;
@@ -21,6 +149,15 @@
 
     <h3>Routed network config</h3>
 
+    <p>
+      This is a variant on the default network which routes traffic
+      from the virtual network to the LAN without applying any NAT.
+      It requires that the IP address range be pre-configured in the
+      routing tables of the router on the host network. This example
+      further specifies that guest traffic may only go out via the
+      <code>eth1</code> host network device.
+    </p>
+
     <pre>
       &lt;network&gt;
        &lt;name&gt;local&lt;/name&gt;
@@ -35,6 +172,14 @@
 
     <h3>Isolated network config</h3>
 
+    <p>
+      This variant provides a completely isolated private network
+      for guests. The guests can talk to each other, and the host
+      OS, but cannot reach any other machines on the LAN, due to
+      the omission of the <code>forward</code> element in the XML
+      description.
+    </p>
+
     <pre>
       &lt;network&gt;
        &lt;name&gt;private&lt;/name&gt;