Agent skill

Ovs DB Analysis

by openshift-eng in openshift-eng/ai-helpers

Analyze Open vSwitch data from sosreport. An agent skill from openshift-eng/ai-helpers.

Apache-2.0Auto-check: notes

Install Ovs DB Analysis

skills CLI
$ npx skills add openshift-eng/ai-helpers --skill ovs-db-analysis -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install openshift-eng/ai-helpers ovs-db-analysis --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/openshift-eng/ai-helpers.git skills-src && mkdir -p .claude/skills && cp -r skills-src/plugins/sosreport/skills/ovs-db-analysis .claude/skills/ovs-db-analysis && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
ovs-db-analysis
GitHub stars
120
Token cost
~2.8k tokens
SKILL.md length
739 words
Files
2 (incl. scripts)
Skills in repo
118
Repo updated
First seen
Licence
Apache-2.0

At a glance

Analyze Open vSwitch data from sosreport. An agent skill from openshift-eng/ai-helpers.

  • Works in 7 steps: Locate the Analysis Script → Run the Analysis → Custom Queries (Optional, requires --db) → …
  • SKILL.md covers When to Use This Skill, Prerequisites, File Locations in Sosreport and Analysis Script, plus 8 more sections
  • Runs Python scripts from its folder; calls python3, dnf and apt

What it does

Ovs DB Analysis is an agent skill from openshift-eng/ai-helpers. Analyze Open vSwitch data from sosreport

Its SKILL.md is about 2.8k tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files, including scripts (for example `scripts/analyze_ovs_db.py`).

The repository describes itself as: Developer productivity tools for Claude Code & other AI assistants. The licence is Apache-2.0.

Example prompts

  • “/ovs-db-analysis”

Requirements

  • Python 3

Workflow steps

7 steps, taken from the step headings in SKILL.md.

  1. Locate the Analysis Script
  2. Run the Analysis
  3. Custom Queries (Optional, requires --db)
  4. Troubleshooting Packet Drops
  5. Checking DPDK Configuration
  6. Investigating Pod Connectivity
  7. Datapath Health Check

What it can do on your machine

Read from SKILL.md and the folder at commit a627176. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/ (Python), which the agent can run.

    Shell commands in SKILL.md call:

    • python3
    • dnf
    • apt

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • github.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Ovs DB Analysis loads about 2.8k tokens when it runs. Until then it costs about 14 tokens; SKILL.md has 739 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~14
When it runs · the whole SKILL.md, loaded when a task matches
~2.8k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NoteRuns commands with sudoSKILL.md:37
    - Fedora/RHEL: `sudo dnf install openvswitch`
  • NoteRuns commands with sudoSKILL.md:38
    - Ubuntu/Debian: `sudo apt install openvswitch-common`

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from openshift-eng/ai-helpers at commit a627176, republished under its Apache-2.0 licence (© openshift-eng). 739 words, ~2,840 tokens.

Download SKILL.mdSave it as .claude/skills/ovs-db-analysis/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
ovs-db-analysis
description
Analyze Open vSwitch data from sosreport

OVS Database and Flow Analysis

This skill provides detailed analysis of Open vSwitch (OVS) data collected via sosreport. It operates in four modes:

  1. Default mode: Full analysis - conf.db + all text files (requires ovsdb-tool, falls back to text files if not available)
  2. Database mode (--db): Database only - analyze conf.db (requires ovsdb-tool)
  3. Text files mode (--flows-only): Text files only - no ovsdb-tool needed
  4. Query mode (--query): Run custom OVSDB JSON queries (requires ovsdb-tool)

When to Use This Skill

Use this skill when:

  • Troubleshooting packet drops - Find drop flows being hit
  • Analyzing flow performance - View top flows by packet count
  • Analyzing OVS configuration from a sosreport
  • Troubleshooting bridge, port, or interface issues
  • Investigating DPDK vs kernelspace datapath
  • Reviewing tunnel configurations (VXLAN, Geneve, GRE)
  • Checking port statistics (drops, errors, traffic)
  • Mapping Kubernetes pods to OVS interfaces

Prerequisites

Default mode (full analysis):

  • ovsdb-tool must be installed (from openvswitch package)
  • Falls back to --flows-only if ovsdb-tool not found
  • Sosreport with sos_commands/openvswitch/ directory and conf.db

Database mode (--db):

  • ovsdb-tool must be installed (from openvswitch package)
    • Check: which ovsdb-tool
    • Fedora/RHEL: sudo dnf install openvswitch
    • Ubuntu/Debian: sudo apt install openvswitch-common
  • Sosreport with conf.db file

Text files mode (--flows-only):

  • No special tools needed - works out of the box!
  • Sosreport with sos_commands/openvswitch/ directory

Query mode (--query):

  • ovsdb-tool must be installed
  • Incompatible with --flows-only

File Locations in Sosreport

The sosreport collects:

sosreport-hostname-date/
├── etc/openvswitch/conf.db              (OVS database - for --db mode)
├── var/lib/openvswitch/conf.db          (alternate location)
└── sos_commands/openvswitch/            (default mode uses these)
    ├── ovs-vsctl_-t_5_show              (topology)
    ├── ovs-vsctl_-t_5_list_bridge       (bridge details)
    ├── ovs-vsctl_-t_5_list_interface    (interface details)
    ├── ovs-vsctl_-t_5_list_Open_vSwitch (system info)
    ├── ovs-ofctl_dump-flows_<bridge>    (OpenFlow entries)
    ├── ovs-ofctl_dump-ports_<bridge>    (Port statistics)
    ├── ovs-appctl_coverage.show         (internal stats)
    ├── ovs-appctl_upcall.show           (datapath health)
    ├── ovs-appctl_tnl.ports.show_-v     (tunnel ports)
    └── ...

Analysis Script

The analysis script is located at:

<plugin-root>/skills/ovs-db-analysis/scripts/analyze_ovs_db.py

Implementation Steps

Step 1: Locate the Analysis Script
bash
SCRIPT_PATH=$(find ~ -name "analyze_ovs_db.py" -path "*/sosreport/skills/ovs-db-analysis/scripts/*" 2>/dev/null | head -1)

if [ -z "$SCRIPT_PATH" ]; then
    echo "ERROR: analyze_ovs_db.py script not found."
    exit 1
fi
Step 2: Run the Analysis
bash
# Default: Full analysis - conf.db + text files (requires ovsdb-tool)
python3 "$SCRIPT_PATH" /path/to/sosreport-hostname-date/

# Analyze from archive
python3 "$SCRIPT_PATH" /path/to/sosreport-hostname-date.tar.xz

# Database only mode (requires ovsdb-tool)
python3 "$SCRIPT_PATH" /path/to/sosreport/ --db

# Text files only mode (no ovsdb-tool needed)
python3 "$SCRIPT_PATH" /path/to/sosreport/ --flows-only
Step 3: Custom Queries (Optional, requires --db)

For specific investigations, use raw OVSDB queries:

bash
# Query all bridges
python3 "$SCRIPT_PATH" /path/to/sosreport/ --query '["Open_vSwitch", {"op":"select", "table":"Bridge", "where":[], "columns":["name","datapath_type","fail_mode"]}]'

# Query VXLAN interfaces
python3 "$SCRIPT_PATH" /path/to/sosreport/ --query '["Open_vSwitch", {"op":"select", "table":"Interface", "where":[["type","==","vxlan"]], "columns":["name","options"]}]'

# Query interfaces with errors
python3 "$SCRIPT_PATH" /path/to/sosreport/ --query '["Open_vSwitch", {"op":"select", "table":"Interface", "where":[], "columns":["name","error"]}]'

Analysis Output

The default mode analyzes:

AnalysisSource FileDescription
System Infoovs-vsctl_-t_5_list_Open_vSwitchOVS/DPDK version, system type, external IDs
Topologyovs-vsctl_-t_5_showBridge overview with ports grouped by type
Bridge Detailsovs-vsctl_-t_5_list_bridgeDatapath type, fail mode, CT zones
Interfacesovs-vsctl_-t_5_list_interfaceBy type, pod interfaces with mapping
OpenFlowovs-ofctl_dump-flows_*Flow counts, drops, top flows
Port Statsovs-ofctl_dump-ports_*RX/TX drops and errors
Tunnelsovs-appctl_tnl.ports.show_-vConfigured tunnel ports
Datapath Healthovs-appctl_upcall.showFlow table usage vs limit
OVS Statsovs-appctl_coverage.showInternal counters (netlink, OVSDB, etc.)

OpenFlow Analysis Features

FeatureDescription
Flow CountTotal flows per bridge (total, drop, with hits)
Drop DetectionFlows with actions=drop that have packet hits
Top FlowsMost active flows sorted by n_packets
Table DistributionFlow counts per OpenFlow table
Port DropsRX/TX drop counters per port
Port ErrorsRX/TX error counters per port
Datapath HealthFlow table usage vs limit (from upcall.show)
OVS StatsInternal statistics (netlink, OpenFlow, OVSDB transactions)
Show full SKILL.md (332 more words)Show less

OVN Internal Tables (Ignore Drops in These)

When analyzing drop flows in OVN-managed bridges (br-int), ignore drops in table 44 and tables 64-87 as these are internal OVN mechanics, not security policy or real packet drops.

⚠️ Note: OVN and OVS are complex systems and table mappings can change between releases. Always verify drop analysis against the specific OVN version in use. When in doubt, check the OVN source code for your release.

TableNamePurpose
44CHK_LB_OUTPUTLoopback prevention - drops packets that would loop back (high volume, normal)
64SAVE_INPORTSave ingress port for later
65LOG_TO_PHYLogical to physical mapping
66MAC_BINDINGMAC binding lookups
67MAC_LOOKUPMAC address table lookups
68-69CHK_LB_HAIRPINLoad balancer hairpin checks
70CT_SNAT_HAIRPINConntrack SNAT hairpin
71-72GET/LOOKUP_FDBFDB (forwarding DB) lookups
73-74CHK_IN_PORT_SECIngress port security
75CHK_OUT_PORT_SECEgress port security
76-77ECMP_NHECMP next-hop handling
78CHK_LB_AFFINITYLoad balancer affinity
79MAC_CACHE_USEMAC cache miss (high volume, normal)
80CT_ZONE_LOOKUPConntrack zone lookup
81-83CT_ORIG_*_LOADConntrack original tuple loading
84FLOOD_REMOTE_CHASSISRemote chassis flooding
85CT_STATE_SAVEConntrack state save
86CT_ORIG_PROTO_LOADConntrack protocol loading
87GET_REMOTE_FDBRemote FDB lookup

Relevant drop tables for troubleshooting:

  • Table 9: Ingress ACLs - actual policy drops (look for reg0=0x8000)
  • Table 0: Initial classification drops
  • Tables < 64: Generally meaningful drops

Common Analysis Scenarios

1. Troubleshooting Packet Drops
bash
# Quick analysis (default mode, no ovsdb-tool)
python3 "$SCRIPT_PATH" /path/to/sosreport/

Look for:

  • ACTIVE DROP FLOWS section showing flows dropping packets
  • PORT STATISTICS showing ports with drops/errors
2. Checking DPDK Configuration
bash
# Default mode shows DPDK info from text files
python3 "$SCRIPT_PATH" /path/to/sosreport/

# Or use database mode for custom queries
python3 "$SCRIPT_PATH" /path/to/sosreport/ --query '["Open_vSwitch", {"op":"select", "table":"Open_vSwitch", "where":[], "columns":["dpdk_initialized","other_config"]}]'
3. Investigating Pod Connectivity

The interface analysis shows pod-to-OVS mapping:

  • Interfaces with external_ids containing iface-id
  • Interface names ending with _h (veth host side)
4. Datapath Health Check

The upcall stats show:

DATAPATH FLOW TABLE HEALTH
  Current flows: 155 / 200,000 (0.1% used)
  Average: 156, Max seen: 215
  ✓ Flow table healthy

If usage > 90%, flows are being evicted too aggressively.

Output Example

================================================================================
OVS ANALYSIS - sosreport-hostname-2024-01-15
================================================================================
Mode: Text file analysis (no ovsdb-tool required)

================================================================================
OVS SYSTEM INFORMATION
================================================================================

  Field                     Value
  ------------------------- --------------------------------------------------
  OVS Version               "3.3.4-62.el9fdp"
  DB Version                "8.5.0"
  System Type               rhcos
  System Version            "4.16"
  DPDK Initialized          false
  Datapath Types            [netdev, system]

  External IDs:
    hostname: master2.example.com
    ovn-encap-ip: 10.32.110.5
    ovn-encap-type: geneve

================================================================================
OVS TOPOLOGY
================================================================================

  System UUID: 7e9a3f70-86fa-4578-a849-4fd807a64a10
  Total Bridges: 2

  Bridge: br-ex
    ports: 3
      internal: br-ex
      patch: patch-br-ex-to-br-int
      system: nm-bond

  Bridge: br-int
    fail_mode: secure
    datapath_type: system
    ports: 12
      geneve: 9 ports
      internal: ovn-k8s-mp0, br-int
      patch: patch-br-int-to-br-ex

================================================================================
OPENFLOW ANALYSIS
================================================================================

  Bridge: br-int
  ----------------------------------------------------------------------
  Total flows: 2,017
  Flows with hits: 318
  Drop flows: 150 (9 actively dropping)

  ⚠️  ACTIVE DROP FLOWS (9):
    table=40, priority=0, packets=8,105
    table=79, priority=100, packets=1,356
      match: ip,reg14=0x2,metadata=0x5,dl_src=00:62:0b:ea:b5:e0

--------------------------------------------------------------------------------
DATAPATH FLOW TABLE HEALTH
--------------------------------------------------------------------------------

  Current flows: 155 / 200,000 (0.1% used)
  Average: 156, Max seen: 215
  ✓ Flow table healthy

Error Handling

ErrorSolution
ovsdb-tool not foundInstall openvswitch package OR use default mode (no --db)
conf.db not foundUse default mode (analyzes text files instead)
sos_commands/openvswitch not foundEnsure sosreport has OVS data collected

See Also

© openshift-eng, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file (scripts) in plugins/sosreport/skills/ovs-db-analysis of openshift-eng/ai-helpers.

  • SKILL.md
  • scripts/analyze_ovs_db.py

Open the folder on GitHubat commit a627176

Compare with similar skills

Ovs DB Analysis next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Ovs DB Analysis compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Ovs DB Analysis this skillopenshift-eng/ai-helpers120—~2.8kAutomated safety check: NotesApache-2.0
Stage ComposeOrkas-AI/Orkas-VideoStudio498—~4.2kAutomated safety check: PassMIT
System Config Analysisopenshift-eng/ai-helpers120—~4kAutomated safety check: PassApache-2.0
Resource Analysisopenshift-eng/ai-helpers120—~3.4kAutomated safety check: PassApache-2.0
Network Analysisopenshift-eng/ai-helpers120—~3.7kAutomated safety check: PassApache-2.0
Logs Analysisopenshift-eng/ai-helpers120—~2.6kAutomated safety check: PassApache-2.0

Similar skills

  • Stage Compose

    Orkas-AI/Orkas-VideoStudio

    Authoring knowledge for Orkas/OVS HTML video compositions -- write an index.html, drive animation from a paused timeline, declare canvas + duration, then run the VideoStudio draft gate to render an…

    498 GitHub stars~4.2k tokensUpdated 16 days ago
    Media & CreativeAuto-check passed
  • System Config Analysis

    openshift-eng/ai-helpers

    Analyze system configuration data from sosreport archives, extracting OS details, installed packages, systemd service status, SELinux/AppArmor policies, and kernel parameters from the sosreport…

    120 GitHub stars~4k tokensUpdated 2 days ago
    DevOps & CloudAuto-check passed
  • Resource Analysis

    openshift-eng/ai-helpers

    Analyze system resource usage data from sosreport archives, extracting memory statistics, CPU load averages, disk space utilization, and process information from the sosreport directory structure to…

    120 GitHub stars~3.4k tokensUpdated 2 days ago
    Data & AnalyticsAuto-check passed
  • Network Analysis

    openshift-eng/ai-helpers

    Analyze network configuration data from sosreport archives, extracting interface configurations, routing tables, active connections, firewall rules (firewalld/iptables), and DNS settings from the…

    120 GitHub stars~3.7k tokensUpdated 2 days ago
    DevOps & CloudAuto-check passed
  • Logs Analysis

    openshift-eng/ai-helpers

    Analyze system and application log data from sosreport archives, extracting error patterns, kernel panics, OOM events, service failures, and application crashes from journald logs and traditional…

    120 GitHub stars~2.6k tokensUpdated 2 days ago
    DevelopmentAuto-check passed

More from openshift-eng/ai-helpers

All 118 skills in this repo
  • Investigate CI Reliability

    openshift-eng/ai-helpers

    Find and independently validate actionable reliability defects across OpenShift release jobs and presubmits, then export portable issue handoffs.

    120 GitHub stars~1.9k tokensUpdated 2 days ago
    Auto-check passed
  • Address Review PR

    openshift-eng/ai-helpers

    Fetch and address all PR review comments — categorize by priority, make code changes, post replies, and push.

    120 GitHub stars~2.9k tokensUpdated 2 days ago
    Auto-check passed
  • Categorize Activity Types

    openshift-eng/ai-helpers

    Categorize Jira issues into Red Hat Sankey Activity Type categories using MCP Jira tools.

    120 GitHub stars~2.4k tokensUpdated 2 days ago
    Auto-check passed
  • Has Review Work

    openshift-eng/ai-helpers

    Decide whether a GitHub PR has unanswered authorized review comments or new required CI failures worth a follow-up agent.

    120 GitHub stars~1.9k tokensUpdated 2 days ago
    Auto-check passed
  • Must Gather Analyzer

    openshift-eng/ai-helpers

    Analyze OpenShift must-gather diagnostic data including cluster operators, pods, nodes, and network components.

    120 GitHub stars~2.3k tokensUpdated 2 days ago
    Auto-check passed
  • Payload Autodl JSON

    openshift-eng/ai-helpers

    Schema for the autodl JSON data file produced by payload-analysis for database ingestion — you must use this skill whenever generating the autodl JSON file

    120 GitHub stars~2.6k tokensUpdated 2 days ago
    Auto-check passed

Questions about Ovs DB Analysis

What does Ovs DB Analysis do?

Analyze Open vSwitch data from sosreport. An agent skill from openshift-eng/ai-helpers. Ovs DB Analysis is an agent skill from openshift-eng/ai-helpers.

How do I install Ovs DB Analysis in Claude Code?

Run `npx skills add openshift-eng/ai-helpers --skill ovs-db-analysis -a claude-code`. Or copy the skill folder (plugins/sosreport/skills/ovs-db-analysis in openshift-eng/ai-helpers) into .claude/skills/ovs-db-analysis in your project. Claude Code loads it when a task matches its description.

How do I install Ovs DB Analysis in Codex?

Run `npx skills add openshift-eng/ai-helpers --skill ovs-db-analysis -a codex`. Or copy the skill folder (plugins/sosreport/skills/ovs-db-analysis in openshift-eng/ai-helpers) into .agents/skills/ovs-db-analysis in your project. Codex loads it when a task matches its description.

Can I use Ovs DB Analysis in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add openshift-eng/ai-helpers --skill ovs-db-analysis -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/ovs-db-analysis, .gemini/skills/ovs-db-analysis, .github/skills/ovs-db-analysis and .opencode/skills/ovs-db-analysis in your project.

What does Ovs DB Analysis need to run?

Going by SKILL.md and its folder, Ovs DB Analysis needs Python for the scripts in its folder and the command-line tools its instructions call (python3, dnf and apt). Our summary lists: Python 3.

Does Ovs DB Analysis access the network?

SKILL.md names 1 domain. As links in the text: github.com. This is read from the text; nothing was executed.

Is Ovs DB Analysis safe to install?

Our automated static check of SKILL.md found notes only (runs commands with sudo), nothing it rates as a warning. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Ovs DB Analysis use?

Ovs DB Analysis is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Ovs DB Analysis use?

About 2.8k tokens (SKILL.md is roughly 11k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Ovs DB Analysis?

Skills that share tags, products or a category with Ovs DB Analysis: Stage Compose (Orkas-AI/Orkas-VideoStudio, 498 stars), System Config Analysis (openshift-eng/ai-helpers, 120 stars), Resource Analysis (openshift-eng/ai-helpers, 120 stars) and Network Analysis (openshift-eng/ai-helpers, 120 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Ovs DB Analysis?

openshift-eng (a GitHub organization) maintains it in openshift-eng/ai-helpers, which has 120 GitHub stars. The repository holds 118 skills in this directory. The repository was last updated on October 6, 2026.

Source: openshift-eng/ai-helpers on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.