11:02 a.m.
From: Pavel Hrdina <phrdina(a)redhat.com>
Also adjust direct links from other pages.
Signed-off-by: Pavel Hrdina <phrdina(a)redhat.com>
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/firewall.rst | 2 +-
docs/formatdomain.rst | 3 +-
docs/formatnwfilter.html.in | 2471 -----------------------------------
docs/formatnwfilter.rst | 1789 +++++++++++++++++++++++++
docs/meson.build | 2 +-
5 files changed, 1793 insertions(+), 2474 deletions(-)
delete mode 100644 docs/formatnwfilter.html.in
create mode 100644 docs/formatnwfilter.rst
diff --git a/docs/firewall.rst b/docs/firewall.rst
index adda0ef1f4..eff9de5a89 100644
--- a/docs/firewall.rst
+++ b/docs/firewall.rst
@@ -250,7 +250,7 @@ source IP address ``!= $IP`` like this:
I'm not going to go into details on all the other protocol matches you can do,
because it'll take far too much space. You can read about the options
-`here <formatnwfilter.html#nwfelemsRulesProto>`__.
+`here <formatnwfilter.html#supported-protocols>`__.
Out of the box in RHEL6/Fedora rawhide, libvirt ships with a set of default
useful rules:
diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index 24fbfd8670..552b5364f8 100644
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -5845,7 +5845,8 @@ complete details.
The ``filter`` attribute specifies the name of the nwfilter to use. Optional
``<parameter>`` elements may be specified for passing additional info to the
nwfilter via the ``name`` and ``value`` attributes. See the
-`nwfilter <formatnwfilter.html#nwfconceptsvars>`__ docs for info on parameters.
+`nwfilter <formatnwfilter.html#usage-of-variables-in-filters>`__ docs for info
+on parameters.
:anchor:`<a id="elementsInput"/>`
diff --git a/docs/formatnwfilter.html.in b/docs/formatnwfilter.html.in
deleted file mode 100644
index 04aeda06ec..0000000000
--- a/docs/formatnwfilter.html.in
+++ /dev/null
@@ -1,2471 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Network Filters</h1>
-
- <ul id="toc">
- </ul>
-
- <p>
- This page provides an introduction to libvirt's network filters,
- their goals, concepts and XML format.
- </p>
-
- <h2><a id="goals">Goals and background</a></h2>
-
- <p>
- The goal of the network filtering XML is to enable administrators
- of a virtualized system to configure and enforce network traffic
- filtering rules on virtual
- machines and manage the parameters of network traffic that
- virtual machines
- are allowed to send or receive.
- The network traffic filtering rules are
- applied on the host when a virtual machine is started. Since the
- filtering rules
- cannot be circumvented from within
- the virtual machine, it makes them mandatory from the point of
- view of a virtual machine user.
- <br/><br/>
- The network filter subsystem allows each virtual machine's network
- traffic filtering rules to be configured individually on a per
- interface basis. The rules are
- applied on the host when the virtual machine is started and can be modified
- while the virtual machine is running. The latter can be achieved by
- modifying the XML description of a network filter.
- <br/><br/>
- Multiple virtual machines can make use of the same generic network filter.
- When such a filter is modified, the network traffic filtering rules
- of all running virtual machines that reference this filter are updated.
- <br/><br/>
- Network filtering support is available <span class="since">since
0.8.1
- (QEMU, KVM)</span>
- </p>
-
- <h2><a id="nwfconcepts">Concepts</a></h2>
- <p>
- The network traffic filtering subsystem enables configuration
- of network traffic filtering rules on individual network
- interfaces that are configured for certain types of
- network configurations. Supported network types are
- </p>
- <ul>
- <li><code>network</code></li>
- <li><code>ethernet</code> -- must be used in bridging
mode</li>
- <li><code>bridge</code></li>
- </ul>
- <p>
- The interface XML is used to reference a top-level filter. In the
- following example, the interface description references
- the filter <code>clean-traffic</code>.
- </p>
-<pre>
-...
-<devices>
- <interface type='bridge'>
- <mac address='00:16:3e:5d:c7:9e'/>
- <filterref filter='clean-traffic'/>
- </interface>
-</devices>
-...</pre>
-
- <p>
- Network filters are written in XML and may either contain references
- to other filters, contain rules for traffic filtering, or
- hold a combination of both. The above referenced filter
- <code>clean-traffic </code> is a filter that only contains references to
- other filters and no actual filtering rules. Since references to
- other filters can be used, a <i>tree</i> of filters can be built.
- The <code>clean-traffic</code> filter can be viewed using the
- command <code>virsh nwfilter-dumpxml clean-traffic</code>.
- <br/><br/>
- As previously mentioned, a single network filter can be referenced
- by multiple virtual machines. Since interfaces will typically
- have individual parameters associated with their respective traffic
- filtering rules, the rules described in a filter XML can
- be parameterized with variables. In this case, the variable name
- is used in the filter XML and the name and value are provided at the
- place where the filter is referenced. In the
- following example, the interface description has been extended with
- the parameter <code>IP</code> and a dotted IP address as value.
- </p>
-<pre>
-...
-<devices>
- <interface type='bridge'>
- <mac address='00:16:3e:5d:c7:9e'/>
- <filterref filter='clean-traffic'>
- <parameter name='IP' value='10.0.0.1'/>
- </filterref>
- </interface>
-</devices>
-...</pre>
-
- <p>
- In this particular example, the <code>clean-traffic</code> network
- traffic filter will be instantiated with the IP address parameter
- 10.0.0.1 and enforce that the traffic from this interface will
- always be using 10.0.0.1 as the source IP address, which is
- one of the purposes of this particular filter.
- <br/><br/>
- </p>
-
- <h3><a id="nwfconceptschains">Filtering
chains</a></h3>
- <p>
- Filtering rules are organized in filter chains. These chains can be
- thought of as having a tree structure with packet
- filtering rules as entries in individual chains (branches). <br/>
- Packets start their filter evaluation in the <code>root</code> chain
- and can then continue their evaluation in other chains, return from
- those chains back into the <code>root</code> chain or be
- dropped or accepted by a filtering rule in one of the traversed chains.
- <br/>
- Libvirt's network filtering system automatically creates individual
- <code>root</code> chains for every virtual machine's network
interface
- on which the user chooses to activate traffic filtering.
- The user may write filtering rules that are either directly instantiated
- in the <code>root</code> chain or may create protocol-specific
- filtering chains for efficient evaluation of protocol-specific rules.
- The following chains exist:
- </p>
- <ul>
- <li>root</li>
- <li>mac <span class="since">(since
0.9.8)</span></li>
- <li>stp (spanning tree protocol)
- <span class="since">(since 0.9.8)</span></li>
- <li>vlan (802.1Q) <span class="since">(since
0.9.8)</span></li>
- <li>arp, rarp</li>
- <li>ipv4</li>
- <li>ipv6</li>
- </ul>
- <p>
- <span class="since">Since 0.9.8</span> multiple chains
evaluating the
- <code>mac</code>, <code>stp</code>,
<code>vlan</code>,
- <code>arp</code>, <code>rarp</code>,
<code>ipv4</code>, or
- <code>ipv6</code> protocol can be created using
- the protocol name only as a prefix in the chain's name. This for
- examples allows chains with names <code>arp-xyz</code> or
- <code>arp-test</code> to be specified and have ARP protocol packets
- evaluated in those chains.
- <br/><br/>
- The following filter shows an example of filtering ARP traffic
- in the <code>arp</code> chain.
- </p>
-<pre>
-<filter name='no-arp-spoofing' chain='arp'
priority='-500'>
- <uuid>f88f1932-debf-4aa1-9fbe-f10d3aa4bc95</uuid>
- <rule action='drop' direction='out'
priority='300'>
- <mac match='no' srcmacaddr='$MAC'/>
- </rule>
- <rule action='drop' direction='out'
priority='350'>
- <arp match='no' arpsrcmacaddr='$MAC'/>
- </rule>
- <rule action='drop' direction='out'
priority='400'>
- <arp match='no' arpsrcipaddr='$IP'/>
- </rule>
- <rule action='drop' direction='in'
priority='450'>
- <arp opcode='Reply'/>
- <arp match='no' arpdstmacaddr='$MAC'/>
- </rule>
- <rule action='drop' direction='in'
priority='500'>
- <arp match='no' arpdstipaddr='$IP'/>
- </rule>
- <rule action='accept' direction='inout'
priority='600'>
- <arp opcode='Request'/>
- </rule>
- <rule action='accept' direction='inout'
priority='650'>
- <arp opcode='Reply'/>
- </rule>
- <rule action='drop' direction='inout'
priority='1000'/>
-</filter>
-</pre>
- <p>
- The consequence of putting ARP-specific rules in the <code>arp</code>
- chain, rather than for example in the <code>root</code> chain, is that
- packets for any other protocol than ARP do not need to be evaluated by
- ARP protocol-specific rules. This improves the efficiency
- of the traffic filtering. However, one must then pay attention to only
- put filtering rules for the given protocol into the chain since
- any other rules will not be evaluated, i.e., an IPv4 rule will not
- be evaluated in the ARP chain since no IPv4 protocol packets will
- traverse the ARP chain.
- <br/><br/>
- </p>
- <h3><a id="nwfconceptschainpriorities">Filtering chain
priorities</a></h3>
- <p>
- All chains are connected to the <code>root</code> chain. The order in
- which those chains are accessed is influenced by the priority of the
- chain. The following table shows the chains that can be assigned a
- priority and their default priorities.
- </p>
- <table class="top_table">
- <tr>
- <th> Chain (prefix) </th>
- <th> Default priority </th>
- </tr>
- <tr>
- <td>stp</td><td>-810</td>
- </tr>
- <tr>
- <td>mac</td><td>-800</td>
- </tr>
- <tr>
- <td>vlan</td><td>-750</td>
- </tr>
- <tr>
- <td>ipv4</td><td>-700</td>
- </tr>
- <tr>
- <td>ipv6</td><td>-600</td>
- </tr>
- <tr>
- <td>arp</td><td>-500</td>
- </tr>
- <tr>
- <td>rarp</td><td>-400</td>
- </tr>
- </table>
- <p>
- A chain with a lower priority value is accessed before one with a
- higher value.
- <br/>
- <span class="since">Since 0.9.8</span> the above listed
chains
- can be assigned custom priorities by writing a value in the
- range [-1000, 1000] into the priority (XML) attribute in the filter
- node. The above example filter shows the default priority of -500
- for <code>arp</code> chains.
- </p>
- <h3><a id="nwfconceptsvars">Usage of variables in
filters</a></h3>
- <p>
-
- Two variables names have so far been reserved for usage by the
- network traffic filtering subsystem: <code>MAC</code> and
- <code>IP</code>.
- <br/><br/>
- <code>MAC</code> is the MAC address of the
- network interface. A filtering rule that references this variable
- will automatically be instantiated with the MAC address of the
- interface. This works without the user having to explicitly provide
- the MAC parameter. Even though it is possible to specify the MAC
- parameter similar to the IP parameter above, it is discouraged
- since libvirt knows what MAC address an interface will be using.
- <br/><br/>
- The parameter <code>IP</code> represents the IP address
- that the operating system inside the virtual machine is expected
- to use on the given interface. The <code>IP</code> parameter
- is special in so far as the libvirt daemon will try to determine
- the IP address (and thus the IP parameter's value) that is being
- used on an interface if the parameter
- is not explicitly provided but referenced.
- For current limitations on IP address detection, consult the
- <a href="#nwflimits">section on limitations</a> on how to use
this
- feature and what to expect when using it.
- <br/><br/>
- The above-shown network filer <code>no-arp-spoofing</code>
- is an example of
- a network filter XML referencing the <code>MAC</code> and
- <code>IP</code> variables.
- <br/><br/>
- Note that referenced variables are always prefixed with the
- $ (dollar) sign. The format of the value of a variable
- must be of the type expected by the filter attribute in the
- XML. In the above example, the <code>IP</code> parameter
- must hold a dotted IP address in decimal numbers format.
- Failure to provide the correct
- value type will result in the filter not being instantiatable
- and will prevent a virtual machine from starting or the
- interface from attaching when hotplugging is used. The types
- that are expected for each XML attribute are shown
- below.
- <br/><br/>
- <span class="since">Since 0.9.8</span> variables can contain
lists of
- elements, e.g., the variable <code>IP</code> can contain multiple IP
- addresses that are valid on a particular interface. The notation for
- providing multiple elements for the IP variable is:
- </p>
-<pre>
-...
-<devices>
- <interface type='bridge'>
- <mac address='00:16:3e:5d:c7:9e'/>
- <filterref filter='clean-traffic'>
- <parameter name='IP' value='10.0.0.1'/>
- <parameter name='IP' value='10.0.0.2'/>
- <parameter name='IP' value='10.0.0.3'/>
- </filterref>
- </interface>
-</devices>
-...</pre>
- <p>
- This then allows filters to enable multiple IP addresses
- per interface. Therefore, with the list
- of IP address shown above, the following rule will create 3
- individual filtering rules, one for each IP address.
- </p>
-<pre>
-...
-<rule action='accept' direction='in'
priority='500'>
- <tcp srpipaddr='$IP'/>
-</rule>
-...
-</pre>
- <p>
- <span class="since">Since 0.9.10</span> it is possible to
access
- individual elements of a variable holding a list of elements.
- A filtering rule like the following accesses the 2nd element
- of the variable DSTPORTS.
- </p>
-<pre>
-...
-<rule action='accept' direction='in'
priority='500'>
- <udp dstportstart='$DSTPORTS[1]'/>
-</rule>
-...
-</pre>
- <p>
- <span class="since">Since 0.9.10</span> it is possible to
create
- filtering rules that instantiate all combinations of rules from
- different lists using the notation of
- <code>$VARIABLE[@<iterator ID>]</code>.
- The following rule allows a virtual machine to
- receive traffic on a set of ports, which are specified in DSTPORTS,
- from the set of source IP address specified in SRCIPADDRESSES.
- The rule generates all combinations of elements of the variable
- DSTPORT with those of SRCIPADDRESSES by using two independent
- iterators to access their elements.
- </p>
-<pre>
-...
-<rule action='accept' direction='in'
priority='500'>
- <ip srcipaddr='$SRCIPADDRESSES[@1]'
dstportstart='$DSTPORTS[@2]'/>
-</rule>
-...
-</pre>
-
- <p>
- In an example we assign concrete values to SRCIPADDRESSES and DSTPORTS
- </p>
-<pre>
-SRCIPADDRESSES = [ 10.0.0.1, 11.1.2.3 ]
-DSTPORTS = [ 80, 8080 ]
-</pre>
- <p>
- Accessing the variables using $SRCIPADDRESSES[@1] and $DSTPORTS[@2] would
- then result in all combinations of addresses and ports being created:
- </p>
-<pre>
-10.0.0.1, 80
-10.0.0.1, 8080
-11.1.2.3, 80
-11.1.2.3, 8080
-</pre>
- <p>
- Accessing the same variables using a single iterator, for example by using
- the notation $SRCIPADDRESSES[@1] and $DSTPORTS[@1], would result in
- parallel access to both lists and result in the following combinations:
- </p>
-<pre>
-10.0.0.1, 80
-11.1.2.3, 8080
-</pre>
- <p>
- Further, the notation of $VARIABLE is short-hand for $VARIABLE[@0]. The
- former notation always assumes the iterator with Id '0'.
- </p>
-
- <h3><a id="nwfelemsRulesAdvIPAddrDetection">Automatic IP
address detection</a></h3>
- <p>
- The detection of IP addresses used on a virtual machine's interface
- is automatically activated if the variable <code>IP</code> is
referenced
- but no value has been assigned to it.
- <span class="since">Since 0.9.13</span>
- the variable <code>CTRL_IP_LEARNING</code> can be used to specify
- the IP address learning method to use. Valid values are
<code>any</code>,
- <code>dhcp</code>, or <code>none</code>.
- <br/><br/>
- The value <code>any</code> means that libvirt may use any packet to
- determine the address in use by a virtual machine, which is the default
- behavior if the variable <code>CTRL_IP_LEARNING</code> is not set.
This method
- will only detect a single IP address on an interface.
- Once a VM's IP address has been detected, its IP network traffic
- will be locked to that address, if for example IP address spoofing
- is prevented by one of its filters. In that case the user of the VM
- will not be able to change the IP address on the interface inside
- the VM, which would be considered IP address spoofing.
- When a VM is migrated to another host or resumed after a suspend operation,
- the first packet sent by the VM will again determine the IP address it can
- use on a particular interface.
- <br/>
- A value of <code>dhcp</code> specifies that libvirt should only honor
DHCP
- server-assigned addresses with valid leases. This method supports the detection
- and usage of multiple IP address per interface.
- When a VM is resumed after a suspend operation, still valid IP address leases
- are applied to its filters. Otherwise the VM is expected to again use DHCP to
obtain new
- IP addresses. The migration of a VM to another physical host requires that
- the VM again runs the DHCP protocol.
- <br/><br/>
- Use of <code>CTRL_IP_LEARNING=dhcp</code> (DHCP snooping) provides
additional
- anti-spoofing security, especially when combined with a filter allowing
- only trusted DHCP servers to assign addresses. To enable this, set the
- variable <code>DHCPSERVER</code> to the IP address of a valid DHCP
server
- and provide filters that use this variable to filter incoming DHCP responses.
- <br/><br/>
- When DHCP snooping is enabled and the DHCP lease expires,
- the VM will no longer be able to use the IP address until it acquires a
- new, valid lease from a DHCP server. If the VM is migrated, it must get
- a new valid DHCP lease to use an IP address (e.g., by
- bringing the VM interface down and up again).
- <br/><br/>
- Note that automatic DHCP detection listens to the DHCP traffic
- the VM exchanges with the DHCP server of the infrastructure. To avoid
- denial-of-service attacks on libvirt, the evaluation of those packets
- is rate-limited, meaning that a VM sending an excessive number of DHCP
- packets per second on an interface will not have all of those packets
- evaluated and thus filters may not get adapted. Normal DHCP client
- behavior is assumed to send a low number of DHCP packets per second.
- Further, it is important to setup appropriate filters on all VMs in
- the infrastructure to avoid them being able to send DHCP
- packets. Therefore VMs must either be prevented from sending UDP and TCP
- traffic from port 67 to port 68 or the <code>DHCPSERVER</code>
- variable should be used on all VMs to restrict DHCP server messages to
- only be allowed to originate from trusted DHCP servers. At the same
- time anti-spoofing prevention must be enabled on all VMs in the subnet.
- <br/><br/>
- If <code>CTRL_IP_LEARNING</code> is set to
<code>none</code>, libvirt does not do
- IP address learning and referencing <code>IP</code> without assigning
it an
- explicit value is an error.
- <br/><br/>
- The following XML provides an example for the activation of IP address learning
- using the DHCP snooping method:
- </p>
-<pre>
-<interface type='bridge'>
- <source bridge='virbr0'/>
- <filterref filter='clean-traffic'>
- <parameter name='CTRL_IP_LEARNING' value='dhcp'/>
- </filterref>
-</interface>
-</pre>
-
- <h3><a id="nwfelemsReservedVars">Reserved
Variables</a></h3>
- <p>
- The following table lists reserved variables in use by libvirt.
- </p>
- <table class="top_table">
- <tr>
- <th> Variable Name </th>
- <th> Semantics </th>
- </tr>
- <tr>
- <td> MAC </td>
- <td> The MAC address of the interface </td>
- </tr>
- <tr>
- <td> IP </td>
- <td> The list of IP addresses in use by an interface </td>
- </tr>
- <tr>
- <td> IPV6 </td>
- <td> The list of IPV6 addresses in use by an interface </td>
- </tr>
- <tr>
- <td> DHCPSERVER </td>
- <td> The list of IP addresses of trusted DHCP servers</td>
- </tr>
- <tr>
- <td> DHCPSERVERV6 </td>
- <td> Not currently implemented:
- The list of IPv6 addresses of trusted DHCP servers</td>
- </tr>
- <tr>
- <td> CTRL_IP_LEARNING </td>
- <td> The choice of the IP address detection mode </td>
- </tr>
- </table>
-
- <h2><a id="nwfelems">Element and attribute
overview</a></h2>
-
- <p>
- The root element required for all network filters is
- named <code>filter</code> with two possible attributes. The
- <code>name</code> attribute provides a unique name of the
- given filter. The <code>chain</code> attribute is optional but
- allows certain filters to be better organized for more efficient
- processing by the firewall subsystem of the underlying host.
- Currently the system only supports the chains <code>root,
- ipv4, ipv6, arp and rarp</code>.
- </p>
-
- <h3><a id="nwfelemsRefs">References to other
filters</a></h3>
- <p>
- Any filter may hold references to other filters. Individual
- filters may be referenced multiple times in a filter tree but
- references between filters must not introduce loops (directed
- acyclic graph).
- <br/><br/>
- The following shows the XML of the <code>clean-traffic</code>
- network filter referencing several other filters.
- </p>
-<pre>
-<filter name='clean-traffic'>
- <uuid>6ef53069-ba34-94a0-d33d-17751b9b8cb1</uuid>
- <filterref filter='no-mac-spoofing'/>
- <filterref filter='no-ip-spoofing'/>
- <filterref filter='allow-incoming-ipv4'/>
- <filterref filter='no-arp-spoofing'/>
- <filterref filter='no-other-l2-traffic'/>
- <filterref filter='qemu-announce-self'/>
-</filter>
-</pre>
-
- <p>
- To reference another filter, the XML node <code>filterref</code>
- needs to be provided inside a <code>filter</code> node. This
- node must have the attribute <code>filter</code> whose value contains
- the name of the filter to be referenced.
- <br/><br/>
- New network filters can be defined at any time and
- may contain references to network filters that are
- not known to libvirt, yet. However, once a virtual machine
- is started or a network interface
- referencing a filter is to be hotplugged, all network filters
- in the filter tree must be available. Otherwise the virtual
- machine will not start or the network interface cannot be
- attached.
- </p>
-
- <h3><a id="nwfelemsRules">Filter rules</a></h3>
- <p>
- The following XML shows a simple example of a network
- traffic filter implementing a rule to drop traffic if
- the IP address (provided through the value of the
- variable IP) in an outgoing IP packet is not the expected
- one, thus preventing IP address spoofing by the VM.
- </p>
-<pre>
-<filter name='no-ip-spoofing' chain='ipv4'>
- <uuid>fce8ae33-e69e-83bf-262e-30786c1f8072</uuid>
- <rule action='drop' direction='out'
priority='500'>
- <ip match='no' srcipaddr='$IP'/>
- </rule>
-</filter>
-</pre>
-
- <p>
- A traffic filtering rule starts with the <code>rule</code>
- node. This node may contain up to three attributes
- </p>
- <ul>
- <li>
- action -- mandatory; must either be <code>drop</code>
- (matching the rule silently discards the packet with no
- further analysis),
- <code>reject</code> (matching the rule generates an ICMP
- reject message with no further analysis) <span
class="since">(since
- 0.9.0)</span>, <code>accept</code> (matching the rule accepts
- the packet with no further analysis), <code>return</code>
- (matching the rule passes this filter, but returns control to
- the calling filter for further
- analysis) <span class="since">(since 0.9.7)</span>,
- or <code>continue</code> (matching the rule goes on to the next
- rule for further analysis) <span class="since">(since
- 0.9.7)</span>.
- </li>
- <li>
- direction -- mandatory; must either be <code>in</code>,
<code>out</code> or
- <code>inout</code> if the rule is for incoming,
- outgoing or incoming-and-outgoing traffic
- </li>
- <li>
- priority -- optional; the priority of the rule controls the order in
- which the rule will be instantiated relative to other rules.
- Rules with lower value will be instantiated before rules with higher
- values.
- Valid values are in the range of 0 to 1000.
- <span class="since">Since 0.9.8</span> this has been
extended to cover
- the range of -1000 to 1000. If this attribute is not
- provided, priority 500 will automatically be assigned.
- <br/>
- Note that filtering rules in the <code>root</code> chain are sorted
- with filters connected to the <code>root</code> chain following
- their priorities. This allows to interleave filtering rules with
- access to filter chains.
- (See also section on
- <a href="#nwfconceptschainpriorities">
- filtering chain priorities
- </a>.)
- </li>
- <li>
- statematch -- optional; possible values are '0' or 'false' to
- turn the underlying connection state matching off; default is 'true'
- <br/>
- Also read the section on <a href="#nwfelemsRulesAdv">advanced
configuration</a>
- topics.
- </li>
- </ul>
- <p>
- The above example indicates that the traffic of type <code>ip</code>
- will be associated with the chain 'ipv4' and the rule will have
- priority 500. If for example another filter is referenced whose
- traffic of type <code>ip</code> is also associated with the chain
- 'ipv4' then that filter's rules will be ordered relative to the
priority
- 500 of the shown rule.
- <br/><br/>
- A rule may contain a single rule for filtering of traffic. The
- above example shows that traffic of type <code>ip</code> is to be
- filtered.
- </p>
-
- <h4><a id="nwfelemsRulesProto">Supported
protocols</a></h4>
- <p>
- The following sections enumerate the list of protocols that
- are supported by the network filtering subsystem. The
- type of traffic a rule is supposed to filter on is provided
- in the <code>rule</code> node as a nested node. Depending
- on the traffic type a rule is filtering, the attributes are
- different. The above example showed the single
- attribute <code>srcipaddr</code> that is valid inside the
- <code>ip</code> traffic filtering node. The following sections
- show what attributes are valid and what type of data they are
- expecting. The following datatypes are available:
- </p>
- <ul>
- <li>UINT8 : 8 bit integer; range 0-255</li>
- <li>UINT16: 16 bit integer; range 0-65535</li>
- <li>MAC_ADDR: MAC address in dotted decimal format, i.e.,
00:11:22:33:44:55</li>
- <li>MAC_MASK: MAC address mask in MAC address format, i.e.,
FF:FF:FF:FC:00:00</li>
- <li>IP_ADDR: IP address in dotted decimal format, i.e., 10.1.2.3</li>
- <li>IP_MASK: IP address mask in either dotted decimal format (255.255.248.0)
or CIDR mask (0-32)</li>
- <li>IPV6_ADDR: IPv6 address in numbers format, i.e., FFFF::1</li>
- <li>IPV6_MASK: IPv6 mask in numbers format (FFFF:FFFF:FC00::) or CIDR mask
(0-128)</li>
- <li>STRING: A string</li>
- <li>BOOLEAN: 'true', 'yes', '1' or 'false',
'no', '0'</li>
- <li>IPSETFLAGS: The source and destination flags of the ipset described
- by up to 6 'src' or 'dst' elements selecting features from
either
- the source or destination part of the packet header; example:
- src,src,dst. The number of 'selectors' to provide here depends
- on the type of ipset that is referenced.</li>
- </ul>
- <p>
- <br/><br/>
- Every attribute except for those of type IP_MASK or IPV6_MASK can
- be negated using the <code>match</code>
- attribute with value <code>no</code>. Multiple negated attributes
- may be grouped together. The following
- XML fragment shows such an example using abstract attributes.
- </p>
-<pre>
-[...]
-<rule action='drop' direction='in'>
- <protocol match='no' attribute1='value1'
attribute2='value2'/>
- <protocol attribute3='value3'/>
-</rule>
-[...]
-</pre>
- <p>
- Rules perform a logical AND evaluation on all values of the given
- protocol attributes. Thus, if a single attribute's value does not match
- the one given in the rule, the whole rule will be skipped during
- evaluation. Therefore, in the above example incoming traffic
- will only be dropped if
- the protocol property attribute1 does not match value1 AND
- the protocol property attribute2 does not match value2 AND
- the protocol property attribute3 matches value3.
- <br/><br/>
- </p>
-
-
- <h5><a id="nwfelemsRulesProtoMAC">MAC
(Ethernet)</a></h5>
- <p>
- Protocol ID: <code>mac</code>
- <br/>
- Note: Rules of this type should go into the <code>root</code> chain.
- </p>
- <table class="top_table">
- <tr>
- <th> Attribute </th>
- <th> Datatype </th>
- <th> Semantics </th>
- </tr>
- <tr>
- <td>srcmacaddr</td>
- <td>MAC_ADDR</td>
- <td>MAC address of sender</td>
- </tr>
- <tr>
- <td>srcmacmask</td>
- <td>MAC_MASK</td>
- <td>Mask applied to MAC address of sender</td>
- </tr>
- <tr>
- <td>dstmacaddr</td>
- <td>MAC_ADDR</td>
- <td>MAC address of destination</td>
- </tr>
- <tr>
- <td>dstmacmask</td>
- <td>MAC_MASK</td>
- <td>Mask applied to MAC address of destination</td>
- </tr>
- <tr>
- <td>protocolid</td>
- <td>UINT16 (0x600-0xffff), STRING</td>
- <td>Layer 3 protocol ID</td>
- </tr>
- <tr>
- <td>comment <span class="since">(Since
0.8.5)</span></td>
- <td>STRING</td>
- <td>text with max. 256 characters</td>
- </tr>
- </table>
- <p>
- Valid Strings for <code>protocolid</code> are: arp, rarp, ipv4, ipv6
- </p>
-<pre>
-[...]
-<mac match='no' srcmacaddr='$MAC'/>
-[...]
-</pre>
-
- <h5><a id="nwfelemsRulesProtoVLAN">VLAN (802.1Q)</a>
- <span class="since">(Since 0.9.8)</span>
- </h5>
- <p>
- Protocol ID: <code>vlan</code>
- <br/>
- Note: Rules of this type should go either into the <code>root</code>
or
- <code>vlan</code> chain.
- </p>
- <table class="top_table">
- <tr>
- <th> Attribute </th>
- <th> Datatype </th>
- <th> Semantics </th>
- </tr>
- <tr>
- <td>srcmacaddr</td>
- <td>MAC_ADDR</td>
- <td>MAC address of sender</td>
- </tr>
- <tr>
- <td>srcmacmask</td>
- <td>MAC_MASK</td>
- <td>Mask applied to MAC address of sender</td>
- </tr>
- <tr>
- <td>dstmacaddr</td>
- <td>MAC_ADDR</td>
- <td>MAC address of destination</td>
- </tr>
- <tr>
- <td>dstmacmask</td>
- <td>MAC_MASK</td>
- <td>Mask applied to MAC address of destination</td>
- </tr>
- <tr>
- <td>vlanid</td>
- <td>UINT16 (0x0-0xfff, 0 - 4095)</td>
- <td>VLAN ID</td>
- </tr>
- <tr>
- <td>encap-protocol</td>
- <td>UINT16 (0x03c-0xfff), String</td>
- <td>Encapsulated layer 3 protocol ID</td>
- </tr>
- <tr>
- <td>comment </td>
- <td>STRING</td>
- <td>text with max. 256 characters</td>
- </tr>
- </table>
- <p>
- Valid Strings for <code>encap-protocol</code> are: arp, ipv4, ipv6
- </p>
-
- <h5><a id="nwfelemsRulesProtoSTP">STP (Spanning Tree
Protocol)</a>
- <span class="since">(Since 0.9.8)</span>
- </h5>
- <p>
- Protocol ID: <code>stp</code>
- <br/>
- Note: Rules of this type should go either into the <code>root</code>
or
- <code>stp</code> chain.
- </p>
- <table class="top_table">
- <tr>
- <th> Attribute </th>
- <th> Datatype </th>
- <th> Semantics </th>
- </tr>
- <tr>
- <td>srcmacaddr</td>
- <td>MAC_ADDR</td>
- <td>MAC address of sender</td>
- </tr>
- <tr>
- <td>srcmacmask</td>
- <td>MAC_MASK</td>
- <td>Mask applied to MAC address of sender</td>
- </tr>
- <tr>
- <td>type</td>
- <td>UINT8</td>
- <td>Bridge Protocol Data Unit (BPDU) type</td>
- </tr>
- <tr>
- <td>flags</td>
- <td>UINT8</td>
- <td>BPDU flag</td>
- </tr>
- <tr>
- <td>root-priority</td>
- <td>UINT16</td>
- <td>Root priority (range start)</td>
- </tr>
- <tr>
- <td>root-priority-hi</td>
- <td>UINT16</td>
- <td>Root priority range end</td>
- </tr>
- <tr>
- <td>root-address</td>
- <td>MAC_ADDRESS</td>
- <td>Root MAC address</td>
- </tr>
- <tr>
- <td>root-address-mask</td>
- <td>MAC_MASK</td>
- <td>Root MAC address mask</td>
- </tr>
- <tr>
- <td>root-cost</td>
- <td>UINT32</td>
- <td>Root path cost (range start)</td>
- </tr>
- <tr>
- <td>root-cost-hi</td>
- <td>UINT32</td>
- <td>Root path cost range end</td>
- </tr>
- <tr>
- <td>sender-priority</td>
- <td>UINT16</td>
- <td>Sender priority (range start)</td>
- </tr>
- <tr>
- <td>sender-priority-hi</td>
- <td>UINT16</td>
- <td>Sender priority range end</td>
- </tr>
- <tr>
- <td>sender-address</td>
- <td>MAC_ADDRESS</td>
- <td>BPDU sender MAC address</td>
- </tr>
- <tr>
- <td>sender-address-mask</td>
- <td>MAC_MASK</td>
- <td>BPDU sender MAC address mask</td>
- </tr>
- <tr>
- <td>port</td>
- <td>UINT16</td>
- <td>Port identifier (range start)</td>
- </tr>
- <tr>
- <td>port_hi</td>
- <td>UINT16</td>
- <td>Port identifier range end</td>
- </tr>
- <tr>
- <td>msg-age</td>
- <td>UINT16</td>
- <td>Message age timer (range start)</td>
- </tr>
- <tr>
- <td>msg-age-hi</td>
- <td>UINT16</td>
- <td>Message age timer range end</td>
- </tr>
- <tr>
- <td>max-age</td>
- <td>UINT16</td>
- <td>Maximum age timer (range start)</td>
- </tr>
- <tr>
- <td>max-age-hi</td>
- <td>UINT16</td>
- <td>Maximum age timer range end</td>
- </tr>
- <tr>
- <td>hello-time</td>
- <td>UINT16</td>
- <td>Hello time timer (range start)</td>
- </tr>
- <tr>
- <td>hello-time-hi</td>
- <td>UINT16</td>
- <td>Hello time timer range end</td>
- </tr>
- <tr>
- <td>forward-delay</td>
- <td>UINT16</td>
- <td>Forward delay (range start)</td>
- </tr>
- <tr>
- <td>forward-delay-hi</td>
- <td>UINT16</td>
- <td>Forward delay range end</td>
- </tr>
- <tr>
- <td>comment</td>
- <td>STRING</td>
- <td>text with max. 256 characters</td>
- </tr>
- </table>
-
- <h5><a
id="nwfelemsRulesProtoARP">ARP/RARP</a></h5>
- <p>
- Protocol ID: <code>arp</code> or <code>rarp</code>
- <br/>
- Note: Rules of this type should either go into the
- <code>root</code> or <code>arp/rarp</code> chain.
- </p>
- <table class="top_table">
- <tr>
- <th> Attribute </th>
- <th> Datatype </th>
- <th> Semantics </th>
- </tr>
- <tr>
- <td>srcmacaddr</td>
- <td>MAC_ADDR</td>
- <td>MAC address of sender</td>
- </tr>
- <tr>
- <td>srcmacmask</td>
- <td>MAC_MASK</td>
- <td>Mask applied to MAC address of sender</td>
- </tr>
- <tr>
- <td>dstmacaddr</td>
- <td>MAC_ADDR</td>
- <td>MAC address of destination</td>
- </tr>
- <tr>
- <td>dstmacmask</td>
- <td>MAC_MASK</td>
- <td>Mask applied to MAC address of destination</td>
- </tr>
- <tr>
- <td>hwtype</td>
- <td>UINT16</td>
- <td>Hardware type</td>
- </tr>
- <tr>
- <td>protocoltype</td>
- <td>UINT16</td>
- <td>Protocol type</td>
- </tr>
- <tr>
- <td>opcode</td>
- <td>UINT16, STRING</td>
- <td>Opcode</td>
- </tr>
- <tr>
- <td>arpsrcmacaddr</td>
- <td>MAC_ADDR</td>
- <td>Source MAC address in ARP/RARP packet</td>
- </tr>
- <tr>
- <td>arpdstmacaddr</td>
- <td>MAC_ADDR</td>
- <td>Destination MAC address in ARP/RARP packet</td>
- </tr>
- <tr>
- <td>arpsrcipaddr</td>
- <td>IP_ADDR</td>
- <td>Source IP address in ARP/RARP packet</td>
- </tr>
- <tr>
- <td>arpsrcipmask <span class="since">(Since
1.2.3)</span></td>
- <td>IP_MASK</td>
- <td>Source IP mask</td>
- </tr>
- <tr>
- <td>arpdstipaddr</td>
- <td>IP_ADDR</td>
- <td>Destination IP address in ARP/RARP packet</td>
- </tr>
- <tr>
- <td>arpdstipmask <span class="since">(Since
1.2.3)</span></td>
- <td>IP_MASK</td>
- <td>Destination IP mask</td>
- </tr>
- <tr>
- <td>comment <span class="since">(Since
0.8.5)</span></td>
- <td>STRING</td>
- <td>text with max. 256 characters</td>
- </tr>
- <tr>
- <td>gratuitous <span class="since">(Since
0.9.2)</span></td>
- <td>BOOLEAN</td>
- <td>boolean indicating whether to check for gratuitous ARP
packet</td>
- </tr>
- </table>
- <p>
- Valid strings for the <code>Opcode</code> field are:
- Request, Reply, Request_Reverse, Reply_Reverse, DRARP_Request,
- DRARP_Reply, DRARP_Error, InARP_Request, ARP_NAK
- <br/><br/>
- </p>
-
- <h5><a id="nwfelemsRulesProtoIP">IPv4</a></h5>
- <p>
- Protocol ID: <code>ip</code>
- <br/>
- Note: Rules of this type should either go into the
- <code>root</code> or <code>ipv4</code> chain.
- </p>
- <table class="top_table">
- <tr>
- <th> Attribute </th>
- <th> Datatype </th>
- <th> Semantics </th>
- </tr>
- <tr>
- <td>srcmacaddr</td>
- <td>MAC_ADDR</td>
- <td>MAC address of sender</td>
- </tr>
- <tr>
- <td>srcmacmask</td>
- <td>MAC_MASK</td>
- <td>Mask applied to MAC address of sender</td>
- </tr>
- <tr>
- <td>dstmacaddr</td>
- <td>MAC_ADDR</td>
- <td>MAC address of destination</td>
- </tr>
- <tr>
- <td>dstmacmask</td>
- <td>MAC_MASK</td>
- <td>Mask applied to MAC address of destination</td>
- </tr>
- <tr>
- <td>srcipaddr</td>
- <td>IP_ADDR</td>
- <td>Source IP address</td>
- </tr>
- <tr>
- <td>srcipmask</td>
- <td>IP_MASK</td>
- <td>Mask applied to source IP address</td>
- </tr>
- <tr>
- <td>dstipaddr</td>
- <td>IP_ADDR</td>
- <td>Destination IP address</td>
- </tr>
- <tr>
- <td>dstipmask</td>
- <td>IP_MASK</td>
- <td>Mask applied to destination IP address</td>
- </tr>
- <tr>
- <td>protocol</td>
- <td>UINT8, STRING</td>
- <td>Layer 4 protocol identifier</td>
- </tr>
- <tr>
- <td>srcportstart</td>
- <td>UINT16</td>
- <td>Start of range of valid source ports; requires
<code>protocol</code></td>
- </tr>
- <tr>
- <td>srcportend</td>
- <td>UINT16</td>
- <td>End of range of valid source ports; requires
<code>protocol</code></td>
- </tr>
- <tr>
- <td>dstportstart</td>
- <td>UINT16</td>
- <td>Start of range of valid destination ports; requires
<code>protocol</code></td>
- </tr>
- <tr>
- <td>dstportend</td>
- <td>UINT16</td>
- <td>End of range of valid destination ports; requires
<code>protocol</code></td>
- </tr>
- <tr>
- <td>dscp</td>
- <td>UINT8 (0x0-0x3f, 0 - 63)</td>
- <td>Differentiated Services Code Point</td>
- </tr>
- <tr>
- <td>comment <span class="since">(Since
0.8.5)</span></td>
- <td>STRING</td>
- <td>text with max. 256 characters</td>
- </tr>
- </table>
- <p>
- Valid strings for <code>protocol</code> are:
- tcp, udp, udplite, esp, ah, icmp, igmp, sctp
- <br/><br/>
- </p>
-
-
- <h5><a id="nwfelemsRulesProtoIPv6">IPv6</a></h5>
- <p>
- Protocol ID: <code>ipv6</code>
- <br/>
- Note: Rules of this type should either go into the
- <code>root</code> or <code>ipv6</code> chain.
- </p>
- <table class="top_table">
- <tr>
- <th> Attribute </th>
- <th> Datatype </th>
- <th> Semantics </th>
- </tr>
- <tr>
- <td>srcmacaddr</td>
- <td>MAC_ADDR</td>
- <td>MAC address of sender</td>
- </tr>
- <tr>
- <td>srcmacmask</td>
- <td>MAC_MASK</td>
- <td>Mask applied to MAC address of sender</td>
- </tr>
- <tr>
- <td>dstmacaddr</td>
- <td>MAC_ADDR</td>
- <td>MAC address of destination</td>
- </tr>
- <tr>
- <td>dstmacmask</td>
- <td>MAC_MASK</td>
- <td>Mask applied to MAC address of destination</td>
- </tr>
- <tr>
- <td>srcipaddr</td>
- <td>IPV6_ADDR</td>
- <td>Source IPv6 address</td>
- </tr>
- <tr>
- <td>srcipmask</td>
- <td>IPV6_MASK</td>
- <td>Mask applied to source IPv6 address</td>
- </tr>
- <tr>
- <td>dstipaddr</td>
- <td>IPV6_ADDR</td>
- <td>Destination IPv6 address</td>
- </tr>
- <tr>
- <td>dstipmask</td>
- <td>IPV6_MASK</td>
- <td>Mask applied to destination IPv6 address</td>
- </tr>
- <tr>
- <td>protocol</td>
- <td>UINT8</td>
- <td>Layer 4 protocol identifier</td>
- </tr>
- <tr>
- <td>srcportstart</td>
- <td>UINT16</td>
- <td>Start of range of valid source ports; requires
<code>protocol</code></td>
- </tr>
- <tr>
- <td>srcportend</td>
- <td>UINT16</td>
- <td>End of range of valid source ports; requires
<code>protocol</code></td>
- </tr>
- <tr>
- <td>dstportstart</td>
- <td>UINT16</td>
- <td>Start of range of valid destination ports; requires
<code>protocol</code></td>
- </tr>
- <tr>
- <td>dstportend</td>
- <td>UINT16</td>
- <td>End of range of valid destination ports; requires
<code>protocol</code></td>
- </tr>
- <tr>
- <td>type<span class="since">(Since
1.2.12)</span></td>
- <td>UINT8</td>
- <td>ICMPv6 type; requires <code>protocol</code> to be set to
<code>icmpv6</code></td>
- </tr>
- <tr>
- <td>typeend<span class="since">(Since
1.2.12)</span></td>
- <td>UINT8</td>
- <td>ICMPv6 type end of range; requires <code>protocol</code>
to be set to <code>icmpv6</code></td>
- </tr>
- <tr>
- <td>code<span class="since">(Since
1.2.12)</span></td>
- <td>UINT8</td>
- <td>ICMPv6 code; requires <code>protocol</code> to be set to
<code>icmpv6</code></td>
- </tr>
- <tr>
- <td>code<span class="since">(Since
1.2.12)</span></td>
- <td>UINT8</td>
- <td>ICMPv6 code end of range; requires <code>protocol</code>
to be set to <code>icmpv6</code></td>
- </tr>
- <tr>
- <td>comment <span class="since">(Since
0.8.5)</span></td>
- <td>STRING</td>
- <td>text with max. 256 characters</td>
- </tr>
- </table>
- <p>
- Valid strings for <code>protocol</code> are:
- tcp, udp, udplite, esp, ah, icmpv6, sctp
- <br/><br/>
- </p>
-
- <h5><a
id="nwfelemsRulesProtoTCP-ipv4">TCP/UDP/SCTP</a></h5>
- <p>
- Protocol ID: <code>tcp</code>, <code>udp</code>,
<code>sctp</code>
- <br/>
- Note: The chain parameter is ignored for this type of traffic
- and should either be omitted or set to <code>root</code>.
- </p>
- <table class="top_table">
- <tr>
- <th> Attribute </th>
- <th> Datatype </th>
- <th> Semantics </th>
- </tr>
- <tr>
- <td>srcmacaddr</td>
- <td>MAC_ADDR</td>
- <td>MAC address of sender</td>
- </tr>
- <tr>
- <td>srcipaddr</td>
- <td>IP_ADDR</td>
- <td>Source IP address</td>
- </tr>
- <tr>
- <td>srcipmask</td>
- <td>IP_MASK</td>
- <td>Mask applied to source IP address</td>
- </tr>
- <tr>
- <td>dstipaddr</td>
- <td>IP_ADDR</td>
- <td>Destination IP address</td>
- </tr>
- <tr>
- <td>dstipmask</td>
- <td>IP_MASK</td>
- <td>Mask applied to destination IP address</td>
- </tr>
-
- <tr>
- <td>srcipfrom</td>
- <td>IP_ADDR</td>
- <td>Start of range of source IP address</td>
- </tr>
- <tr>
- <td>srcipto</td>
- <td>IP_ADDR</td>
- <td>End of range of source IP address</td>
- </tr>
- <tr>
- <td>dstipfrom</td>
- <td>IP_ADDR</td>
- <td>Start of range of destination IP address</td>
- </tr>
- <tr>
- <td>dstipto</td>
- <td>IP_ADDR</td>
- <td>End of range of destination IP address</td>
- </tr>
-
- <tr>
- <td>srcportstart</td>
- <td>UINT16</td>
- <td>Start of range of valid source ports</td>
- </tr>
- <tr>
- <td>srcportend</td>
- <td>UINT16</td>
- <td>End of range of valid source ports</td>
- </tr>
- <tr>
- <td>dstportstart</td>
- <td>UINT16</td>
- <td>Start of range of valid destination ports</td>
- </tr>
- <tr>
- <td>dstportend</td>
- <td>UINT16</td>
- <td>End of range of valid destination ports</td>
- </tr>
- <tr>
- <td>dscp</td>
- <td>UINT8 (0x0-0x3f, 0 - 63)</td>
- <td>Differentiated Services Code Point</td>
- </tr>
- <tr>
- <td>comment <span class="since">(Since
0.8.5)</span></td>
- <td>STRING</td>
- <td>text with max. 256 characters</td>
- </tr>
- <tr>
- <td>state <span class="since">(Since
0.8.5)</span></td>
- <td>STRING</td>
- <td>comma separated list of NEW,ESTABLISHED,RELATED,INVALID or
NONE</td>
- </tr>
- <tr>
- <td>flags <span class="since">(Since
0.9.1)</span></td>
- <td>STRING</td>
- <td>TCP-only: format of mask/flags with mask and flags each being a comma
separated list of SYN,ACK,URG,PSH,FIN,RST or NONE or ALL</td>
- </tr>
- <tr>
- <td>ipset <span class="since">(Since
0.9.13)</span></td>
- <td>STRING</td>
- <td>The name of an IPSet managed outside of libvirt</td>
- </tr>
- <tr>
- <td>ipsetflags <span class="since">(Since
0.9.13)</span></td>
- <td>IPSETFLAGS</td>
- <td>flags for the IPSet; requires ipset attribute</td>
- </tr>
- </table>
- <p>
- <br/><br/>
- </p>
-
-
- <h5><a id="nwfelemsRulesProtoICMP">ICMP</a></h5>
- <p>
- Protocol ID: <code>icmp</code>
- <br/>
- Note: The chain parameter is ignored for this type of traffic
- and should either be omitted or set to <code>root</code>.
- </p>
- <table class="top_table">
- <tr>
- <th> Attribute </th>
- <th> Datatype </th>
- <th> Semantics </th>
- </tr>
- <tr>
- <td>srcmacaddr</td>
- <td>MAC_ADDR</td>
- <td>MAC address of sender</td>
- </tr>
- <tr>
- <td>srcmacmask</td>
- <td>MAC_MASK</td>
- <td>Mask applied to MAC address of sender</td>
- </tr>
- <tr>
- <td>dstmacaddr</td>
- <td>MAC_ADDR</td>
- <td>MAC address of destination</td>
- </tr>
- <tr>
- <td>dstmacmask</td>
- <td>MAC_MASK</td>
- <td>Mask applied to MAC address of destination</td>
- </tr>
- <tr>
- <td>srcipaddr</td>
- <td>IP_ADDR</td>
- <td>Source IP address</td>
- </tr>
- <tr>
- <td>srcipmask</td>
- <td>IP_MASK</td>
- <td>Mask applied to source IP address</td>
- </tr>
- <tr>
- <td>dstipaddr</td>
- <td>IP_ADDR</td>
- <td>Destination IP address</td>
- </tr>
- <tr>
- <td>dstipmask</td>
- <td>IP_MASK</td>
- <td>Mask applied to destination IP address</td>
- </tr>
-
- <tr>
- <td>srcipfrom</td>
- <td>IP_ADDR</td>
- <td>Start of range of source IP address</td>
- </tr>
- <tr>
- <td>srcipto</td>
- <td>IP_ADDR</td>
- <td>End of range of source IP address</td>
- </tr>
- <tr>
- <td>dstipfrom</td>
- <td>IP_ADDR</td>
- <td>Start of range of destination IP address</td>
- </tr>
- <tr>
- <td>dstipto</td>
- <td>IP_ADDR</td>
- <td>End of range of destination IP address</td>
- </tr>
- <tr>
- <td>type</td>
- <td>UINT16</td>
- <td>ICMP type</td>
- </tr>
- <tr>
- <td>code</td>
- <td>UINT16</td>
- <td>ICMP code</td>
- </tr>
- <tr>
- <td>dscp</td>
- <td>UINT8 (0x0-0x3f, 0 - 63)</td>
- <td>Differentiated Services Code Point</td>
- </tr>
- <tr>
- <td>comment <span class="since">(Since
0.8.5)</span></td>
- <td>STRING</td>
- <td>text with max. 256 characters</td>
- </tr>
- <tr>
- <td>state <span class="since">(Since
0.8.5)</span></td>
- <td>STRING</td>
- <td>comma separated list of NEW,ESTABLISHED,RELATED,INVALID or
NONE</td>
- </tr>
- <tr>
- <td>ipset <span class="since">(Since
0.9.13)</span></td>
- <td>STRING</td>
- <td>The name of an IPSet managed outside of libvirt</td>
- </tr>
- <tr>
- <td>ipsetflags <span class="since">(Since
0.9.13)</span></td>
- <td>IPSETFLAGS</td>
- <td>flags for the IPSet; requires ipset attribute</td>
- </tr>
- </table>
- <p>
- <br/><br/>
- </p>
-
- <h5><a id="nwfelemsRulesProtoMisc">IGMP, ESP, AH, UDPLITE,
'ALL'</a></h5>
- <p>
- Protocol ID: <code>igmp</code>, <code>esp</code>,
<code>ah</code>, <code>udplite</code>,
<code>all</code>
- <br/>
- Note: The chain parameter is ignored for this type of traffic
- and should either be omitted or set to <code>root</code>.
- </p>
- <table class="top_table">
- <tr>
- <th> Attribute </th>
- <th> Datatype </th>
- <th> Semantics </th>
- </tr>
- <tr>
- <td>srcmacaddr</td>
- <td>MAC_ADDR</td>
- <td>MAC address of sender</td>
- </tr>
- <tr>
- <td>srcmacmask</td>
- <td>MAC_MASK</td>
- <td>Mask applied to MAC address of sender</td>
- </tr>
- <tr>
- <td>dstmacaddr</td>
- <td>MAC_ADDR</td>
- <td>MAC address of destination</td>
- </tr>
- <tr>
- <td>dstmacmask</td>
- <td>MAC_MASK</td>
- <td>Mask applied to MAC address of destination</td>
- </tr>
- <tr>
- <td>srcipaddr</td>
- <td>IP_ADDR</td>
- <td>Source IP address</td>
- </tr>
- <tr>
- <td>srcipmask</td>
- <td>IP_MASK</td>
- <td>Mask applied to source IP address</td>
- </tr>
- <tr>
- <td>dstipaddr</td>
- <td>IP_ADDR</td>
- <td>Destination IP address</td>
- </tr>
- <tr>
- <td>dstipmask</td>
- <td>IP_MASK</td>
- <td>Mask applied to destination IP address</td>
- </tr>
-
- <tr>
- <td>srcipfrom</td>
- <td>IP_ADDR</td>
- <td>Start of range of source IP address</td>
- </tr>
- <tr>
- <td>srcipto</td>
- <td>IP_ADDR</td>
- <td>End of range of source IP address</td>
- </tr>
- <tr>
- <td>dstipfrom</td>
- <td>IP_ADDR</td>
- <td>Start of range of destination IP address</td>
- </tr>
- <tr>
- <td>dstipto</td>
- <td>IP_ADDR</td>
- <td>End of range of destination IP address</td>
- </tr>
- <tr>
- <td>dscp</td>
- <td>UINT8 (0x0-0x3f, 0 - 63)</td>
- <td>Differentiated Services Code Point</td>
- </tr>
- <tr>
- <td>comment <span class="since">(Since
0.8.5)</span></td>
- <td>STRING</td>
- <td>text with max. 256 characters</td>
- </tr>
- <tr>
- <td>state <span class="since">(Since
0.8.5)</span></td>
- <td>STRING</td>
- <td>comma separated list of NEW,ESTABLISHED,RELATED,INVALID or
NONE</td>
- </tr>
- <tr>
- <td>ipset <span class="since">(Since
0.9.13)</span></td>
- <td>STRING</td>
- <td>The name of an IPSet managed outside of libvirt</td>
- </tr>
- <tr>
- <td>ipsetflags <span class="since">(Since
0.9.13)</span></td>
- <td>IPSETFLAGS</td>
- <td>flags for the IPSet; requires ipset attribute</td>
- </tr>
- </table>
- <p>
- <br/><br/>
- </p>
-
-
- <h5><a id="nwfelemsRulesProtoTCP-ipv6">TCP/UDP/SCTP over
IPV6</a></h5>
- <p>
- Protocol ID: <code>tcp-ipv6</code>, <code>udp-ipv6</code>,
<code>sctp-ipv6</code>
- <br/>
- Note: The chain parameter is ignored for this type of traffic
- and should either be omitted or set to <code>root</code>.
- </p>
- <table class="top_table">
- <tr>
- <th> Attribute </th>
- <th> Datatype </th>
- <th> Semantics </th>
- </tr>
- <tr>
- <td>srcmacaddr</td>
- <td>MAC_ADDR</td>
- <td>MAC address of sender</td>
- </tr>
- <tr>
- <td>srcipaddr</td>
- <td>IPV6_ADDR</td>
- <td>Source IP address</td>
- </tr>
- <tr>
- <td>srcipmask</td>
- <td>IPV6_MASK</td>
- <td>Mask applied to source IP address</td>
- </tr>
- <tr>
- <td>dstipaddr</td>
- <td>IPV6_ADDR</td>
- <td>Destination IP address</td>
- </tr>
- <tr>
- <td>dstipmask</td>
- <td>IPV6_MASK</td>
- <td>Mask applied to destination IP address</td>
- </tr>
-
- <tr>
- <td>srcipfrom</td>
- <td>IPV6_ADDR</td>
- <td>Start of range of source IP address</td>
- </tr>
- <tr>
- <td>srcipto</td>
- <td>IPV6_ADDR</td>
- <td>End of range of source IP address</td>
- </tr>
- <tr>
- <td>dstipfrom</td>
- <td>IPV6_ADDR</td>
- <td>Start of range of destination IP address</td>
- </tr>
- <tr>
- <td>dstipto</td>
- <td>IPV6_ADDR</td>
- <td>End of range of destination IP address</td>
- </tr>
-
- <tr>
- <td>srcportstart</td>
- <td>UINT16</td>
- <td>Start of range of valid source ports</td>
- </tr>
- <tr>
- <td>srcportend</td>
- <td>UINT16</td>
- <td>End of range of valid source ports</td>
- </tr>
- <tr>
- <td>dstportstart</td>
- <td>UINT16</td>
- <td>Start of range of valid destination ports</td>
- </tr>
- <tr>
- <td>dstportend</td>
- <td>UINT16</td>
- <td>End of range of valid destination ports</td>
- </tr>
- <tr>
- <td>dscp</td>
- <td>UINT8 (0x0-0x3f, 0 - 63)</td>
- <td>Differentiated Services Code Point</td>
- </tr>
- <tr>
- <td>comment <span class="since">(Since
0.8.5)</span></td>
- <td>STRING</td>
- <td>text with max. 256 characters</td>
- </tr>
- <tr>
- <td>state <span class="since">(Since
0.8.5)</span></td>
- <td>STRING</td>
- <td>comma separated list of NEW,ESTABLISHED,RELATED,INVALID or
NONE</td>
- </tr>
- <tr>
- <td>flags <span class="since">(Since
0.9.1)</span></td>
- <td>STRING</td>
- <td>TCP-only: format of mask/flags with mask and flags each being a comma
separated list of SYN,ACK,URG,PSH,FIN,RST or NONE or ALL</td>
- </tr>
- <tr>
- <td>ipset <span class="since">(Since
0.9.13)</span></td>
- <td>STRING</td>
- <td>The name of an IPSet managed outside of libvirt</td>
- </tr>
- <tr>
- <td>ipsetflags <span class="since">(Since
0.9.13)</span></td>
- <td>IPSETFLAGS</td>
- <td>flags for the IPSet; requires ipset attribute</td>
- </tr>
- </table>
- <p>
- <br/><br/>
- </p>
-
-
- <h5><a
id="nwfelemsRulesProtoICMPv6">ICMPv6</a></h5>
- <p>
- Protocol ID: <code>icmpv6</code>
- <br/>
- Note: The chain parameter is ignored for this type of traffic
- and should either be omitted or set to <code>root</code>.
- </p>
- <table class="top_table">
- <tr>
- <th> Attribute </th>
- <th> Datatype </th>
- <th> Semantics </th>
- </tr>
- <tr>
- <td>srcmacaddr</td>
- <td>MAC_ADDR</td>
- <td>MAC address of sender</td>
- </tr>
- <tr>
- <td>srcipaddr</td>
- <td>IPV6_ADDR</td>
- <td>Source IPv6 address</td>
- </tr>
- <tr>
- <td>srcipmask</td>
- <td>IPV6_MASK</td>
- <td>Mask applied to source IPv6 address</td>
- </tr>
- <tr>
- <td>dstipaddr</td>
- <td>IPV6_ADDR</td>
- <td>Destination IPv6 address</td>
- </tr>
- <tr>
- <td>dstipmask</td>
- <td>IPV6_MASK</td>
- <td>Mask applied to destination IPv6 address</td>
- </tr>
-
- <tr>
- <td>srcipfrom</td>
- <td>IPV6_ADDR</td>
- <td>Start of range of source IP address</td>
- </tr>
- <tr>
- <td>srcipto</td>
- <td>IPV6_ADDR</td>
- <td>End of range of source IP address</td>
- </tr>
- <tr>
- <td>dstipfrom</td>
- <td>IPV6_ADDR</td>
- <td>Start of range of destination IP address</td>
- </tr>
- <tr>
- <td>dstipto</td>
- <td>IPV6_ADDR</td>
- <td>End of range of destination IP address</td>
- </tr>
-
- <tr>
- <td>type</td>
- <td>UINT16</td>
- <td>ICMPv6 type</td>
- </tr>
- <tr>
- <td>code</td>
- <td>UINT16</td>
- <td>ICMPv6 code</td>
- </tr>
- <tr>
- <td>dscp</td>
- <td>UINT8 (0x0-0x3f, 0 - 63)</td>
- <td>Differentiated Services Code Point</td>
- </tr>
- <tr>
- <td>comment <span class="since">(Since
0.8.5)</span></td>
- <td>STRING</td>
- <td>text with max. 256 characters</td>
- </tr>
- <tr>
- <td>state <span class="since">(Since
0.8.5)</span></td>
- <td>STRING</td>
- <td>comma separated list of NEW,ESTABLISHED,RELATED,INVALID or
NONE</td>
- </tr>
- <tr>
- <td>ipset <span class="since">(Since
0.9.13)</span></td>
- <td>STRING</td>
- <td>The name of an IPSet managed outside of libvirt</td>
- </tr>
- <tr>
- <td>ipsetflags <span class="since">(Since
0.9.13)</span></td>
- <td>IPSETFLAGS</td>
- <td>flags for the IPSet; requires ipset attribute</td>
- </tr>
- </table>
- <p>
- <br/><br/>
- </p>
-
- <h5><a id="nwfelemsRulesProtoMiscv6">ESP, AH, UDPLITE,
'ALL' over IPv6</a></h5>
- <p>
- Protocol ID: <code>esp-ipv6</code>, <code>ah-ipv6</code>,
<code>udplite-ipv6</code>, <code>all-ipv6</code>
- <br/>
- Note: The chain parameter is ignored for this type of traffic
- and should either be omitted or set to <code>root</code>.
- </p>
- <table class="top_table">
- <tr>
- <th> Attribute </th>
- <th> Datatype </th>
- <th> Semantics </th>
- </tr>
- <tr>
- <td>srcmacaddr</td>
- <td>MAC_ADDR</td>
- <td>MAC address of sender</td>
- </tr>
- <tr>
- <td>srcipaddr</td>
- <td>IPV6_ADDR</td>
- <td>Source IPv6 address</td>
- </tr>
- <tr>
- <td>srcipmask</td>
- <td>IPV6_MASK</td>
- <td>Mask applied to source IPv6 address</td>
- </tr>
- <tr>
- <td>dstipaddr</td>
- <td>IPV6_ADDR</td>
- <td>Destination IPv6 address</td>
- </tr>
- <tr>
- <td>dstipmask</td>
- <td>IPV6_MASK</td>
- <td>Mask applied to destination IPv6 address</td>
- </tr>
-
- <tr>
- <td>srcipfrom</td>
- <td>IPV6_ADDR</td>
- <td>Start of range of source IP address</td>
- </tr>
- <tr>
- <td>srcipto</td>
- <td>IPV6_ADDR</td>
- <td>End of range of source IP address</td>
- </tr>
- <tr>
- <td>dstipfrom</td>
- <td>IPV6_ADDR</td>
- <td>Start of range of destination IP address</td>
- </tr>
- <tr>
- <td>dstipto</td>
- <td>IPV6_ADDR</td>
- <td>End of range of destination IP address</td>
- </tr>
- <tr>
- <td>dscp</td>
- <td>UINT8 (0x0-0x3f, 0 - 63)</td>
- <td>Differentiated Services Code Point</td>
- </tr>
- <tr>
- <td>comment <span class="since">(Since
0.8.5)</span></td>
- <td>STRING</td>
- <td>text with max. 256 characters</td>
- </tr>
- <tr>
- <td>state <span class="since">(Since
0.8.5)</span></td>
- <td>STRING</td>
- <td>comma separated list of NEW,ESTABLISHED,RELATED,INVALID or
NONE</td>
- </tr>
- <tr>
- <td>ipset <span class="since">(Since
0.9.13)</span></td>
- <td>STRING</td>
- <td>The name of an IPSet managed outside of libvirt</td>
- </tr>
- <tr>
- <td>ipsetflags <span class="since">(Since
0.9.13)</span></td>
- <td>IPSETFLAGS</td>
- <td>flags for the IPSet; requires ipset attribute</td>
- </tr>
- </table>
- <p>
- <br/><br/>
- </p>
-
- <h3><a id="nwfelemsRulesAdv">Advanced Filter Configuration
Topics</a></h3>
- <p>
- The following sections discuss advanced filter configuration
- topics.
- </p>
-
- <h4><a id="nwfelemsRulesAdvTracking">Connection
tracking</a></h4>
- <p>
- The network filtering subsystem (on Linux) makes use of the connection
- tracking support of iptables. This helps in enforcing the
- directionality of network traffic (state match) as well as
- counting and limiting the number of simultaneous connections towards
- a VM. As an example, if a VM has TCP port 8080
- open as a server, clients may connect to the VM on port 8080.
- Connection tracking and enforcement of directionality then prevents
- the VM from initiating a connection from
- (TCP client) port 8080 to the host back to a remote host.
- More importantly, tracking helps to prevent
- remote attackers from establishing a connection back to a VM. For example,
- if the user inside the VM established a connection to
- port 80 on an attacker site, then the attacker will not be able to
- initiate a connection from TCP port 80 back towards the VM.
- By default the connection state match that enables connection tracking
- and then enforcement of directionality of traffic is turned on. <br/>
- The following shows an example XML fragment where this feature has been
- turned off for incoming connections to TCP port 12345.
- </p>
-<pre>
-[...]
-<rule direction='in' action='accept'
statematch='false'>
- <tcp dstportstart='12345'/>
-</rule>
-[...]
-</pre>
- <p>
- This now allows incoming traffic to TCP port 12345, but would also
- enable the initiation from (client) TCP port 12345 within the VM,
- which may or may not be desirable.
- </p>
-
- <h4><a id="nwfelemsRulesAdvLimiting">Limiting Number of
Connections</a></h4>
- <p>
- To limit the number of connections a VM may establish, a rule must
- be provided that sets a limit of connections for a given
- type of traffic. If for example a VM
- is supposed to be allowed to only ping one other IP address at a time
- and is supposed to have only one active incoming ssh connection at a
- time, the following XML fragment can be used to achieve this.
- </p>
-<pre>
-[...]
-<rule action='drop' direction='in' priority='400'>
- <tcp connlimit-above='1'/>
-</rule>
-<rule action='accept' direction='in'
priority='500'>
- <tcp dstportstart='22'/>
-</rule>
-<rule action='drop' direction='out'
priority='400'>
- <icmp connlimit-above='1'/>
-</rule>
-<rule action='accept' direction='out'
priority='500'>
- <icmp/>
-</rule>
-<rule action='accept' direction='out'
priority='500'>
- <udp dstportstart='53'/>
-</rule>
-<rule action='drop' direction='inout'
priority='1000'>
- <all/>
-</rule>
-[...]
-</pre>
- <p>
- Note that the rule for the limit has to logically appear
- before the rule for accepting the traffic.<br/>
- An additional rule for letting DNS traffic to port 22
- go out the VM has been added to avoid ssh sessions not
- getting established for reasons related to DNS lookup failures
- by the ssh daemon. Leaving this rule out may otherwise lead to
- fun-filled debugging joy (symptom: ssh client seems to hang
- while trying to connect).
- <br/><br/>
- Lot of care must be taken with timeouts related
- to tracking of traffic. An ICMP ping that
- the user may have terminated inside the VM may have a long
- timeout in the host's connection tracking system and therefore
- not allow another ICMP ping to go through for a while. Therefore,
- the timeouts have to be tuned in the host's sysfs, i.e.,
- </p>
-
-<pre>
-echo 3 > /proc/sys/net/netfilter/nf_conntrack_icmp_timeout
-</pre>
- <p>
- sets the ICMP connection tracking timeout to 3 seconds. The
- effect of this is that once one ping is terminated, another
- one can start after 3 seconds.<br/>
- Further, we want to point out that a client that for whatever
- reason has not properly closed a TCP connection may cause a
- connection to be held open for a longer period of time,
- depending to what timeout the <code>TCP established</code> state
- timeout has been set to on the host. Also, idle connections may time
- out in the connection tracking system but can be reactivated once
- packets are exchanged. However, a newly initiated connection may force
- an idle connection into TCP backoff if the number of allowed connections
- is set to a too low limit, the new connection is established
- and hits (not exceeds) the limit of allowed connections and for
- example a key is pressed on the old ssh session, which now has become
- unresponsive due to its traffic being dropped.
- Therefore, the limit of connections should be rather high so that
- fluctuations in new TCP connections don't cause odd
- traffic behavior in relation to idle connections.
- </p>
-
- <h2><a id="nwfcli">Command line tools</a></h2>
- <p>
- The libvirt command line tool <code>virsh</code> has been extended
- with life-cycle support for network filters. All commands related
- to the network filtering subsystem start with the prefix
- <code>nwfilter</code>. The following commands are available:
- </p>
- <ul>
- <li>nwfilter-list : list UUIDs and names of all network filters</li>
- <li>nwfilter-define : define a new network filter or update an existing
one</li>
- <li>nwfilter-undefine : delete a network filter given its name; it must not be
currently in use</li>
- <li>nwfilter-dumpxml : display a network filter given its name</li>
- <li>nwfilter-edit : edit a network filter given its name</li>
- </ul>
-
- <h2><a id="nwfexamples">Pre-existing network
filters</a></h2>
- <p>
- The following is a list of example network filters that are
- automatically installed with libvirt.</p>
- <table class="top_table">
- <tr>
- <th> Name </th>
- <th> Description </th>
- </tr>
- <tr>
- <td> no-arp-spoofing </td>
- <td> Prevent a VM from spoofing ARP traffic; this filter
- only allows ARP request and reply messages and enforces
- that those packets contain the MAC and IP addresses
- of the VM.</td>
- </tr>
- <tr>
- <td> allow-arp </td>
- <td> Allow ARP traffic in both directions</td>
- </tr>
- <tr>
- <td> allow-ipv4 </td>
- <td> Allow IPv4 traffic in both directions</td>
- </tr>
- <tr>
- <td> allow-ipv6 </td>
- <td> Allow IPv6 traffic in both directions</td>
- </tr>
- <tr>
- <td> allow-incoming-ipv4 </td>
- <td> Allow incoming IPv4 traffic</td>
- </tr>
- <tr>
- <td> allow-incoming-ipv6 </td>
- <td> Allow incoming IPv6 traffic</td>
- </tr>
- <tr>
- <td> allow-dhcp </td>
- <td> Allow a VM to request an IP address via DHCP (from any
- DHCP server)</td>
- </tr>
- <tr>
- <td> allow-dhcpv6 </td>
- <td> Similar to allow-dhcp, but for DHCPv6 </td>
- </tr>
- <tr>
- <td> allow-dhcp-server </td>
- <td> Allow a VM to request an IP address from a specified
- DHCP server. The dotted decimal IP address of the DHCP
- server must be provided in a reference to this filter.
- The name of the variable must be <i>DHCPSERVER</i>.</td>
- </tr>
- <tr>
- <td> allow-dhcpv6-server </td>
- <td> Similar to allow-dhcp-server, but for DHCPv6 </td>
- </tr>
- <tr>
- <td> no-ip-spoofing </td>
- <td> Prevent a VM from sending of IPv4 packets with
- a source IP address different from the one
- in the packet. </td>
- </tr>
- <tr>
- <td> no-ipv6-spoofing </td>
- <td> Similar to no-ip-spoofing, but for IPv6 </td>
- </tr>
- <tr>
- <td> no-ip-multicast </td>
- <td> Prevent a VM from sending IP multicast packets. </td>
- </tr>
- <tr>
- <td> no-ipv6-multicast </td>
- <td> Similar to no-ip-multicast, but for IPv6 </td>
- </tr>
- <tr>
- <td> clean-traffic </td>
- <td> Prevent MAC, IP and ARP spoofing. This filter references
- several other filters as building blocks. </td>
- </tr>
- </table>
- <p>
- Note that most of the above filters are only building blocks and
- require a combination with other filters to provide useful network
- traffic filtering.
- The most useful one in the above list is the <i>clean-traffic</i>
- filter. This filter itself can for example be combined with the
- <i>no-ip-multicast</i>
- filter to prevent virtual machines from sending IP multicast traffic
- on top of the prevention of packet spoofing.
- </p>
-
- <h2><a id="nwfwrite">Writing your own
filters</a></h2>
-
- <p>
- Since libvirt only provides a couple of example networking filters, you
- may consider writing your own. When planning on doing so
- there are a couple of things
- you may need to know regarding the network filtering subsystem and how
- it works internally. Certainly you also have to know and understand
- the protocols very well that you want to be filtering on so that
- no further traffic than what you want can pass and that in fact the
- traffic you want to allow does pass.
- <br/><br/>
- The network filtering subsystem is currently only available on
- Linux hosts and only works for QEMU and KVM type of virtual machines.
- On Linux
- it builds upon the support for <code>ebtables</code>,
<code>iptables
- </code> and <code>ip6tables</code> and makes use of their
features.
- From the above list of supported protocols the following ones are
- implemented using <code>ebtables</code>:
- </p>
- <ul>
- <li>mac</li>
- <li>stp (spanning tree protocol)</li>
- <li>vlan (802.1Q)</li>
- <li>arp, rarp</li>
- <li>ipv4</li>
- <li>ipv6</li>
- </ul>
-
- <p>
- All other protocols over IPv4 are supported using iptables, those over
- IPv6 are implemented using ip6tables.
- <br/><br/>
- On a Linux host, all traffic filtering instantiated by libvirt's network
- filter subsystem first passes through the filtering support implemented
- by ebtables and only then through iptables or ip6tables filters. If
- a filter tree has rules with the protocols <code>mac</code>,
- <code>stp</code>, <code>vlan</code>
- <code>arp</code>, <code>rarp</code>,
<code>ipv4</code>,
- or <code>ipv6</code> ebtables rules will automatically be instantiated.
- <br/>
- The role of the <code>chain</code> attribute in the network filter
- XML is that internally a new user-defined ebtables table is created
- that then for example receives all <code>arp</code> traffic coming
- from or going to a virtual machine if the chain <code>arp</code>
- has been specified. Further, a rule is generated in an interface's
- <code>root</code> chain that directs all ipv4 traffic into the
- user-defined chain. Therefore, all ARP traffic rules should then be
- placed into filters specifying this chain. This type of branching
- into user-defined tables is only supported with filtering on the ebtables
- layer.
- <br/>
- <span class="since">Since 0.9.8</span> multiple chains for the
same
- protocol can be created. For this the name of the chain must have
- a prefix of one of the previously enumerated protocols. To create an
- additional chain for handling of ARP traffic, a chain with name
- <code>arp-test</code> can be specified.
- <br/>
- As an example, it is
- possible to filter on UDP traffic by source and destination ports using
- the <code>ip</code> protocol filter and specifying attributes for the
- protocol, source and destination IP addresses and ports of UDP packets
- that are to be accepted. This allows
- early filtering of UDP traffic with ebtables. However, once an IP or IPv6
- packet, such as a UDP packet,
- has passed the ebtables layer and there is at least one rule in a filter
- tree that instantiates iptables or ip6tables rules, a rule to let
- the UDP packet pass will also be necessary to be provided for those
- filtering layers. This can be
- achieved with a rule containing an appropriate <code>udp</code> or
- <code>udp-ipv6</code> traffic filtering node.
- </p>
-
- <h3><a id="nwfwriteexample">Example custom
filter</a></h3>
- <p>
- As an example we want to now build a filter that fulfills the following
- list of requirements:
- </p>
- <ul>
- <li>prevents a VM's interface from MAC, IP and ARP spoofing</li>
- <li>opens only TCP ports 22 and 80 of a VM's interface</li>
- <li>allows the VM to send ping traffic from an interface
- but not let the VM be pinged on the interface</li>
- <li>allows the VM to do DNS lookups (UDP towards port 53)</li>
- </ul>
- <p>
- The requirement to prevent spoofing is fulfilled by the existing
- <code>clean-traffic</code> network filter, thus we will reference this
- filter from our custom filter.
- <br/>
- To enable traffic for TCP ports 22 and 80 we will add 2 rules to
- enable this type of traffic. To allow the VM to send ping traffic
- we will add a rule for ICMP traffic. For simplicity reasons
- we allow general ICMP traffic to be initiated from the VM, not
- just ICMP echo request and response messages. To then
- disallow all other traffic to reach or be initiated by the
- VM we will then need to add a rule that drops all other traffic.
- Assuming our VM is called <i>test</i> and
- the interface we want to associate our filter with is called
<i>eth0</i>,
- we name our filter <i>test-eth0</i>.
- The result of these considerations is the following network filter XML:
- </p>
-<pre>
-<filter name='test-eth0'>
- <!-- reference the clean traffic filter to prevent
- MAC, IP and ARP spoofing. By not providing
- and IP address parameter, libvirt will detect the
- IP address the VM is using. -->
- <filterref filter='clean-traffic'/>
-
- <!-- enable TCP ports 22 (ssh) and 80 (http) to be reachable -->
- <rule action='accept' direction='in'>
- <tcp dstportstart='22'/>
- </rule>
-
- <rule action='accept' direction='in'>
- <tcp dstportstart='80'/>
- </rule>
-
- <!-- enable general ICMP traffic to be initiated by the VM;
- this includes ping traffic -->
- <rule action='accept' direction='out'>
- <icmp/>
- </rule>
-
- <!-- enable outgoing DNS lookups using UDP -->
- <rule action='accept' direction='out'>
- <udp dstportstart='53'/>
- </rule>
-
- <!-- drop all other traffic -->
- <rule action='drop' direction='inout'>
- <all/>
- </rule>
-
-</filter>
-</pre>
- <p>
- Note that none of the rules in the above XML contain the
- IP address of the VM as either source or destination address, yet
- the filtering of the traffic works correctly. The reason is that
- the evaluation of the rules internally happens on a
- per-interface basis and the rules are evaluated based on the knowledge
- about which (tap) interface has sent or will receive the packet rather
- than what their source or destination IP address may be.
- <br/><br/>
- An XML fragment for a possible network interface description inside
- the domain XML of the <code>test</code> VM could then look like this:
- </p>
-<pre>
-[...]
-<interface type='bridge'>
- <source bridge='mybridge'/>
- <filterref filter='test-eth0'/>
-</interface>
-[...]
-</pre>
-
- <p>
- To more strictly control the ICMP traffic and enforce that only
- ICMP echo requests can be sent from the VM
- and only ICMP echo responses be received by the VM, the above
- <code>ICMP</code> rule can be replaced with the following two rules:
- </p>
-<pre>
-<!-- enable outgoing ICMP echo requests-->
-<rule action='accept' direction='out'>
- <icmp type='8'/>
-</rule>
-
-<!-- enable incoming ICMP echo replies-->
-<rule action='accept' direction='in'>
- <icmp type='0'/>
-</rule>
-</pre>
-
- <h3><a id="nwfwriteexample2nd">Second example custom
filter</a></h3>
- <p>
- In this example we now want to build a similar filter as in the
- example above, but extend the list of requirements with an
- ftp server located inside the VM. Further, we will be using features
- that have been added in <span class="since">version
0.8.5</span>.
- The requirements for this filter are:
- </p>
- <ul>
- <li>prevents a VM's interface from MAC, IP and ARP spoofing</li>
- <li>opens only TCP ports 22 and 80 of a VM's interface</li>
- <li>allows the VM to send ping traffic from an interface
- but not let the VM be pinged on the interface</li>
- <li>allows the VM to do DNS lookups (UDP towards port 53)</li>
- <li>enable an ftp server (in active mode) to be run inside the VM</li>
- </ul>
- <p>
- The additional requirement of allowing an ftp server to be run inside
- the VM maps into the requirement of allowing port 21 to be reachable
- for ftp control traffic as well as enabling the VM to establish an
- outgoing tcp connection originating from the VM's TCP port 20 back to
- the ftp client (ftp active mode). There are several ways of how this
- filter can be written and we present 2 solutions.
- <br/><br/>
- The 1st solution makes use of the <code>state</code> attribute of
- the TCP protocol that gives us a hook into the connection tracking
- framework of the Linux host. For the VM-initiated ftp data connection
- (ftp active mode) we use the <code>RELATED</code> state that allows
- us to detect that the VM-initiated ftp data connection is a consequence of
- ( or 'has a relationship with' ) an existing ftp control connection,
- thus we want to allow it to let packets
- pass the firewall. The <code>RELATED</code> state, however, is only
- valid for the very first packet of the outgoing TCP connection for the
- ftp data path. Afterwards, the state to compare against is
- <code>ESTABLISHED</code>, which then applies equally
- to the incoming and outgoing direction. All this is related to the ftp
- data traffic originating from TCP port 20 of the VM. This then leads to
- the following solution
- <span class="since">(since 0.8.5 (QEMU, KVM))</span>:
- </p>
-<pre>
-<filter name='test-eth0'>
- <!-- reference the clean traffic filter to prevent
- MAC, IP and ARP spoofing. By not providing
- and IP address parameter, libvirt will detect the
- IP address the VM is using. -->
- <filterref filter='clean-traffic'/>
-
- <!-- enable TCP port 21 (ftp-control) to be reachable -->
- <rule action='accept' direction='in'>
- <tcp dstportstart='21'/>
- </rule>
-
- <!-- enable TCP port 20 for VM-initiated ftp data connection
- related to an existing ftp control connection -->
- <rule action='accept' direction='out'>
- <tcp srcportstart='20' state='RELATED,ESTABLISHED'/>
- </rule>
-
- <!-- accept all packets from client on the ftp data connection -->
- <rule action='accept' direction='in'>
- <tcp dstportstart='20' state='ESTABLISHED'/>
- </rule>
-
- <!-- enable TCP ports 22 (ssh) and 80 (http) to be reachable -->
- <rule action='accept' direction='in'>
- <tcp dstportstart='22'/>
- </rule>
-
- <rule action='accept' direction='in'>
- <tcp dstportstart='80'/>
- </rule>
-
- <!-- enable general ICMP traffic to be initiated by the VM;
- this includes ping traffic -->
- <rule action='accept' direction='out'>
- <icmp/>
- </rule>
-
- <!-- enable outgoing DNS lookups using UDP -->
- <rule action='accept' direction='out'>
- <udp dstportstart='53'/>
- </rule>
-
- <!-- drop all other traffic -->
- <rule action='drop' direction='inout'>
- <all/>
- </rule>
-
-</filter>
-</pre>
- <p>
- Before trying out a filter using the <code>RELATED</code> state,
- you have to make sure that the appropriate connection tracking module
- has been loaded into the host's kernel. Depending on the version of the
- kernel, you must run either one of the following two commands before
- the ftp connection with the VM is established.
- </p>
-<pre>
-modprobe nf_conntrack_ftp # where available or
-
-modprobe ip_conntrack_ftp # if above is not available
-</pre>
- <p>
- If other protocols than ftp are to be used in conjunction with the
- <code>RELATED</code> state, their corresponding module must be loaded.
- Modules exist at least for the protocols ftp, tftp, irc, sip,
- sctp, and amanda.
- </p>
- <p>
- The 2nd solution makes uses the state flags of connections more
- than the previous solution did.
- In this solution we take advantage of the fact that the
- <code>NEW</code> state of a connection is valid when the very
- first packet of a traffic flow is seen. Subsequently, if the very first
- packet of a flow is accepted, the flow becomes a connection and enters
- the <code>ESTABLISHED</code> state. This allows us to write a general
- rule for allowing packets of <code>ESTABLISHED</code> connections to
- reach the VM or be sent by the VM.
- We write specific rules for the very first packets identified by the
- <code>NEW</code> state and for which ports they are acceptable. All
- packets for ports that are not explicitly accepted will be dropped and
- therefore the connection will not go into the <code>ESTABLISHED</code>
- state and any subsequent packets be dropped.
- </p>
-
-<pre>
-<filter name='test-eth0'>
- <!-- reference the clean traffic filter to prevent
- MAC, IP and ARP spoofing. By not providing
- and IP address parameter, libvirt will detect the
- IP address the VM is using. -->
- <filterref filter='clean-traffic'/>
-
- <!-- let the packets of all previously accepted connections reach the VM
-->
- <rule action='accept' direction='in'>
- <all state='ESTABLISHED'/>
- </rule>
-
- <!-- let the packets of all previously accepted and related connections be sent
from the VM -->
- <rule action='accept' direction='out'>
- <all state='ESTABLISHED,RELATED'/>
- </rule>
-
- <!-- enable traffic towards port 21 (ftp), 22 (ssh) and 80 (http) -->
- <rule action='accept' direction='in'>
- <tcp dstportstart='21' dstportend='22'
state='NEW'/>
- </rule>
-
- <rule action='accept' direction='in'>
- <tcp dstportstart='80' state='NEW'/>
- </rule>
-
- <!-- enable general ICMP traffic to be initiated by the VM;
- this includes ping traffic -->
- <rule action='accept' direction='out'>
- <icmp state='NEW'/>
- </rule>
-
- <!-- enable outgoing DNS lookups using UDP -->
- <rule action='accept' direction='out'>
- <udp dstportstart='53' state='NEW'/>
- </rule>
-
- <!-- drop all other traffic -->
- <rule action='drop' direction='inout'>
- <all/>
- </rule>
-
-</filter>
-
-</pre>
-
- <h2><a id="nwflimits">Limitations</a></h2>
- <p>
- The following sections list (current) limitations of the network
- filtering subsystem.
- </p>
-
- <h3><a id="nwflimitsmigr">VM Migration</a></h3>
- <p>
- VM migration is only supported if the whole filter tree
- that is referenced by a virtual machine's top level filter
- is also available on the target host. The network filter
- <i>clean-traffic</i>
- for example should be available on all libvirt installations
- of version 0.8.1 or later and thus enable migration of VMs that
- for example reference this filter. All other
- custom filters must be migrated using higher layer software. It is
- outside the scope of libvirt to ensure that referenced filters
- on the source system are equivalent to those on the target system
- and vice versa.
- <br/><br/>
- Migration must occur between libvirt installations of version
- 0.8.1 or later in order not to lose the network traffic filters
- associated with an interface.
- </p>
- <h3><a id="nwflimitsvlan">VLAN filtering on
Linux</a></h3>
- <p>
- VLAN (802.1Q) packets, if sent by a virtual machine, cannot be filtered
- with rules for protocol IDs <code>arp</code>,
<code>rarp</code>,
- <code>ipv4</code> and <code>ipv6</code> but only
- with protocol IDs <code>mac</code> and <code>vlan</code>.
Therefore,
- the example filter <code>clean-traffic</code> will not work as
expected.
- </p>
- </body>
-</html>
diff --git a/docs/formatnwfilter.rst b/docs/formatnwfilter.rst
new file mode 100644
index 0000000000..434da5b1fd
--- /dev/null
+++ b/docs/formatnwfilter.rst
@@ -0,0 +1,1789 @@
+.. role:: since
+
+===============
+Network Filters
+===============
+
+.. contents::
+
+This page provides an introduction to libvirt's network filters, their goals,
+concepts and XML format.
+
+Goals and background
+--------------------
+
+The goal of the network filtering XML is to enable administrators of a
+virtualized system to configure and enforce network traffic filtering rules on
+virtual machines and manage the parameters of network traffic that virtual
+machines are allowed to send or receive. The network traffic filtering rules are
+applied on the host when a virtual machine is started. Since the filtering rules
+cannot be circumvented from within the virtual machine, it makes them mandatory
+from the point of view of a virtual machine user.
+
+The network filter subsystem allows each virtual machine's network traffic
+filtering rules to be configured individually on a per interface basis. The
+rules are applied on the host when the virtual machine is started and can be
+modified while the virtual machine is running. The latter can be achieved by
+modifying the XML description of a network filter.
+
+Multiple virtual machines can make use of the same generic network filter. When
+such a filter is modified, the network traffic filtering rules of all running
+virtual machines that reference this filter are updated.
+
+Network filtering support is available :since:`since 0.8.1 (QEMU, KVM)`
+
+Concepts
+--------
+
+The network traffic filtering subsystem enables configuration of network traffic
+filtering rules on individual network interfaces that are configured for certain
+types of network configurations. Supported network types are
+
+- ``network``
+
+- ``ethernet`` -- must be used in bridging mode
+
+- ``bridge``
+
+The interface XML is used to reference a top-level filter. In the following
+example, the interface description references the filter ``clean-traffic``.
+
+::
+
+ ...
+ <devices>
+ <interface type='bridge'>
+ <mac address='00:16:3e:5d:c7:9e'/>
+ <filterref filter='clean-traffic'/>
+ </interface>
+ </devices>
+ ...
+
+Network filters are written in XML and may either contain references to other
+filters, contain rules for traffic filtering, or hold a combination of both. The
+above referenced filter ``clean-traffic`` is a filter that only contains
+references to other filters and no actual filtering rules. Since references to
+other filters can be used, a *tree* of filters can be built. The
+``clean-traffic`` filter can be viewed using the command
+``virsh nwfilter-dumpxml clean-traffic``.
+
+As previously mentioned, a single network filter can be referenced by multiple
+virtual machines. Since interfaces will typically have individual parameters
+associated with their respective traffic filtering rules, the rules described in
+a filter XML can be parameterized with variables. In this case, the variable
+name is used in the filter XML and the name and value are provided at the place
+where the filter is referenced. In the following example, the interface
+description has been extended with the parameter ``IP`` and a dotted IP address
+as value.
+
+::
+
+ ...
+ <devices>
+ <interface type='bridge'>
+ <mac address='00:16:3e:5d:c7:9e'/>
+ <filterref filter='clean-traffic'>
+ <parameter name='IP' value='10.0.0.1'/>
+ </filterref>
+ </interface>
+ </devices>
+ ...
+
+In this particular example, the ``clean-traffic`` network traffic filter will be
+instantiated with the IP address parameter 10.0.0.1 and enforce that the traffic
+from this interface will always be using 10.0.0.1 as the source IP address,
+which is one of the purposes of this particular filter.
+
+Filtering chains
+~~~~~~~~~~~~~~~~
+
+Filtering rules are organized in filter chains. These chains can be thought of
+as having a tree structure with packet filtering rules as entries in individual
+chains (branches).
+
+Packets start their filter evaluation in the ``root`` chain and can then
+continue their evaluation in other chains, return from those chains back into
+the ``root`` chain or be dropped or accepted by a filtering rule in one of the
+traversed chains.
+
+Libvirt's network filtering system automatically creates individual ``root``
+chains for every virtual machine's network interface on which the user chooses
+to activate traffic filtering. The user may write filtering rules that are
+either directly instantiated in the ``root`` chain or may create
+protocol-specific filtering chains for efficient evaluation of protocol-specific
+rules. The following chains exist:
+
+- root
+
+- mac :since:`(since 0.9.8)`
+
+- stp (spanning tree protocol) :since:`(since 0.9.8)`
+
+- vlan (802.1Q) :since:`(since 0.9.8)`
+
+- arp, rarp
+
+- ipv4
+
+- ipv6
+
+:since:`Since 0.9.8` multiple chains evaluating the ``mac``, ``stp``, ``vlan``,
+``arp``, ``rarp``, ``ipv4``, or ``ipv6`` protocol can be created using the
+protocol name only as a prefix in the chain's name. This for examples allows
+chains with names ``arp-xyz`` or ``arp-test`` to be specified and have ARP
+protocol packets evaluated in those chains.
+
+The following filter shows an example of filtering ARP traffic in the ``arp``
+chain.
+
+::
+
+ <filter name='no-arp-spoofing' chain='arp'
priority='-500'>
+ <uuid>f88f1932-debf-4aa1-9fbe-f10d3aa4bc95</uuid>
+ <rule action='drop' direction='out' priority='300'>
+ <mac match='no' srcmacaddr='$MAC'/>
+ </rule>
+ <rule action='drop' direction='out' priority='350'>
+ <arp match='no' arpsrcmacaddr='$MAC'/>
+ </rule>
+ <rule action='drop' direction='out' priority='400'>
+ <arp match='no' arpsrcipaddr='$IP'/>
+ </rule>
+ <rule action='drop' direction='in' priority='450'>
+ <arp opcode='Reply'/>
+ <arp match='no' arpdstmacaddr='$MAC'/>
+ </rule>
+ <rule action='drop' direction='in' priority='500'>
+ <arp match='no' arpdstipaddr='$IP'/>
+ </rule>
+ <rule action='accept' direction='inout'
priority='600'>
+ <arp opcode='Request'/>
+ </rule>
+ <rule action='accept' direction='inout'
priority='650'>
+ <arp opcode='Reply'/>
+ </rule>
+ <rule action='drop' direction='inout'
priority='1000'/>
+ </filter>
+
+The consequence of putting ARP-specific rules in the ``arp`` chain, rather than
+for example in the ``root`` chain, is that packets for any other protocol than
+ARP do not need to be evaluated by ARP protocol-specific rules. This improves
+the efficiency of the traffic filtering. However, one must then pay attention to
+only put filtering rules for the given protocol into the chain since any other
+rules will not be evaluated, i.e., an IPv4 rule will not be evaluated in the ARP
+chain since no IPv4 protocol packets will traverse the ARP chain.
+
+Filtering chain priorities
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All chains are connected to the ``root`` chain. The order in which those chains
+are accessed is influenced by the priority of the chain. The following table
+shows the chains that can be assigned a priority and their default priorities.
+
+============== ================
+Chain (prefix) Default priority
+============== ================
+stp -810
+mac -800
+vlan -750
+ipv4 -700
+ipv6 -600
+arp -500
+rarp -400
+============== ================
+
+A chain with a lower priority value is accessed before one with a higher value.
+
+:since:`Since 0.9.8` the above listed chains can be assigned custom priorities
+by writing a value in the range [-1000, 1000] into the priority (XML) attribute
+in the filter node. The above example filter shows the default priority of -500
+for ``arp`` chains.
+
+Usage of variables in filters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Two variables names have so far been reserved for usage by the network traffic
+filtering subsystem: ``MAC`` and ``IP``.
+
+``MAC`` is the MAC address of the network interface. A filtering rule that
+references this variable will automatically be instantiated with the MAC address
+of the interface. This works without the user having to explicitly provide the
+MAC parameter. Even though it is possible to specify the MAC parameter similar
+to the IP parameter above, it is discouraged since libvirt knows what MAC
+address an interface will be using.
+
+The parameter ``IP`` represents the IP address that the operating system inside
+the virtual machine is expected to use on the given interface. The ``IP``
+parameter is special in so far as the libvirt daemon will try to determine the
+IP address (and thus the IP parameter's value) that is being used on an
+interface if the parameter is not explicitly provided but referenced. For
+current limitations on IP address detection, consult the section on
+`Limitations`_ on how to use this feature and what to expect when using it.
+
+The above-shown network filer ``no-arp-spoofing`` is an example of a network
+filter XML referencing the ``MAC`` and ``IP`` variables.
+
+Note that referenced variables are always prefixed with the $ (dollar) sign. The
+format of the value of a variable must be of the type expected by the filter
+attribute in the XML. In the above example, the ``IP`` parameter must hold a
+dotted IP address in decimal numbers format. Failure to provide the correct
+value type will result in the filter not being instantiatable and will prevent a
+virtual machine from starting or the interface from attaching when hotplugging
+is used. The types that are expected for each XML attribute are shown below.
+
+:since:`Since 0.9.8` variables can contain lists of elements, e.g., the variable
+``IP`` can contain multiple IP addresses that are valid on a particular
+interface. The notation for providing multiple elements for the IP variable is:
+
+::
+
+ ...
+ <devices>
+ <interface type='bridge'>
+ <mac address='00:16:3e:5d:c7:9e'/>
+ <filterref filter='clean-traffic'>
+ <parameter name='IP' value='10.0.0.1'/>
+ <parameter name='IP' value='10.0.0.2'/>
+ <parameter name='IP' value='10.0.0.3'/>
+ </filterref>
+ </interface>
+ </devices>
+ ...
+
+This then allows filters to enable multiple IP addresses per interface.
+Therefore, with the list of IP address shown above, the following rule will
+create 3 individual filtering rules, one for each IP address.
+
+::
+
+ ...
+ <rule action='accept' direction='in' priority='500'>
+ <tcp srpipaddr='$IP'/>
+ </rule>
+ ...
+
+:since:`Since 0.9.10` it is possible to access individual elements of a variable
+holding a list of elements. A filtering rule like the following accesses the 2nd
+element of the variable DSTPORTS.
+
+::
+
+ ...
+ <rule action='accept' direction='in' priority='500'>
+ <udp dstportstart='$DSTPORTS[1]'/>
+ </rule>
+ ...
+
+:since:`Since 0.9.10` it is possible to create filtering rules that instantiate
+all combinations of rules from different lists using the notation of
+``$VARIABLE[@<iterator ID>]``. The following rule allows a virtual machine to
+receive traffic on a set of ports, which are specified in DSTPORTS, from the set
+of source IP address specified in SRCIPADDRESSES. The rule generates all
+combinations of elements of the variable DSTPORT with those of SRCIPADDRESSES by
+using two independent iterators to access their elements.
+
+::
+
+ ...
+ <rule action='accept' direction='in' priority='500'>
+ <ip srcipaddr='$SRCIPADDRESSES[@1]'
dstportstart='$DSTPORTS[@2]'/>
+ </rule>
+ ...
+
+In an example we assign concrete values to SRCIPADDRESSES and DSTPORTS
+
+::
+
+ SRCIPADDRESSES = [ 10.0.0.1, 11.1.2.3 ]
+ DSTPORTS = [ 80, 8080 ]
+
+Accessing the variables using $SRCIPADDRESSES[@1] and $DSTPORTS[@2] would then
+result in all combinations of addresses and ports being created:
+
+::
+
+ 10.0.0.1, 80
+ 10.0.0.1, 8080
+ 11.1.2.3, 80
+ 11.1.2.3, 8080
+
+Accessing the same variables using a single iterator, for example by using the
+notation $SRCIPADDRESSES[@1] and $DSTPORTS[@1], would result in parallel access
+to both lists and result in the following combinations:
+
+::
+
+ 10.0.0.1, 80
+ 11.1.2.3, 8080
+
+Further, the notation of $VARIABLE is short-hand for $VARIABLE[@0]. The former
+notation always assumes the iterator with Id '0'.
+
+Automatic IP address detection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The detection of IP addresses used on a virtual machine's interface is
+automatically activated if the variable ``IP`` is referenced but no value has
+been assigned to it. :since:`Since 0.9.13` the variable ``CTRL_IP_LEARNING`` can
+be used to specify the IP address learning method to use. Valid values are
+``any``, ``dhcp``, or ``none``.
+
+The value ``any`` means that libvirt may use any packet to determine the address
+in use by a virtual machine, which is the default behavior if the variable
+``CTRL_IP_LEARNING`` is not set. This method will only detect a single IP
+address on an interface. Once a VM's IP address has been detected, its IP
+network traffic will be locked to that address, if for example IP address
+spoofing is prevented by one of its filters. In that case the user of the VM
+will not be able to change the IP address on the interface inside the VM, which
+would be considered IP address spoofing. When a VM is migrated to another host
+or resumed after a suspend operation, the first packet sent by the VM will again
+determine the IP address it can use on a particular interface.
+
+A value of ``dhcp`` specifies that libvirt should only honor DHCP
+server-assigned addresses with valid leases. This method supports the detection
+and usage of multiple IP address per interface. When a VM is resumed after a
+suspend operation, still valid IP address leases are applied to its filters.
+Otherwise the VM is expected to again use DHCP to obtain new IP addresses. The
+migration of a VM to another physical host requires that the VM again runs the
+DHCP protocol.
+
+Use of ``CTRL_IP_LEARNING=dhcp`` (DHCP snooping) provides additional
+anti-spoofing security, especially when combined with a filter allowing only
+trusted DHCP servers to assign addresses. To enable this, set the variable
+``DHCPSERVER`` to the IP address of a valid DHCP server and provide filters that
+use this variable to filter incoming DHCP responses.
+
+When DHCP snooping is enabled and the DHCP lease expires, the VM will no longer
+be able to use the IP address until it acquires a new, valid lease from a DHCP
+server. If the VM is migrated, it must get a new valid DHCP lease to use an IP
+address (e.g., by bringing the VM interface down and up again).
+
+Note that automatic DHCP detection listens to the DHCP traffic the VM exchanges
+with the DHCP server of the infrastructure. To avoid denial-of-service attacks
+on libvirt, the evaluation of those packets is rate-limited, meaning that a VM
+sending an excessive number of DHCP packets per second on an interface will not
+have all of those packets evaluated and thus filters may not get adapted. Normal
+DHCP client behavior is assumed to send a low number of DHCP packets per second.
+Further, it is important to setup appropriate filters on all VMs in the
+infrastructure to avoid them being able to send DHCP packets. Therefore VMs must
+either be prevented from sending UDP and TCP traffic from port 67 to port 68 or
+the ``DHCPSERVER`` variable should be used on all VMs to restrict DHCP server
+messages to only be allowed to originate from trusted DHCP servers. At the same
+time anti-spoofing prevention must be enabled on all VMs in the subnet.
+
+If ``CTRL_IP_LEARNING`` is set to ``none``, libvirt does not do IP address
+learning and referencing ``IP`` without assigning it an explicit value is an
+error.
+
+The following XML provides an example for the activation of IP address learning
+using the DHCP snooping method:
+
+::
+
+ <interface type='bridge'>
+ <source bridge='virbr0'/>
+ <filterref filter='clean-traffic'>
+ <parameter name='CTRL_IP_LEARNING' value='dhcp'/>
+ </filterref>
+ </interface>
+
+Reserved Variables
+~~~~~~~~~~~~~~~~~~
+
+The following table lists reserved variables in use by libvirt.
+
++------------------+----------------------------------------------------------+
+| Variable Name | Semantics |
++==================+==========================================================+
+| MAC | The MAC address of the interface |
++------------------+----------------------------------------------------------+
+| IP | The list of IP addresses in use by an interface |
++------------------+----------------------------------------------------------+
+| IPV6 | The list of IPV6 addresses in use by an interface |
++------------------+----------------------------------------------------------+
+| DHCPSERVER | The list of IP addresses of trusted DHCP servers |
++------------------+----------------------------------------------------------+
+| DHCPSERVERV6 | Not currently implemented: The list of IPv6 addresses of |
+| | trusted DHCP servers |
++------------------+----------------------------------------------------------+
+| CTRL_IP_LEARNING | The choice of the IP address detection mode |
++------------------+----------------------------------------------------------+
+
+Element and attribute overview
+------------------------------
+
+The root element required for all network filters is named ``filter`` with two
+possible attributes. The ``name`` attribute provides a unique name of the given
+filter. The ``chain`` attribute is optional but allows certain filters to be
+better organized for more efficient processing by the firewall subsystem of the
+underlying host. Currently the system only supports the chains
+``root, ipv4, ipv6, arp and rarp``.
+
+References to other filters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Any filter may hold references to other filters. Individual filters may be
+referenced multiple times in a filter tree but references between filters must
+not introduce loops (directed acyclic graph).
+
+The following shows the XML of the ``clean-traffic`` network filter referencing
+several other filters.
+
+::
+
+ <filter name='clean-traffic'>
+ <uuid>6ef53069-ba34-94a0-d33d-17751b9b8cb1</uuid>
+ <filterref filter='no-mac-spoofing'/>
+ <filterref filter='no-ip-spoofing'/>
+ <filterref filter='allow-incoming-ipv4'/>
+ <filterref filter='no-arp-spoofing'/>
+ <filterref filter='no-other-l2-traffic'/>
+ <filterref filter='qemu-announce-self'/>
+ </filter>
+
+To reference another filter, the XML node ``filterref`` needs to be provided
+inside a ``filter`` node. This node must have the attribute ``filter`` whose
+value contains the name of the filter to be referenced.
+
+New network filters can be defined at any time and may contain references to
+network filters that are not known to libvirt, yet. However, once a virtual
+machine is started or a network interface referencing a filter is to be
+hotplugged, all network filters in the filter tree must be available. Otherwise
+the virtual machine will not start or the network interface cannot be attached.
+
+Filter rules
+~~~~~~~~~~~~
+
+The following XML shows a simple example of a network traffic filter
+implementing a rule to drop traffic if the IP address (provided through the
+value of the variable IP) in an outgoing IP packet is not the expected one, thus
+preventing IP address spoofing by the VM.
+
+::
+
+ <filter name='no-ip-spoofing' chain='ipv4'>
+ <uuid>fce8ae33-e69e-83bf-262e-30786c1f8072</uuid>
+ <rule action='drop' direction='out' priority='500'>
+ <ip match='no' srcipaddr='$IP'/>
+ </rule>
+ </filter>
+
+A traffic filtering rule starts with the ``rule`` node. This node may contain up
+to three attributes
+
+- action -- mandatory; must either be ``drop`` (matching the rule silently
+ discards the packet with no further analysis), ``reject`` (matching the rule
+ generates an ICMP reject message with no further analysis) :since:`(since
+ 0.9.0)` , ``accept`` (matching the rule accepts the packet with no further
+ analysis), ``return`` (matching the rule passes this filter, but returns
+ control to the calling filter for further analysis) :since:`(since 0.9.7)` ,
+ or ``continue`` (matching the rule goes on to the next rule for further
+ analysis) :since:`(since 0.9.7)` .
+
+- direction -- mandatory; must either be ``in``, ``out`` or ``inout`` if the
+ rule is for incoming, outgoing or incoming-and-outgoing traffic
+
+- priority -- optional; the priority of the rule controls the order in which
+ the rule will be instantiated relative to other rules. Rules with lower value
+ will be instantiated before rules with higher values. Valid values are in the
+ range of 0 to 1000. :since:`Since 0.9.8` this has been extended to cover the
+ range of -1000 to 1000. If this attribute is not provided, priority 500 will
+ automatically be assigned.
+
+ Note that filtering rules in the ``root`` chain are sorted with filters
+ connected to the ``root`` chain following their priorities. This allows to
+ interleave filtering rules with access to filter chains. (See also section on
+ `Filtering chain priorities`_ .)
+
+- statematch -- optional; possible values are '0' or 'false' to turn
the
+ underlying connection state matching off; default is 'true'
+
+ Also read the section on `Advanced Filter Configuration Topics`_.
+
+The above example indicates that the traffic of type ``ip`` will be associated
+with the chain 'ipv4' and the rule will have priority 500. If for example
+another filter is referenced whose traffic of type ``ip`` is also associated
+with the chain 'ipv4' then that filter's rules will be ordered relative to
the
+priority 500 of the shown rule.
+
+A rule may contain a single rule for filtering of traffic. The above example
+shows that traffic of type ``ip`` is to be filtered.
+
+Supported protocols
+^^^^^^^^^^^^^^^^^^^
+
+The following sections enumerate the list of protocols that are supported by the
+network filtering subsystem. The type of traffic a rule is supposed to filter on
+is provided in the ``rule`` node as a nested node. Depending on the traffic type
+a rule is filtering, the attributes are different. The above example showed the
+single attribute ``srcipaddr`` that is valid inside the ``ip`` traffic filtering
+node. The following sections show what attributes are valid and what type of
+data they are expecting. The following datatypes are available:
+
+- UINT8 : 8 bit integer; range 0-255
+
+- UINT16: 16 bit integer; range 0-65535
+
+- MAC_ADDR: MAC address in dotted decimal format, i.e., 00:11:22:33:44:55
+
+- MAC_MASK: MAC address mask in MAC address format, i.e., FF:FF:FF:FC:00:00
+
+- IP_ADDR: IP address in dotted decimal format, i.e., 10.1.2.3
+
+- IP_MASK: IP address mask in either dotted decimal format (255.255.248.0) or
+ CIDR mask (0-32)
+
+- IPV6_ADDR: IPv6 address in numbers format, i.e., FFFF::1
+
+- IPV6_MASK: IPv6 mask in numbers format (FFFF:FFFF:FC00::) or CIDR mask
+ (0-128)
+
+- STRING: A string
+
+- BOOLEAN: 'true', 'yes', '1' or 'false', 'no',
'0'
+
+- IPSETFLAGS: The source and destination flags of the ipset described by up to
+ 6 'src' or 'dst' elements selecting features from either the source
or
+ destination part of the packet header; example: src,src,dst. The number of
+ 'selectors' to provide here depends on the type of ipset that is referenced.
+
+Every attribute except for those of type IP_MASK or IPV6_MASK can be negated
+using the ``match`` attribute with value ``no``. Multiple negated attributes may
+be grouped together. The following XML fragment shows such an example using
+abstract attributes.
+
+::
+
+ [...]
+ <rule action='drop' direction='in'>
+ <protocol match='no' attribute1='value1'
attribute2='value2'/>
+ <protocol attribute3='value3'/>
+ </rule>
+ [...]
+
+Rules perform a logical AND evaluation on all values of the given protocol
+attributes. Thus, if a single attribute's value does not match the one given in
+the rule, the whole rule will be skipped during evaluation. Therefore, in the
+above example incoming traffic will only be dropped if the protocol property
+attribute1 does not match value1 AND the protocol property attribute2 does not
+match value2 AND the protocol property attribute3 matches value3.
+
+MAC (Ethernet)
+''''''''''''''
+
+Protocol ID: ``mac``
+
+Note: Rules of this type should go into the ``root`` chain.
+
++-------------------------+-------------------------+-------------------------+
+| Attribute | Datatype | Semantics |
++=========================+=========================+=========================+
+| srcmacaddr | MAC_ADDR | MAC address of sender |
++-------------------------+-------------------------+-------------------------+
+| srcmacmask | MAC_MASK | Mask applied to MAC |
+| | | address of sender |
++-------------------------+-------------------------+-------------------------+
+| dstmacaddr | MAC_ADDR | MAC address of |
+| | | destination |
++-------------------------+-------------------------+-------------------------+
+| dstmacmask | MAC_MASK | Mask applied to MAC |
+| | | address of destination |
++-------------------------+-------------------------+-------------------------+
+| protocolid | UINT16 (0x600-0xffff), | Layer 3 protocol ID |
+| | STRING | |
++-------------------------+-------------------------+-------------------------+
+| comment :since:`(Since | STRING | text with max. 256 |
+| 0.8.5)` | | characters |
++-------------------------+-------------------------+-------------------------+
+
+Valid Strings for ``protocolid`` are: arp, rarp, ipv4, ipv6
+
+::
+
+ [...]
+ <mac match='no' srcmacaddr='$MAC'/>
+ [...]
+
+VLAN (802.1Q) :since:`(Since 0.9.8)`
+''''''''''''''''''''''''''''''''''''
+
+Protocol ID: ``vlan``
+
+Note: Rules of this type should go either into the ``root`` or ``vlan`` chain.
+
++----------------+-----------------------------+-----------------------------+
+| Attribute | Datatype | Semantics |
++================+=============================+=============================+
+| srcmacaddr | MAC_ADDR | MAC address of sender |
++----------------+-----------------------------+-----------------------------+
+| srcmacmask | MAC_MASK | Mask applied to MAC address |
+| | | of sender |
++----------------+-----------------------------+-----------------------------+
+| dstmacaddr | MAC_ADDR | MAC address of destination |
++----------------+-----------------------------+-----------------------------+
+| dstmacmask | MAC_MASK | Mask applied to MAC address |
+| | | of destination |
++----------------+-----------------------------+-----------------------------+
+| vlanid | UINT16 (0x0-0xfff, 0 - | VLAN ID |
+| | 4095) | |
++----------------+-----------------------------+-----------------------------+
+| encap-protocol | UINT16 (0x03c-0xfff), | Encapsulated layer 3 |
+| | String | protocol ID |
++----------------+-----------------------------+-----------------------------+
+| comment | STRING | text with max. 256 |
+| | | characters |
++----------------+-----------------------------+-----------------------------+
+
+Valid Strings for ``encap-protocol`` are: arp, ipv4, ipv6
+
+STP (Spanning Tree Protocol) (Since 0.9.8)
+''''''''''''''''''''''''''''''''''''''''''
+
+Protocol ID: ``stp``
+
+Note: Rules of this type should go either into the ``root`` or ``stp`` chain.
+
+=================== =========== =====================================
+Attribute Datatype Semantics
+=================== =========== =====================================
+srcmacaddr MAC_ADDR MAC address of sender
+srcmacmask MAC_MASK Mask applied to MAC address of sender
+type UINT8 Bridge Protocol Data Unit (BPDU) type
+flags UINT8 BPDU flag
+root-priority UINT16 Root priority (range start)
+root-priority-hi UINT16 Root priority range end
+root-address MAC_ADDRESS Root MAC address
+root-address-mask MAC_MASK Root MAC address mask
+root-cost UINT32 Root path cost (range start)
+root-cost-hi UINT32 Root path cost range end
+sender-priority UINT16 Sender priority (range start)
+sender-priority-hi UINT16 Sender priority range end
+sender-address MAC_ADDRESS BPDU sender MAC address
+sender-address-mask MAC_MASK BPDU sender MAC address mask
+port UINT16 Port identifier (range start)
+port_hi UINT16 Port identifier range end
+msg-age UINT16 Message age timer (range start)
+msg-age-hi UINT16 Message age timer range end
+max-age UINT16 Maximum age timer (range start)
+max-age-hi UINT16 Maximum age timer range end
+hello-time UINT16 Hello time timer (range start)
+hello-time-hi UINT16 Hello time timer range end
+forward-delay UINT16 Forward delay (range start)
+forward-delay-hi UINT16 Forward delay range end
+comment STRING text with max. 256 characters
+=================== =========== =====================================
+
+ARP/RARP
+''''''''
+
+Protocol ID: ``arp`` or ``rarp``
+
+Note: Rules of this type should either go into the ``root`` or ``arp/rarp``
+chain.
+
++-----------------------------+----------------+-----------------------------+
+| Attribute | Datatype | Semantics |
++=============================+================+=============================+
+| srcmacaddr | MAC_ADDR | MAC address of sender |
++-----------------------------+----------------+-----------------------------+
+| srcmacmask | MAC_MASK | Mask applied to MAC address |
+| | | of sender |
++-----------------------------+----------------+-----------------------------+
+| dstmacaddr | MAC_ADDR | MAC address of destination |
++-----------------------------+----------------+-----------------------------+
+| dstmacmask | MAC_MASK | Mask applied to MAC address |
+| | | of destination |
++-----------------------------+----------------+-----------------------------+
+| hwtype | UINT16 | Hardware type |
++-----------------------------+----------------+-----------------------------+
+| protocoltype | UINT16 | Protocol type |
++-----------------------------+----------------+-----------------------------+
+| opcode | UINT16, STRING | Opcode |
++-----------------------------+----------------+-----------------------------+
+| arpsrcmacaddr | MAC_ADDR | Source MAC address in |
+| | | ARP/RARP packet |
++-----------------------------+----------------+-----------------------------+
+| arpdstmacaddr | MAC_ADDR | Destination MAC address in |
+| | | ARP/RARP packet |
++-----------------------------+----------------+-----------------------------+
+| arpsrcipaddr | IP_ADDR | Source IP address in |
+| | | ARP/RARP packet |
++-----------------------------+----------------+-----------------------------+
+| arpsrcipmask :since:`(Since | IP_MASK | Source IP mask |
+| 1.2.3)` | | |
++-----------------------------+----------------+-----------------------------+
+| arpdstipaddr | IP_ADDR | Destination IP address in |
+| | | ARP/RARP packet |
++-----------------------------+----------------+-----------------------------+
+| arpdstipmask :since:`(Since | IP_MASK | Destination IP mask |
+| 1.2.3)` | | |
++-----------------------------+----------------+-----------------------------+
+| comment :since:`(Since | STRING | text with max. 256 |
+| 0.8.5)` | | characters |
++-----------------------------+----------------+-----------------------------+
+| gratuitous :since:`(Since | BOOLEAN | boolean indicating whether |
+| 0.9.2)` | | to check for gratuitous ARP |
+| | | packet |
++-----------------------------+----------------+-----------------------------+
+
+Valid strings for the ``Opcode`` field are: Request, Reply, Request_Reverse,
+Reply_Reverse, DRARP_Request, DRARP_Reply, DRARP_Error, InARP_Request, ARP_NAK
+
+IPv4
+''''
+
+Protocol ID: ``ip``
+
+Note: Rules of this type should either go into the ``root`` or ``ipv4`` chain.
+
++-------------------------+-------------------------+-------------------------+
+| Attribute | Datatype | Semantics |
++=========================+=========================+=========================+
+| srcmacaddr | MAC_ADDR | MAC address of sender |
++-------------------------+-------------------------+-------------------------+
+| srcmacmask | MAC_MASK | Mask applied to MAC |
+| | | address of sender |
++-------------------------+-------------------------+-------------------------+
+| dstmacaddr | MAC_ADDR | MAC address of |
+| | | destination |
++-------------------------+-------------------------+-------------------------+
+| dstmacmask | MAC_MASK | Mask applied to MAC |
+| | | address of destination |
++-------------------------+-------------------------+-------------------------+
+| srcipaddr | IP_ADDR | Source IP address |
++-------------------------+-------------------------+-------------------------+
+| srcipmask | IP_MASK | Mask applied to source |
+| | | IP address |
++-------------------------+-------------------------+-------------------------+
+| dstipaddr | IP_ADDR | Destination IP address |
++-------------------------+-------------------------+-------------------------+
+| dstipmask | IP_MASK | Mask applied to |
+| | | destination IP address |
++-------------------------+-------------------------+-------------------------+
+| protocol | UINT8, STRING | Layer 4 protocol |
+| | | identifier |
++-------------------------+-------------------------+-------------------------+
+| srcportstart | UINT16 | Start of range of valid |
+| | | source ports; requires |
+| | | ``protocol`` |
++-------------------------+-------------------------+-------------------------+
+| srcportend | UINT16 | End of range of valid |
+| | | source ports; requires |
+| | | ``protocol`` |
++-------------------------+-------------------------+-------------------------+
+| dstportstart | UINT16 | Start of range of valid |
+| | | destination ports; |
+| | | requires ``protocol`` |
++-------------------------+-------------------------+-------------------------+
+| dstportend | UINT16 | End of range of valid |
+| | | destination ports; |
+| | | requires ``protocol`` |
++-------------------------+-------------------------+-------------------------+
+| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services |
+| | 63) | Code Point |
++-------------------------+-------------------------+-------------------------+
+| comment :since:`(Since | STRING | text with max. 256 |
+| 0.8.5)` | | characters |
++-------------------------+-------------------------+-------------------------+
+
+Valid strings for ``protocol`` are: tcp, udp, udplite, esp, ah, icmp, igmp, sctp
+
+IPv6
+''''
+
+Protocol ID: ``ipv6``
+
+Note: Rules of this type should either go into the ``root`` or ``ipv6`` chain.
+
++--------------------------------+-----------+--------------------------------+
+| Attribute | Datatype | Semantics |
++================================+===========+================================+
+| srcmacaddr | MAC_ADDR | MAC address of sender |
++--------------------------------+-----------+--------------------------------+
+| srcmacmask | MAC_MASK | Mask applied to MAC address of |
+| | | sender |
++--------------------------------+-----------+--------------------------------+
+| dstmacaddr | MAC_ADDR | MAC address of destination |
++--------------------------------+-----------+--------------------------------+
+| dstmacmask | MAC_MASK | Mask applied to MAC address of |
+| | | destination |
++--------------------------------+-----------+--------------------------------+
+| srcipaddr | IPV6_ADDR | Source IPv6 address |
++--------------------------------+-----------+--------------------------------+
+| srcipmask | IPV6_MASK | Mask applied to source IPv6 |
+| | | address |
++--------------------------------+-----------+--------------------------------+
+| dstipaddr | IPV6_ADDR | Destination IPv6 address |
++--------------------------------+-----------+--------------------------------+
+| dstipmask | IPV6_MASK | Mask applied to destination |
+| | | IPv6 address |
++--------------------------------+-----------+--------------------------------+
+| protocol | UINT8 | Layer 4 protocol identifier |
++--------------------------------+-----------+--------------------------------+
+| srcportstart | UINT16 | Start of range of valid source |
+| | | ports; requires ``protocol`` |
++--------------------------------+-----------+--------------------------------+
+| srcportend | UINT16 | End of range of valid source |
+| | | ports; requires ``protocol`` |
++--------------------------------+-----------+--------------------------------+
+| dstportstart | UINT16 | Start of range of valid |
+| | | destination ports; requires |
+| | | ``protocol`` |
++--------------------------------+-----------+--------------------------------+
+| dstportend | UINT16 | End of range of valid |
+| | | destination ports; requires |
+| | | ``protocol`` |
++--------------------------------+-----------+--------------------------------+
+| type :since:`(Since 1.2.12)` | UINT8 | ICMPv6 type; requires |
+| | | ``protocol`` to be set to |
+| | | ``icmpv6`` |
++--------------------------------+-----------+--------------------------------+
+| typeend :since:`(Since | UINT8 | ICMPv6 type end of range; |
+| 1.2.12)` | | requires ``protocol`` to be |
+| | | set to ``icmpv6`` |
++--------------------------------+-----------+--------------------------------+
+| code :since:`(Since 1.2.12)` | UINT8 | ICMPv6 code; requires |
+| | | ``protocol`` to be set to |
+| | | ``icmpv6`` |
++--------------------------------+-----------+--------------------------------+
+| code :since:`(Since 1.2.12)` | UINT8 | ICMPv6 code end of range; |
+| | | requires ``protocol`` to be |
+| | | set to ``icmpv6`` |
++--------------------------------+-----------+--------------------------------+
+| comment :since:`(Since 0.8.5)` | STRING | text with max. 256 characters |
++--------------------------------+-----------+--------------------------------+
+
+Valid strings for ``protocol`` are: tcp, udp, udplite, esp, ah, icmpv6, sctp
+
+TCP/UDP/SCTP
+''''''''''''
+
+Protocol ID: ``tcp``, ``udp``, ``sctp``
+
+Note: The chain parameter is ignored for this type of traffic and should either
+be omitted or set to ``root``.
+
++-------------------------+-------------------------+-------------------------+
+| Attribute | Datatype | Semantics |
++=========================+=========================+=========================+
+| srcmacaddr | MAC_ADDR | MAC address of sender |
++-------------------------+-------------------------+-------------------------+
+| srcipaddr | IP_ADDR | Source IP address |
++-------------------------+-------------------------+-------------------------+
+| srcipmask | IP_MASK | Mask applied to source |
+| | | IP address |
++-------------------------+-------------------------+-------------------------+
+| dstipaddr | IP_ADDR | Destination IP address |
++-------------------------+-------------------------+-------------------------+
+| dstipmask | IP_MASK | Mask applied to |
+| | | destination IP address |
++-------------------------+-------------------------+-------------------------+
+| srcipfrom | IP_ADDR | Start of range of |
+| | | source IP address |
++-------------------------+-------------------------+-------------------------+
+| srcipto | IP_ADDR | End of range of source |
+| | | IP address |
++-------------------------+-------------------------+-------------------------+
+| dstipfrom | IP_ADDR | Start of range of |
+| | | destination IP address |
++-------------------------+-------------------------+-------------------------+
+| dstipto | IP_ADDR | End of range of |
+| | | destination IP address |
++-------------------------+-------------------------+-------------------------+
+| srcportstart | UINT16 | Start of range of valid |
+| | | source ports |
++-------------------------+-------------------------+-------------------------+
+| srcportend | UINT16 | End of range of valid |
+| | | source ports |
++-------------------------+-------------------------+-------------------------+
+| dstportstart | UINT16 | Start of range of valid |
+| | | destination ports |
++-------------------------+-------------------------+-------------------------+
+| dstportend | UINT16 | End of range of valid |
+| | | destination ports |
++-------------------------+-------------------------+-------------------------+
+| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services |
+| | 63) | Code Point |
++-------------------------+-------------------------+-------------------------+
+| comment :since:`(Since | STRING | text with max. 256 |
+| 0.8.5)` | | characters |
++-------------------------+-------------------------+-------------------------+
+| state :since:`(Since | STRING | comma separated list of |
+| 0.8.5)` | | NEW,ESTA |
+| | | BLISHED,RELATED,INVALID |
+| | | or NONE |
++-------------------------+-------------------------+-------------------------+
+| flags :since:`(Since | STRING | TCP-only: format of |
+| 0.9.1)` | | mask/flags with mask |
+| | | and flags each being a |
+| | | comma separated list of |
+| | | SYN,ACK,URG,PSH,FIN,RST |
+| | | or NONE or ALL |
++-------------------------+-------------------------+-------------------------+
+| ipset :since:`(Since | STRING | The name of an IPSet |
+| 0.9.13)` | | managed outside of |
+| | | libvirt |
++-------------------------+-------------------------+-------------------------+
+| ipsetflags | IPSETFLAGS | flags for the IPSet; |
+| :since:`(Since 0.9.13)` | | requires ipset |
+| | | attribute |
++-------------------------+-------------------------+-------------------------+
+
+ICMP
+''''
+
+Protocol ID: ``icmp``
+
+Note: The chain parameter is ignored for this type of traffic and should either
+be omitted or set to ``root``.
+
++-------------------------+-------------------------+-------------------------+
+| Attribute | Datatype | Semantics |
++=========================+=========================+=========================+
+| srcmacaddr | MAC_ADDR | MAC address of sender |
++-------------------------+-------------------------+-------------------------+
+| srcmacmask | MAC_MASK | Mask applied to MAC |
+| | | address of sender |
++-------------------------+-------------------------+-------------------------+
+| dstmacaddr | MAC_ADDR | MAC address of |
+| | | destination |
++-------------------------+-------------------------+-------------------------+
+| dstmacmask | MAC_MASK | Mask applied to MAC |
+| | | address of destination |
++-------------------------+-------------------------+-------------------------+
+| srcipaddr | IP_ADDR | Source IP address |
++-------------------------+-------------------------+-------------------------+
+| srcipmask | IP_MASK | Mask applied to source |
+| | | IP address |
++-------------------------+-------------------------+-------------------------+
+| dstipaddr | IP_ADDR | Destination IP address |
++-------------------------+-------------------------+-------------------------+
+| dstipmask | IP_MASK | Mask applied to |
+| | | destination IP address |
++-------------------------+-------------------------+-------------------------+
+| srcipfrom | IP_ADDR | Start of range of |
+| | | source IP address |
++-------------------------+-------------------------+-------------------------+
+| srcipto | IP_ADDR | End of range of source |
+| | | IP address |
++-------------------------+-------------------------+-------------------------+
+| dstipfrom | IP_ADDR | Start of range of |
+| | | destination IP address |
++-------------------------+-------------------------+-------------------------+
+| dstipto | IP_ADDR | End of range of |
+| | | destination IP address |
++-------------------------+-------------------------+-------------------------+
+| type | UINT16 | ICMP type |
++-------------------------+-------------------------+-------------------------+
+| code | UINT16 | ICMP code |
++-------------------------+-------------------------+-------------------------+
+| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services |
+| | 63) | Code Point |
++-------------------------+-------------------------+-------------------------+
+| comment :since:`(Since | STRING | text with max. 256 |
+| 0.8.5)` | | characters |
++-------------------------+-------------------------+-------------------------+
+| state :since:`(Since | STRING | comma separated list of |
+| 0.8.5)` | | NEW,ESTA |
+| | | BLISHED,RELATED,INVALID |
+| | | or NONE |
++-------------------------+-------------------------+-------------------------+
+| ipset :since:`(Since | STRING | The name of an IPSet |
+| 0.9.13)` | | managed outside of |
+| | | libvirt |
++-------------------------+-------------------------+-------------------------+
+| ipsetflags | IPSETFLAGS | flags for the IPSet; |
+| :since:`(Since 0.9.13)` | | requires ipset |
+| | | attribute |
++-------------------------+-------------------------+-------------------------+
+
+IGMP, ESP, AH, UDPLITE, 'ALL'
+'''''''''''''''''''''''''''''
+
+Protocol ID: ``igmp``, ``esp``, ``ah``, ``udplite``, ``all``
+
+Note: The chain parameter is ignored for this type of traffic and should either
+be omitted or set to ``root``.
+
++-------------------------+-------------------------+-------------------------+
+| Attribute | Datatype | Semantics |
++=========================+=========================+=========================+
+| srcmacaddr | MAC_ADDR | MAC address of sender |
++-------------------------+-------------------------+-------------------------+
+| srcmacmask | MAC_MASK | Mask applied to MAC |
+| | | address of sender |
++-------------------------+-------------------------+-------------------------+
+| dstmacaddr | MAC_ADDR | MAC address of |
+| | | destination |
++-------------------------+-------------------------+-------------------------+
+| dstmacmask | MAC_MASK | Mask applied to MAC |
+| | | address of destination |
++-------------------------+-------------------------+-------------------------+
+| srcipaddr | IP_ADDR | Source IP address |
++-------------------------+-------------------------+-------------------------+
+| srcipmask | IP_MASK | Mask applied to source |
+| | | IP address |
++-------------------------+-------------------------+-------------------------+
+| dstipaddr | IP_ADDR | Destination IP address |
++-------------------------+-------------------------+-------------------------+
+| dstipmask | IP_MASK | Mask applied to |
+| | | destination IP address |
++-------------------------+-------------------------+-------------------------+
+| srcipfrom | IP_ADDR | Start of range of |
+| | | source IP address |
++-------------------------+-------------------------+-------------------------+
+| srcipto | IP_ADDR | End of range of source |
+| | | IP address |
++-------------------------+-------------------------+-------------------------+
+| dstipfrom | IP_ADDR | Start of range of |
+| | | destination IP address |
++-------------------------+-------------------------+-------------------------+
+| dstipto | IP_ADDR | End of range of |
+| | | destination IP address |
++-------------------------+-------------------------+-------------------------+
+| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services |
+| | 63) | Code Point |
++-------------------------+-------------------------+-------------------------+
+| comment :since:`(Since | STRING | text with max. 256 |
+| 0.8.5)` | | characters |
++-------------------------+-------------------------+-------------------------+
+| state :since:`(Since | STRING | comma separated list of |
+| 0.8.5)` | | NEW,ESTA |
+| | | BLISHED,RELATED,INVALID |
+| | | or NONE |
++-------------------------+-------------------------+-------------------------+
+| ipset :since:`(Since | STRING | The name of an IPSet |
+| 0.9.13)` | | managed outside of |
+| | | libvirt |
++-------------------------+-------------------------+-------------------------+
+| ipsetflags | IPSETFLAGS | flags for the IPSet; |
+| :since:`(Since 0.9.13)` | | requires ipset |
+| | | attribute |
++-------------------------+-------------------------+-------------------------+
+
+TCP/UDP/SCTP over IPV6
+''''''''''''''''''''''
+
+Protocol ID: ``tcp-ipv6``, ``udp-ipv6``, ``sctp-ipv6``
+
+Note: The chain parameter is ignored for this type of traffic and should either
+be omitted or set to ``root``.
+
++-------------------------+-------------------------+-------------------------+
+| Attribute | Datatype | Semantics |
++=========================+=========================+=========================+
+| srcmacaddr | MAC_ADDR | MAC address of sender |
++-------------------------+-------------------------+-------------------------+
+| srcipaddr | IPV6_ADDR | Source IP address |
++-------------------------+-------------------------+-------------------------+
+| srcipmask | IPV6_MASK | Mask applied to source |
+| | | IP address |
++-------------------------+-------------------------+-------------------------+
+| dstipaddr | IPV6_ADDR | Destination IP address |
++-------------------------+-------------------------+-------------------------+
+| dstipmask | IPV6_MASK | Mask applied to |
+| | | destination IP address |
++-------------------------+-------------------------+-------------------------+
+| srcipfrom | IPV6_ADDR | Start of range of |
+| | | source IP address |
++-------------------------+-------------------------+-------------------------+
+| srcipto | IPV6_ADDR | End of range of source |
+| | | IP address |
++-------------------------+-------------------------+-------------------------+
+| dstipfrom | IPV6_ADDR | Start of range of |
+| | | destination IP address |
++-------------------------+-------------------------+-------------------------+
+| dstipto | IPV6_ADDR | End of range of |
+| | | destination IP address |
++-------------------------+-------------------------+-------------------------+
+| srcportstart | UINT16 | Start of range of valid |
+| | | source ports |
++-------------------------+-------------------------+-------------------------+
+| srcportend | UINT16 | End of range of valid |
+| | | source ports |
++-------------------------+-------------------------+-------------------------+
+| dstportstart | UINT16 | Start of range of valid |
+| | | destination ports |
++-------------------------+-------------------------+-------------------------+
+| dstportend | UINT16 | End of range of valid |
+| | | destination ports |
++-------------------------+-------------------------+-------------------------+
+| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services |
+| | 63) | Code Point |
++-------------------------+-------------------------+-------------------------+
+| comment :since:`(Since | STRING | text with max. 256 |
+| 0.8.5)` | | characters |
++-------------------------+-------------------------+-------------------------+
+| state :since:`(Since | STRING | comma separated list of |
+| 0.8.5)` | | NEW,ESTA |
+| | | BLISHED,RELATED,INVALID |
+| | | or NONE |
++-------------------------+-------------------------+-------------------------+
+| flags :since:`(Since | STRING | TCP-only: format of |
+| 0.9.1)` | | mask/flags with mask |
+| | | and flags each being a |
+| | | comma separated list of |
+| | | SYN,ACK,URG,PSH,FIN,RST |
+| | | or NONE or ALL |
++-------------------------+-------------------------+-------------------------+
+| ipset :since:`(Since | STRING | The name of an IPSet |
+| 0.9.13)` | | managed outside of |
+| | | libvirt |
++-------------------------+-------------------------+-------------------------+
+| ipsetflags | IPSETFLAGS | flags for the IPSet; |
+| :since:`(Since 0.9.13)` | | requires ipset |
+| | | attribute |
++-------------------------+-------------------------+-------------------------+
+
+ICMPv6
+''''''
+
+Protocol ID: ``icmpv6``
+
+Note: The chain parameter is ignored for this type of traffic and should either
+be omitted or set to ``root``.
+
++-------------------------+-------------------------+-------------------------+
+| Attribute | Datatype | Semantics |
++=========================+=========================+=========================+
+| srcmacaddr | MAC_ADDR | MAC address of sender |
++-------------------------+-------------------------+-------------------------+
+| srcipaddr | IPV6_ADDR | Source IPv6 address |
++-------------------------+-------------------------+-------------------------+
+| srcipmask | IPV6_MASK | Mask applied to source |
+| | | IPv6 address |
++-------------------------+-------------------------+-------------------------+
+| dstipaddr | IPV6_ADDR | Destination IPv6 |
+| | | address |
++-------------------------+-------------------------+-------------------------+
+| dstipmask | IPV6_MASK | Mask applied to |
+| | | destination IPv6 |
+| | | address |
++-------------------------+-------------------------+-------------------------+
+| srcipfrom | IPV6_ADDR | Start of range of |
+| | | source IP address |
++-------------------------+-------------------------+-------------------------+
+| srcipto | IPV6_ADDR | End of range of source |
+| | | IP address |
++-------------------------+-------------------------+-------------------------+
+| dstipfrom | IPV6_ADDR | Start of range of |
+| | | destination IP address |
++-------------------------+-------------------------+-------------------------+
+| dstipto | IPV6_ADDR | End of range of |
+| | | destination IP address |
++-------------------------+-------------------------+-------------------------+
+| type | UINT16 | ICMPv6 type |
++-------------------------+-------------------------+-------------------------+
+| code | UINT16 | ICMPv6 code |
++-------------------------+-------------------------+-------------------------+
+| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services |
+| | 63) | Code Point |
++-------------------------+-------------------------+-------------------------+
+| comment :since:`(Since | STRING | text with max. 256 |
+| 0.8.5)` | | characters |
++-------------------------+-------------------------+-------------------------+
+| state :since:`(Since | STRING | comma separated list of |
+| 0.8.5)` | | NEW,ESTA |
+| | | BLISHED,RELATED,INVALID |
+| | | or NONE |
++-------------------------+-------------------------+-------------------------+
+| ipset :since:`(Since | STRING | The name of an IPSet |
+| 0.9.13)` | | managed outside of |
+| | | libvirt |
++-------------------------+-------------------------+-------------------------+
+| ipsetflags | IPSETFLAGS | flags for the IPSet; |
+| :since:`(Since 0.9.13)` | | requires ipset |
+| | | attribute |
++-------------------------+-------------------------+-------------------------+
+
+ESP, AH, UDPLITE, 'ALL' over IPv6
+'''''''''''''''''''''''''''''''''
+
+Protocol ID: ``esp-ipv6``, ``ah-ipv6``, ``udplite-ipv6``, ``all-ipv6``
+
+Note: The chain parameter is ignored for this type of traffic and should either
+be omitted or set to ``root``.
+
++-------------------------+-------------------------+-------------------------+
+| Attribute | Datatype | Semantics |
++=========================+=========================+=========================+
+| srcmacaddr | MAC_ADDR | MAC address of sender |
++-------------------------+-------------------------+-------------------------+
+| srcipaddr | IPV6_ADDR | Source IPv6 address |
++-------------------------+-------------------------+-------------------------+
+| srcipmask | IPV6_MASK | Mask applied to source |
+| | | IPv6 address |
++-------------------------+-------------------------+-------------------------+
+| dstipaddr | IPV6_ADDR | Destination IPv6 |
+| | | address |
++-------------------------+-------------------------+-------------------------+
+| dstipmask | IPV6_MASK | Mask applied to |
+| | | destination IPv6 |
+| | | address |
++-------------------------+-------------------------+-------------------------+
+| srcipfrom | IPV6_ADDR | Start of range of |
+| | | source IP address |
++-------------------------+-------------------------+-------------------------+
+| srcipto | IPV6_ADDR | End of range of source |
+| | | IP address |
++-------------------------+-------------------------+-------------------------+
+| dstipfrom | IPV6_ADDR | Start of range of |
+| | | destination IP address |
++-------------------------+-------------------------+-------------------------+
+| dstipto | IPV6_ADDR | End of range of |
+| | | destination IP address |
++-------------------------+-------------------------+-------------------------+
+| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services |
+| | 63) | Code Point |
++-------------------------+-------------------------+-------------------------+
+| comment :since:`(Since | STRING | text with max. 256 |
+| 0.8.5)` | | characters |
++-------------------------+-------------------------+-------------------------+
+| state :since:`(Since | STRING | comma separated list of |
+| 0.8.5)` | | NEW,ESTA |
+| | | BLISHED,RELATED,INVALID |
+| | | or NONE |
++-------------------------+-------------------------+-------------------------+
+| ipset :since:`(Since | STRING | The name of an IPSet |
+| 0.9.13)` | | managed outside of |
+| | | libvirt |
++-------------------------+-------------------------+-------------------------+
+| ipsetflags | IPSETFLAGS | flags for the IPSet; |
+| :since:`(Since 0.9.13)` | | requires ipset |
+| | | attribute |
++-------------------------+-------------------------+-------------------------+
+
+Advanced Filter Configuration Topics
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following sections discuss advanced filter configuration topics.
+
+Connection tracking
+^^^^^^^^^^^^^^^^^^^
+
+The network filtering subsystem (on Linux) makes use of the connection tracking
+support of iptables. This helps in enforcing the directionality of network
+traffic (state match) as well as counting and limiting the number of
+simultaneous connections towards a VM. As an example, if a VM has TCP port 8080
+open as a server, clients may connect to the VM on port 8080. Connection
+tracking and enforcement of directionality then prevents the VM from initiating
+a connection from (TCP client) port 8080 to the host back to a remote host. More
+importantly, tracking helps to prevent remote attackers from establishing a
+connection back to a VM. For example, if the user inside the VM established a
+connection to port 80 on an attacker site, then the attacker will not be able to
+initiate a connection from TCP port 80 back towards the VM. By default the
+connection state match that enables connection tracking and then enforcement of
+directionality of traffic is turned on.
+
+The following shows an example XML fragment where this feature has been turned
+off for incoming connections to TCP port 12345.
+
+::
+
+ [...]
+ <rule direction='in' action='accept'
statematch='false'>
+ <tcp dstportstart='12345'/>
+ </rule>
+ [...]
+
+This now allows incoming traffic to TCP port 12345, but would also enable the
+initiation from (client) TCP port 12345 within the VM, which may or may not be
+desirable.
+
+Limiting Number of Connections
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To limit the number of connections a VM may establish, a rule must be provided
+that sets a limit of connections for a given type of traffic. If for example a
+VM is supposed to be allowed to only ping one other IP address at a time and is
+supposed to have only one active incoming ssh connection at a time, the
+following XML fragment can be used to achieve this.
+
+::
+
+ [...]
+ <rule action='drop' direction='in' priority='400'>
+ <tcp connlimit-above='1'/>
+ </rule>
+ <rule action='accept' direction='in' priority='500'>
+ <tcp dstportstart='22'/>
+ </rule>
+ <rule action='drop' direction='out' priority='400'>
+ <icmp connlimit-above='1'/>
+ </rule>
+ <rule action='accept' direction='out' priority='500'>
+ <icmp/>
+ </rule>
+ <rule action='accept' direction='out' priority='500'>
+ <udp dstportstart='53'/>
+ </rule>
+ <rule action='drop' direction='inout' priority='1000'>
+ <all/>
+ </rule>
+ [...]
+
+Note that the rule for the limit has to logically appear before the rule for
+accepting the traffic.
+
+An additional rule for letting DNS traffic to port 22 go out the VM has been
+added to avoid ssh sessions not getting established for reasons related to DNS
+lookup failures by the ssh daemon. Leaving this rule out may otherwise lead to
+fun-filled debugging joy (symptom: ssh client seems to hang while trying to
+connect).
+
+Lot of care must be taken with timeouts related to tracking of traffic. An ICMP
+ping that the user may have terminated inside the VM may have a long timeout in
+the host's connection tracking system and therefore not allow another ICMP ping
+to go through for a while. Therefore, the timeouts have to be tuned in the
+host's sysfs, i.e.,
+
+::
+
+ echo 3 > /proc/sys/net/netfilter/nf_conntrack_icmp_timeout
+
+sets the ICMP connection tracking timeout to 3 seconds. The effect of this is
+that once one ping is terminated, another one can start after 3 seconds.
+
+Further, we want to point out that a client that for whatever reason has not
+properly closed a TCP connection may cause a connection to be held open for a
+longer period of time, depending to what timeout the ``TCP established`` state
+timeout has been set to on the host. Also, idle connections may time out in the
+connection tracking system but can be reactivated once packets are exchanged.
+However, a newly initiated connection may force an idle connection into TCP
+backoff if the number of allowed connections is set to a too low limit, the new
+connection is established and hits (not exceeds) the limit of allowed
+connections and for example a key is pressed on the old ssh session, which now
+has become unresponsive due to its traffic being dropped. Therefore, the limit
+of connections should be rather high so that fluctuations in new TCP connections
+don't cause odd traffic behavior in relation to idle connections.
+
+Command line tools
+------------------
+
+The libvirt command line tool ``virsh`` has been extended with life-cycle
+support for network filters. All commands related to the network filtering
+subsystem start with the prefix ``nwfilter``. The following commands are
+available:
+
+- nwfilter-list : list UUIDs and names of all network filters
+
+- nwfilter-define : define a new network filter or update an existing one
+
+- nwfilter-undefine : delete a network filter given its name; it must not be
+ currently in use
+
+- nwfilter-dumpxml : display a network filter given its name
+
+- nwfilter-edit : edit a network filter given its name
+
+Pre-existing network filters
+----------------------------
+
+The following is a list of example network filters that are automatically
+installed with libvirt.
+
++---------------------+-------------------------------------------------------+
+| Name | Description |
++=====================+=======================================================+
+| no-arp-spoofing | Prevent a VM from spoofing ARP traffic; this filter |
+| | only allows ARP request and reply messages and |
+| | enforces that those packets contain the MAC and IP |
+| | addresses of the VM. |
++---------------------+-------------------------------------------------------+
+| allow-arp | Allow ARP traffic in both directions |
++---------------------+-------------------------------------------------------+
+| allow-ipv4 | Allow IPv4 traffic in both directions |
++---------------------+-------------------------------------------------------+
+| allow-ipv6 | Allow IPv6 traffic in both directions |
++---------------------+-------------------------------------------------------+
+| allow-incoming-ipv4 | Allow incoming IPv4 traffic |
++---------------------+-------------------------------------------------------+
+| allow-incoming-ipv6 | Allow incoming IPv6 traffic |
++---------------------+-------------------------------------------------------+
+| allow-dhcp | Allow a VM to request an IP address via DHCP (from |
+| | any DHCP server) |
++---------------------+-------------------------------------------------------+
+| allow-dhcpv6 | Similar to allow-dhcp, but for DHCPv6 |
++---------------------+-------------------------------------------------------+
+| allow-dhcp-server | Allow a VM to request an IP address from a specified |
+| | DHCP server. The dotted decimal IP address of the |
+| | DHCP server must be provided in a reference to this |
+| | filter. The name of the variable must be |
+| | *DHCPSERVER*. |
++---------------------+-------------------------------------------------------+
+| allow-dhcpv6-server | Similar to allow-dhcp-server, but for DHCPv6 |
++---------------------+-------------------------------------------------------+
+| no-ip-spoofing | Prevent a VM from sending of IPv4 packets with a |
+| | source IP address different from the one in the |
+| | packet. |
++---------------------+-------------------------------------------------------+
+| no-ipv6-spoofing | Similar to no-ip-spoofing, but for IPv6 |
++---------------------+-------------------------------------------------------+
+| no-ip-multicast | Prevent a VM from sending IP multicast packets. |
++---------------------+-------------------------------------------------------+
+| no-ipv6-multicast | Similar to no-ip-multicast, but for IPv6 |
++---------------------+-------------------------------------------------------+
+| clean-traffic | Prevent MAC, IP and ARP spoofing. This filter |
+| | references several other filters as building blocks. |
++---------------------+-------------------------------------------------------+
+
+Note that most of the above filters are only building blocks and require a
+combination with other filters to provide useful network traffic filtering. The
+most useful one in the above list is the *clean-traffic* filter. This filter
+itself can for example be combined with the *no-ip-multicast* filter to prevent
+virtual machines from sending IP multicast traffic on top of the prevention of
+packet spoofing.
+
+Writing your own filters
+------------------------
+
+Since libvirt only provides a couple of example networking filters, you may
+consider writing your own. When planning on doing so there are a couple of
+things you may need to know regarding the network filtering subsystem and how it
+works internally. Certainly you also have to know and understand the protocols
+very well that you want to be filtering on so that no further traffic than what
+you want can pass and that in fact the traffic you want to allow does pass.
+
+The network filtering subsystem is currently only available on Linux hosts and
+only works for QEMU and KVM type of virtual machines. On Linux it builds upon
+the support for ``ebtables``, ``iptables`` and ``ip6tables`` and makes use of
+their features. From the above list of supported protocols the following ones
+are implemented using ``ebtables``:
+
+- mac
+
+- stp (spanning tree protocol)
+
+- vlan (802.1Q)
+
+- arp, rarp
+
+- ipv4
+
+- ipv6
+
+All other protocols over IPv4 are supported using iptables, those over IPv6 are
+implemented using ip6tables.
+
+On a Linux host, all traffic filtering instantiated by libvirt's network filter
+subsystem first passes through the filtering support implemented by ebtables and
+only then through iptables or ip6tables filters. If a filter tree has rules with
+the protocols ``mac``, ``stp``, ``vlan`` ``arp``, ``rarp``, ``ipv4``, or
+``ipv6`` ebtables rules will automatically be instantiated.
+
+The role of the ``chain`` attribute in the network filter XML is that internally
+a new user-defined ebtables table is created that then for example receives all
+``arp`` traffic coming from or going to a virtual machine if the chain ``arp``
+has been specified. Further, a rule is generated in an interface's ``root``
+chain that directs all ipv4 traffic into the user-defined chain. Therefore, all
+ARP traffic rules should then be placed into filters specifying this chain. This
+type of branching into user-defined tables is only supported with filtering on
+the ebtables layer.
+
+:since:`Since 0.9.8` multiple chains for the same protocol can be created. For
+this the name of the chain must have a prefix of one of the previously
+enumerated protocols. To create an additional chain for handling of ARP traffic,
+a chain with name ``arp-test`` can be specified.
+
+As an example, it is possible to filter on UDP traffic by source and destination
+ports using the ``ip`` protocol filter and specifying attributes for the
+protocol, source and destination IP addresses and ports of UDP packets that are
+to be accepted. This allows early filtering of UDP traffic with ebtables.
+However, once an IP or IPv6 packet, such as a UDP packet, has passed the
+ebtables layer and there is at least one rule in a filter tree that instantiates
+iptables or ip6tables rules, a rule to let the UDP packet pass will also be
+necessary to be provided for those filtering layers. This can be achieved with a
+rule containing an appropriate ``udp`` or ``udp-ipv6`` traffic filtering node.
+
+Example custom filter
+~~~~~~~~~~~~~~~~~~~~~
+
+As an example we want to now build a filter that fulfills the following list of
+requirements:
+
+- prevents a VM's interface from MAC, IP and ARP spoofing
+
+- opens only TCP ports 22 and 80 of a VM's interface
+
+- allows the VM to send ping traffic from an interface but not let the VM be
+ pinged on the interface
+
+- allows the VM to do DNS lookups (UDP towards port 53)
+
+The requirement to prevent spoofing is fulfilled by the existing
+``clean-traffic`` network filter, thus we will reference this filter from our
+custom filter.
+
+To enable traffic for TCP ports 22 and 80 we will add 2 rules to enable this
+type of traffic. To allow the VM to send ping traffic we will add a rule for
+ICMP traffic. For simplicity reasons we allow general ICMP traffic to be
+initiated from the VM, not just ICMP echo request and response messages. To then
+disallow all other traffic to reach or be initiated by the VM we will then need
+to add a rule that drops all other traffic. Assuming our VM is called *test* and
+the interface we want to associate our filter with is called *eth0*, we name our
+filter *test-eth0*. The result of these considerations is the following network
+filter XML:
+
+::
+
+ <filter name='test-eth0'>
+ <!-- reference the clean traffic filter to prevent
+ MAC, IP and ARP spoofing. By not providing
+ and IP address parameter, libvirt will detect the
+ IP address the VM is using. -->
+ <filterref filter='clean-traffic'/>
+
+ <!-- enable TCP ports 22 (ssh) and 80 (http) to be reachable -->
+ <rule action='accept' direction='in'>
+ <tcp dstportstart='22'/>
+ </rule>
+
+ <rule action='accept' direction='in'>
+ <tcp dstportstart='80'/>
+ </rule>
+
+ <!-- enable general ICMP traffic to be initiated by the VM;
+ this includes ping traffic -->
+ <rule action='accept' direction='out'>
+ <icmp/>
+ </rule>
+
+ <!-- enable outgoing DNS lookups using UDP -->
+ <rule action='accept' direction='out'>
+ <udp dstportstart='53'/>
+ </rule>
+
+ <!-- drop all other traffic -->
+ <rule action='drop' direction='inout'>
+ <all/>
+ </rule>
+
+ </filter>
+
+Note that none of the rules in the above XML contain the IP address of the VM as
+either source or destination address, yet the filtering of the traffic works
+correctly. The reason is that the evaluation of the rules internally happens on
+a per-interface basis and the rules are evaluated based on the knowledge about
+which (tap) interface has sent or will receive the packet rather than what their
+source or destination IP address may be.
+
+An XML fragment for a possible network interface description inside the domain
+XML of the ``test`` VM could then look like this:
+
+::
+
+ [...]
+ <interface type='bridge'>
+ <source bridge='mybridge'/>
+ <filterref filter='test-eth0'/>
+ </interface>
+ [...]
+
+To more strictly control the ICMP traffic and enforce that only ICMP echo
+requests can be sent from the VM and only ICMP echo responses be received by the
+VM, the above ``ICMP`` rule can be replaced with the following two rules:
+
+::
+
+ <!-- enable outgoing ICMP echo requests-->
+ <rule action='accept' direction='out'>
+ <icmp type='8'/>
+ </rule>
+
+ <!-- enable incoming ICMP echo replies-->
+ <rule action='accept' direction='in'>
+ <icmp type='0'/>
+ </rule>
+
+Second example custom filter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In this example we now want to build a similar filter as in the example above,
+but extend the list of requirements with an ftp server located inside the VM.
+Further, we will be using features that have been added in :since:`version
+0.8.5` . The requirements for this filter are:
+
+- prevents a VM's interface from MAC, IP and ARP spoofing
+
+- opens only TCP ports 22 and 80 of a VM's interface
+
+- allows the VM to send ping traffic from an interface but not let the VM be
+ pinged on the interface
+
+- allows the VM to do DNS lookups (UDP towards port 53)
+
+- enable an ftp server (in active mode) to be run inside the VM
+
+The additional requirement of allowing an ftp server to be run inside the VM
+maps into the requirement of allowing port 21 to be reachable for ftp control
+traffic as well as enabling the VM to establish an outgoing tcp connection
+originating from the VM's TCP port 20 back to the ftp client (ftp active mode).
+There are several ways of how this filter can be written and we present 2
+solutions.
+
+The 1st solution makes use of the ``state`` attribute of the TCP protocol that
+gives us a hook into the connection tracking framework of the Linux host. For
+the VM-initiated ftp data connection (ftp active mode) we use the ``RELATED``
+state that allows us to detect that the VM-initiated ftp data connection is a
+consequence of ( or 'has a relationship with' ) an existing ftp control
+connection, thus we want to allow it to let packets pass the firewall. The
+``RELATED`` state, however, is only valid for the very first packet of the
+outgoing TCP connection for the ftp data path. Afterwards, the state to compare
+against is ``ESTABLISHED``, which then applies equally to the incoming and
+outgoing direction. All this is related to the ftp data traffic originating from
+TCP port 20 of the VM. This then leads to the following solution :since:`(since
+0.8.5 (QEMU, KVM))` :
+
+::
+
+ <filter name='test-eth0'>
+ <!-- reference the clean traffic filter to prevent
+ MAC, IP and ARP spoofing. By not providing
+ and IP address parameter, libvirt will detect the
+ IP address the VM is using. -->
+ <filterref filter='clean-traffic'/>
+
+ <!-- enable TCP port 21 (ftp-control) to be reachable -->
+ <rule action='accept' direction='in'>
+ <tcp dstportstart='21'/>
+ </rule>
+
+ <!-- enable TCP port 20 for VM-initiated ftp data connection
+ related to an existing ftp control connection -->
+ <rule action='accept' direction='out'>
+ <tcp srcportstart='20' state='RELATED,ESTABLISHED'/>
+ </rule>
+
+ <!-- accept all packets from client on the ftp data connection -->
+ <rule action='accept' direction='in'>
+ <tcp dstportstart='20' state='ESTABLISHED'/>
+ </rule>
+
+ <!-- enable TCP ports 22 (ssh) and 80 (http) to be reachable -->
+ <rule action='accept' direction='in'>
+ <tcp dstportstart='22'/>
+ </rule>
+
+ <rule action='accept' direction='in'>
+ <tcp dstportstart='80'/>
+ </rule>
+
+ <!-- enable general ICMP traffic to be initiated by the VM;
+ this includes ping traffic -->
+ <rule action='accept' direction='out'>
+ <icmp/>
+ </rule>
+
+ <!-- enable outgoing DNS lookups using UDP -->
+ <rule action='accept' direction='out'>
+ <udp dstportstart='53'/>
+ </rule>
+
+ <!-- drop all other traffic -->
+ <rule action='drop' direction='inout'>
+ <all/>
+ </rule>
+
+ </filter>
+
+Before trying out a filter using the ``RELATED`` state, you have to make sure
+that the appropriate connection tracking module has been loaded into the host's
+kernel. Depending on the version of the kernel, you must run either one of the
+following two commands before the ftp connection with the VM is established.
+
+::
+
+ modprobe nf_conntrack_ftp # where available or
+
+ modprobe ip_conntrack_ftp # if above is not available
+
+If other protocols than ftp are to be used in conjunction with the ``RELATED``
+state, their corresponding module must be loaded. Modules exist at least for the
+protocols ftp, tftp, irc, sip, sctp, and amanda.
+
+The 2nd solution makes uses the state flags of connections more than the
+previous solution did. In this solution we take advantage of the fact that the
+``NEW`` state of a connection is valid when the very first packet of a traffic
+flow is seen. Subsequently, if the very first packet of a flow is accepted, the
+flow becomes a connection and enters the ``ESTABLISHED`` state. This allows us
+to write a general rule for allowing packets of ``ESTABLISHED`` connections to
+reach the VM or be sent by the VM. We write specific rules for the very first
+packets identified by the ``NEW`` state and for which ports they are acceptable.
+All packets for ports that are not explicitly accepted will be dropped and
+therefore the connection will not go into the ``ESTABLISHED`` state and any
+subsequent packets be dropped.
+
+::
+
+ <filter name='test-eth0'>
+ <!-- reference the clean traffic filter to prevent
+ MAC, IP and ARP spoofing. By not providing
+ and IP address parameter, libvirt will detect the
+ IP address the VM is using. -->
+ <filterref filter='clean-traffic'/>
+
+ <!-- let the packets of all previously accepted connections reach the VM -->
+ <rule action='accept' direction='in'>
+ <all state='ESTABLISHED'/>
+ </rule>
+
+ <!-- let the packets of all previously accepted and related connections be sent
from the VM -->
+ <rule action='accept' direction='out'>
+ <all state='ESTABLISHED,RELATED'/>
+ </rule>
+
+ <!-- enable traffic towards port 21 (ftp), 22 (ssh) and 80 (http) -->
+ <rule action='accept' direction='in'>
+ <tcp dstportstart='21' dstportend='22'
state='NEW'/>
+ </rule>
+
+ <rule action='accept' direction='in'>
+ <tcp dstportstart='80' state='NEW'/>
+ </rule>
+
+ <!-- enable general ICMP traffic to be initiated by the VM;
+ this includes ping traffic -->
+ <rule action='accept' direction='out'>
+ <icmp state='NEW'/>
+ </rule>
+
+ <!-- enable outgoing DNS lookups using UDP -->
+ <rule action='accept' direction='out'>
+ <udp dstportstart='53' state='NEW'/>
+ </rule>
+
+ <!-- drop all other traffic -->
+ <rule action='drop' direction='inout'>
+ <all/>
+ </rule>
+
+ </filter>
+
+Limitations
+-----------
+
+The following sections list (current) limitations of the network filtering
+subsystem.
+
+VM Migration
+~~~~~~~~~~~~
+
+VM migration is only supported if the whole filter tree that is referenced by a
+virtual machine's top level filter is also available on the target host. The
+network filter *clean-traffic* for example should be available on all libvirt
+installations of version 0.8.1 or later and thus enable migration of VMs that
+for example reference this filter. All other custom filters must be migrated
+using higher layer software. It is outside the scope of libvirt to ensure that
+referenced filters on the source system are equivalent to those on the target
+system and vice versa.
+
+Migration must occur between libvirt installations of version 0.8.1 or later in
+order not to lose the network traffic filters associated with an interface.
+
+VLAN filtering on Linux
+~~~~~~~~~~~~~~~~~~~~~~~
+
+VLAN (802.1Q) packets, if sent by a virtual machine, cannot be filtered with
+rules for protocol IDs ``arp``, ``rarp``, ``ipv4`` and ``ipv6`` but only with
+protocol IDs ``mac`` and ``vlan``. Therefore, the example filter
+``clean-traffic`` will not work as expected.
diff --git a/docs/meson.build b/docs/meson.build
index a8e360c8a4..0458eea683 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -21,7 +21,6 @@ docs_html_in_files = [
'formatcaps',
'formatnetwork',
'formatnode',
- 'formatnwfilter',
'index',
'remote',
'storage',
@@ -74,6 +73,7 @@ docs_rst_files = [
'formatdomain',
'formatdomaincaps',
'formatnetworkport',
+ 'formatnwfilter',
'formatsecret',
'formatsnapshot',
'formatstorage',
--
2.35.1