From: Stefan Berger Date: Wed, 11 Jan 2012 11:42:37 +0000 (-0500) Subject: Add documentation new ways to access members of variables X-Git-Tag: v0.9.10-rc1~214 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a20cc3cc4f47ef6e706e9bda764401caaa2a10c2;p=thirdparty%2Flibvirt.git Add documentation new ways to access members of variables 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] --- diff --git a/docs/formatnwfilter.html.in b/docs/formatnwfilter.html.in index 9851ebff53..9cb7644925 100644 --- a/docs/formatnwfilter.html.in +++ b/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 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'. +

Element and attribute overview