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 9851ebff53cfbb1a964985bb72a497d6b0adecb0..9cb7644925b2b4859e2d9a283eda8a1388007cc6 100644 (file)
--- a/docs/formatnwfilter.html.in
+++ b/docs/formatnwfilter.html.in
@@ -308,7 +308,69 @@
   </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>
+  ...
+  &lt;rule action='accept' direction='in' priority='500'&gt;
+    &lt;udp dstportstart='$DSTPORTS[1]'/&gt;
+  &lt;/rule&gt;
+  ...
+</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[@&lt;iterator ID&gt;]</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>
+  ...
+  &lt;rule action='accept' direction='in' priority='500'&gt;
+    &lt;ip srcipaddr='$SRCIPADDRESSES[@1]' dstportstart='$DSTPORTS[@2]'/&gt;
+  &lt;/rule&gt;
+  ...
+</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>
     <h2><a name="nwfelems">Element and attribute overview</a></h2>
 
     <p>