-
- 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 following is the XML description of the network filer
- no-arp-spoofing. It serves as an example for
- a network filter XML referencing the MAC and
- IP parameters. This particular filter is referenced by the
- clean-traffic filter.
+ 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:
+
+ Since 0.9.8 multiple chains evaluating the
+ mac, stp, vlan,
+ arp or rarp 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'>
+<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'/>
@@ -169,8 +177,93 @@
<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.
+
+
+ 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 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.
+
+
+ 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
@@ -182,7 +275,38 @@
interface from attaching when hotplugging is used. The types
that are expected for each XML attribute are shown
below.
+
+ 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> + ... +
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
+ .)
mac,
+ stp, vlan
arp, rarp, ip, or ipv6
ebtables rules will automatically be instantiated.
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
+ 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
@@ -1458,6 +1596,12 @@
into user-defined tables is only supported with filtering on the ebtables
layer.
arp-test can be specified.
+ ip protocol filter and specifying attributes for the
@@ -1803,6 +1947,13 @@
0.8.1 or later in order not to lose the network traffic filters
associated with an interface.
-
+
+ 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.
+