libvirt/docs/schemas/network.rng

312 lines
10 KiB
Plaintext
Raw Normal View History

<?xml version="1.0"?>
<!-- A Relax NG schema for the libvirt network XML format -->
<grammar xmlns="http://relaxng.org/ns/structure/1.0"
datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
<start>
<ref name="network"/>
</start>
<include href='basictypes.rng'/>
conf: support abstracted interface info in network XML The network XML is updated in the following ways: 1) The <forward> element can now contain a list of forward interfaces: <forward .... > <interface dev='eth10'/> <interface dev='eth11'/> <interface dev='eth12'/> <interface dev='eth13'/> </forward> The first of these takes the place of the dev attribute that is normally in <forward> - when defining a network you can specify either one, and on output both will be present. If you specify both on input, they must match. 2) In addition to forward modes of 'nat' and 'route', these new modes are supported: private, passthrough, vepa - when this network is referenced by a domain's interface, it will have the same effect as if the interface had been defined as type='direct', e.g.: <interface type='direct'> <source mode='${mode}' dev='${dev}> ... </interface> where ${mode} is one of the three new modes, and ${dev} is an interface selected from the list given in <forward>. bridge - if a <forward> dev (or multiple devs) is defined, and forward mode is 'bridge' this is just like the modes 'private', 'passthrough', and 'vepa' above. If there is no forward dev specified but a bridge name is given (e.g. "<bridge name='br0'/>"), then guest interfaces using this network will use libvirt's "host bridge" mode, equivalent to this: <interface type='bridge'> <source bridge='${bridge-name}'/> ... </interface> 3) A network can have multiple <portgroup> elements, which may be selected by the guest interface definition (by adding "portgroup='${name}'" in the <source> element along with the network name). Currently a portgroup can only contain a virtportprofile, but the intent is that other configuration items may be put there int the future (e.g. bandwidth config). When building a guest's interface, if the <interface> XML itself has no virtportprofile, and if the requested network has a portgroup with a name matching the name given in the <interface> (or if one of the network's portgroups is marked with the "default='yes'" attribute), the virtportprofile from that portgroup will be used by the interface. 4) A network can have a virtportprofile defined at the top level, which will be used by a guest interface when connecting in one of the 'direct' modes if the guest interface XML itself hasn't specified any virtportprofile, and if there are also no matching portgroups on the network.
2011-07-20 03:01:09 +00:00
<include href='networkcommon.rng'/>
<define name="network">
<element name="network">
<optional>
<attribute name="connections">
<data type="unsignedInt"/>
</attribute>
</optional>
<!-- Enables IPv6 guest-to-guest communications on a network
with no gateways addresses specified -->
<optional>
<attribute name="ipv6">
<choice>
<value>yes</value>
<value>no</value>
</choice>
</attribute>
</optional>
<interleave>
<!-- The name of the network, used to refer to it through the API
and in virsh -->
<element name="name">
<text/>
</element>
<!-- <uuid> element -->
<optional>
<element name="uuid"><ref name="UUID"/></element>
</optional>
<!-- <bridge> element -->
<optional>
<!-- The name of the network to be set up; this will back
the network on the host -->
<element name="bridge">
<optional>
<attribute name="name">
<ref name="deviceName"/>
</attribute>
</optional>
<optional>
<attribute name="stp">
<choice>
<value>on</value>
<value>off</value>
</choice>
</attribute>
</optional>
<optional>
<attribute name="delay">
<data type="integer"/>
</attribute>
</optional>
</element>
</optional>
Give each virtual network bridge its own fixed MAC address This fixes https://bugzilla.redhat.com/show_bug.cgi?id=609463 The problem was that, since a bridge always acquires the MAC address of the connected interface with the numerically lowest MAC, as guests are started and stopped, it was possible for the MAC address to change over time, and this change in the network was being detected by Windows 7 (it sees the MAC of the default route change), so on each reboot it would bring up a dialog box asking about this "new network". The solution is to create a dummy tap interface with a MAC guaranteed to be lower than any guest interface's MAC, and attach that tap to the bridge as soon as it's created. Since all guest MAC addresses start with 0xFE, we can just generate a MAC with the standard "0x52, 0x54, 0" prefix, and it's guaranteed to always win (physical interfaces are never connected to these bridges, so we don't need to worry about competing numerically with them). Note that the dummy tap is never set to IFF_UP state - that's not necessary in order for the bridge to take its MAC, and not setting it to UP eliminates the clutter of having an (eg) "virbr0-nic" displayed in the output of the ifconfig command. I chose to not auto-generate the MAC address in the network XML parser, as there are likely to be consumers of that API that don't need or want to have a MAC address associated with the bridge. Instead, in bridge_driver.c when the network is being defined, if there is no MAC, one is generated. To account for virtual network configs that already exist when upgrading from an older version of libvirt, I've added a %post script to the specfile that searches for all network definitions in both the config directory (/etc/libvirt/qemu/networks) and the state directory (/var/lib/libvirt/network) that are missing a mac address, generates a random address, and adds it to the config (and a matching address to the state file, if there is one). docs/formatnetwork.html.in: document <mac address.../> docs/schemas/network.rng: add nac address to schema libvirt.spec.in: %post script to update existing networks src/conf/network_conf.[ch]: parse and format <mac address.../> src/libvirt_private.syms: export a couple private symbols we need src/network/bridge_driver.c: auto-generate mac address when needed, create dummy interface if mac address is present. tests/networkxml2xmlin/isolated-network.xml tests/networkxml2xmlin/routed-network.xml tests/networkxml2xmlout/isolated-network.xml tests/networkxml2xmlout/routed-network.xml: add mac address to some tests
2011-02-09 08:28:12 +00:00
<!-- <mac> element -->
<optional>
<element name="mac">
<attribute name="address"><ref name="uniMacAddr"/></attribute>
Give each virtual network bridge its own fixed MAC address This fixes https://bugzilla.redhat.com/show_bug.cgi?id=609463 The problem was that, since a bridge always acquires the MAC address of the connected interface with the numerically lowest MAC, as guests are started and stopped, it was possible for the MAC address to change over time, and this change in the network was being detected by Windows 7 (it sees the MAC of the default route change), so on each reboot it would bring up a dialog box asking about this "new network". The solution is to create a dummy tap interface with a MAC guaranteed to be lower than any guest interface's MAC, and attach that tap to the bridge as soon as it's created. Since all guest MAC addresses start with 0xFE, we can just generate a MAC with the standard "0x52, 0x54, 0" prefix, and it's guaranteed to always win (physical interfaces are never connected to these bridges, so we don't need to worry about competing numerically with them). Note that the dummy tap is never set to IFF_UP state - that's not necessary in order for the bridge to take its MAC, and not setting it to UP eliminates the clutter of having an (eg) "virbr0-nic" displayed in the output of the ifconfig command. I chose to not auto-generate the MAC address in the network XML parser, as there are likely to be consumers of that API that don't need or want to have a MAC address associated with the bridge. Instead, in bridge_driver.c when the network is being defined, if there is no MAC, one is generated. To account for virtual network configs that already exist when upgrading from an older version of libvirt, I've added a %post script to the specfile that searches for all network definitions in both the config directory (/etc/libvirt/qemu/networks) and the state directory (/var/lib/libvirt/network) that are missing a mac address, generates a random address, and adds it to the config (and a matching address to the state file, if there is one). docs/formatnetwork.html.in: document <mac address.../> docs/schemas/network.rng: add nac address to schema libvirt.spec.in: %post script to update existing networks src/conf/network_conf.[ch]: parse and format <mac address.../> src/libvirt_private.syms: export a couple private symbols we need src/network/bridge_driver.c: auto-generate mac address when needed, create dummy interface if mac address is present. tests/networkxml2xmlin/isolated-network.xml tests/networkxml2xmlin/routed-network.xml tests/networkxml2xmlout/isolated-network.xml tests/networkxml2xmlout/routed-network.xml: add mac address to some tests
2011-02-09 08:28:12 +00:00
<empty/>
</element>
</optional>
<!-- <forward> element -->
<optional>
<!-- The device through which the bridge is connected to the
rest of the network -->
<element name="forward">
<optional>
<attribute name="dev">
<ref name="deviceName"/>
</attribute>
</optional>
<optional>
<attribute name="mode">
<choice>
<value>nat</value>
<value>route</value>
conf: support abstracted interface info in network XML The network XML is updated in the following ways: 1) The <forward> element can now contain a list of forward interfaces: <forward .... > <interface dev='eth10'/> <interface dev='eth11'/> <interface dev='eth12'/> <interface dev='eth13'/> </forward> The first of these takes the place of the dev attribute that is normally in <forward> - when defining a network you can specify either one, and on output both will be present. If you specify both on input, they must match. 2) In addition to forward modes of 'nat' and 'route', these new modes are supported: private, passthrough, vepa - when this network is referenced by a domain's interface, it will have the same effect as if the interface had been defined as type='direct', e.g.: <interface type='direct'> <source mode='${mode}' dev='${dev}> ... </interface> where ${mode} is one of the three new modes, and ${dev} is an interface selected from the list given in <forward>. bridge - if a <forward> dev (or multiple devs) is defined, and forward mode is 'bridge' this is just like the modes 'private', 'passthrough', and 'vepa' above. If there is no forward dev specified but a bridge name is given (e.g. "<bridge name='br0'/>"), then guest interfaces using this network will use libvirt's "host bridge" mode, equivalent to this: <interface type='bridge'> <source bridge='${bridge-name}'/> ... </interface> 3) A network can have multiple <portgroup> elements, which may be selected by the guest interface definition (by adding "portgroup='${name}'" in the <source> element along with the network name). Currently a portgroup can only contain a virtportprofile, but the intent is that other configuration items may be put there int the future (e.g. bandwidth config). When building a guest's interface, if the <interface> XML itself has no virtportprofile, and if the requested network has a portgroup with a name matching the name given in the <interface> (or if one of the network's portgroups is marked with the "default='yes'" attribute), the virtportprofile from that portgroup will be used by the interface. 4) A network can have a virtportprofile defined at the top level, which will be used by a guest interface when connecting in one of the 'direct' modes if the guest interface XML itself hasn't specified any virtportprofile, and if there are also no matching portgroups on the network.
2011-07-20 03:01:09 +00:00
<value>bridge</value>
<value>passthrough</value>
<value>private</value>
<value>vepa</value>
<value>hostdev</value>
</choice>
</attribute>
</optional>
<optional>
<attribute name="managed">
<choice>
<value>yes</value>
<value>no</value>
</choice>
</attribute>
</optional>
<interleave>
<choice>
<group>
<zeroOrMore>
<element name='interface'>
<attribute name='dev'>
<ref name='deviceName'/>
</attribute>
<optional>
<attribute name="connections">
<data type="unsignedInt"/>
</attribute>
</optional>
</element>
</zeroOrMore>
</group>
<group>
<zeroOrMore>
<element name='address'>
<attribute name='type'>
<value>pci</value>
</attribute>
<ref name="pciaddress"/>
<optional>
<attribute name="connections">
<data type="unsignedInt"/>
</attribute>
</optional>
</element>
</zeroOrMore>
</group>
</choice>
<optional>
<element name='pf'>
<attribute name='dev'>
<ref name='deviceName'/>
</attribute>
</element>
</optional>
</interleave>
</element>
</optional>
conf: support abstracted interface info in network XML The network XML is updated in the following ways: 1) The <forward> element can now contain a list of forward interfaces: <forward .... > <interface dev='eth10'/> <interface dev='eth11'/> <interface dev='eth12'/> <interface dev='eth13'/> </forward> The first of these takes the place of the dev attribute that is normally in <forward> - when defining a network you can specify either one, and on output both will be present. If you specify both on input, they must match. 2) In addition to forward modes of 'nat' and 'route', these new modes are supported: private, passthrough, vepa - when this network is referenced by a domain's interface, it will have the same effect as if the interface had been defined as type='direct', e.g.: <interface type='direct'> <source mode='${mode}' dev='${dev}> ... </interface> where ${mode} is one of the three new modes, and ${dev} is an interface selected from the list given in <forward>. bridge - if a <forward> dev (or multiple devs) is defined, and forward mode is 'bridge' this is just like the modes 'private', 'passthrough', and 'vepa' above. If there is no forward dev specified but a bridge name is given (e.g. "<bridge name='br0'/>"), then guest interfaces using this network will use libvirt's "host bridge" mode, equivalent to this: <interface type='bridge'> <source bridge='${bridge-name}'/> ... </interface> 3) A network can have multiple <portgroup> elements, which may be selected by the guest interface definition (by adding "portgroup='${name}'" in the <source> element along with the network name). Currently a portgroup can only contain a virtportprofile, but the intent is that other configuration items may be put there int the future (e.g. bandwidth config). When building a guest's interface, if the <interface> XML itself has no virtportprofile, and if the requested network has a portgroup with a name matching the name given in the <interface> (or if one of the network's portgroups is marked with the "default='yes'" attribute), the virtportprofile from that portgroup will be used by the interface. 4) A network can have a virtportprofile defined at the top level, which will be used by a guest interface when connecting in one of the 'direct' modes if the guest interface XML itself hasn't specified any virtportprofile, and if there are also no matching portgroups on the network.
2011-07-20 03:01:09 +00:00
<!-- <virtualport> element -->
<optional>
<ref name="virtualPortProfile"/>
</optional>
<!-- <portgroup> elements -->
<zeroOrMore>
<element name="portgroup">
<attribute name="name">
<ref name="deviceName"/>
</attribute>
<optional>
<attribute name="default">
<choice>
<value>yes</value>
<value>no</value>
</choice>
</attribute>
</optional>
<interleave>
<optional>
<ref name="virtualPortProfile"/>
</optional>
<optional>
<ref name="bandwidth"/>
</optional>
conf: add <vlan> element to network and domain interface elements The following config elements now support a <vlan> subelements: within a domain: <interface>, and the <actual> subelement of <interface> within a network: the toplevel, as well as any <portgroup> Each vlan element must have one or more <tag id='n'/> subelements. If there is more than one tag, it is assumed that vlan trunking is being requested. If trunking is required with only a single tag, the attribute "trunk='yes'" should be added to the toplevel <vlan> element. Some examples: <interface type='hostdev'/> <vlan> <tag id='42'/> </vlan> <mac address='52:54:00:12:34:56'/> ... </interface> <network> <name>vlan-net</name> <vlan trunk='yes'> <tag id='30'/> </vlan> <virtualport type='openvswitch'/> </network> <interface type='network'/> <source network='vlan-net'/> ... </interface> <network> <name>trunk-vlan</name> <vlan> <tag id='42'/> <tag id='43'/> </vlan> ... </network> <network> <name>multi</name> ... <portgroup name='production'/> <vlan> <tag id='42'/> </vlan> </portgroup> <portgroup name='test'/> <vlan> <tag id='666'/> </vlan> </portgroup> </network> <interface type='network'/> <source network='multi' portgroup='test'/> ... </interface> IMPORTANT NOTE: As of this patch there is no backend support for the vlan element for *any* network device type. When support is added in later patches, it will only be for those select network types that support setting up a vlan on the host side, without the guest's involvement. (For example, it will be possible to configure a vlan for a guest connected to an openvswitch bridge, but it won't be possible to do that for one that is connected to a standard Linux host bridge.)
2012-08-12 07:51:30 +00:00
<optional>
<ref name="vlan"/>
</optional>
</interleave>
conf: support abstracted interface info in network XML The network XML is updated in the following ways: 1) The <forward> element can now contain a list of forward interfaces: <forward .... > <interface dev='eth10'/> <interface dev='eth11'/> <interface dev='eth12'/> <interface dev='eth13'/> </forward> The first of these takes the place of the dev attribute that is normally in <forward> - when defining a network you can specify either one, and on output both will be present. If you specify both on input, they must match. 2) In addition to forward modes of 'nat' and 'route', these new modes are supported: private, passthrough, vepa - when this network is referenced by a domain's interface, it will have the same effect as if the interface had been defined as type='direct', e.g.: <interface type='direct'> <source mode='${mode}' dev='${dev}> ... </interface> where ${mode} is one of the three new modes, and ${dev} is an interface selected from the list given in <forward>. bridge - if a <forward> dev (or multiple devs) is defined, and forward mode is 'bridge' this is just like the modes 'private', 'passthrough', and 'vepa' above. If there is no forward dev specified but a bridge name is given (e.g. "<bridge name='br0'/>"), then guest interfaces using this network will use libvirt's "host bridge" mode, equivalent to this: <interface type='bridge'> <source bridge='${bridge-name}'/> ... </interface> 3) A network can have multiple <portgroup> elements, which may be selected by the guest interface definition (by adding "portgroup='${name}'" in the <source> element along with the network name). Currently a portgroup can only contain a virtportprofile, but the intent is that other configuration items may be put there int the future (e.g. bandwidth config). When building a guest's interface, if the <interface> XML itself has no virtportprofile, and if the requested network has a portgroup with a name matching the name given in the <interface> (or if one of the network's portgroups is marked with the "default='yes'" attribute), the virtportprofile from that portgroup will be used by the interface. 4) A network can have a virtportprofile defined at the top level, which will be used by a guest interface when connecting in one of the 'direct' modes if the guest interface XML itself hasn't specified any virtportprofile, and if there are also no matching portgroups on the network.
2011-07-20 03:01:09 +00:00
</element>
</zeroOrMore>
<!-- <domain> element -->
<optional>
<element name="domain">
<attribute name="name"><ref name="dnsName"/></attribute>
</element>
</optional>
<!-- Define the DNS related elements like TXT records
and other features in the <dns> element -->
<optional>
<element name="dns">
<zeroOrMore>
<element name="txt">
<attribute name="name"><ref name="dnsName"/></attribute>
<attribute name="value"><text/></attribute>
</element>
</zeroOrMore>
<zeroOrMore>
<element name="srv">
<attribute name="service"><text/></attribute>
<attribute name="protocol"><ref name="protocol"/></attribute>
<optional>
<attribute name="domain"><ref name="dnsName"/></attribute>
<attribute name="target"><text/></attribute>
<attribute name="port"><ref name="unsignedShort"/></attribute>
<attribute name="priority"><ref name="unsignedShort"/></attribute>
<attribute name="weight"><ref name="unsignedShort"/></attribute>
</optional>
</element>
</zeroOrMore>
<zeroOrMore>
<element name="host">
<attribute name="ip"><ref name="ipAddr"/></attribute>
<oneOrMore>
<element name="hostname"><ref name="dnsName"/></element>
</oneOrMore>
</element>
</zeroOrMore>
</element>
</optional>
<optional>
<ref name="bandwidth"/>
</optional>
conf: add <vlan> element to network and domain interface elements The following config elements now support a <vlan> subelements: within a domain: <interface>, and the <actual> subelement of <interface> within a network: the toplevel, as well as any <portgroup> Each vlan element must have one or more <tag id='n'/> subelements. If there is more than one tag, it is assumed that vlan trunking is being requested. If trunking is required with only a single tag, the attribute "trunk='yes'" should be added to the toplevel <vlan> element. Some examples: <interface type='hostdev'/> <vlan> <tag id='42'/> </vlan> <mac address='52:54:00:12:34:56'/> ... </interface> <network> <name>vlan-net</name> <vlan trunk='yes'> <tag id='30'/> </vlan> <virtualport type='openvswitch'/> </network> <interface type='network'/> <source network='vlan-net'/> ... </interface> <network> <name>trunk-vlan</name> <vlan> <tag id='42'/> <tag id='43'/> </vlan> ... </network> <network> <name>multi</name> ... <portgroup name='production'/> <vlan> <tag id='42'/> </vlan> </portgroup> <portgroup name='test'/> <vlan> <tag id='666'/> </vlan> </portgroup> </network> <interface type='network'/> <source network='multi' portgroup='test'/> ... </interface> IMPORTANT NOTE: As of this patch there is no backend support for the vlan element for *any* network device type. When support is added in later patches, it will only be for those select network types that support setting up a vlan on the host side, without the guest's involvement. (For example, it will be possible to configure a vlan for a guest connected to an openvswitch bridge, but it won't be possible to do that for one that is connected to a standard Linux host bridge.)
2012-08-12 07:51:30 +00:00
<optional>
<ref name="vlan"/>
</optional>
<optional>
<element name="link">
<attribute name="state">
<choice>
<value>up</value>
<value>down</value>
</choice>
</attribute>
<empty/>
</element>
</optional>
<!-- <ip> element -->
<zeroOrMore>
<!-- The IP element sets up NAT'ing and an optional DHCP server
local to the host. -->
<element name="ip">
<optional>
<attribute name="address"><ref name="ipAddr"/></attribute>
</optional>
<optional>
<choice>
<attribute name="netmask"><ref name="ipv4Addr"/></attribute>
<attribute name="prefix"><ref name="ipPrefix"/></attribute>
</choice>
</optional>
<optional>
<attribute name="family"><ref name="addr-family"/></attribute>
</optional>
<optional>
<element name="tftp">
<attribute name="root"><text/></attribute>
</element>
</optional>
<optional>
<!-- Define the range(s) of IP addresses that the DHCP
server should hand out -->
<element name="dhcp">
<zeroOrMore>
<element name="range">
<attribute name="start"><ref name="ipAddr"/></attribute>
<attribute name="end"><ref name="ipAddr"/></attribute>
</element>
</zeroOrMore>
<zeroOrMore>
<element name="host">
<choice>
<group>
<choice>
<attribute name="mac"><ref name="uniMacAddr"/></attribute>
<attribute name="id"><ref name="DUID"/></attribute>
</choice>
<optional>
<attribute name="name"><text/></attribute>
</optional>
</group>
<attribute name="name"><text/></attribute>
</choice>
<attribute name="ip"><ref name="ipAddr"/></attribute>
</element>
</zeroOrMore>
<optional>
<element name="bootp">
<attribute name="file"><ref name="filePath"/></attribute>
<optional>
<attribute name="server"><ref name="dnsName"/></attribute>
</optional>
</element>
</optional>
</element>
</optional>
</element>
</zeroOrMore>
</interleave>
</element>
</define>
</grammar>