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:
-
Active links — systems and port pairs must match between the dump and UFM.
-
Hosts — number of hosts and their descriptions.
-
Per-host module/port counts — number of ports and HCA modules after multinic consolidation.
-
Switches and routers — counts and links.
-
Node/port inventory divergence (
divergencesection, schema v2) — every node and port that ismissing(SM has it, UFM doesn't),stale(UFM has it, SM doesn't), ormismatch(both have it, but a comparable attribute differs). -
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 |
|
409 – Conflict |
A validation run is already in progress |
|
501 – Not Implemented |
Validation is not supported under |
|
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 |
|---|---|
|
|
|
|
|
id of the most recently completed report, or |
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 identifier; usable with GET /<report_id> |
|
|
same value as |
|
|
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 |
|---|---|
|
|
version of the |
|
|
when the run completed, local time ( |
|
|
path of the OpenSM dump file used for this run |
|
|
live |
|
|
reserved for free-form run warnings; currently always empty |
|
|
overall result: |
|
|
high-level counts compared between the dump and UFM (see below) |
|
|
per-category comparison detail: links, hosts, multinic, switches, routers (see below) |
|
|
schema v2 GUID-keyed node/port inventory divergence (see below) |
|
|
warning-only port label mismatches between the dump and UFM (does not affect |
|
|
warning-only CA node description mismatches (same effect as above) |
|
|
provenance of the capture: dump file stat identity, capture attempts/timing, and whether the UFM model read is fenced |
summary
|
Field |
Description |
|---|---|
|
|
number of active links seen in the dump / in UFM |
|
|
number of hosts seen in the dump / in UFM |
|
|
number of switches seen in the dump / in UFM |
|
|
number of routers seen in the dump / in UFM |
|
|
count of port label mismatches (see |
|
|
count of CA node description mismatches (see |
gaps
|
Field |
Description |
|---|---|
|
|
active links present on one side only, rendered as human-readable |
|
|
host display names present on one side only |
|
|
|
|
|
per common host, |
|
|
|
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 |
|---|---|
|
|
authoritative, complete counts for each bucket ( |
|
|
up to |
|
|
detail records retained per bucket for this run (configurable, see |
|
`bucket_metadata.<nodes |
ports>..total_count` |
|
|
how many detail records were kept vs. dropped due to the limit |
|
|
|
|
|
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 |
|
|
SHA-256 over the full divergence result, for quick equality checks between runs |
node_description_warnings
|
Field |
Description |
|---|---|
|
|
|
|
|
explains that only CA (host) node descriptions are compared — UFM does not retain the SM-reported description for switches |
|
|
number of CA nodes compared |
|
|
list of CA nodes whose description differs between the dump and UFM |
snapshot
|
Field |
Description |
|---|---|
|
|
number of attempts needed to capture a stable dump (retries if the dump changed mid-read) |
|
|
UTC timestamps bounding the capture window |
|
|
dump file identity ( |
|
|
always |
|
|
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 |
|---|---|---|---|
|
|
boolean |
|
when |
|
|
integer ≥ 1 |
|
interval between periodic runs, in minutes |
|
|
integer ≥ 1 |
|
number of reports retained on disk; older reports are pruned once this is exceeded |
|
|
string |
|
path to the OpenSM dump file compared against UFM's model; must resolve under |
|
|
integer ≥ 1 |
|
maximum capture attempts before a run fails because the dump file kept changing while being read |
|
|
integer, 0–10000 |
|
number of individual divergence records retained per bucket in the |
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 |
|---|---|---|
|
|
boolean |
— |
|
|
integer |
≥ 1 |
|
|
integer |
≥ 1; older reports are pruned immediately if the new value is lower than the current report count |
|
|
string |
non-empty; must resolve under |
|
|
integer |
≥ 1 |
|
|
integer |
0–10000 |
Last updated: