Tia Zanella

Posted on Apr 10 • Originally published at osirisjson.org

OSIRIS JSON Producer for Cisco

#cisco #opensource #solutionarchitects #topology

The OSIRIS JSON Cisco producer connects to Cisco infrastructure platforms (APIC, NX-OS, IOS-XE) and generates OSIRIS JSON snapshots of your network topology, devices, interfaces, and connections.

Install the core dispatcher and the Cisco producer:

go install go.osirisjson.org/producers/cmd/osirisjson-producer@latest
go install go.osirisjson.org/producers/cmd/osirisjson-producer-cisco@latest

The core dispatcher lets you run osirisjson-producer cisco .... Without it, invoke the vendor binary directly as osirisjson-producer-cisco ....

Make sure $GOPATH/bin (or $HOME/go/bin) is in your PATH. See the getting started page for more install options.

Supported platforms

    ACI / APIC

    available

  Application Policy Infrastructure Controller

  Transport: REST API




    NX-OS

    available

  Nexus data center switches

  Transport: NX-API CLI




    IOS-XE

    available

  Enterprise routers and switches

  Transport: NETCONF/YANG over SSH

CLI usage

The Cisco producer uses a dispatcher-style CLI with sub-producers:

osirisjson-producer cisco <subcommand> [flags]

Single mode

Connect to one device and save an OSIRIS JSON document as cisco-<type>-<timestamp>-<hostname>.json:

# ACI fabric snapshot via APIC
osirisjson-producer cisco apic -h 10.0.0.1 -u admin -p secret

# NX-OS device snapshot
osirisjson-producer cisco nxos -h switch01.example.com -u admin -p secret

# IOS-XE device snapshot
osirisjson-producer cisco iosxe -h router01.example.com -u admin --insecure

If -p / --password is omitted, the CLI prompts interactively.

Batch mode

Collect from multiple devices listed in a CSV file. Output is organized as a hierarchical directory structure: DC/Floor/Room/Zone/Hostname.json.

osirisjson-producer cisco apic -s datacenter.csv -o ./output -u admin -p secret

Generate a CSV template to get started:

osirisjson-producer cisco template --generate apic

The CSV template uses these columns:

Column	Required	Description
`dc`		Datacenter name (used for output folder hierarchy)
`floor`		Floor identifier
`room`		Room identifier
`zone`		Zone or pod identifier
`hostname`	yes	Device label used as output filename
`type`	yes	Producer type: `apic`, `nxos`, `iosxe`
`ip`	yes	IP address or FQDN of the target device
`port`		Override port (default: producer-specific)
`owner`		`self` (default), `isp`, or `colo` - operator metadata only
`notes`		Free-text notes (ignored by producer)

Credentials are provided via -u/-p flags and apply to all targets in the batch.

Flags reference

Single mode flags

Flag	Short	Description
`--host`	`-h`	Target host (IP or FQDN, optionally with `:port`)
`--username`	`-u`	Username for authentication
`--password`	`-p`	Password (omit for interactive prompt)
`--port`	`-P`	Override port (default: producer-specific)
`--detail`		Detail level: `minimal` (default) or `detailed`
`--insecure`		Skip TLS certificate verification
`--safe-failure-mode`		Secret handling: `fail-closed` (default), `log-and-redact`, `off`

Batch mode flags

Flag	Short	Description
`--source`	`-s`	CSV file with targets
`--output`	`-o`	Output directory (hierarchical: `DC/Floor/Room/Zone/Hostname.json`)
`--username`	`-u`	Default username for all targets
`--password`	`-p`	Default password for all targets

Global flags

Flag	Description
`--version` / `-v`	Display version and exit
`--help`	Display help and exit

What each platform collects

ACI / APIC

The APIC producer queries the following MO classes via the REST API:

Minimal mode:

MO Class	Description
`fabricNode`	Fabric nodes (controllers, spines, leafs)
`topSystem`	System attributes (uptime, state, fabric MAC, control plane MTU)
`firmwareRunning`	Running firmware versions
`fvTenant`	Tenant definitions
`fvCtx`	VRF contexts
`fvBD`	Bridge domains
`fvSubnet`	Subnets
`fvAEPg`	Application endpoint groups
`l3extOut`	L3 external connectivity
`faultInst`	Active fault instances

Detailed mode adds:

MO Class	Description
`fvCEp`	Client endpoints (MAC, VLAN encap, leaf attachment)

NX-OS

The NX-OS producer sends NX-API CLI commands in batched requests:

Minimal mode:

Command	Description
`show version`	Device model, serial number, OS version, uptime
`show inventory`	Hardware inventory (modules, power supplies, fans)
`show interface brief`	Interface names, states, speeds, VLANs
`show vlan brief`	VLAN IDs, names, and member interfaces
`show vrf all detail`	VRF definitions and member interfaces
`show lldp neighbors detail`	LLDP neighbor discovery
`show vpc brief`	vPC domain, peer status, keepalive
`show port-channel summary`	Port-channel configurations

Detailed mode adds:

Command	Description
`show interface`	Full interface stats (MTU, bandwidth, duplex, counters)
`show system resources`	CPU idle %, memory usage, load averages
`show environment`	Power supplies, fan status, temperatures

IOS-XE

The IOS-XE producer uses NETCONF/YANG RPCs over SSH (default port 830):

Minimal mode:

YANG Model	Description
`Cisco-IOS-XE-native`	Device version and hostname
`ietf-interfaces`	Interface details
`Cisco-IOS-XE-device-hardware-oper`	Hardware inventory
`Cisco-IOS-XE-cdp-oper`	CDP neighbor discovery
`Cisco-IOS-XE-native (vrf)`	VRF definitions

Detailed mode adds:

YANG Model	Description
`Cisco-IOS-XE-bgp-oper`	BGP neighbor details
`Cisco-IOS-XE-ospf-oper`	OSPF process and neighbor state
`Cisco-IOS-XE-process-cpu-oper`	CPU utilization
`Cisco-IOS-XE-memory-oper`	Memory statistics

OSIRIS JSON output structure

All three producers emit the same OSIRIS JSON envelope:

{
  "$schema": "https://osirisjson.org/schema/v1.0/osiris.schema.json",
  "version": "1.0.0",
  "metadata": {
    "generator": {
      "name": "osirisjson-producer-cisco-<platform>",
      "version": "0.1.0"
    },
    "scope": {
      "providers": ["cisco"]
    }
  },
  "topology": {
    "resources": [ ... ],
    "connections": [ ... ],
    "groups": [ ... ]
  }
}

Resource types by platform

Resource types follow the OSIRIS JSON v1.0 specification. Standard types are used where defined; vendor-specific types use the osiris.cisco.* namespace.

IOS-XE:

network.router - Primary device (standard)
network.interface - Physical and logical interfaces (standard)
osiris.cisco.interface.lag - Port-channel / LAG interfaces

NX-OS:

osiris.cisco.switch.spine / osiris.cisco.switch.leaf - Device (role-classified)
network.interface - Physical and logical interfaces (standard)
osiris.cisco.interface.lag - Port-channels

APIC:

osiris.cisco.controller - APIC controllers
osiris.cisco.switch.spine / osiris.cisco.switch.leaf - Fabric switches
osiris.cisco.domain.bridge - Bridge domains
network.subnet - Subnets (standard)
osiris.cisco.l3out - L3 external networks
osiris.cisco.endpoint - Client endpoints (detailed mode only)

Connection types

IOS-XE / NX-OS: physical.ethernet for CDP/LLDP-discovered links between interfaces
APIC: contains for tenant hierarchy containment, network for bridge domain associations

Group types by platform

IOS-XE: logical.vrf

NX-OS: logical.vrf, network.vlan, network.vpc

APIC: logical.tenant, logical.vrf, osiris.cisco.epg

Connection discovery

IOS-XE discovers neighbors via CDP (Cisco Discovery Protocol)
NX-OS discovers neighbors via LLDP (Link Layer Discovery Protocol)
APIC uses containment hierarchy (tenants -> BDs -> subnets -> EPGs) rather than point-to-point links

Remote devices discovered via CDP/LLDP are added as stub resources with status: unknown.

Examples

IOS-XE - single device, minimal mode

osirisjson-producer cisco iosxe -h 10.99.0.1 -u admin -p secret

Output (trimmed):

{
  "$schema": "https://osirisjson.org/schema/v1.0/osiris.schema.json",
  "version": "1.0.0",
  "metadata": {
    "generator": {
      "name": "osirisjson-producer-cisco-iosxe",
      "version": "0.1.0"
    },
    "scope": {
      "providers": ["cisco"]
    }
  },
  "topology": {
    "resources": [
      {
        "id": "cisco-iosxe-LAB-RTR01",
        "type": "network.router",
        "name": "LAB-RTR01",
        "status": "active",
        "provider": {
          "name": "cisco",
          "type": "ISR4451-X/K9",
          "version": "16.9"
        },
        "extensions": {
          "osiris.cisco": {
            "inventory": [
              { "name": "Chassis", "description": "ISR4451-X/K9", "serial": "FDO12345678" }
            ]
          }
        }
      },
      {
        "id": "cisco-iosxe-LAB-RTR01-GigabitEthernet0/0/0",
        "type": "network.interface",
        "name": "GigabitEthernet0/0/0",
        "status": "active",
        "properties": {
          "speed": "1000000000",
          "description": "WAN uplink"
        }
      }
    ],
    "connections": [
      {
        "source": "cisco-iosxe-LAB-RTR01-GigabitEthernet0/0/0",
        "target": "cisco-iosxe-stub-REMOTE-SW01-GigabitEthernet1/0/1",
        "type": "physical.ethernet",
        "status": "active"
      }
    ],
    "groups": [
      {
        "id": "cisco-iosxe-LAB-RTR01-vrf-CORP",
        "type": "logical.vrf",
        "name": "CORP",
        "members": [
          "cisco-iosxe-LAB-RTR01-GigabitEthernet0/0/0",
          "cisco-iosxe-LAB-RTR01-Loopback0"
        ]
      }
    ]
  }
}

NX-OS - single device, detailed mode

osirisjson-producer cisco nxos -h switch01.lab -u admin -p secret --detail detailed

Output (trimmed):

{
  "$schema": "https://osirisjson.org/schema/v1.0/osiris.schema.json",
  "version": "1.0.0",
  "metadata": {
    "generator": {
      "name": "osirisjson-producer-cisco-nxos",
      "version": "0.1.0"
    },
    "scope": {
      "providers": ["cisco"]
    }
  },
  "topology": {
    "resources": [
      {
        "id": "cisco-nxos-LAB-SW01",
        "type": "osiris.cisco.switch.leaf",
        "name": "LAB-SW01",
        "status": "active",
        "provider": {
          "name": "cisco",
          "type": "Nexus9000 C9508",
          "version": "10.3(4a)"
        },
        "extensions": {
          "osiris.cisco": {
            "bios_version": "08.40",
            "kernel_uptime": "15d 3h 22m 10s",
            "cpu_idle": 85.5,
            "load_avg_1min": 1.23,
            "memory_used": 8192,
            "memory_free": 24576,
            "power_supplies": [
              { "id": "1", "model": "NXA-PAC-1100W", "watts": 350, "status": "ok" }
            ],
            "fans": [
              { "name": "Fan1", "status": "ok" }
            ],
            "temperatures": [
              { "sensor": "SUP slot 1", "celsius": 35.5 }
            ]
          }
        }
      },
      {
        "id": "cisco-nxos-LAB-SW01-Ethernet1/1",
        "type": "network.interface",
        "name": "Ethernet1/1",
        "status": "active",
        "properties": {
          "speed": "10000000000",
          "description": "Server-facing"
        }
      }
    ],
    "connections": [
      {
        "source": "cisco-nxos-LAB-SW01-Ethernet1/1",
        "target": "cisco-nxos-stub-REMOTE-SW01-Ethernet1/49",
        "type": "physical.ethernet",
        "status": "active"
      }
    ],
    "groups": [
      {
        "id": "cisco-nxos-LAB-SW01-vlan-100",
        "type": "network.vlan",
        "name": "PROD",
        "members": ["cisco-nxos-LAB-SW01-Ethernet1/1"]
      },
      {
        "id": "cisco-nxos-LAB-SW01-vpc-10",
        "type": "network.vpc",
        "name": "vPC domain 10",
        "extensions": {
          "osiris.cisco": {
            "role": "primary",
            "peer_status": "peer-ok",
            "keepalive_status": "peer-alive"
          }
        }
      }
    ]
  }
}

APIC - ACI fabric snapshot

osirisjson-producer cisco apic -h 10.0.0.1 -u admin -p secret --detail detailed

Output (trimmed):

{
  "$schema": "https://osirisjson.org/schema/v1.0/osiris.schema.json",
  "version": "1.0.0",
  "metadata": {
    "generator": {
      "name": "osirisjson-producer-cisco-apic",
      "version": "0.1.0"
    },
    "scope": {
      "providers": ["cisco"]
    }
  },
  "topology": {
    "resources": [
      {
        "id": "cisco-apic-apic1",
        "type": "osiris.cisco.controller",
        "name": "apic1",
        "status": "active",
        "provider": {
          "name": "cisco",
          "type": "APIC-SERVER-M3",
          "version": "6.0(2h)",
          "site": "pod-1"
        }
      },
      {
        "id": "cisco-apic-spine1",
        "type": "osiris.cisco.switch.spine",
        "name": "spine1",
        "status": "active",
        "provider": {
          "name": "cisco",
          "type": "N9K-C9336C-FX2",
          "version": "n9000-16.0(2h)",
          "site": "pod-1"
        },
        "extensions": {
          "osiris.cisco": {
            "fabric_mac": "AA:BB:CC:DD:EE:01",
            "control_plane_mtu": 9000,
            "faults": [
              { "code": "F1527", "severity": "warning", "description": "storage full" }
            ]
          }
        }
      },
      {
        "id": "cisco-apic-bd-bd_App",
        "type": "osiris.cisco.domain.bridge",
        "name": "bd_App",
        "status": "active"
      },
      {
        "id": "cisco-apic-subnet-10.0.0.1/24",
        "type": "network.subnet",
        "name": "10.0.0.1/24",
        "status": "active"
      },
      {
        "id": "cisco-apic-ep-AA:BB:CC:DD:EE:FF",
        "type": "osiris.cisco.endpoint",
        "name": "AA:BB:CC:DD:EE:FF",
        "status": "active",
        "properties": {
          "encap": "vlan-100",
          "leaf": "leaf1",
          "interface": "eth1/1"
        }
      }
    ],
    "groups": [
      {
        "id": "cisco-apic-tenant-tn_Example",
        "type": "logical.tenant",
        "name": "tn_Example",
        "children": [
          "cisco-apic-vrf-tn_Example-vrf_Main",
          "cisco-apic-epg-tn_Example-epg_WEB"
        ]
      },
      {
        "id": "cisco-apic-vrf-tn_Example-vrf_Main",
        "type": "logical.vrf",
        "name": "vrf_Main"
      },
      {
        "id": "cisco-apic-epg-tn_Example-epg_WEB",
        "type": "osiris.cisco.epg",
        "name": "epg_WEB",
        "members": ["cisco-apic-ep-AA:BB:CC:DD:EE:FF"]
      }
    ]
  }
}

Batch mode - multi-device collection

Create a CSV inventory file:

dc,floor,room,zone,hostname,type,ip,port,owner,notes
AMS-01,F3,R301,POD-A,apic-01,apic,10.10.1.1,,self,Primary controller
AMS-01,F3,R301,POD-A,nx-spine-01,nxos,10.10.1.10,,self,Spine switch
AMS-01,F3,R302,POD-B,xe-router-01,iosxe,172.16.0.1,,isp,PE router

Run the batch:

osirisjson-producer cisco apic -s inventory.csv -o ./output -u admin -p secret

The resulting output directory:

output/
  AMS-01/
    F3/
      R301/
        POD-A/
          apic-01.json
          nx-spine-01.json
      R302/
        POD-B/
          xe-router-01.json

Source: https://osirisjson.org/en/docs/producers/network/cisco

DEV Community

OSIRIS JSON Producer for Cisco

Supported platforms

CLI usage

Single mode

Batch mode

Flags reference

Single mode flags

Batch mode flags

Global flags

What each platform collects

ACI / APIC

NX-OS

IOS-XE

OSIRIS JSON output structure

Resource types by platform

Connection types

Group types by platform

Connection discovery

Examples

IOS-XE - single device, minimal mode

NX-OS - single device, detailed mode

APIC - ACI fabric snapshot

Batch mode - multi-device collection

Top comments (0)