[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...
Dan.
Index: formatnetwork.html.in
===================================================================
RCS file: /data/cvs/libvirt/docs/formatnetwork.html.in,v
retrieving revision 1.1
diff -r1.1 formatnetwork.html.in
4a5,122
> <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="192.168.122.1" netmask="255.255.255.0">
> <dhcp>
> <range start="192.168.122.2" end="192.168.122.254" />
> </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>
9a128,137
> <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>
>
23a152,160
> <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>
>
37a175,182
> <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