OVS-FLOWVIZ(8)                   Open vSwitch                   OVS-FLOWVIZ(8)

NAME
       ovs-flowviz - utility for visualizing OpenFlow and datapath flows

SYNOPSIS
       ovs-flowviz  [-i [alias,]file | --input [alias,]file] [-c file | --con‐
       fig file] [-f filter | --filter filter] [-l filter |  --highlight  fil‐
       ter] [--style style] flow-type format [args…]

       ovs-flowviz --help

DESCRIPTION
       ovs-flowviz helps visualize OpenFlow and datapath flow dumps in differ‐
       ent formats in order to make them more easily understood.

       ovs-flowviz  reads  flows  from  stdin  or from a file specified by the
       --input option, filters them, highlights them, and finally outputs them
       in one of the predefined formats.

OPTIONS
       -h, --help
              Print a brief help message to the console.

       -i [<alias>,]<file>, --input [<alias>,]<file>
              File to read flows from. If not provided, ovs-flowviz will  read
              flows from stdin.

              This  option can be specified multiple times.  The file path can
              prepended by an alias that will be shown in the output.  For ex‐
              ample: --input node1,/path/to/file1 --input node2,/path/to/file2

       -c <file>, --config <file>
              Style configuration file to use,  overriding  the  default  one.
              Styles  defined  in the style configuration file can be selected
              using the --style option.

              For more details on the style configuration file, see the  Style
              Configuration File section below.

       -f <filter>, --filter <filter>
              Flow filter expression. Only those flows matching the expression
              will be shown (although some formats implement filtering differ‐
              ently, see the Datapath tree format section below).

              The filtering syntax is detailed in Filtering Syntax.

       -l <filter>, --highlight <filter>
              Highlight the flows that match the provided filter expression.

              The filtering syntax is detailed in Filtering Syntax.

       --style <style>
              Style.  The selected style must be defined in the style configu‐
              ration file.

       flow-type
              openflow or datapath.

       format See the Supported formats section.

SUPPORTED FORMATS
       ovs-flowviz supports several visualization formats  for  both  OpenFlow
       and datapath flows:
                   ─────────────────────────────────────────────
                     Flow Type   Format    Description
                   ─────────────────────────────────────────────
                     Both        console   Prints the flows in
                                           a     configurable,
                                           colorful  style  in
                                           the console.
                   ─────────────────────────────────────────────
                     Both        json      Prints the flows in
                                           JSON format.
                   ─────────────────────────────────────────────
                     Both        html      Prints the flows in
                                           an HTML list.
                   ─────────────────────────────────────────────
                     OpenFlow    cookie    Prints the flows in
                                           the  console sorted
                                           by cookie.
                   ─────────────────────────────────────────────
                     OpenFlow    logic     Prints the  logical
                                           structure  of flows
                                           in the console.
                   ─────────────────────────────────────────────
                     Datapath    tree      Prints the flows as
                                           a  tree   structure
                                           arranged   by   re‐
                                           circ_id         and
                                           in_port.
                   ─────────────────────────────────────────────
                     Datapath    graph     Prints  a  graphviz
                                           graph of the  flows
                                           arranged   by   re‐
                                           circ_id         and
                                           in_port.
                   ┌───────────┬─────────┬─────────────────────┐
                   │           │         │                     │
   Console format  │           │         │                     │
       The console format works│for both OpenFlow and datapath flow types, and
       prints  flows in the terminal using the style determined│by the --style
       option.     │           │         │                     │
                   │           │         │                     │
       Arguments:  │           │         │                     │
                   │           │         │                     │
       -h, --heat-map          │         │                     │
              Color│of the packet and byte counters to reflect their  relative
              size.│  The  color  gradient  goes through the following colors:
              blue (coldest, lowest), cyan, green, yellow, red (hottest, high‐
              est) │           │         │                     │
                   │           │         │                     │
              Note filtering is│applied before the range is calculated.
                   │           │         │                     │
   JSON format     │           │         │                     │
       The json format works for both OpenFlow and datapath  flow  types,  and
       prints  flows  in JSON format. See│the JSON Syntax section for more de‐
       tails.      │           │         │                     │
                   │           │         │                     │
   HTML format     │           │         │                     │
       The html format works for both OpenFlow and datapath flows, and  prints
       flows  in  an HTML table│that offers some basic interactivity. OpenFlow
       flows are sorted in tables and datapath  flows  are  arranged  in  flow
       trees (see Datapath tree│format for more details).      │
                   │           │         │                     │
       Styles  defined  via  Style Configuration File and selected via --style
       option also apply to the│html format.                   │
                   │           │         │                     │
   OpenFlow cookie format      │         │                     │
       The OpenFlow│cookie format is similar to the console format but instead
       of arranging│the flows by table, it arranges the flows by cookie.
                   │           │         │                     │
   OpenFlow logic format       │         │                     │
       The OpenFlow│logic format helps visualize the logic structure of  Open‐
       Flow pipelines by arranging flows into logical blocks.  A logical block
       is a set of flows that have:      │                     │

       • Same priority.

       • Match on the same fields (regardless of the match value and mask).

       • Execute  the  same actions (regardless of the actions’ arguments, ex‐
         cept for resubmit and output).

       • Optionally, the cookie can be included as part of the logical flow.

       Arguments:

       -s, --show-flows
              Show all the flows under each logical block.

       -d, --ovn-detrace
              Use ovn-detrace.py script to extract cookie information (implies
              ‘-c’).

       -c, --cookie
              Consider the cookie in the logical block.

       --ovn-detrace-path <path>
              Use an alternative path to search for ovn_detrace.py.

       --ovnnb-db <conn>
              OVN NB database  connection  method  (implies  ‘-d’).   Default:
              “unix:/var/run/ovn/ovnnb_db.sock”.

       --ovnsb-db <conn>
              OVN  SB  database  connection  method  (implies ‘-d’).  Default:
              “unix:/var/run/ovn/ovnsb_db.sock”.

       --o <filter>, --ovn-filter <filter>
              Specify the filter to be run  on  the  ovn-detrace  information.
              Syntax:        python        regular       expression       (See
              https://docs.python.org/3/library/re.html).

       -h, --heat-map
              Change the color of the packet  and  byte  counters  to  reflect
              their relative size. The color gradient goes through the follow‐
              ing  colors:  blue  (coldest,  lowest), cyan, green, yellow, red
              (hottest, highest)

              Note filtering is applied before the range is calculated.

   Datapath tree format
       The datapath tree format arranges  datapath  flows  in  a  hierarchical
       tree.   The  tree  is  comprised  of blocks with the same recirc_id and
       in_port.  Within those blocks, flows with the same action are combined.
       And matches which are the same are omitted to reduce the visual noise.

       When a flow’s actions includes the recirc() action with a specific  re‐
       circ_id,  flows  matching  on  that  recirc_id and the same in_port are
       listed below. This is done recursively for all actions.

       The result is a hierarchical representation that shows how actions  are
       related  to  each  other via recirculation. Note that flows with a spe‐
       cific non-zero recirc_id are listed below each group of flows that have
       a corresponding recirc() action. Therefore, the output contains  dupli‐
       cated flows and can be verbose.

       Filtering  works  in  a slightly different way for datapath flow trees.
       Unlike other formats where a filter simply removes non-matching  flows,
       the  output  of  a filtered datapath flow tree will show full sub-trees
       that contain at least one flow that satisfies the filter.

       The html format prints this same tree as an interactive HTML table  and
       the graph format shows the same tree as a graphviz graph.

   Datapath graph format
       The  datapath  graph  generates a graphviz visual representation of the
       same tree-like flow hierarchy that the tree format prints.

       Arguments:

       -h, --html
              Print the graphviz format as an svg image alongside an  interac‐
              tive HTML table of flows.

JSON SYNTAX
       Printing  a  single-file  OpenFlow  or datapath dump without PMD thread
       blocks in json format results in a list of JSON  objects,  each  repre‐
       senting a flow.

       This  list  can be found inside one or more levels of JSON dictionaries
       if multiple files are processed (filename used as key) or if PMD thread
       blocks are found in datapath flows (name of the thread used as key).

       Each flow object includes the following keys:

       orig   Original flow string.

       info   Object with the flow information such as: cookie, duration,  ta‐
              ble, n_packets, n_bytes, etc.

       match  Object with the flow match.  For each match, the object contains
              a key-value where the key is the name of the match as defined in
              ovs-fields(7)  and  ovs-ofctl(8),  and  the value represents the
              match value. The way each value is represented  depends  on  its
              type. See Value representation.

       actions
              List  of  action objects.  Each action is represented by an JSON
              object that has one key and one value.  The key  corresponds  to
              the  action name. The value represents the arguments of the key.
              See Action representation.

       ufid   The UFID (datapath flows only).

   Value representation
       Values are represented differently depending on their type:

       • Flags: The value of flags is true.

       • Decimal / Hexadecimal: Represented by their integer value.   If  they
         support  masking,  represented  by  a dictionary with two keys: value
         contains the field value and mask contains the mask.  Both are  inte‐
         gers.

       • Ethernet: Represented by a string: {address}[/{mask}]

       • IPv4 / IPv6: Represented by a string {address}[/{mask}]

       • Registers:  Represented  by a dictionary with three keys: field` con‐
         tains the field value (string), start, and end  represent  the  first
         and last bit of the register value.

       For example, the register

          NXM_NX_REG10[0..15]

       is represented as

          {
              "field": "NXM_NX_REG10",
              "start": 0,
              "end": 15
          },

   Action representation
       Actions  are  generally  represented by an object that has a single key
       and value. The key is the action name as defined ovs-actions(7).

       The value of actions that have no arguments (such as drop) is (boolean)
       true.

       The value of actions  that  have  a  list  of  arguments  (e.g:  resub‐
       mit([port],[table],[ct]))  is  an object that has the name of the argu‐
       ment as key. The argument names for each action is defined  in  ovs-ac‐
       tions. For example, the action

          resubmit(,10)

       is represented as

          {
              "resubmit": {
                  "port": "",
                  "table": 10
              }
          }

       The  value  of  actions  that  have  a key-word list as arguments (e.g:
       ct([argument])) is an object whose keys correspond to the keys  defined
       in  ovs-actions(7).  The way values are represented depends on the type
       of the argument.  For example, the action

          ct(table=14,zone=NXM_NX_REG12[0..15],nat)

       is represented as

          {
              "ct": {
                  "table": 14,
                  "zone": {
                      "field": "NXM_NX_REG12",
                      "start": 0,
                      "end": 15
                  },
                  "nat": true
              }
          }

STYLE CONFIGURATION FILE
       The style configuration file is selected via the  --config  option  and
       has  INI  syntax. It can define any number of styles to be used by both
       console and html formats. Once defined in the configuration file,  for‐
       mats are selected using the --style option.

       INI  sections  are  used  to  define styles, [styles.mystyle] defines a
       style called mystle. Within a section styles can be defined as:

          [FORMAT].[PORTION].[SELECTOR].[ELEMENT] = [VALUE]

       FORMAT Either console or html

       PORTION
              Part of the key-value the style applies to: key to indicate  the
              key  part  of a key-value, value to indicate the value part of a
              key-value, flag to indicate a single flag or delim  to  indicate
              delimiters such as parentheses, brackets, etc.

       SELECTOR
              Select  the key-value the style applies to: highlighted to indi‐
              cate highlighted key-values,  type.<type>  to  indicate  certain
              types such as IPAddress or EthMask or <keyname> to select a par‐
              ticular key name.

       ELEMENT
              Select the style element to modify: color or underline (only for
              console format).

       VALUE  Ether  a color hex, other color names defined in the rich python
              library                                                       (‐
              https://rich.readthedocs.io/en/stable/appendix/colors.html)   or
              true if the element is underline.

       A default configuration file is shipped with ovs-flowviz and  its  path
       is  printed  in the --help output. A detailed description of the syntax
       alongside some examples are available there.

FILTERING SYNTAX
       ovs-flowviz provides rich highlighting and filtering. The special  com‐
       mand ovs-flowviz filter dumps the filtering syntax:

          $ ovs-flowviz filter
          Filter Syntax
          *************

             [! | not ] {key}[[.subkey]...] [OPERATOR] {value})] [LOGICAL OPERATOR] ...

            Comparison operators:
                =   equality
                <   less than
                >   more than
                ~=  masking (valid for IP and Ethernet fields)

            Logical operators:
                !{expr}:  NOT
                {expr} && {expr}: AND
                {expr} || {expr}: OR

            Matches and flow metadata:
                To compare against a match or info field, use the field directly, e.g:
                    priority=100
                    n_bytes>10
                Use simple keywords for flags:
                    tcp and ip_src=192.168.1.1

            Actions:
                Actions values might be dictionaries, use subkeys to access individual
                values, e.g:
                    output.port=3
                Use simple keywords for flags
                    drop

            Examples of valid filters:
                nw_addr~=192.168.1.1 && (tcp_dst=80 || tcp_dst=443)
                arp=true && !arp_tsa=192.168.1.1
                n_bytes>0 && drop=true

       Example expressions:

          n_bytes > 0 and drop
          nw_src~=192.168.1.1 or arp.tsa=192.168.1.1
          ! tcp && output.port=2

EXAMPLES
       Print OpenFlow flows sorted by cookie adding OVN data to each one:

          $ ovs-flowviz -i flows.txt openflow cookie --ovn-detrace

       Print OpenFlow logical structure, showing the flows and heat-map:

          $ ovs-flowviz -i flows.txt openflow logic --show-flows --heat-map

       Display  OpenFlow flows in HTML format with “light” style and highlight
       drops:

          $ ovs-flowviz -i flows.txt --style "light" --highlight "n_packets > 0 and drop" openflow html > flows.html

       Display the datapath flows in an interactive graphviz + HTML view:

          $ ovs-flowviz -i flows.txt datapath graph --html > flows.html

       Display the datapath flow trees that lead to packets being sent to port
       10:

          $ ovs-flowviz -i flows.txt --filter "output.port=10" datapath tree

AUTHOR
       The Open vSwitch Development Community

COPYRIGHT
       2016-2024, The Open vSwitch Development Community


3.5                              Feb 17, 2025                   OVS-FLOWVIZ(8)