This patch adds documentation about the new 'ways' that users can access the contents of variables in filters: - access via index: $TEST[2] - access via iterators $TEST[@1] --- docs/formatnwfilter.html.in | 62 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) Index: libvirt-iterator/docs/formatnwfilter.html.in =================================================================== --- libvirt-iterator.orig/docs/formatnwfilter.html.in +++ libvirt-iterator/docs/formatnwfilter.html.in @@ -308,7 +308,69 @@ </rule> ... +
+ 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 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 + the notation $SRCIPADDRESSES[@1] and $DSTPORTS[@1], would result in the 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'. +