ovs-dpctl-top(8)

💅 ovs-dpctl-top — the Open vSwitch manual page, bestie edition

okay so you know top, right? the little live dashboard that shows you what your machine is Doing? Yeah. This is that, but for ovs-dpctl dump-flows. It's called ovs-dpctl-top, it lives in the Open vSwitch manual, and it's genuinely iconic. Let's go. ✨

---

🌸 NAME 🌸

ovs-dpctl-top — top-like behavior for ovs-dpctl dump-flows

---

🦋 SYNOPSIS 🦋

ovs-dpctl-top [-h] [-v] [-f FLOWFILES] [-V] [-s] [--host HOST] [-a |
--accumulate] [--accumulate-decay ACCUMULATEDECAY] [-d DELAY]

---

✨ DESCRIPTION ✨

So this program takes everything ovs-dpctl dumps about your flows and summarizes it — it aggregates the number of packets, the total bytes, and how often each of these fields shows up: 👑

• Datapath in_port
• Ethernet type
• Source and destination MAC addresses
• IP protocol
• Source and destination IPv4 addresses
• Source and destination IPv6 addresses
• UDP and TCP destination port
• Tunnel source and destination addresses

---

Output shows four values:

• FIELDS: the flow fields, like in_port(1).
• COUNT: how many lines in the dump-flow output contain that flow field.
• PACKETS: the total number of packets containing that flow field.
• BYTES: the total number of bytes containing that flow field. If units aren't present, the values are in bytes.
• AVERAGE: the average packet size, which is BYTES/PACKET.

🎀 Top Behavior

While you're in top mode — which is the default behavior, no cap — these single-character commands are at your disposal, bestie:

• a — toggles top in accumulate and live mode. (Accumulate mode is described below, don't worry.)
• s — toggles which column is used to sort content in decreasing order. A DESC title gets placed over that column. 💅
• _ — a space indicating to collect dump-flow content again.
• h — halt output. Any character will restart sampling.
• f — cycle through flow fields.
• q — q for quit.

💜 Accumulate Mode

There are two supported modes: live and accumulate. The default is live. The parameter --accumulate, or the a character while you're in top mode, enables the latter.

In live mode, recent dump-flow content is presented. Whereas accumulate mode keeps track of the prior historical information — until the flow is reset, not when the flow is purged. Reset flows are determined when the packet count for a flow has decreased from its previous sample.

⚠️ One caveat, and this one's lowkey important: eventually the system will run out of memory because, after the accumulate-decay period, any flows that have not been refreshed are purged. The goal here is to free memory of flows that aren't active. Statistics are not decremented — their purpose is to reflect the overall history of the flow fields. 🫶

🔥 Debugging Errors

Parsing errors get counted and displayed in the status line at the beginning of the output. If you want to see exactly what output did not get parsed, run the --verbose option together with --script, like this:

$ ovs-dpctl dump-flows | ovs-dpctl-top --script --verbose

Error messages will identify content that failed to parse. So helpful. 😭

🌈 Access Remote Hosts

The --host must follow the format user@hostname. This script simply calls ssh user@Hostname without checking for login credentials — so public keys should be installed on the system identified by hostname, like so:

$ ssh-copy-id user@hostname

Consult the ssh-copy-id man pages for more details. iykyk. 🧚

⭐ Expected usage

$ ovs-dpctl-top

or to run as a script:

$ ovs-dpctl dump-flows > dump-flows.log

$ ovs-dpctl-top --script --flow-file dump-flows.log

---

👑 OPTIONS 👑

• -h, --help — show this help message and exit. classic.
• -v, --version — show program's version number and exit.
• -f FLOWFILES, --flow-file FLOWFILES — file containing flows from ovs-dpctl dump-flow.
• -V, --verbose — enable debug level verbosity.
• -s, --script — run from a script (no user interface). main character energy for automation.
• --host HOST — specify a user@host for retrieving flows. See Accessing Remote Hosts above for more info.
• -a, --accumulate — accumulate dump-flow content.
• --accumulate-decay ACCUMULATEDECAY — decay old accumulated flows. The default is 5 minutes. A value of 0 disables decay entirely.
• -d DELAY, --delay DELAY — delay in milliseconds to collect dump-flow content (that's your sample rate, bestie).

---

okay that's literally the whole page, bestie, you ate it 💖 this was the Open vSwitch manual, version 4.0.0, for ovs-dpctl-top(8) — go forth and watch those flows, periodt. 🎀🦋✨