Networking NVIDIA UFM Enterprise REST API Guide

Topology Model Validation REST API

Topology Model Validation compares UFM's in-memory topology model against OpenSM's subnet database dump (opensm-smdb.dump, the source of truth) and reports where the two sides disagree. A single run checks:

  1. Active links — systems and port pairs must match between the dump and UFM.

  2. Hosts — number of hosts and their descriptions.

  3. Per-host module/port counts — number of ports and HCA modules after multinic consolidation.

  4. Switches and routers — counts and links.

  5. Node/port inventory divergence (divergence section, schema v2) — every node and port that is missing (SM has it, UFM doesn't), stale (UFM has it, SM doesn't), or mismatch (both have it, but a comparable attribute differs).

  6. Port labels and CA node descriptions — warning-only checks that do not affect the overall pass/fail status.

Each run is persisted as a timestamped JSON report. Older reports are pruned automatically based on the configured retention count.

Limitation: Host-level comparisons (hosts, per-host module/port counts, CA node descriptions) are not supported when [Server] multinic_host_mode = legacy, because legacy aggregation merges several SM CA nodes into a single UFM host device. A run requested in this mode is refused with HTTP 501 Not Implemented; link, switch and router checks are unaffected by this restriction.

Error Responses

HTTP Status

Meaning

400 – Bad Request

Invalid request body/parameter (e.g. bad report_id format, invalid configure value)

409 – Conflict

A validation run is already in progress

501 – Not Implemented

Validation is not supported under multinic_host_mode = legacy

500 – Internal Server Error

Unexpected error


REST APIs to Manage Topology Model Validation

Start a Topology Model Validation Run

Triggers one validation run (UFM model vs. OpenSM dump) as a background job. Only one run may be in progress at a time.

Request URL: /ufmRest/app/topology_model_validation/start

Method: POST

Status Codes: 202 – Accepted (redirects to the created job); 409 – Conflict (a run is already in progress); 501 – Not Implemented (legacy multinic host mode)

Example:

curl -k -u admin:123456 -X POST -H "Content-Type: application/json" https://[UFM_Server_name_or_IP]/ufmRest/app/topology_model_validation/start

This action is asynchronous. UFM responds with a redirect to the newly created job:

<!doctype html>
<html lang=en>
<title>Redirecting...</title>
<h1>Redirecting...</h1>
<p>You should be redirected automatically to the target URL: <a href="/ufmRest/jobs/1">/ufmRest/jobs/1</a>. If not, click the link.

Check the job status using the job ID from the redirect target:

curl -k -u admin:123456 -X GET https://[UFM_Server_name_or_IP]/ufmRest/jobs/1

Response:

{
    "ID": "1",
    "Status": "Completed",
    "Progress": 100,
    "Description": "Topology model validation",
    "Created": "2026-10-12 14:50:43",
    "LastUpdated": "2026-10-12 14:50:43",
    "Summary": "{\"report_id\": \"2026-10-12-17-50-43\", \"status\": \"Completed successfully\"}",
    "RelatedObjects": "",
    "CreatedBy": "admin",
    "Operation": "Topology model validation",
    "Foreground": true,
    "SiteName": ""
}

Once Status reaches a terminal state (Completed, Completed with Errors, or Exception/Failed), the Summary field contains a JSON-encoded string with the generated report_id and the run's overall status. Use report_id with GET /<report_id> (or simply GET /last_report) to retrieve the full report.


Check Validation Run Status

Returns whether a validation run is currently in progress, and the id of the most recently completed report.

Request URL: /ufmRest/app/topology_model_validation/status

Method: GET

Status Codes: 200 – OK

Example:

curl -k -u admin:123456 -X GET -H "Content-Type: application/json" https://[UFM_Server_name_or_IP]/ufmRest/app/topology_model_validation/status

Response:

{
    "busy": false,
    "last_report_id": "2026-10-12-17-50-43"
}

Field

Description

busy

true while a validation run (started via /start) is executing; false otherwise

last_report_id

id of the most recently completed report, or null if none exists yet


List Stored Validation Reports

Returns metadata for every report currently retained on disk, oldest first. The retention count is controlled by max_reports_saved (see Update Configuration below); older reports are pruned automatically.

Request URL: /ufmRest/app/topology_model_validation/

Method: GET

Status Codes: 200 – OK

Example:

curl -k -u admin:123456 -X GET -H "Content-Type: application/json" https://[UFM_Server_name_or_IP]/ufmRest/app/topology_model_validation/

Response:

[
    {
        "report_id": "2026-10-12-17-50-43",
        "timestamp": "2026-10-12-17-50-43",
        "mtime": 1791816643.1320791
    }
]

Field

Description

report_id

report identifier; usable with GET /<report_id>

timestamp

same value as report_id — when the run completed (local time, YYYY-MM-DD-HH-MM-SS)

mtime

report file's last-modified time (Unix epoch seconds)


Get the Last Validation Report

Returns the most recently completed validation report in full.

Request URL: /ufmRest/app/topology_model_validation/last_report

Method: GET

Status Codes: 200 – OK; 404 – Not Found (no report has completed yet)

Example:

curl -k -u admin:123456 -X GET -H "Content-Type: application/json" https://[UFM_Server_name_or_IP]/ufmRest/app/topology_model_validation/last_report

Response:

{
    "schema_version": 2,
    "divergence": {
        "summary": {
            "nodes_missing": 0,
            "nodes_stale": 0,
            "nodes_mismatched": 0,
            "ports_missing": 0,
            "ports_stale": 0,
            "ports_mismatched": 0
        },
        "nodes": { "missing": [], "stale": [], "mismatch": [] },
        "ports": { "missing": [], "stale": [], "mismatch": [] },
        "detail_limit_per_bucket": 1000,
        "bucket_metadata": {
            "nodes": {
                "missing": { "total_count": 0, "retained_count": 0, "omitted_count": 0, "truncated": false, "fingerprint_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" },
                "stale": { "total_count": 0, "retained_count": 0, "omitted_count": 0, "truncated": false, "fingerprint_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" },
                "mismatch": { "total_count": 0, "retained_count": 0, "omitted_count": 0, "truncated": false, "fingerprint_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" }
            },
            "ports": {
                "missing": { "total_count": 0, "retained_count": 0, "omitted_count": 0, "truncated": false, "fingerprint_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" },
                "stale": { "total_count": 0, "retained_count": 0, "omitted_count": 0, "truncated": false, "fingerprint_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" },
                "mismatch": { "total_count": 0, "retained_count": 0, "omitted_count": 0, "truncated": false, "fingerprint_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" }
            }
        },
        "fingerprint_sha256": "64803347305dfb68a2891cfd7231b88fa324580020558553c842b31e5db7930c"
    },
    "timestamp": "2026-10-12-17-50-43",
    "dump_file": "/opt/ufm/files/log/opensm-smdb.dump",
    "multinic_mode": "derived",
    "warnings": [],
    "summary": {
        "dump_active_links": 3,
        "ufm_active_links": 3,
        "dump_hosts": 3,
        "ufm_hosts": 3,
        "dump_switches": 1,
        "ufm_switches": 1,
        "dump_routers": 0,
        "ufm_routers": 0,
        "port_label_warnings": 0,
        "node_description_warnings": 0
    },
    "gaps": {
        "links": { "dump_active_links": 3, "ufm_active_links": 3, "count_match": true, "missing_in_ufm": [], "missing_in_dump": [] },
        "hosts": { "dump_hosts": 3, "ufm_hosts": 3, "count_match": true, "hosts_only_in_dump": [], "hosts_only_in_ufm": [], "supported": true },
        "multinic": { "module_count_mismatches": [], "port_count_mismatches": [] },
        "switches": { "dump_switches": 1, "ufm_switches": 1, "count_match": true },
        "routers": { "dump_routers": 0, "ufm_routers": 0, "count_match": true }
    },
    "port_label_warnings": { "label_mismatches": [] },
    "node_description_warnings": {
        "supported": true,
        "unsupported_reason": null,
        "scope": "Only CA node descriptions are compared. UFM parses a switch description (MF0;<name>:<type>/U<n>) down to the system name and does not keep what the SM reported, so the two sides hold no comparable string for it.",
        "compared_nodes": 3,
        "description_mismatches": []
    },
    "snapshot": {
        "capture_attempts": 1,
        "capture_started_at": "2026-10-12T14:50:43Z",
        "capture_completed_at": "2026-10-12T14:50:43Z",
        "smdb": { "mtime_ns": 1791816582993978186, "size_bytes": 3905, "inode": 1459461, "device": 2050, "stable_during_capture": true },
        "ufm_model_consistency": "best_effort",
        "ufm_model_consistency_note": "Only the SMDB dump file was verified unchanged during the capture. The UFM model was read live and is not fenced, so the two sides are not guaranteed to come from the same SM sweep."
    },
    "status": "Completed successfully"
}

Report Field Reference

Field

Description

schema_version

version of the divergence section's schema (currently 2)

timestamp

when the run completed, local time (YYYY-MM-DD-HH-MM-SS); this is the report's id

dump_file

path of the OpenSM dump file used for this run

multinic_mode

live [Server] multinic_host_mode at the time of the run: derived, off, or legacy

warnings

reserved for free-form run warnings; currently always empty

status

overall result: Completed successfully, Completed with warnings, or Completed with errors

summary

high-level counts compared between the dump and UFM (see below)

gaps

per-category comparison detail: links, hosts, multinic, switches, routers (see below)

divergence

schema v2 GUID-keyed node/port inventory divergence (see below)

port_label_warnings

warning-only port label mismatches between the dump and UFM (does not affect status pass/fail beyond upgrading it to "with warnings")

node_description_warnings

warning-only CA node description mismatches (same effect as above)

snapshot

provenance of the capture: dump file stat identity, capture attempts/timing, and whether the UFM model read is fenced

summary

Field

Description

dump_active_links / ufm_active_links

number of active links seen in the dump / in UFM

dump_hosts / ufm_hosts

number of hosts seen in the dump / in UFM

dump_switches / ufm_switches

number of switches seen in the dump / in UFM

dump_routers / ufm_routers

number of routers seen in the dump / in UFM

port_label_warnings

count of port label mismatches (see port_label_warnings section)

node_description_warnings

count of CA node description mismatches (see node_description_warnings section)

gaps

Field

Description

links.missing_in_ufm / missing_in_dump

active links present on one side only, rendered as human-readable <desc> (0x<guid>)/<port> <-> <desc> (0x<guid>)/<port> strings

hosts.hosts_only_in_dump / hosts_only_in_ufm

host display names present on one side only

hosts.supported

false in legacy multinic mode — host counts are still reported, but gap lists are empty and meaningless (see unsupported_reason)

multinic.module_count_mismatches / port_count_mismatches

per common host, {"host", "expected_*", "actual_*"} where expected = dump, actual = UFM

switches / routers

count_match plus the raw counts from each side

divergence (schema v2 — object-by-object GUID inventory)

Three buckets per object type (nodes, ports):

  • missing — the SM dump reports the object and UFM does not.

  • stale — UFM reports the object and the SM dump does not (excluding ports/nodes UFM itself already reports as down).

  • mismatch — both sides have the object, but a comparable attribute differs (node: node_type, system_guid; port: node_guid, state, lid).

Field

Description

divergence.summary.*

authoritative, complete counts for each bucket (nodes_missing, nodes_stale, nodes_mismatched, ports_missing, ports_stale, ports_mismatched) — always accurate regardless of the detail limit

divergence.nodes.* / divergence.ports.*

up to detail_limit_per_bucket individual records per bucket

detail_limit_per_bucket

detail records retained per bucket for this run (configurable, see max_divergence_details_per_bucket)

`bucket_metadata.<nodes

ports>..total_count`

bucket_metadata...retained_count / omitted_count

how many detail records were kept vs. dropped due to the limit

bucket_metadata...truncated

true if omitted_count > 0

bucket_metadata...fingerprint_sha256

SHA-256 over every issue in that bucket (not just the retained ones) — lets two runs be compared for an exact match even when details were truncated

fingerprint_sha256 (top of divergence)

SHA-256 over the full divergence result, for quick equality checks between runs

node_description_warnings

Field

Description

supported

false in legacy multinic mode

scope

explains that only CA (host) node descriptions are compared — UFM does not retain the SM-reported description for switches

compared_nodes

number of CA nodes compared

description_mismatches

list of CA nodes whose description differs between the dump and UFM

snapshot

Field

Description

capture_attempts

number of attempts needed to capture a stable dump (retries if the dump changed mid-read)

capture_started_at / capture_completed_at

UTC timestamps bounding the capture window

smdb

dump file identity (mtime_ns, size_bytes, inode, device) and stable_during_capture confirming it did not change during the read

ufm_model_consistency

always best_effort — only the dump file is verified unchanged; the live UFM model is read without being fenced

ufm_model_consistency_note

human-readable explanation of the above


Get a Specific Validation Report by ID

Returns a previously stored report by its report_id (as returned by GET / or in a completed job's Summary).

Request URL: /ufmRest/app/topology_model_validation/<report_id>

Method: GET

Status Codes: 200 – OK; 400 – Bad Request (report_id does not match the expected format YYYY-MM-DD-HH-MM-SS, optionally suffixed with -<n> when two runs complete within the same second); 404 – Not Found (no report exists for that id)

Example:

curl -k -u admin:123456 -X GET -H "Content-Type: application/json" https://[UFM_Server_name_or_IP]/ufmRest/app/topology_model_validation/2026-10-12-17-50-43

Response: identical structure to GET /last_report above (the response is the same report, just selected by id instead of "most recent").


Get Topology Model Validation Configuration

Returns the feature's current configuration.

Request URL: /ufmRest/app/topology_model_validation/configure

Method: GET

Status Codes: 200 – OK

Example:

curl -k -u admin:123456 -X GET -H "Content-Type: application/json" https://[UFM_Server_name_or_IP]/ufmRest/app/topology_model_validation/configure

Response:

{
    "periodic_enabled": false,
    "periodic_interval_minutes": 60,
    "max_reports_saved": 10,
    "dump_file": "/opt/ufm/files/log/opensm-smdb.dump",
    "max_sync_retries": 3,
    "max_divergence_details_per_bucket": 1000
}

Field

Type

Default

Description

periodic_enabled

boolean

false

when true, a validation run is scheduled automatically every periodic_interval_minutes

periodic_interval_minutes

integer ≥ 1

60

interval between periodic runs, in minutes

max_reports_saved

integer ≥ 1

10

number of reports retained on disk; older reports are pruned once this is exceeded

dump_file

string

/opt/ufm/files/log/opensm-smdb.dump

path to the OpenSM dump file compared against UFM's model; must resolve under /opt/ufm/files

max_sync_retries

integer ≥ 1

3

maximum capture attempts before a run fails because the dump file kept changing while being read

max_divergence_details_per_bucket

integer, 0–10000

1000

number of individual divergence records retained per bucket in the divergence section (complete counts/fingerprints are unaffected)


Update Topology Model Validation Configuration

Updates one or more configuration parameters. Only the parameters included in the request body are changed; omitted parameters keep their current value. Changes are persisted to gv.cfg ([TopologyModelValidation] section) and take effect immediately — no restart required.

Request URL: /ufmRest/app/topology_model_validation/configure

Method: POST

Status Codes: 202 – Accepted; 400 – Bad Request (invalid value, or the change could not be persisted, e.g. a read-only gv.cfg in Kubernetes deployments)

Example:

curl -k -u admin:123456 -X POST -H "Content-Type: application/json" https://[UFM_Server_name_or_IP]/ufmRest/app/topology_model_validation/configure -d '{ "max_reports_saved": 9 }'

This action is synchronous and returns no response body on success (202 Accepted).

Payload parameters (all optional — include only the ones you want to change):

Field

Type

Validation

periodic_enabled

boolean

—

periodic_interval_minutes

integer

≥ 1

max_reports_saved

integer

≥ 1; older reports are pruned immediately if the new value is lower than the current report count

dump_file

string

non-empty; must resolve under /opt/ufm/files

max_sync_retries

integer

≥ 1

max_divergence_details_per_bucket

integer

0–10000

Last updated: