docs/formatnetwork.html.in

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html>
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4   <body>
   5     <h1>Network XML format</h1>
   6
   7     <ul id="toc">
   8     </ul>
   9
  10     <p>
  11       This page provides an introduction to the network XML format. For
  12       background information on the concepts referred to here, consult the
  13       <a href="https://wiki.libvirt.org/page/Networking">relevant wiki page</a>.
  14     </p>
  15
  16     <h2><a id="elements">Element and attribute overview</a></h2>
  17
  18     <p>
  19       The root element required for all virtual networks is
  20       named <code>network</code> and has no configurable attributes
  21       (although <span class="since">since 0.10.0</span> there is one
  22       optional read-only attribute - when examining the live
  23       configuration of a network, the
  24       attribute <code>connections</code>, if present, specifies the
  25       number of guest interfaces currently connected via this
  26       network).  The network XML format is
  27       available <span class="since">since 0.3.0</span>
  28     </p>
  29
  30     <h3><a id="elementsMetadata">General metadata</a></h3>
  31
  32     <p>
  33       The first elements provide basic metadata about the virtual
  34       network.
  35     </p>
  36
  37     <pre>
  38 &lt;network ipv6='yes' trustGuestRxFilters='no'&gt;
  39   &lt;name&gt;default&lt;/name&gt;
  40   &lt;uuid&gt;3e3fce45-4f53-4fa7-bb32-11f34168b82b&lt;/uuid&gt;
  41   &lt;metadata&gt;
  42     &lt;app1:foo xmlns:app1="http://app1.org/app1/"&gt;..&lt;/app1:foo&gt;
  43     &lt;app2:bar xmlns:app2="http://app1.org/app2/"&gt;..&lt;/app2:bar&gt;
  44   &lt;/metadata&gt;
  45   ...</pre>
  46
  47     <dl>
  48       <dt><code>name</code></dt>
  49       <dd>The content of the <code>name</code> element provides
  50         a short name for the virtual network. This name should
  51         consist only of alpha-numeric characters and is required
  52         to be unique within the scope of a single host. It is
  53         used to form the filename for storing the persistent
  54         configuration file. <span class="since">Since 0.3.0</span></dd>
  55       <dt><code>uuid</code></dt>
  56       <dd>The content of the <code>uuid</code> element provides
  57         a globally unique identifier for the virtual network.
  58         The format must be RFC 4122 compliant, eg <code>3e3fce45-4f53-4fa7-bb32-11f34168b82b</code>.
  59         If omitted when defining/creating a new network, a random
  60         UUID is generated. <span class="since">Since 0.3.0</span></dd>
  61       <dd>The <code>metadata</code> node can be used by applications to
  62         store custom metadata in the form of XML nodes/trees. Applications
  63         must use custom namespaces on their XML nodes/trees, with only
  64         one top-level element per namespace (if the application needs
  65         structure, they should have sub-elements to their namespace
  66         element). <span class="since">Since 2.1.0</span></dd>
  67       <dt><code>ipv6</code></dt>
  68       <dd>When set to <code>yes</code>, the optional parameter
  69         <code>ipv6</code> enables
  70         a network definition with no IPv6 gateway addresses specified
  71         to have guest-to-guest communications.  For further information,
  72         see the example below for the example with no gateway addresses.
  73         <span class="since">Since 1.0.1</span></dd>
  74       <dt><code>trustGuestRxFilters</code></dt>
  75       <dd>The optional parameter <code>trustGuestRxFilters</code> can
  76         be used to set that attribute of the same name for each domain
  77         interface connected to this network (<span class="since">since
  78         1.2.10</span>). See
  79         the <a href="formatdomain.html#elementsNICS">Network
  80         interfaces</a> section of the domain XML documentation for
  81         more details. Note that an explicit setting of this attribute
  82         in a portgroup or the individual domain interface will
  83         override the setting in the network.</dd>
  84     </dl>
  85
  86     <h3><a id="elementsConnect">Connectivity</a></h3>
  87
  88     <p>
  89       The next set of elements control how a virtual network is
  90       provided connectivity to the physical LAN (if at all).
  91     </p>
  92
  93     <pre>
  94 ...
  95 &lt;bridge name="virbr0" stp="on" delay="5" macTableManager="libvirt"/&gt;
  96 &lt;mtu size="9000"/&gt;
  97 &lt;domain name="example.com" localOnly="no"/&gt;
  98 &lt;forward mode="nat" dev="eth0"/&gt;
  99 ...</pre>
 100
 101     <dl>
 102       <dt><code>bridge</code></dt>
 103       <dd>The <code>name</code> attribute on the <code>bridge</code> element
 104         defines the name of a bridge device which will be used to construct
 105         the virtual network. The virtual machines will be connected to this
 106         bridge device allowing them to talk to each other. The bridge device
 107         may also be connected to the LAN. When defining
 108         a new network with a <code>&lt;forward&gt;</code> mode of
 109
 110         "nat", "route", or "open" (or an isolated network with
 111         no <code>&lt;forward&gt;</code> element), libvirt will
 112         automatically generate a unique name for the bridge device if
 113         none is given, and this name will be permanently stored in the
 114         network configuration so that that the same name will be used
 115         every time the network is started. For these types of networks
 116         (nat, route, open, and isolated), a bridge name beginning with the
 117         prefix "virbr" is recommended (and that is what is
 118         auto-generated), but not enforced.
 119         Attribute <code>stp</code> specifies if Spanning Tree Protocol
 120         is 'on' or 'off' (default is
 121         'on'). Attribute <code>delay</code> sets the bridge's forward
 122         delay value in seconds (default is 0).
 123         <span class="since">Since 0.3.0</span>
 124
 125         <p>
 126           The <code>macTableManager</code> attribute of the bridge
 127           element is used to tell libvirt how the bridge's MAC address
 128           table (used to determine the correct egress port for packets
 129           based on destination MAC address) will be managed. In the
 130           default <code>kernel</code> setting, the kernel
 131           automatically adds and removes entries, typically using
 132           learning, flooding, and promiscuous mode on the bridge's
 133           ports in order to determine the proper egress port for
 134           packets.  When <code>macTableManager</code> is set
 135           to <code>libvirt</code>, libvirt disables kernel management
 136           of the MAC table (in the case of the Linux host bridge, this
 137           means enabling vlan_filtering on the bridge, and disabling
 138           learning and unicast_filter for all bridge ports), and
 139           explicitly adds/removes entries to the table according to
 140           the MAC addresses in the domain interface configurations.
 141           Allowing libvirt to manage the MAC table can improve
 142           performance - with a Linux host bridge, for example, turning
 143           off learning and unicast_flood on ports has its own
 144           performance advantage, and can also lead to an additional
 145           boost by permitting the kernel to automatically turn off
 146           promiscuous mode on some ports of the bridge (in particular,
 147           the port attaching the bridge to the physical
 148           network). However, it can also cause some networking setups
 149           to stop working (e.g. vlan tagging, multicast,
 150           guest-initiated changes to MAC address) and is not supported
 151           by older kernels.
 152           <span class="since">Since 1.2.11, requires kernel 3.17 or
 153           newer</span>
 154         </p>
 155
 156         <p>
 157           The optional <code>zone</code> attribute of
 158           the <code>bridge</code> element is used to specify
 159           the <a href="https://firewalld.org">firewalld</a>
 160           zone for the bridge of a network with <code>forward</code>
 161           mode of "nat", "route", "open", or one with
 162           no <code>forward</code> specified. By default, the bridges
 163           of all virtual networks with these forward modes are placed
 164           in the firewalld zone named "libvirt", which permits
 165           incoming DNS, DHCP, TFTP, and SSH to the host from guests on
 166           the network. This behavior can be changed either by
 167           modifying the libvirt zone (using firewalld management
 168           tools), or by placing the network in a different zone (which
 169           will also be managed using firewalld tools).
 170           <span class="since">Since 5.1.0</span>
 171         </p>
 172       </dd>
 173
 174       <dt><code>mtu</code></dt>
 175       <dd>
 176         The <code>size</code> attribute of the <code>mtu></code>
 177         element specifies the Maximum Transmission Unit (MTU) for the
 178         network. <span class="since">Since 3.1.0</span>. In the case
 179         of a libvirt-managed network (one with forward mode
 180         of <code>nat</code>, <code>route</code>, <code>open</code>, or
 181         no <code>forward</code> element (i.e. an isolated network),
 182         this will be the MTU assigned to the bridge device when
 183         libvirt creates it, and thereafter also assigned to all tap
 184         devices created to connect guest interfaces. Network types not
 185         specifically mentioned here don't support having an MTU set in
 186         the libvirt network config. If mtu size is unspecified, the
 187         default setting for the type of device being used is assumed
 188         (usually 1500).
 189       </dd>
 190
 191       <dt><code>domain</code></dt>
 192       <dd>
 193         The <code>name</code> attribute on the <code>domain</code>
 194         element defines the DNS domain of the DHCP server. This
 195         element is optional, and is only used for those networks with
 196         a <code>&lt;forward&gt;</code> mode of "nat" or "route" (or an
 197         isolated network with no <code>&lt;forward&gt;</code>
 198         element). <span class="since">Since 0.4.5</span>
 199
 200         <p>
 201           If the optional <code>localOnly</code> attribute on the
 202           <code>domain</code> element is "yes", then DNS requests under
 203           this domain will only be resolved by the virtual network's own
 204           DNS server - they will not be forwarded to the host's upstream
 205           DNS server.  If <code>localOnly</code> is "no", and by
 206           default, unresolved requests <b>will</b> be forwarded.
 207           <span class="since">Since 1.2.12</span>
 208         </p>
 209       </dd>
 210       <dt><code>forward</code></dt>
 211       <dd>Inclusion of the <code>forward</code> element indicates that
 212         the virtual network is to be connected to the physical
 213         LAN.<span class="since">Since 0.3.0.</span>
 214         The <code>mode</code> attribute determines the method of
 215         forwarding. If there is no <code>forward</code> element, the
 216         network will be isolated from any other network (unless a
 217         guest connected to that network is acting as a router, of
 218         course). The following are valid settings
 219         for <code>mode</code> (if there is a <code>forward</code>
 220         element but mode is not specified, <code>mode='nat'</code> is
 221         assumed):
 222         <dl>
 223           <dt><code>nat</code></dt>
 224           <dd>
 225             All traffic between guests connected to this network and
 226             the physical network will be forwarded to the physical
 227             network via the host's IP routing stack, after the guest's
 228             IP address is translated to appear as the host machine's
 229             public IP address (a.k.a. Network Address Translation, or
 230             "NAT"). This allows multiple guests, all having access to
 231             the physical network, on a host that is only allowed a
 232             single public IP address. If a network has any IPv6
 233             addresses defined, the IPv6 traffic will be forwarded
 234             using plain routing, since IPv6 has no concept of NAT.
 235             Firewall rules will allow outbound connections to any
 236             other network device whether ethernet, wireless, dialup,
 237             or VPN. If the <code>dev</code> attribute is set, the
 238             firewall rules will restrict forwarding to the named
 239             device only. Inbound connections from other networks are
 240             all prohibited; all connections between guests on the same
 241             network, and to/from the host to the guests, are
 242             unrestricted and not NATed.<span class="since">Since
 243             0.4.2</span>
 244
 245             <p><span class="since">Since 1.0.3</span> it is possible to
 246             specify a public IPv4 address and port range to be used for
 247             the NAT by using the <code>&lt;nat&gt;</code> subelement.
 248             Note that all addresses from the range are used, not just those
 249             that are in use on the host.
 250             The address range is set with the <code>&lt;address&gt;</code>
 251             subelements and <code>start</code> and <code>stop</code>
 252             attributes:
 253             </p>
 254             <pre>
 255 ...
 256   &lt;forward mode='nat'&gt;
 257     &lt;nat&gt;
 258       &lt;address start='1.2.3.4' end='1.2.3.10'/&gt;
 259     &lt;/nat&gt;
 260   &lt;/forward&gt;
 261 ...</pre>
 262             <p>
 263             A single IPv4 address can be set by setting
 264             <code>start</code> and <code>end</code> attributes to
 265             the same value.
 266             </p>
 267             <p>
 268             The port range to be used for the <code>&lt;nat&gt;</code> can
 269             be set via the subelement <code>&lt;port&gt;</code>:
 270             </p>
 271             <pre>
 272 ...
 273   &lt;forward mode='nat'&gt;
 274     &lt;nat&gt;
 275       &lt;port start='500' end='1000'/&gt;
 276     &lt;/nat&gt;
 277   &lt;/forward&gt;
 278 ...</pre>
 279           </dd>
 280
 281           <dt><code>route</code></dt>
 282           <dd>
 283             Guest network traffic will be forwarded to the physical
 284             network via the host's IP routing stack, but without
 285             having NAT applied. Again, if the <code>dev</code>
 286             attribute is set, firewall rules will restrict forwarding
 287             to the named device only. This presumes that the local LAN
 288             router has suitable routing table entries to return
 289             traffic to this host. All incoming and outgoing sessions
 290             to guest on these networks are unrestricted. (To restrict
 291             incoming traffic to a guest on a routed network, you can
 292             configure <a href="formatnwfilter.html">nwfilter rules</a>
 293             on the guest's interfaces.)
 294             <span class="since">Since 0.4.2</span>
 295           </dd>
 296
 297           <dt><code>open</code></dt>
 298           <dd>
 299             As with mode='route', guest network traffic will be
 300             forwarded to the physical network via the host's IP
 301             routing stack, but there will be no firewall rules added
 302             to either enable or prevent any of this traffic. When
 303             forward='open' is set, the <code>dev</code> attribute
 304             cannot be set (because the forward dev is enforced with
 305             firewall rules, and the purpose of forward='open' is to
 306             have a forwarding mode where libvirt doesn't add any
 307             firewall rules).  This mode presumes that the local LAN
 308             router has suitable routing table entries to return
 309             traffic to this host, and that some other management
 310             system has been used to put in place any necessary
 311             firewall rules. Although no firewall rules will be added
 312             for the network, it is of course still possible to add
 313             restrictions for specific guests using
 314             <a href="formatnwfilter.html">nwfilter rules</a> on the
 315             guests' interfaces.)
 316             <span class="since">Since 2.2.0</span>
 317           </dd>
 318
 319           <dt><code>bridge</code></dt>
 320           <dd>
 321             This network describes either 1) an existing host bridge
 322             that was configured outside of libvirt (if
 323             a <code>&lt;bridge name='xyz'/&gt;</code> element has been
 324             specified, <span class="since">Since 0.9.4</span>), 2) an
 325             existing Open vSwitch bridge that was configured outside of
 326             libvirt (if both a <code>&lt;bridge name='xyz'/&gt;</code>
 327             element <b>and</b> a <code>&lt;virtualport
 328             type='openvswitch'/&gt;</code> have been
 329             specified <span class="since">Since 0.10.0</span>) 3) an
 330             interface or group of interfaces to be used for a "direct"
 331             connection via macvtap using macvtap's "bridge" mode (if
 332             the forward element has one or
 333             more <code>&lt;interface&gt;</code>
 334             subelements, <span class="since">Since 0.9.4</span>)
 335             (see <a href="formatdomain.html#elementsNICSDirect">Direct
 336             attachment to physical interface</a> for descriptions of
 337             the various macvtap modes). libvirt doesn't attempt to
 338             manage the bridge interface at all, thus
 339             the <code>&lt;bridge&gt;</code> element's <code>stp</code>
 340             and <code>delay</code> attributes are not allowed; no
 341             iptables rules, IP addresses, or DHCP/DNS services are
 342             added; at the IP level, the guest interface appears to be
 343             directly connected to the physical
 344             interface.<span class="since">Since 0.9.4</span>
 345           </dd>
 346           <dt><code>private</code></dt>
 347           <dd>
 348             This network uses a macvtap "direct" connection in
 349             "private" mode to connect each guest to the network. The
 350             physical interface to be used will be picked from among
 351             those listed in <code>&lt;interface&gt;</code> subelements
 352             of the <code>&lt;forward&gt;</code> element; when using
 353             802.1Qbh mode (as indicated by
 354             the <code>&lt;virtualport&gt;</code> type attribute - note
 355             that this requires an 802.1Qbh-capable hardware switch),
 356             each physical interface can only be in use by a single
 357             guest interface at a time; in modes other than 802.1Qbh,
 358             multiple guest interfaces can share each physical
 359             interface (libvirt will attempt to balance usage between
 360             all available interfaces).<span class="since">Since
 361             0.9.4</span>
 362           </dd>
 363           <dt><code>vepa</code></dt>
 364           <dd>
 365             This network uses a macvtap "direct" connection in "vepa"
 366             mode to connect each guest to the network (this requires
 367             that the physical interfaces used be connected to a
 368             vepa-capable hardware switch. The physical interface to be
 369             used will be picked from among those listed
 370             in <code>&lt;interface&gt;</code> subelements of
 371             the <code>&lt;forward&gt;</code> element; multiple guest
 372             interfaces can share each physical interface (libvirt will
 373             attempt to balance usage between all available
 374             interfaces).<span class="since">Since 0.9.4</span>
 375           </dd>
 376           <dt><code>passthrough</code></dt>
 377           <dd>
 378             This network uses a macvtap "direct" connection in
 379             "passthrough" mode to connect each guest to the network
 380             (note that this is <i>not</i> the same thing as "PCI
 381             passthrough"). The physical interface to be used will be
 382             picked from among those listed
 383             in <code>&lt;interface&gt;</code> subelements of
 384             the <code>&lt;forward&gt;</code> element.  Each physical
 385             interface can only be in use by a single guest interface
 386             at a time, so libvirt will keep track of which interfaces
 387             are currently in use, and only assign unused interfaces
 388             (if there are no available physical interfaces when a
 389             domain interface is being attached, an error will be
 390             logged, and the operation causing the attach will fail
 391             (usually either a domain start, or a hotplug interface
 392             attach to a domain).<span class="since">Since 0.9.4</span>
 393           </dd>
 394           <dt><code>hostdev</code></dt>
 395           <dd>
 396             This network facilitates PCI Passthrough of a network
 397             device.  A network device is chosen from the interface
 398             pool and directly assigned to the guest using generic
 399             device passthrough, after first optionally setting the
 400             device's MAC address and vlan tag to the configured value,
 401             and optionally associating the device with an 802.1Qbh
 402             capable switch using a <code>&lt;virtualport&gt;</code>
 403             element.  Note that - due to limitations in standard
 404             single-port PCI ethernet card driver design - only SR-IOV
 405             (Single Root I/O Virtualization) virtual function (VF)
 406             devices can be assigned in this manner; to assign a
 407             standard single-port PCI or PCIe ethernet card to a guest,
 408             use the traditional <code>&lt;hostdev&gt;</code> device
 409             definition. <span class="since"> Since 0.10.0</span>
 410
 411             <p>
 412               To force use of a particular type of device assignment,
 413               a &lt;forward type='hostdev'&gt; interface can have an
 414               optional <code>driver</code> sub-element with
 415               a <code>name</code> attribute set to either "vfio" (VFIO
 416               is a new method of device assignment that is compatible
 417               with UEFI Secure Boot) or "kvm" (the legacy device
 418               assignment handled directly by the KVM kernel module)
 419               <span class="since">Since 1.0.5 (QEMU and KVM only,
 420               requires kernel 3.6 or newer)</span>. When specified,
 421               device assignment will fail if the requested method of
 422               device assignment isn't available on the host. When not
 423               specified, the default is "vfio" on systems where the
 424               VFIO driver is available and loaded, and "kvm" on older
 425               systems, or those where the VFIO driver hasn't been
 426               loaded <span class="since">Since 1.1.3</span> (prior to
 427               that the default was always "kvm").
 428             </p>
 429
 430             <p>Note that this "intelligent passthrough" of network
 431             devices is very similar to the functionality of a
 432             standard <code>&lt;hostdev&gt;</code> device, the
 433             difference being that this method allows specifying a MAC
 434             address, vlan tag, and <code>&lt;virtualport&gt;</code>
 435             for the passed-through device. If these capabilities are
 436             not required, if you have a standard single-port PCI,
 437             PCIe, or USB network card that doesn't support SR-IOV (and
 438             hence would anyway lose the configured MAC address during
 439             reset after being assigned to the guest domain), or if you
 440             are using a version of libvirt older than 0.10.0, you
 441             should use a standard
 442             <code>&lt;hostdev&gt;</code> device definition in the
 443             domain's configuration to assign the device to the guest
 444             instead of defining an <code>&lt;interface
 445             type='network'&gt;</code> pointing to a network
 446             with <code>&lt;forward mode='hostdev'/&gt;</code>.
 447             </p>
 448           </dd>
 449         </dl>
 450         As mentioned above, a <code>&lt;forward&gt;</code> element can
 451         have multiple <code>&lt;interface&gt;</code> subelements, each
 452         one giving the name of a physical interface that can be used
 453         for this network <span class="since">Since 0.9.4</span>:
 454         <pre>
 455 ...
 456   &lt;forward mode='passthrough'&gt;
 457     &lt;interface dev='eth10'/&gt;
 458     &lt;interface dev='eth11'/&gt;
 459     &lt;interface dev='eth12'/&gt;
 460     &lt;interface dev='eth13'/&gt;
 461     &lt;interface dev='eth14'/&gt;
 462   &lt;/forward&gt;
 463 ...
 464         </pre>
 465         <p>
 466           <span class="since">since 0.10.0</span>,
 467           <code>&lt;interface&gt;</code> also has an optional read-only
 468           attribute - when examining the live configuration of a
 469           network, the attribute <code>connections</code>, if present,
 470           specifies the number of guest interfaces currently connected
 471           via this physical interface.
 472         </p>
 473         <p>
 474           Additionally, <span class="since">since 0.9.10</span>, libvirt
 475           allows a shorthand for specifying all virtual interfaces
 476           associated with a single physical function, by using
 477           the <code>&lt;pf&gt;</code> subelement to call out the
 478           corresponding physical interface associated with multiple
 479           virtual interfaces:
 480         </p>
 481         <pre>
 482 ...
 483   &lt;forward mode='passthrough'&gt;
 484     &lt;pf dev='eth0'/&gt;
 485   &lt;/forward&gt;
 486 ...
 487         </pre>
 488
 489         <p>When a guest interface is being constructed, libvirt will pick
 490         an interface from this list to use for the connection. In
 491         modes where physical interfaces can be shared by multiple
 492         guest interfaces, libvirt will choose the interface that
 493         currently has the least number of connections. For those modes
 494         that do not allow sharing of the physical device (in
 495         particular, 'passthrough' mode, and 'private' mode when using
 496         802.1Qbh), libvirt will choose an unused physical interface
 497         or, if it can't find an unused interface, fail the operation.</p>
 498
 499         <p>
 500           <span class="since">since 0.10.0</span> When using forward
 501           mode 'hostdev', the interface pool is specified with a list
 502           of <code>&lt;address&gt;</code> elements, each of which has
 503           <code>&lt;type&gt;</code> (must always be <code>'pci'</code>),
 504           <code>&lt;domain&gt;</code>, <code>&lt;bus&gt;</code>,
 505           <code>&lt;slot&gt;</code>and <code>&lt;function&gt;</code>
 506           attributes.
 507         </p>
 508         <pre>
 509 ...
 510   &lt;forward mode='hostdev' managed='yes'&gt;
 511     &lt;driver name='vfio'/&gt;
 512     &lt;address type='pci' domain='0' bus='4' slot='0' function='1'/&gt;
 513     &lt;address type='pci' domain='0' bus='4' slot='0' function='2'/&gt;
 514     &lt;address type='pci' domain='0' bus='4' slot='0' function='3'/&gt;
 515   &lt;/forward&gt;
 516 ...
 517         </pre>
 518
 519         Alternatively the interface pool can also be defined using a
 520         single physical function  <code>&lt;pf&gt;</code> subelement to
 521         call out the  corresponding physical interface associated with
 522         multiple virtual interfaces (similar to passthrough mode):
 523
 524         <pre>
 525 ...
 526   &lt;forward mode='hostdev' managed='yes'&gt;
 527     &lt;pf dev='eth0'/&gt;
 528   &lt;/forward&gt;
 529 ...
 530         </pre>
 531
 532       </dd>
 533     </dl>
 534     <h5><a id="elementQoS">Quality of service</a></h5>
 535
 536 <pre>
 537 ...
 538   &lt;forward mode='nat' dev='eth0'/&gt;
 539   <b>&lt;bandwidth&gt;
 540     &lt;inbound average='1000' peak='5000' burst='5120'/&gt;
 541     &lt;outbound average='128' peak='256' burst='256'/&gt;
 542   &lt;/bandwidth&gt;</b>
 543 ...</pre>
 544
 545       <p>
 546         The <code>&lt;bandwidth&gt;</code> element allows setting
 547         quality of service for a particular network
 548         (<span class="since">since 0.9.4</span>). Setting
 549         <code>bandwidth</code> for a network is supported only
 550         for networks with a <code>&lt;forward&gt;</code> mode
 551         of <code>route</code>, <code>nat</code>, or no mode at all
 552         (i.e. an "isolated" network). Setting <code>bandwidth</code>
 553         is <b>not</b> supported for forward modes
 554         of <code>bridge</code>, <code>passthrough</code>, <code>private</code>,
 555         or <code>hostdev</code>. Attempts to do this will lead to
 556         a failure to define the network or to create a transient network.
 557       </p>
 558       <p>
 559         The <code>&lt;bandwidth&gt;</code> element can only be a
 560         subelement of a domain's <code>&lt;interface&gt;</code>, a
 561         subelement of a <code>&lt;network&gt;</code>, or a subelement of
 562         a <code>&lt;portgroup&gt;</code> in a <code>&lt;network&gt;</code>.
 563       </p>
 564       <p>
 565         As a subelement of a domain's <code>&lt;interface&gt;</code>,
 566         the bandwidth only applies to that one interface of the domain.
 567         As a subelement of a <code>&lt;network&gt;</code>, the bandwidth
 568         is a total aggregate bandwidth to/from all guest interfaces attached
 569         to that network, <b>not</b> to each guest interface individually.
 570         If a domain's <code>&lt;interface&gt;</code> has
 571         <code>&lt;bandwidth&gt;</code> element values higher
 572         than the aggregate for the entire network, then the aggregate
 573         bandwidth for the <code>&lt;network&gt;</code> takes precedence.
 574         This is because the two choke points are independent of each other
 575         where the domain's <code>&lt;interface&gt;</code> bandwidth control
 576         is applied on the interface's tap device, while the
 577         <code>&lt;network&gt;</code> bandwidth control is applied on the
 578         interface part of the bridge device created for that network.
 579       </p>
 580       <p>
 581         As a subelement of a
 582         <code>&lt;portgroup&gt;</code> in a <code>&lt;network&gt;</code>,
 583         if a domain's <code>&lt;interface&gt;</code> has a
 584         <code>portgroup</code> attribute in its
 585         <code>&lt;source&gt;</code> element <b>and</b> if the
 586         <code>&lt;interface&gt;</code>
 587         itself has no <code>&lt;bandwidth&gt;</code> element, then the
 588         <code>&lt;bandwidth&gt;</code> element of the portgroup will be
 589         applied individually to each guest interface defined to be a
 590         member of that portgroup. Any <code>&lt;bandwidth&gt;</code>
 591         element in the domain's <code>&lt;interface&gt;</code> definition
 592         will override the setting in the portgroup
 593         (<span class="since">since 1.0.1</span>).
 594       </p>
 595       <p>
 596         Incoming and outgoing traffic can be shaped independently. The
 597         <code>bandwidth</code> element can have at most one
 598         <code>inbound</code> and at most one <code>outbound</code>
 599         child element. Leaving either of these children elements out
 600         results in no QoS applied for that traffic direction.  So,
 601         when you want to shape only incoming traffic, use
 602         <code>inbound</code> only, and vice versa. Each of these
 603         elements have one mandatory attribute - <code>average</code> (or
 604         <code>floor</code> as described below). The attributes are as follows,
 605         where accepted values for each attribute is an integer number.
 606       </p>
 607         <dl>
 608           <dt><code>average</code></dt>
 609           <dd>
 610           Specifies the desired average bit rate for the interface
 611           being shaped (in kilobytes/second).
 612           </dd>
 613           <dt><code>peak</code></dt>
 614           <dd>
 615           Optional attribute which specifies the maximum rate at
 616           which the bridge can send data (in kilobytes/second).
 617           Note the limitation of implementation: this attribute in the
 618           <code>outbound</code> element is ignored (as Linux ingress
 619           filters don't know it yet).
 620           </dd>
 621           <dt><code>burst</code></dt>
 622           <dd>
 623           Optional attribute which specifies the amount of kilobytes that
 624           can be transmitted in a single burst at <code>peak</code> speed.
 625           </dd>
 626           <dt><code>floor</code></dt>
 627           <dd>
 628           Optional attribute available only for the <code>inbound</code>
 629           element. This attribute guarantees minimal throughput for
 630           shaped interfaces. This, however, requires that all traffic
 631           goes through one point where QoS decisions can take place, hence
 632           why this attribute works only for virtual networks for now
 633           (that is <code>&lt;interface type='network'/&gt;</code> with a
 634           forward type of route, nat, or no forward at all). Moreover, the
 635           virtual network the interface is connected to is required to have
 636           at least inbound QoS set (<code>average</code> at least). If
 637           using the <code>floor</code> attribute users don't need to specify
 638           <code>average</code>. However, <code>peak</code> and
 639           <code>burst</code> attributes still require <code>average</code>.
 640           Currently, the Linux kernel doesn't allow ingress qdiscs to have
 641           any classes therefore <code>floor</code> can be applied only
 642           on <code>inbound</code> and not <code>outbound</code>.
 643           </dd>
 644         </dl>
 645
 646       <p>
 647         Attributes <code>average</code>, <code>peak</code>, and
 648         <code>burst</code> are available
 649         <span class="since">since 0.9.4</span>, while the
 650         <code>floor</code> attribute is available
 651         <span class="since">since 1.0.1</span>.
 652       </p>
 653
 654     <h5><a id="elementVlanTag">Setting VLAN tag (on supported network types only)</a></h5>
 655
 656 <pre>
 657 &lt;network&gt;
 658   &lt;name&gt;ovs-net&lt;/name&gt;
 659   &lt;forward mode='bridge'/&gt;
 660   &lt;bridge name='ovsbr0'/&gt;
 661   &lt;virtualport type='openvswitch'&gt;
 662     &lt;parameters interfaceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/&gt;
 663   &lt;/virtualport&gt;
 664   <b>&lt;vlan trunk='yes'&gt;</b>
 665     <b>&lt;tag id='42' nativeMode='untagged'/&gt;</b>
 666     <b>&lt;tag id='47'/&gt;</b>
 667   <b>&lt;/vlan&gt;</b>
 668   &lt;portgroup name='dontpanic'&gt;
 669     <b>&lt;vlan&gt;</b>
 670       <b>&lt;tag id='42'/&gt;</b>
 671     <b>&lt;/vlan&gt;</b>
 672   &lt;/portgroup&gt;
 673 &lt;/network&gt;
 674 </pre>
 675
 676     <p>
 677       If (and only if) the network connection used by the guest
 678       supports VLAN tagging transparent to the guest, an
 679       optional <code>&lt;vlan&gt;</code> element can specify one or
 680       more VLAN tags to apply to the guest's network
 681       traffic <span class="since">Since 0.10.0</span>. Network
 682       connections that support guest-transparent VLAN tagging include
 683       1) type='bridge' interfaces connected to an Open vSwitch bridge
 684       <span class="since">Since 0.10.0</span>, 2) SRIOV Virtual
 685       Functions (VF) used via type='hostdev' (direct device
 686       assignment) <span class="since">Since 0.10.0</span>, and 3)
 687       SRIOV VFs used via type='direct' with mode='passthrough'
 688       (macvtap "passthru" mode) <span class="since">Since
 689       1.3.5</span>. All other connection types, including standard
 690       linux bridges and libvirt's own virtual networks, <b>do not</b>
 691       support it. 802.1Qbh (vn-link) and 802.1Qbg (VEPA) switches
 692       provide their own way (outside of libvirt) to tag guest traffic
 693       onto a specific VLAN. Each tag is given in a
 694       separate <code>&lt;tag&gt;</code> subelement
 695       of <code>&lt;vlan&gt;</code> (for example: <code>&lt;tag
 696       id='42'/&gt;</code>). For VLAN trunking of multiple tags (which
 697       is supported only on Open vSwitch connections),
 698       multiple <code>&lt;tag&gt;</code> subelements can be specified,
 699       which implies that the user wants to do VLAN trunking on the
 700       interface for all the specified tags. In the case that VLAN
 701       trunking of a single tag is desired, the optional
 702       attribute <code>trunk='yes'</code> can be added to the toplevel
 703       <code>&lt;vlan&gt;</code> element to differentiate trunking of a
 704       single tag from normal tagging.
 705     </p>
 706     <p>
 707       For network connections using Open vSwitch it is also possible
 708       to configure 'native-tagged' and 'native-untagged' VLAN modes
 709       <span class="since">Since 1.1.0.</span> This is done with the
 710       optional <code>nativeMode</code> attribute on
 711       the <code>&lt;tag&gt;</code> subelement: <code>nativeMode</code>
 712       may be set to 'tagged' or 'untagged'. The <code>id</code>
 713       attribute of the <code>&lt;tag&gt;</code> subelement
 714       containing <code>nativeMode</code> sets which VLAN is considered
 715       to be the "native" VLAN for this interface, and
 716       the <code>nativeMode</code> attribute determines whether or not
 717       traffic for that VLAN will be tagged.
 718     </p>
 719     <p>
 720       <code>&lt;vlan&gt;</code> elements can also be specified in
 721       a <code>&lt;portgroup&gt;</code> element, as well as directly in
 722       a domain's <code>&lt;interface&gt;</code> element. In the case
 723       that a vlan tag is specified in multiple locations, the setting
 724       in <code>&lt;interface&gt;</code> takes precedence, followed by
 725       the setting in the <code>&lt;portgroup&gt;</code> selected by
 726       the interface config. The <code>&lt;vlan&gt;</code>
 727       in <code>&lt;network&gt;</code> will be selected only if none is
 728       given in <code>&lt;portgroup&gt;</code>
 729       or <code>&lt;interface&gt;</code>.
 730     </p>
 731
 732     <h5><a id="elementsPortgroup">Portgroups</a></h5>
 733
 734 <pre>
 735 ...
 736   &lt;forward mode='private'/&gt;
 737     &lt;interface dev="eth20"/&gt;
 738     &lt;interface dev="eth21"/&gt;
 739     &lt;interface dev="eth22"/&gt;
 740     &lt;interface dev="eth23"/&gt;
 741     &lt;interface dev="eth24"/&gt;
 742   &lt;/forward&gt;
 743   <b>&lt;portgroup name='engineering' default='yes'&gt;
 744     &lt;virtualport type='802.1Qbh'&gt;
 745       &lt;parameters profileid='test'/&gt;
 746     &lt;/virtualport&gt;
 747     &lt;bandwidth&gt;
 748       &lt;inbound average='1000' peak='5000' burst='5120'/&gt;
 749       &lt;outbound average='1000' peak='5000' burst='5120'/&gt;
 750     &lt;/bandwidth&gt;
 751   &lt;/portgroup&gt;</b>
 752   <b>&lt;portgroup name='sales' trustGuestRxFilters='no'&gt;
 753     &lt;virtualport type='802.1Qbh'&gt;
 754       &lt;parameters profileid='salestest'/&gt;
 755     &lt;/virtualport&gt;
 756     &lt;bandwidth&gt;
 757       &lt;inbound average='500' peak='2000' burst='2560'/&gt;
 758       &lt;outbound average='128' peak='256' burst='256'/&gt;
 759     &lt;/bandwidth&gt;
 760   &lt;/portgroup&gt;</b>
 761 ...</pre>
 762
 763     <p>
 764       <span class="since">Since 0.9.4</span>
 765       A portgroup provides a method of easily putting guest
 766       connections to the network into different classes, with each
 767       class potentially having a different level/type of service.
 768       <span class="since">Since 0.9.4</span> Each
 769       network can have multiple portgroup elements (and one of those
 770       can optionally be designated as the 'default' portgroup for the
 771       network), and each portgroup has a name, as well as various
 772       attributes and subelements associated with it. The currently supported
 773       subelements are <code>&lt;bandwidth&gt;</code>
 774       (described <a href="formatnetwork.html#elementQoS">here</a>)
 775       and <code>&lt;virtualport&gt;</code>
 776       (documented <a href="formatdomain.html#elementsNICSDirect">here</a>).
 777       If a domain interface definition specifies a portgroup (by
 778       adding a <code>portgroup</code> attribute to
 779       the <code>&lt;source&gt;</code> subelement), that portgroup's
 780       info will be merged into the interface's configuration. If no
 781       portgroup is given in the interface definition, and one of the
 782       network's portgroups has <code>default='yes'</code>, that
 783       default portgroup will be used. If no portgroup is given in the
 784       interface definition, and there is no default portgroup, then
 785       none will be used. Any <code>&lt;bandwidth&gt;</code>
 786
 787       specified directly in the domain XML will take precedence over
 788       any setting in the chosen portgroup. if
 789       a <code>&lt;virtualport&gt;</code> is specified in the portgroup
 790       (and/or directly in the network definition), the multiple
 791       virtualports will be merged, and any parameter that is specified
 792       in more than one virtualport, and is not identical, will be
 793       considered an error, and will prevent the interface from
 794       starting.
 795     </p>
 796     <p>
 797       portgroups also support the optional
 798       parameter <code>trustGuestRxFilters</code> which can be used to
 799       set that attribute of the same name for each domain interface
 800       using this portgroup (<span class="since">since
 801       1.2.10</span>). See
 802       the <a href="formatdomain.html#elementsNICS">Network
 803       interfaces</a> section of the domain XML documentation for more
 804       details. Note that an explicit setting of this attribute in the
 805       portgroup overrides the network-wide setting, and an explicit
 806       setting in the individual domain interface will override the
 807       setting in the portgroup.
 808     </p>
 809
 810     <h5><a id="elementsStaticroute">Static Routes</a></h5>
 811     <p>
 812       Static route definitions are used to provide routing information
 813       to the virtualization host for networks which are not directly
 814       reachable from the virtualization host, but *are* reachable from
 815       a guest domain that is itself reachable from the
 816       host <span class="since">since 1.0.6</span>.
 817     </p>
 818
 819     <p>
 820       As shown in <a href="formatnetwork.html#examplesNoGateway">this
 821       example</a>, it is possible to define a virtual network
 822       interface with no IPv4 or IPv6 addresses.  Such networks are
 823       useful to provide host connectivity to networks which are only
 824       reachable via a guest.  A guest with connectivity both to the
 825       guest-only network and to another network that is directly
 826       reachable from the host can act as a gateway between the
 827       networks.  A static route added to the "host-visible" network
 828       definition provides the routing information so that IP packets
 829       can be sent from the virtualization host to guests on the hidden
 830       network.
 831     </p>
 832
 833     <p>
 834       Here is a fragment of a definition which shows the static
 835       route specification as well as the  IPv4 and IPv6 definitions
 836       for network addresses which are referred to in the
 837       <code>gateway</code> gateway address specifications.  Note
 838       that the third static route specification includes the
 839       <code>metric</code> attribute specification with a value of 2.
 840       This particular route would *not* be preferred if there was
 841       another existing rout on the system with the same address and
 842       prefix but with a lower value for the metric. If there is a
 843       route in the host system configuration that should be overridden
 844       by a route in a virtual network whenever the virtual network is
 845       running, the configuration for the system-defined route should
 846       be modified to have a higher metric, and the route on the
 847       virtual network given a lower metric (for example, the default
 848       metric of "1").
 849     </p>
 850
 851     <pre>
 852 ...
 853   &lt;ip address="192.168.122.1" netmask="255.255.255.0"&gt;
 854     &lt;dhcp&gt;
 855       &lt;range start="192.168.122.128" end="192.168.122.254"/&gt;
 856     &lt;/dhcp&gt;
 857   &lt;/ip&gt;
 858   &lt;route address="192.168.222.0" prefix="24" gateway="192.168.122.2"/&gt;
 859   &lt;ip family="ipv6" address="2001:db8:ca2:2::1" prefix="64"/&gt;
 860   &lt;route family="ipv6" address="2001:db8:ca2:3::" prefix="64" gateway="2001:db8:ca2:2::2"/&gt;
 861   &lt;route family="ipv6" address="2001:db9:4:1::" prefix="64" gateway="2001:db8:ca2:2::3" metric='2'/&gt;
 862 ...
 863     </pre>
 864
 865     <h3><a id="elementsAddress">Addressing</a></h3>
 866
 867     <p>
 868       The final set of elements define the addresses (IPv4 and/or
 869       IPv6, as well as MAC) to be assigned to the bridge device
 870       associated with the virtual network, and optionally enable DHCP
 871       services. These elements are only valid for isolated networks
 872       (no <code>forward</code> element specified), and for those with
 873       a forward mode of 'route' or 'nat'.
 874     </p>
 875
 876     <pre>
 877 ...
 878 &lt;mac address='00:16:3E:5D:C7:9E'/&gt;
 879 &lt;domain name="example.com"/&gt;
 880 &lt;dns&gt;
 881   &lt;txt name="example" value="example value"/&gt;
 882   &lt;forwarder addr="8.8.8.8"/&gt;
 883   &lt;forwarder domain='example.com' addr="8.8.4.4"/&gt;
 884   &lt;forwarder domain='www.example.com'/&gt;
 885   &lt;srv service='name' protocol='tcp' domain='test-domain-name' target='.'
 886     port='1024' priority='10' weight='10'/&gt;
 887   &lt;host ip='192.168.122.2'&gt;
 888     &lt;hostname&gt;myhost&lt;/hostname&gt;
 889     &lt;hostname&gt;myhostalias&lt;/hostname&gt;
 890   &lt;/host&gt;
 891 &lt;/dns&gt;
 892 &lt;ip address="192.168.122.1" netmask="255.255.255.0" localPtr="yes"&gt;
 893   &lt;dhcp&gt;
 894     &lt;range start="192.168.122.100" end="192.168.122.254"/&gt;
 895     &lt;host mac="00:16:3e:77:e2:ed" name="foo.example.com" ip="192.168.122.10"/&gt;
 896     &lt;host mac="00:16:3e:3e:a9:1a" name="bar.example.com" ip="192.168.122.11"/&gt;
 897   &lt;/dhcp&gt;
 898 &lt;/ip&gt;
 899 &lt;ip family="ipv6" address="2001:db8:ca2:2::1" prefix="64" localPtr="yes"/&gt;
 900 &lt;route family="ipv6" address="2001:db9:ca1:1::" prefix="64" gateway="2001:db8:ca2:2::2"/&gt;
 901 </pre>
 902
 903     <dl>
 904       <dt><code>mac</code></dt>
 905       <dd>The <code>address</code> attribute defines a MAC
 906         (hardware) address formatted as 6 groups of 2-digit
 907         hexadecimal numbers, the groups separated by colons
 908         (eg, <code>"52:54:00:1C:DA:2F"</code>).  This MAC address is
 909         assigned to the bridge device when it is created.  Generally
 910         it is best to not specify a MAC address when creating a
 911         network - in this case, if a defined MAC address is needed for
 912         proper operation, libvirt will automatically generate a random
 913         MAC address and save it in the config. Allowing libvirt to
 914         generate the MAC address will assure that it is compatible
 915         with the idiosyncrasies of the platform where libvirt is
 916         running. <span class="since">Since 0.8.8</span>
 917       </dd>
 918       <dt><code>dns</code></dt>
 919       <dd> The dns element of a network contains configuration
 920         information for the virtual network's DNS
 921         server <span class="since">Since 0.9.3</span>.
 922
 923         <p>
 924           The dns element can have an optional <code>enable</code>
 925           attribute <span class="since">Since 2.2.0</span>.
 926           If <code>enable</code> is "no", then no DNS server will be
 927           setup by libvirt for this network (and any other
 928           configuration in <code>&lt;dns&gt;</code> will be ignored).
 929           If <code>enable</code> is "yes" or unspecified (including
 930           the complete absence of any <code>&lt;dns&gt;</code>
 931           element) then a DNS server will be setup by libvirt to
 932           listen on all IP addresses specified in the network's
 933           configuration.
 934         </p>
 935         <p>
 936           The dns element
 937           can have an optional <code>forwardPlainNames</code>
 938           attribute <span class="since">Since 1.1.2</span>.
 939           If <code>forwardPlainNames</code> is "no", then DNS resolution
 940           requests for names that are not qualified with a domain
 941           (i.e. names with no "." character) will not be forwarded to
 942           the host's upstream DNS server - they will only be resolved if
 943           they are known locally within the virtual network's own DNS
 944           server. If <code>forwardPlainNames</code> is "yes",
 945           unqualified names <b>will</b> be forwarded to the upstream DNS
 946           server if they can't be resolved by the virtual network's own
 947           DNS server.
 948         </p>
 949
 950         Currently supported sub-elements of <code>&lt;dns&gt;</code> are:
 951         <dl>
 952           <dt><code>forwarder</code></dt>
 953           <dd>The dns element can have 0 or
 954             more <code>&lt;forwarder&gt;</code> elements.  Each
 955             forwarder element defines an alternate DNS server to use
 956             for some, or all, DNS requests sent to this network's DNS
 957             server. There are two attributes - <code>domain</code>,
 958             and <code>addr</code>; at least one of these must be
 959             specified in any <code>&lt;forwarder&gt;</code>
 960             element. If both <code>domain</code> and <code>addr</code>
 961             are specified, then all requests that match the given
 962             domain will be forwarded to the DNS server at addr. If
 963             only <code>domain</code> is specified, then all matching
 964             domains will be resolved locally (or via the host's
 965             standard DNS forwarding if they can't be resolved
 966             locally). If an <code>addr</code> is specified by itself,
 967             then all DNS requests to the network's DNS server will be
 968             forwarded to the DNS server at that address with no
 969             exceptions. <code>addr</code> <span class="since">Since
 970             1.1.3</span>, <code>domain</code> <span class="since">Since
 971             2.2.0</span>.
 972           </dd>
 973           <dt><code>txt</code></dt>
 974           <dd>A <code>dns</code> element can have 0 or more <code>txt</code> elements.
 975             Each txt element defines a DNS TXT record and has two attributes, both
 976             required: a name that can be queried via dns, and a value that will be
 977             returned when that name is queried. names cannot contain embedded spaces
 978             or commas. value is a single string that can contain multiple values
 979             separated by commas. <span class="since">Since 0.9.3</span>
 980           </dd>
 981           <dt><code>host</code></dt>
 982           <dd>The <code>host</code> element within <code>dns</code> is the
 983             definition of DNS hosts to be passed to the DNS service. The IP
 984             address is identified by the <code>ip</code> attribute and the names
 985             for that IP address are identified in the <code>hostname</code>
 986             sub-elements of the <code>host</code> element.
 987             <span class="since">Since 0.9.3</span>
 988           </dd>
 989         </dl>
 990         <dl>
 991           <dt><code>srv</code></dt>
 992           <dd>The <code>dns</code> element can have also 0 or more <code>srv</code>
 993             record elements. Each <code>srv</code> record element defines a DNS SRV record
 994             and has 2 mandatory and 5 optional attributes. The mandatory attributes
 995             are service <code>name</code> and <code>protocol</code> (tcp, udp)
 996             and the optional attributes are <code>target</code>,
 997             <code>port</code>, <code>priority</code>, <code>weight</code> and
 998             <code>domain</code> as defined in DNS server SRV RFC (RFC 2782).
 999             <span class="since">Since 0.9.9</span>
1000           </dd>
1001         </dl>
1002       </dd>
1003       <dt><code>ip</code></dt>
1004       <dd>The <code>address</code> attribute defines an IPv4 address in
1005         dotted-decimal format, or an IPv6 address in standard colon-separated
1006         hexadecimal format, that will be configured on the bridge device
1007         associated with the virtual network. To the guests this IPv4 address
1008         will be their IPv4 default route. For IPv6, the default route is
1009         established via Router Advertisement. For IPv4 addresses, the
1010         <code>netmask</code> attribute defines the significant bits of the
1011         network address, again specified in dotted-decimal format. For IPv6
1012         addresses, and as an alternate method for IPv4 addresses, the
1013         significant bits of the network address can be specified with the
1014         <code>prefix</code> attribute, which is an integer (for example,
1015         <code>netmask='255.255.255.0'</code> could also be given as
1016         <code>prefix='24'</code>). The <code>family</code> attribute is used
1017         to specify the type of address - <code>ipv4</code> or
1018         <code>ipv6</code>; if no <code>family</code> is given,
1019         <code>ipv4</code> is assumed. More than one address of each family can
1020         be defined for a network. The optional <code>localPtr</code> attribute
1021         (<span class="since">since 3.0.0</span>) configures the DNS server to
1022         not forward any reverse DNS requests for IP addresses from the network
1023         configured by the <code>address</code> and
1024         <code>netmask</code>/<code>prefix</code> attributes. For some unusual
1025         network prefixes (not divisible by 8 for IPv4 or not divisible by 4 for
1026         IPv6) libvirt may be unable to compute the PTR domain automatically.
1027         The <code>ip</code> element is supported <span class="since">since
1028         0.3.0</span>. IPv6, multiple addresses on a single network,
1029         <code>family</code>, and <code>prefix</code> are supported
1030         <span class="since">since 0.8.7</span>. The <code>ip</code> element may
1031         contain the following elements:
1032
1033         <dl>
1034           <dt><code>tftp</code></dt>
1035           <dd>The optional <code>tftp</code> element and its mandatory
1036             <code>root</code> attribute enable TFTP services. The attribute
1037             specifies the path to the root directory served via TFTP. The
1038             <code>tftp</code> element is not supported for IPv6 addresses,
1039             and can only be specified on a single IPv4 address per network.
1040             <span class="since">Since 0.7.1</span>
1041           </dd>
1042
1043           <dt><code>dhcp</code></dt>
1044           <dd>The presence of this element enables DHCP services on the
1045             virtual network. The <code>dhcp</code> element is supported for
1046             both IPv4 (<span class="since">since 0.3.0</span>) and IPv6
1047             (<span class="since">since 1.0.1</span>), but only for one IP
1048             address of each type per network. The following sub-elements are
1049             supported:
1050             <dl>
1051               <dt><code>range</code></dt>
1052               <dd>The <code>start</code> and <code>end</code> attributes on the
1053                 <code>range</code> element specify the boundaries of a pool of
1054                 addresses to be provided to DHCP clients. These two addresses
1055                 must lie within the scope of the network defined on the parent
1056                 <code>ip</code> element.  There may be zero or more
1057                 <code>range</code> elements specified.
1058                 <span class="since">Since 0.3.0</span>
1059               </dd>
1060               <dt><code>host</code></dt>
1061               <dd>Within the <code>dhcp</code> element there may be zero or
1062                 more <code>host</code> elements. These specify hosts which will
1063                 be given names and predefined IP addresses by the built-in DHCP
1064                 server. Any IPv4 <code>host</code> element must specify the MAC
1065                 address of the host to be assigned a given name (via the
1066                 <code>mac</code> attribute), the IP to be assigned to that host
1067                 (via the <code>ip</code> attribute), and the name itself (the
1068                 <code>name</code> attribute). The IPv6 <code>host</code>
1069                 element differs slightly from that for IPv4: there is no
1070                 <code>mac</code> attribute since a MAC address has no defined
1071                 meaning in IPv6. Instead, the <code>name</code> attribute is
1072                 used to identify the host to be assigned the IPv6 address. For
1073                 DHCPv6, the name is the plain name of the client host sent by the
1074                 client to the server. Note that this method of assigning a
1075                 specific IP address can also be used for IPv4 instead of the
1076                 <code>mac</code> attribute.
1077                 <span class="since">Since 0.4.5</span>
1078               </dd>
1079               <dt><code>bootp</code></dt>
1080               <dd>The optional <code>bootp</code> element specifies BOOTP
1081                 options to be provided by the DHCP server for IPv4 only. Two
1082                 attributes are supported: <code>file</code> is mandatory and
1083                 gives the file to be used for the boot image;
1084                 <code>server</code> is optional and gives the address of the
1085                 TFTP server from which the boot image will be fetched.
1086                 <code>server</code> defaults to the same host that runs the
1087                 DHCP server, as is the case when the <code>tftp</code> element
1088                 is used. The BOOTP options currently have to be the same for
1089                 all address ranges and statically assigned addresses. <span
1090                 class="since">Since 0.7.1</span> (<code>server</code>
1091                 <span class="since">since 0.7.3</span>)
1092               </dd>
1093             </dl>
1094           </dd>
1095         </dl>
1096       </dd>
1097     </dl>
1098
1099     <h3><a id="elementsNamespaces">Network namespaces</a></h3>
1100
1101     <p>
1102       A special XML namespace is available for passing options directly to the
1103       underlying dnsmasq configuration file. Usage of XML namespaces comes with no
1104       support guarantees, so use at your own risk.
1105     </p>
1106
1107     <p>
1108       This example XML will pass the option strings <code>foo=bar</code> and
1109       <code>cname=*.foo.example.com,master.example.com</code> directly to the
1110       underlying dnsmasq instance.
1111       <pre>
1112 &lt;network xmlns:dnsmasq='http://libvirt.org/schemas/network/dnsmasq/1.0'&gt;
1113   ...
1114   &lt;dnsmasq:options&gt;
1115     &lt;dnsmasq:option value="foo=bar"/&gt;
1116     &lt;dnsmasq:option value="cname=*.foo.example.com,master.example.com"/&gt;
1117   &lt;/dnsmasq:options&gt;
1118 &lt;/network&gt;</pre>
1119     </p>
1120
1121     <h2><a id="examples">Example configuration</a></h2>
1122
1123     <h3><a id="examplesNAT">NAT based network</a></h3>
1124
1125     <p>
1126       This example is the so called "default" virtual network. It is
1127       provided and enabled out-of-the-box for all libvirt installations.
1128       This is a configuration that allows guest OS to get outbound
1129       connectivity regardless of whether the host uses ethernet, wireless,
1130       dialup, or VPN networking without requiring any specific admin
1131       configuration. In the absence of host networking, it at least allows
1132       guests to talk directly to each other.
1133     </p>
1134
1135     <pre>
1136 &lt;network&gt;
1137   &lt;name&gt;default&lt;/name&gt;
1138   &lt;bridge name="virbr0"/&gt;
1139   &lt;forward mode="nat"/&gt;
1140   &lt;ip address="192.168.122.1" netmask="255.255.255.0"&gt;
1141     &lt;dhcp&gt;
1142       &lt;range start="192.168.122.2" end="192.168.122.254"/&gt;
1143     &lt;/dhcp&gt;
1144   &lt;/ip&gt;
1145   &lt;ip family="ipv6" address="2001:db8:ca2:2::1" prefix="64"/&gt;
1146 &lt;/network&gt;</pre>
1147
1148
1149     <p>
1150       Below is a variation of the above example which adds an IPv6
1151       dhcp range definition.
1152     </p>
1153
1154     <pre>
1155 &lt;network&gt;
1156   &lt;name&gt;default6&lt;/name&gt;
1157   &lt;bridge name="virbr0"/&gt;
1158   &lt;forward mode="nat"/&gt;
1159   &lt;ip address="192.168.122.1" netmask="255.255.255.0"&gt;
1160     &lt;dhcp&gt;
1161       &lt;range start="192.168.122.2" end="192.168.122.254"/&gt;
1162     &lt;/dhcp&gt;
1163   &lt;/ip&gt;
1164   &lt;ip family="ipv6" address="2001:db8:ca2:2::1" prefix="64"&gt;
1165     &lt;dhcp&gt;
1166       &lt;range start="2001:db8:ca2:2:1::10" end="2001:db8:ca2:2:1::ff"/&gt;
1167     &lt;/dhcp&gt;
1168   &lt;/ip&gt;
1169 &lt;/network&gt;</pre>
1170
1171     <h3><a id="examplesRoute">Routed network config</a></h3>
1172
1173     <p>
1174       This is a variant on the default network which routes traffic
1175       from the virtual network to the LAN without applying any NAT.
1176       It requires that the IP address range be pre-configured in the
1177       routing tables of the router on the host network. This example
1178       further specifies that guest traffic may only go out via the
1179       <code>eth1</code> host network device.
1180     </p>
1181
1182     <pre>
1183 &lt;network&gt;
1184   &lt;name&gt;local&lt;/name&gt;
1185   &lt;bridge name="virbr1"/&gt;
1186   &lt;forward mode="route" dev="eth1"/&gt;
1187   &lt;ip address="192.168.122.1" netmask="255.255.255.0"&gt;
1188     &lt;dhcp&gt;
1189       &lt;range start="192.168.122.2" end="192.168.122.254"/&gt;
1190     &lt;/dhcp&gt;
1191   &lt;/ip&gt;
1192   &lt;ip family="ipv6" address="2001:db8:ca2:2::1" prefix="64"/&gt;
1193 &lt;/network&gt;</pre>
1194
1195     <p>
1196       Below is another IPv6 variation.  Instead of a dhcp range being
1197       specified, this example has a couple of IPv6 host definitions.
1198       Note that most of the dhcp host definitions use an "id" (client
1199       id or DUID) since this has proven to be a more reliable way
1200       of specifying the interface and its association with an IPv6
1201       address.  The first is a DUID-LLT, the second a DUID-LL, and
1202       the third a DUID-UUID.  <span class="since">Since 1.0.3</span>
1203     </p>
1204
1205     <pre>
1206 &lt;network&gt;
1207   &lt;name&gt;local6&lt;/name&gt;
1208   &lt;bridge name="virbr1"/&gt;
1209   &lt;forward mode="route" dev="eth1"/&gt;
1210   &lt;ip address="192.168.122.1" netmask="255.255.255.0"&gt;
1211     &lt;dhcp&gt;
1212       &lt;range start="192.168.122.2" end="192.168.122.254"/&gt;
1213     &lt;/dhcp&gt;
1214   &lt;/ip&gt;
1215   &lt;ip family="ipv6" address="2001:db8:ca2:2::1" prefix="64"&gt;
1216     &lt;dhcp&gt;
1217       &lt;host name="paul" ip="2001:db8:ca2:2:3::1"/&gt;
1218       &lt;host id="0:1:0:1:18:aa:62:fe:0:16:3e:44:55:66" ip="2001:db8:ca2:2:3::2"/&gt;
1219       &lt;host id="0:3:0:1:0:16:3e:11:22:33" name="ralph" ip="2001:db8:ca2:2:3::3"/&gt;
1220       &lt;host id="0:4:7e:7d:f0:7d:a8:bc:c5:d2:13:32:11:ed:16:ea:84:63"
1221         name="badbob" ip="2001:db8:ca2:2:3::4"/&gt;
1222     &lt;/dhcp&gt;
1223   &lt;/ip&gt;
1224 &lt;/network&gt;</pre>
1225
1226     <p>
1227       Below is yet another IPv6 variation.  This variation has only
1228       IPv6 defined with DHCPv6 on the primary IPv6 network.  A static
1229       link if defined for a second IPv6 network which will not be
1230       directly visible on the bridge interface but there will be a
1231       static route defined for this network via the specified
1232       gateway. Note that the gateway address must be directly
1233       reachable via (on the same subnet as) one of the &lt;ip&gt;
1234       addresses defined for this &lt;network&gt;.
1235       <span class="since">Since 1.0.6</span>
1236     </p>
1237
1238     <pre>
1239 &lt;network&gt;
1240   &lt;name&gt;net7&lt;/name&gt;
1241   &lt;bridge name="virbr7"/&gt;
1242   &lt;forward mode="route"/&gt;
1243   &lt;ip family="ipv6" address="2001:db8:ca2:7::1" prefix="64"&gt;
1244     &lt;dhcp&gt;
1245       &lt;range start="2001:db8:ca2:7::100" end="2001:db8:ca2::1ff"/&gt;
1246       &lt;host id="0:4:7e:7d:f0:7d:a8:bc:c5:d2:13:32:11:ed:16:ea:84:63"
1247         name="lucas" ip="2001:db8:ca2:2:3::4"/&gt;
1248     &lt;/dhcp&gt;
1249   &lt;/ip&gt;
1250   &lt;route family="ipv6" address="2001:db8:ca2:8::" prefix="64" gateway="2001:db8:ca2:7::4"/&gt;
1251 &lt;/network&gt;</pre>
1252
1253     <h3><a id="examplesPrivate">Isolated network config</a></h3>
1254
1255     <p>
1256       This variant provides a completely isolated private network
1257       for guests. The guests can talk to each other, and the host
1258       OS, but cannot reach any other machines on the LAN, due to
1259       the omission of the <code>forward</code> element in the XML
1260       description.
1261     </p>
1262
1263     <pre>
1264 &lt;network&gt;
1265   &lt;name&gt;private&lt;/name&gt;
1266   &lt;bridge name="virbr2"/&gt;
1267   &lt;ip address="192.168.152.1" netmask="255.255.255.0"&gt;
1268     &lt;dhcp&gt;
1269       &lt;range start="192.168.152.2" end="192.168.152.254"/&gt;
1270     &lt;/dhcp&gt;
1271   &lt;/ip&gt;
1272   &lt;ip family="ipv6" address="2001:db8:ca2:3::1" prefix="64"/&gt;
1273 &lt;/network&gt;</pre>
1274
1275     <h3><a id="examplesPrivate6">Isolated IPv6 network config</a></h3>
1276
1277     <p>
1278       This variation of an isolated network defines only IPv6.
1279       Note that most of the dhcp host definitions use an "id" (client
1280       id or DUID) since this has proven to be a more reliable way
1281       of specifying the interface and its association with an IPv6
1282       address.  The first is a DUID-LLT, the second a DUID-LL, and
1283       the third a DUID-UUID.  <span class="since">Since 1.0.3</span>
1284     </p>
1285
1286     <pre>
1287 &lt;network&gt;
1288   &lt;name&gt;sixnet&lt;/name&gt;
1289   &lt;bridge name="virbr6"/&gt;
1290   &lt;ip family="ipv6" address="2001:db8:ca2:6::1" prefix="64"&gt;
1291     &lt;dhcp&gt;
1292       &lt;host name="peter" ip="2001:db8:ca2:6:6::1"/&gt;
1293       &lt;host id="0:1:0:1:18:aa:62:fe:0:16:3e:44:55:66" ip="2001:db8:ca2:6:6::2"/&gt;
1294       &lt;host id="0:3:0:1:0:16:3e:11:22:33" name="dariusz" ip="2001:db8:ca2:6:6::3"/&gt;
1295       &lt;host id="0:4:7e:7d:f0:7d:a8:bc:c5:d2:13:32:11:ed:16:ea:84:63"
1296         name="anita" ip="2001:db8:ca2:6:6::4"/&gt;
1297     &lt;/dhcp&gt;
1298   &lt;/ip&gt;
1299 &lt;/network&gt;</pre>
1300
1301     <h3><a id="examplesBridge">Using an existing host bridge</a></h3>
1302
1303     <p>
1304       <span class="since">Since 0.9.4</span>
1305       This shows how to use a pre-existing host bridge "br0". The
1306       guests will effectively be directly connected to the physical
1307       network (i.e. their IP addresses will all be on the subnet of
1308       the physical network, and there will be no restrictions on
1309       inbound or outbound connections).
1310     </p>
1311
1312     <pre>
1313 &lt;network&gt;
1314   &lt;name&gt;host-bridge&lt;/name&gt;
1315   &lt;forward mode="bridge"/&gt;
1316   &lt;bridge name="br0"/&gt;
1317 &lt;/network&gt;</pre>
1318
1319     <h3><a id="examplesDirect">Using a macvtap "direct" connection</a></h3>
1320
1321     <p>
1322       <span class="since">Since 0.9.4, QEMU and KVM only, requires
1323       Linux kernel 2.6.34 or newer</span>
1324       This shows how to use macvtap to connect to the physical network
1325       directly through one of a group of physical devices (without
1326       using a host bridge device). As with the host bridge network,
1327       the guests will effectively be directly connected to the
1328       physical network so their IP addresses will all be on the subnet
1329       of the physical network, and there will be no restrictions on
1330       inbound or outbound connections. Note that, due to a limitation
1331       in the implementation of macvtap, these connections do not allow
1332       communication directly between the host and the guests - if you
1333       require this you will either need the attached physical switch
1334       to be operating in a mirroring mode (so that all traffic coming
1335       to the switch is reflected back to the host's interface), or
1336       provide alternate means for this communication (e.g. a second
1337       interface on each guest that is connected to an isolated
1338       network). The other forward modes that use macvtap (private,
1339       vepa, and passthrough) would be used in a similar fashion.
1340     </p>
1341
1342     <pre>
1343 &lt;network&gt;
1344   &lt;name&gt;direct-macvtap&lt;/name&gt;
1345   &lt;forward mode="bridge"&gt;
1346     &lt;interface dev="eth20"/&gt;
1347     &lt;interface dev="eth21"/&gt;
1348     &lt;interface dev="eth22"/&gt;
1349     &lt;interface dev="eth23"/&gt;
1350     &lt;interface dev="eth24"/&gt;
1351   &lt;/forward&gt;
1352 &lt;/network&gt;</pre>
1353
1354     <h3><a id="examplesNoGateway">Network config with no gateway addresses</a></h3>
1355
1356     <p>
1357     A valid network definition can contain no IPv4 or IPv6 addresses.  Such a definition
1358     can be used for a "very private" or "very isolated" network since it will not be
1359     possible to communicate with the virtualization host via this network.  However,
1360     this virtual network interface can be used for communication between virtual guest
1361     systems.  This works for IPv4 and <span class="since">(Since 1.0.1)</span> IPv6.
1362     However, the new ipv6='yes' must be added for guest-to-guest IPv6
1363     communication.
1364     </p>
1365
1366     <pre>
1367 &lt;network ipv6='yes'&gt;
1368   &lt;name&gt;nogw&lt;/name&gt;
1369   &lt;uuid&gt;7a3b7497-1ec7-8aef-6d5c-38dff9109e93&lt;/uuid&gt;
1370   &lt;bridge name="virbr2" stp="on" delay="0"/&gt;
1371   &lt;mac address='00:16:3E:5D:C7:9E'/&gt;
1372 &lt;/network&gt;</pre>
1373
1374   </body>
1375 </html>