diff mbox

[ovs-dev] Documentation: Add a new topic document about ofproto/trace

Message ID 898b5a946c058a49264be840ac9d52a6846d0c08.1491215237.git.tredaelli@redhat.com
State Accepted
Headers show

Commit Message

Timothy Redaelli April 5, 2017, 11:10 a.m. UTC
Add a new document "Tracing packets inside Open vSwitch" that explains
how to use "ofproto/trace" to debug flows inside the vswitch.

Signed-off-by: Timothy Redaelli <tredaelli@redhat.com>
 Documentation/topics/index.rst   |   1 +
 Documentation/topics/tracing.rst | 128 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 129 insertions(+)
 create mode 100644 Documentation/topics/tracing.rst
diff mbox


diff --git a/Documentation/topics/index.rst b/Documentation/topics/index.rst
index fd42414..3c65e44 100644
--- a/Documentation/topics/index.rst
+++ b/Documentation/topics/index.rst
@@ -47,6 +47,7 @@  OVS
+   tracing
diff --git a/Documentation/topics/tracing.rst b/Documentation/topics/tracing.rst
new file mode 100644
index 0000000..bc45493
--- /dev/null
+++ b/Documentation/topics/tracing.rst
@@ -0,0 +1,128 @@ 
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+          http://www.apache.org/licenses/LICENSE-2.0
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+      Convention for heading levels in Open vSwitch documentation:
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+      Avoid deeper levels because they do not render well.
+Tracing packets inside Open vSwitch
+Open vSwitch (OVS) is a programmable software switch that can execute actions
+at per packet level. This document explains how to use the tracing tool
+to know what is happening with packets as they go through the data plane
+Packet Tracing
+In order to understand the tool, let's use the following flows as an
+    table=3,ip,tcp,tcp_dst=80,action=output:2
+    table=2,ip,tcp,tcp_dst=22,action=output:1
+    table=0,in_port=3,ip,nw_src=,action=resubmit(,2)
+    table=0,in_port=3,ip,nw_src=,action=resubmit(,3)
+.. note::
+    If you can't use a "real" OVS setup you can use ``ovs-sandbox``,
+    as described in :doc:`/tutorials/ovs-advanced`.
+The first line adds a rule in table 3 matching on TCP/IP packet with
+destination port 80 (HTTP). If a packet matches, the action is to output the
+packet on OpenFlow port 2.
+The second line is similar but matches on destination port 22. If a packet
+matches, the action is to output the packet on OpenFlow port 1.
+The next two lines matches on source IP addresses. If there is a match, the
+packet is submitted to table indicated as parameter to the resubmit() action.
+Now let's see if a packet from IP address and destination
+port 22 would really go to OpenFlow port 1::
+    $ ovs-appctl ofproto/trace br0 in_port=3,tcp,nw_src=,tcp_dst=22
+    Flow: tcp,in_port=3,vlan_tci=0x0000,dl_src=00:00:00:00:00:00,dl_dst=00:00:00:00:00:00,nw_src=,nw_dst=,nw_tos=0,nw_ecn=0,nw_ttl=0,tp_src=0,tp_dst=22,tcp_flags=0
+    bridge("br0")
+    -------------
+     0. ip,in_port=3,nw_src=, priority 32768
+        resubmit(,2)
+     2. tcp,tp_dst=22, priority 32768
+        output:1
+    Final flow: unchanged
+    Megaflow: recirc_id=0,tcp,in_port=3,nw_src=,nw_frag=no,tp_dst=22
+    Datapath actions: 1
+The first line is the trace command. The br0 is the bridge where the packet is
+going through. The next arguments describe the packet itself. For instance,
+the nw_src matches with the IP source address. All the packet fields are well
+documented in the `ovs-ofctl(8)`_ man-page.
+The second line shows the flow extracted from the packet described in the
+command line. Unspecified packet fields are zeroed.
+The second group of lines shows the packet's trip through bridge br0. We see,
+in table 0, the OpenFlow flow that the fields matched, along with its
+priority, followed by its actions, one per line. In this case, we see that
+this packet matches the flow that resubmit those packets to table 2.
+The "resubmit" causes a second lookup in OpenFlow table 2, described by the
+block of text that starts with "2.". In the second lookup we see that this
+packet matches the rule that outputs those packets to OpenFlow port #1.
+In summary, it is possible to follow the flow entries and actions until the
+final decision is made. At the end, the trace tool shows the Megaflow which
+matches on all relevant fields followed by the data path actions.
+Let's see what happens with the same packet but with another TCP destination
+    $ ovs-appctl ofproto/trace br0 in_port=3,tcp,nw_src=,tcp_dst=80
+    Flow: tcp,in_port=3,vlan_tci=0x0000,dl_src=00:00:00:00:00:00,dl_dst=00:00:00:00:00:00,nw_src=,nw_dst=,nw_tos=0,nw_ecn=0,nw_ttl=0,tp_src=0,tp_dst=80,tcp_flags=0
+    bridge("br0")
+    -------------
+     0. ip,in_port=3,nw_src=, priority 32768
+        resubmit(,2)
+     2. No match.
+        drop
+    Final flow: unchanged
+    Megaflow: recirc_id=0,tcp,in_port=3,nw_src=,nw_frag=no,tp_dst=0x40/0xffc0
+    Datapath actions: drop
+In the second group of lines, in table 0, you can see that the packet matches
+with the rule because of the source IP address, so it is resubmitted to the
+table 2 as before. However, it doesn't match any rule there. When the packet
+doesn't match any rule in the flow tables, it is called a table miss. The
+virtual switch table miss behavior can be configured and it depends on the
+OpenFlow version being used. In this example the default action was to drop the
+This document is heavily based on content from Flavio Bruno Leitner at Red Hat:
+- https://developers.redhat.com/blog/2016/10/12/tracing-packets-inside-open-vswitch/
+.. _ovs-ofctl(8): http://openvswitch.org/support/dist-docs/ovs-ofctl.8.html