This patch adds several aspects of documentation about the network filtering system:
- chains, chains' priorities and chains' default priorities - talks about lists of elements, i.e., a variable assigned multiple values (part of already ACK-ed series) - already mentions the vlan, stp and mac chains added later on (https://www.redhat.com/archives/libvir-list/2011-October/msg01238.html) - mentions limitations of vlan filtering (when sent by VM) on Linux systems --- docs/formatnwfilter.html.in | 227 ++++++++++++++++++++++++++++++++++++-------- 1 file changed, 189 insertions(+), 38 deletions(-) Index: libvirt-acl/docs/formatnwfilter.html.in =================================================================== --- libvirt-acl.orig/docs/formatnwfilter.html.in +++ libvirt-acl/docs/formatnwfilter.html.in @@ -109,40 +109,48 @@ <br/><br/> </p> - <h3><a name="nwfconceptsvars">Usage of variables in filters</a></h3> + <h3><a name="nwfconceptschains">Filtering chains</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 following is the XML description of the network filer - <code>no-arp-spoofing</code>. It serves as an example for - a network filter XML referencing the <code>MAC</code> and - <code>IP</code> parameters. This particular filter is referenced by the - <code>clean-traffic</code> 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). <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>ip</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> or <code>rarp</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'> +<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> </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 name="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><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 name="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 @@ -182,7 +275,38 @@ 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> <h2><a name="nwfelems">Element and attribute overview</a></h2> @@ -280,10 +404,21 @@ <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 and therefore evaluated - before rules with higher value. - Valid values are in the range of 0 to 1000. If this attribute is not - provided, the value 500 will automatically be assigned. + 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 @@ -1431,6 +1566,8 @@ </p> <ul> <li>mac</li> + <li>stp (spanning tree protocol)</li> + <li>vlan (802.1Q)</li> <li>arp, rarp</li> <li>ip</li> <li>ipv6</li> @@ -1444,13 +1581,14 @@ 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>ip</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> + 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 @@ -1458,6 +1596,12 @@ 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 @@ -1803,6 +1947,13 @@ 0.8.1 or later in order not to lose the network traffic filters associated with an interface. </p> - + <h3><a name="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> -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
