UFM Topology Support

UFM Topology Support

Feature Summary

The UFM Topology feature allows CVT to read the UFM periodic topology file and use it in two ways:

1. Load directly -- load the UFM topology for cable validation without requiring a manually crafted PTP file.

2. Generate a stub PTP -- produce a Unified PTP Excel file from the UFM topology that users can enrich offline (add rack layout, IPs, server profiles) and re-upload.

This feature is available only when CVT runs as a UFM plugin (CV_UFM_PLUGIN_MODE=true). The topology source is the IBDM periodic topo file that UFM writes to disk at /opt/ufm/files/periodicTopo/master.topo.

Architecture

/opt/ufm/files/periodicTopo/master.topo
            |
            v
    TopoFileParser (topo_ib_file_parser.py)
            |
            v
  SwitchData / HostData / LinkData
            |
    +-------+-------+
    |               |
    v               v
Load for        UfmPtpGenerator
validation      (ufm_ptp_generator.py)
    |               |
    v               v
Active          unified_ptp.xlsx
Topology        (4 sheets)

Key Components

User Workflows

UI Walkthrough

UFM Tab in Load Topology Wizard

• The UFM tab appears in the Load Topology wizard only when CVT is running in UFM plugin mode (CV_UFM_PLUGIN_MODE=true).

• The tab provides two actions:

  • Load UFM Topology -- loads the UFM periodic topology directly for validation.

  • Generate PTP from UFM -- generates a stub PTP Excel file from the UFM topology, which the user can then download, edit offline, and re-upload.

• Optional enrichment inputs can be provided:

  • IP File -- maps hostnames to IP addresses (populates the IP column in the Nodes sheet).

  • HCA Mapping -- overrides the default mlx5_X port derivation for hosts with non-standard port naming.

  • Server Profile -- replaces the auto-generated Server Profile sheet entirely.

  • DNS toggle -- use hostnames for agent communication (default: true).

• hca_mapping and server_profile are mutually exclusive; providing both results in a 400 error.

Tab Visibility

• When CV_UFM_PLUGIN_MODE=false (standalone deployment), the UFM tab is hidden from the UI.

• The UI checks window["is_ufm"] to control tab visibility.

REST API Quick Reference

POST /topology/load/ufm

Load the UFM periodic topo file directly for validation.

Request body (all fields optional):

{ "ip_file": "uploads/topology/ip/fabric.ip", "hca_mapping": "uploads/topology/hca_mapping/mapping.csv", "server_profile": "uploads/topology/server_profile/profile.csv", "dns": true }

Response: 202 Accepted

Poll GET /topology/load/result for completion status.

POST /topology/generate/ptp

Generate a stub PTP xlsx from the UFM periodic topo file.

Request body (all fields optional):

{ "output": "my_fabric_ptp.xlsx", "ip_file": "uploads/topology/ip/fabric.ip", "hca_mapping": "uploads/topology/hca_mapping/mapping.csv", "server_profile": "uploads/topology/server_profile/profile.csv" }

Response: 202 Accepted

Poll GET /topology/load/result for completion. On success:

{ "status": "completed", "file": "ufm_ptp_20260311_143000.xlsx", "switches": 42, "hosts": 120, "links": 500, "warnings": [] }

Download via GET /files_manager/ptp/files/ufm_ptp_20260311_143000.xlsx.

Validation Rules

• hca_mapping and server_profile are mutually exclusive -- 400 if both provided.

• Both endpoints require CV_UFM_PLUGIN_MODE=true -- 400 otherwise.

• Both operations are asynchronous -- clients must poll for results.

Generated PTP File Format

The output follows the Unified PTP Excel format with four sheets:

Nodes Sheet

Links Sheet

DC Floor Layout Sheet

Headers only (empty stub for user to fill).

Server Profile Sheet

Auto-generated default mapping based on observed HCA indices:

Range determined from the maximum mlx5_X index observed across all host links. Overridden entirely if server_profile CSV is provided.

Data Transformation Rules

Configuration

Docker Volume Mount

The CVT container requires read-only access to UFM filesystem:

/opt/ufm/files:/opt/ufm/files:ro

Configured in conf/plugin/cablevalidation_shared_volumes.conf.

Prerequisites

1. UFM plugin mode enabled: CVT must be deployed as a UFM plugin with CV_UFM_PLUGIN_MODE=true.

2. UFM periodic topology file exists: UFM must have generated the topo file at the configured path.

3. Volume mount configured: The CVT container must have read access to /opt/ufm/files.

Last updated: June 03, 2026