diff --git a/ChangeLog b/ChangeLog index 808c5a2b14..507323b8e3 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +Tue Apr 29 10:06:00 EST 2008 Daniel P. Berrange + + * 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 * src/hash.c: remove bogus test code accidentally added in diff --git a/docs/formatnetwork.html b/docs/formatnetwork.html index 42584de88a..e951cd7885 100644 --- a/docs/formatnetwork.html +++ b/docs/formatnetwork.html @@ -114,8 +114,104 @@

Network XML format

+

+ This page provides an introduction to the network XML format. For background + information on the concepts referred to here, consult the network driver architecture + page. +

+

Element and attribute overview

+

+ The root element required for all virtual networks is + named network and has no attributes. +

+

General metadata

+

+ The first elements provide basic metadata about the virtual + network. +

+ 
+      <network>
+        <name>default</name>
+        <uuid>3e3fce45-4f53-4fa7-bb32-11f34168b82b</uuid>
+        ...
+
name
The content of the name 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.
uuid
The content of the uuid element provides + a globally unique identifier for the virtual network. + The format must be RFC 4122 compliant, eg 3e3fce45-4f53-4fa7-bb32-11f34168b82b. + If omitted when defining/creating a new network, a random + UUID is generated.
+

Connectivity

+

+ The next set of elements control how a virtual network is + provided connectivity to the physical LAN (if at all). +

+ 
+        ...
+        <bridge name="virbr0" />
+	<forward type="nat"/>
+	...
+
bridge
The name attribute on the bridge 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 vir, but the name + virbr0 is reserved for the "default" virtual network. + This element should always be provided when defining a new network +
forward
Inclusion of the forward 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 dev attribute + is set, the firewall rules will restrict forwarding to the named + device only. If the type attribute is set to route + 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.
+

Addressing

+

+ The final set of elements define the IPv4 address range available, + and optionally enable DHCP sevices. +

+ 
+        ...
+	<ip address="192.168.122.1" netmask="255.255.255.0">
+	  <dhcp>
+	    <range start="192.168.122.2" end="192.168.122.254" />
+	  </dhcp>
+	</ip>
+      </network>
+
ip
The address 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 netmask + attribute defines the significant bits of the network address, + again specified in dotted-decimal format. +
dhcp
Immediately within the ip element there is an + optional dhcp element. The presence of this element + enables DHCP services on the virtual network. It will further + contain one or more range elements. +
range
The start and end attributes on the + range 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 + ip element. +

Example configuration

NAT based network

+

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

       <network>
 	<name>default</name>
@@ -128,6 +224,14 @@
 	</ip>
       </network>

Routed network config

+

+ 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 + eth1 host network device. + 

       <network>
 	<name>local</name>
@@ -140,6 +244,13 @@
 	</ip>
       </network>

Isolated network config

+

+ 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 forward element in the XML + description. + 

       <network>
 	<name>private</name>
diff --git a/docs/formatnetwork.html.in b/docs/formatnetwork.html.in
index 1932bf061f..d3da000321 100644
--- a/docs/formatnetwork.html.in
+++ b/docs/formatnetwork.html.in
@@ -2,11 +2,139 @@
   
     
Network XML format

 
+    

+      This page provides an introduction to the network XML format. For background
+      information on the concepts referred to here, consult the network driver architecture
+      page.
+    

+
+    
Element and attribute overview

+
+    

+      The root element required for all virtual networks is
+      named network and has no attributes.
+    

+
+    
General metadata

+
+    

+      The first elements provide basic metadata about the virtual
+      network.
+    

+
+    
+      <network>
+        <name>default</name>
+        <uuid>3e3fce45-4f53-4fa7-bb32-11f34168b82b</uuid>
+        ...

+
+    

+      
name

+      
The content of the name 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.

+      
uuid

+      
The content of the uuid element provides
+	a globally unique identifier for the virtual network.
+	The format must be RFC 4122 compliant, eg 3e3fce45-4f53-4fa7-bb32-11f34168b82b.
+	If omitted when defining/creating a new network, a random
+	UUID is generated.

+    

+
+    
Connectivity

+
+    

+      The next set of elements control how a virtual network is
+      provided connectivity to the physical LAN (if at all).
+    

+
+    
+        ...
+        <bridge name="virbr0" />
+	<forward type="nat"/>
+	...

+
+    

+      
bridge

+      
The name attribute on the bridge 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 vir, but the name
+	virbr0 is reserved for the "default" virtual network.
+	This element should always be provided when defining a new network
+      

+      
forward

+      
Inclusion of the forward 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 dev attribute
+	is set, the firewall rules will restrict forwarding to the named
+	device only. If the type attribute is set to route
+	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.

+    

+
+    
Addressing

+
+    

+      The final set of elements define the IPv4 address range available,
+      and optionally enable DHCP sevices.
+    

+
+    
+        ...
+	<ip address="192.168.122.1" netmask="255.255.255.0">
+	  <dhcp>
+	    <range start="192.168.122.2" end="192.168.122.254" />
+	  </dhcp>
+	</ip>
+      </network>

+
+    

+      
ip

+      
The address 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 netmask
+	attribute defines the significant bits of the network address,
+	again specified in dotted-decimal format.
+      

+      
dhcp

+      
Immediately within the ip element there is an
+	optional dhcp element. The presence of this element
+	enables DHCP services on the virtual network. It will further
+	contain one or more range elements.
+      

+      
range

+      
The start and end attributes on the
+	range 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
+	ip element.
+      

+    

 
     
Example configuration

 
     
NAT based network

 
+    

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

+
     
       <network>
 	<name>default</name>
@@ -21,6 +149,15 @@
 
     
Routed network config

 
+    

+      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
+      eth1 host network device.
+    

+
     
       <network>
 	<name>local</name>
@@ -35,6 +172,14 @@
 
     
Isolated network config

 
+    

+      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 forward element in the XML
+      description.
+    

+
     
       <network>
 	<name>private</name>