From efca596141ccf93e4b6941c93cb58edae93fbc54 Mon Sep 17 00:00:00 2001 From: Guillaume Espanel Date: Wed, 10 Nov 2021 17:53:23 +0100 Subject: [PATCH] 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 | 55 ++++++++++++++++++++++++- 1 file changed, 53 insertions(+), 2 deletions(-) diff --git a/contrib/neutron/br-int-flows-analyze.py b/contrib/neutron/br-int-flows-analyze.py index 66cdb78..cd2ec25 100644 --- a/contrib/neutron/br-int-flows-analyze.py +++ b/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):