[Libvir] PATCH: Add docs on the network XML format

Daniel P. Berrange berrange at redhat.com
Tue Apr 29 02:27:07 UTC 2008

This patch fills in the network driver XML format page on
the website which has been requested many times...


Index: formatnetwork.html.in
RCS file: /data/cvs/libvirt/docs/formatnetwork.html.in,v
retrieving revision 1.1
diff -r1.1 formatnetwork.html.in
>     <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>
>       <network>
>         <name>default</name>
>         <uuid>3e3fce45-4f53-4fa7-bb32-11f34168b82b</uuid>
>         ...</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>
>         ...
>         <bridge name="virbr0" />
> 	<forward type="nat"/>
> 	...</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>
>         ...
> 	<ip address="" netmask="">
> 	  <dhcp>
> 	    <range start="" end="" />
> 	  </dhcp>
> 	</ip>
>       </network></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>
>     <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>
>     <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>
>     <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>

|: Red Hat, Engineering, Boston   -o-   http://people.redhat.com/berrange/ :|
|: http://libvirt.org  -o-  http://virt-manager.org  -o-  http://ovirt.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: GnuPG: 7D3B9505  -o-  F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|

More information about the libvir-list mailing list