Add some comments to br-int-flows-analyze.py

That script was lacking some comments and explainations about how it
works, what it does and its limitations

Change-Id: I7c5badf03f7903f42e33d5dfa750c76ddca882c4

contrib/neutron/br-int-flows-analyze.py

@@ -25,9 +25,60 @@ import libvirt
 import pyparsing as pp
 import sympy as sm
 
+# This tool will print-out a dump of the OVS rules that may pertain to a given
+# VM (a la ovs-ofctl dump-flows, but filtering-out rules that cannot be passed
+# by traffic egressing or ingressing a VM). The main use-case for this tool is
+# to help with the diagnosis of issues related to OpenStack security groups or
+# to OVS flows.
+#
+# The tool starts by creating a cursor associated with an initial set of rules
+# to match, which will then be used to walk through the rules dump and build a
+# tree of the passed rules. All the passed rules are then listed sequentially.
+#
+# In addition to that simple rules dump, the tool will walk-back the tree from
+# every output node (i.e. rules that have an output or NORMAL action) in order
+# to print the paths that could lead to an output node or to a group of output
+# nodes when they can be grouped, along, when possible, a short summary of the
+# last filtering rules (e.g. source IP, dest. port) passed before each output.
+#
+# This last part can be particularly helpful when dealing with port ranges, as
+# they are broken down into sets of rules with each rule dedicated to matching
+# a single masked port defintion (the flow dump ends-up being filled with many
+# rules matching things like "tp_dst=0x7ff0/0xfff8") and security groups using
+# the "--remote-secgroup" option, which are turned into conjunction rule sets.
+#
+# Keep in mind that the summary wont necessarily always make sense, because of
+# two important reasons :
+#
+# 1. This tool is not aware of all the fields a rule can filter on. It handles
+#    the "basic" ones, but it notably doesn't understand the ct-related flags.
+# 2. The aggregation function only merges rules that are at the last hierarchy
+#    level before the rule resulting in a successful output.
+#
+# Usage :
+#
+# First, you may need to install, python3-sympy and python3-pyparsing.
+#
+# Then, run br-int-flows-analyze.py --vm-uuid VM_UUID --ingress/--egress. It
+# should produce the rules that may handle ingress/egress traffic pertaining
+# to the VM followed by a summary of all the different paths the traffic may
+# take through the rules.
+#
+# Another way to run the tool is to use a combination of the --flow-file and
+# --fields flags, if you saved the dump generated by running
+# ovs-ofctl --names --no-stats --read-only --color=always --sort \
+#           dump-flows br-int
+# For example, running with a --flow-file
+# and --field in_port=IGNORE dl_vlan=2 dl_dst=fa:16:3e:d5:be:ff
+# Will start walking the tree, initialized with a cursor filtering-out rules
+# that :
+# - match any in_port (unless the port is called IGNORE)
+# - match a dl_vlan value different from 2
+# - match a dl_dst value different from fa:16:3e:d5:be:ff
+
 # 😱
-# Sorry, this parser is bugged and very poorly written, but it seems to work
-# well enough for our use-case.
+# Sorry, this parser is poorly written and probably bugged. Despite that, it
+# seems to work well enough for our current use-case.
 
 
 def mask_to_range(n, mask, width=None):