Managing network devices

Note that this part of the documentation uses the old 6.4 CLI but equivalent 7.0 commands exist. Consult getting started with the CLI for more details.

Managing switches is an essential part of MetalSoft. MetalSoft will automatically configure switch ports depending on the intent expressed by the user in the infrastructure designer. For that to happen the switches must be added in the MetalSoft database.

The process of adding the switches to the MetalSoft database can be either automatic via ZTP or manual via the UI or the CLI.

• Registering switches using ZTP.

Note that via this CLI-based process the system only touches the ports towards the servers and the SVIs that will act as gateways but will not configure BGP sessions towards the spine network or routing tables. Those must be created manually configured on the switches prior or after adding the switches in the database but before provisioning on those switches. If the BGP session configuration is needed please use the ZTP process.

Getting switch details using the CLI

To list all the switches (to ascertain the switch ID), run the following:

metalcloud-cli network-device list
┌──────┬──────────────────────────────────────────┬──────┬─────────────────┬───────────────────┬──────────────────────────┬──────────────────┬────────┐
│ #    │ IDENTIFIER                               │ SITE │ ADDRESS         │ MAC               │ SERIAL                   │ DRIVER           │ STATUS │
├──────┼──────────────────────────────────────────┼──────┼─────────────────┼───────────────────┼──────────────────────────┼──────────────────┼────────┤
│ 229  │ pod01-leaf01                             │  558 │ 192.168.224.11  │ 00:00:00:00:00:00 │                          │ sonic_enterprise │ active │
│ 230  │ pod01-leaf02                             │  558 │ 192.168.224.12  │ 00:00:00:00:00:00 │                          │ sonic_enterprise │ active │
│ 231  │ pod01-leaf03                             │  558 │ 192.168.224.13  │ 00:00:00:00:00:00 │                          │ sonic_enterprise │ active │
│ 232  │ pod01-leaf04                             │  558 │ 192.168.224.14  │ 00:00:00:00:00:00 │                          │ sonic_enterprise │ active │
│ 233  │ pod02-leaf01                             │  558 │ 192.168.224.19  │ 00:00:00:00:00:00 │                          │ sonic_enterprise │ active │
│ 234  │ pod02-leaf02                             │  558 │ 192.168.224.20  │ 00:00:00:00:00:00 │                          │ sonic_enterprise │ active │
│ 235  │ pod02-leaf03                             │  558 │ 192.168.224.21  │ 00:00:00:00:00:00 │                          │ sonic_enterprise │ active │
│ 236  │ pod02-leaf04                             │  558 │ 192.168.224.22  │ 00:00:00:00:00:00 │                          │ sonic_enterprise │ active │
│ 237  │ pod01-spine01                            │  558 │ 192.168.224.17  │ 00:00:00:00:00:00 │                          │ sonic_enterprise │ active │
│ 238  │ pod01-spine02                            │  558 │ 192.168.224.18  │ 00:00:00:00:00:00 │                          │ sonic_enterprise │ active │
│ 239  │ pod02-spine01                            │  558 │ 192.168.224.25  │ 00:00:00:00:00:00 │                          │ sonic_enterprise │ active │
│ 240  │ pod02-spine02                            │  558 │ 192.168.224.26  │ 00:00:00:00:00:00 │                          │ sonic_enterprise │ active │
└──────┴──────────────────────────────────────────┴──────┴─────────────────┴───────────────────┴──────────────────────────┴──────────────────┴────────┘

To get some basic details about a switch use the following command. You can use both the switch id or the switch label (which is usually the same as the switch hostname).

metalcloud-cli network-device get 229
┌─────┬──────────────┬──────┬────────────────┬───────────────────┬────────┬──────────────────┬────────┐
│ #   │ IDENTIFIER   │ SITE │ ADDRESS        │ MAC               │ SERIAL │ DRIVER           │ STATUS │
├─────┼──────────────┼──────┼────────────────┼───────────────────┼────────┼──────────────────┼────────┤
│ 229 │ pod01-leaf01 │  558 │ 192.168.224.11 │ 00:00:00:00:00:00 │        │ sonic_enterprise │ active │
└─────┴──────────────┴──────┴────────────────┴───────────────────┴────────┴──────────────────┴────────┘

To get the switch configuration use the yaml format:

metalcloud-cli network-device get 229 --format yaml
id: "229"
revision: 1
status: active
siteid: 558
identifierstring: pod01-leaf01
description: ""
chassisidentifier: ""
country: ""
city: ""
sitemeta: ""
siteroom: ""
siterack: ""
rackpositionupperunit: 0
rackpositionlowerunit: 0
managementaddress: 192.168.224.11
managementaddressmask: 255.255.255.0
managementaddressgateway: 192.168.224.1
managementport: 22
syslogenabled: 0
username: admin
managementpassword: rqi|aes-cbc|usd4/N+CmvKyHRJiIiXnCpwxx1agbC2uR4O6VpvrW896dRKUF09t1PMODHVx/YOw
managementmacaddress: "00:00:00:00:00:00"
serialnumber: ""
driver: sonic_enterprise
position: leaf
orderindex: 10
tags: ""
readyforinitialconfiguration: 0
bootstrapreadinesscheckinprogress: 0
subnetoobid: 0
subnetoobindex: 0
requiresosinstall: false
bootstrapskipinitialconfiguration: 0
bootstrapexpectedpartnerhostname: ""
loopbackaddressipv4: null
loopbackaddressipv6: ""
asn: 65316
vtepaddressipv4: null
vtepaddressipv6: ""
mlagsystemmac: ""
mlagdomainid: 0
quarantinevlan: 5
defaultmtu: 0
variablesmaterializedforosassets: {}
secretsmaterializedforosassets: {}
bootstrapreadinesscheckresult: {}
isgateway: true
extensioninfo: null
links: []
additionalproperties: {}

Adding a switch using the CLI

To add a switch to the database using the CLI create a configuration file leaf_switch.yaml:

identifierString: iad1-bm-sw-01
siteName: test-site
provisionerType: evpnvxlanl2
provisionerPosition: leaf
driver: junos18
managementUsername: metalsoft
managementAddress: 10.72.0.61
managementPort: 22
managementProtocol: ssh
managementMACAddress: "00:00:00:00:00:00"
primaryWANIPv4SubnetPool: 192.168.253.0
primaryWANIPv4SubnetPrefixSize: 24
primaryWANIPv6SubnetPoolID: 3
primaryWANIPv6SubnetCIDR: fd9f:1a77:a3a0:0000:0000:0000:0000:0000/48
primarySANSubnetPool: 100.64.0.1
primarySANSubnetPrefixSize: 21
quarantineSubnetStart: 10.73.254.0
quarantineSubnetEnd: 10.73.254.63
quarantineSubnetPrefixSize: 26
quarantineSubnetGateway: 10.73.254.2
requiresOSInstall: false
isBorderDevice: true
isStorageSwitch: false
networkTypesAllowed:
- wan
- lan
- quarantine
managementPassword: ""
primaryWANIPv6SubnetPool: ""
primaryWANIPv6SubnetPrefixSize: 0

Add the new switch by running:

$ metalcloud-cli network-device create --config-source leaf_switch.yaml

Notes on parameters:

• management*: These properties must be set to allow MetalSoft access to the respective switch.
• provisionerType: can be one of evpnvxlanl2, vlan, vpls,lan.
• isBorderDevice: If set to true this switch can be used as part of an external connection
• isStorageSwitch: If set to true this switch can be used as part of SAN networks.
• quarantineSubnet*: These properties only apply if the legacy provisioning mode (PXE) is required. These define which subnet to use for the transient provisioning network.
• primaryWANIP*: These properties control the default WAN subnet that will be used. If one does not exist it will be created upon the creation of the switch.
• primarySAN*: These properties control the default SAN subnet that will be used. If one does not exist it will be created upon the creation of the switch.

Editing switch configurations using the CLI

1. Retrieve the current switch configuration and place it in a file

metalcloud-cli network-device get 229 -format yaml

2. Save the output to switch.yaml and edit the configuration file switch.yaml
3. Reconfigure the switch

metalcloud-cli network-device update -config-source switch.yaml

Deleting a switch using the CLI

1. If the switch is part of a pair first delete the pair. Refer to managing switch pairs for instructions.
2. Delete the switch

metalcloud-cli network-device delete 229

Network device properties for DCI and dual-stack overlays

Network devices support several properties that are important for Data Center Interconnect (DCI) and IPv6 overlay scenarios:

• Custom Variables — free-form key-value pairs that can be referenced in network device configuration templates. Useful for device-specific overrides.
• External VTEP IPv4 Address — the VTEP address reachable from remote sites. This may differ from the local VTEP address if NAT or a separate DCI underlay is used. Required for Fabric Interconnects.
• Loopback IPv6 Address — an IPv6 loopback address for the network device, used in dual-stack overlay configurations.
• VTEP IPv6 Address — the IPv6 VTEP address for VXLAN overlay networking with an IPv6 underlay.

These properties can be configured when adding or editing a network device via the Admin UI or the API:

curl -X PATCH "https://<your-server>/api/v2/network-devices/{id}" \
  -H "Content-Type: application/json" \
  -d '{
    "customVariables": {"role": "border-leaf"},
    "externalVtepAddress": "203.0.113.10",
    "loopbackAddressIpv6": "2001:db8::1",
    "vtepAddressIpv6": "2001:db8:vtep::1"
  }'

Creating switch pairs

To enable multi-chassis link aggregation on the switches, switch pairs must be created. Refer to managing switch pairs for more details.

SNMP monitoring

MetalSoft can subscribe to SNMP monitoring for network devices. Once enabled, the monitoring agent collects SNMP data and uses it to generate health summaries.

Enabling SNMP monitoring

# Enable for a single device
curl -X POST "https://<your-server>/api/v2/network-devices/{networkDeviceId}/actions/snmp-monitoring-subscribe" \
  -H "Authorization: Bearer <API_KEY>"

# Enable for multiple devices in one request
curl -X POST "https://<your-server>/api/v2/network-devices/actions/snmp-monitoring-subscribe/batch" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
    "networkDeviceIds": [229, 230, 231]
  }'

Disabling SNMP monitoring

# Disable for a single device
curl -X POST "https://<your-server>/api/v2/network-devices/{networkDeviceId}/actions/snmp-monitoring-unsubscribe" \
  -H "Authorization: Bearer <API_KEY>"

# Disable for multiple devices
curl -X POST "https://<your-server>/api/v2/network-devices/actions/snmp-monitoring-unsubscribe/batch" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
    "networkDeviceIds": [229, 230]
  }'

SNMP service management

Separate from monitoring, MetalSoft can enable or disable the SNMP service on the device itself:

curl -X POST "https://<your-server>/api/v2/network-devices/{networkDeviceId}/actions/snmp-service-enable" \
  -H "Authorization: Bearer <API_KEY>"

curl -X POST "https://<your-server>/api/v2/network-devices/{networkDeviceId}/actions/snmp-service-disable" \
  -H "Authorization: Bearer <API_KEY>"

Getting SNMP agent info

curl "https://<your-server>/api/v2/network-devices/snmp-monitoring/agent-info/batch?networkDeviceIds=229,230" \
  -H "Authorization: Bearer <API_KEY>"

Network device health monitoring

Getting the health summary

Returns the AI monitoring agent’s stored health analysis for a device, including severity, trend, suspected root causes, and notable events. Returns null if no analysis has been stored yet.

curl "https://<your-server>/api/v2/network-devices/{networkDeviceId}/health-summary" \
  -H "Authorization: Bearer <API_KEY>"

Health monitoring filter

Subscribe to real-time health monitoring events for the current user session via WebSocket:

curl "https://<your-server>/api/v2/network-devices/health-monitoring-filter" \
  -H "Authorization: Bearer <API_KEY>"

Configuration snapshots

MetalSoft can capture configuration snapshots from network devices. The target snapshot is the version the system reconciles toward; use sync-target-snapshot-with-latest-snapshot to accept the current running config as the new target.

Listing snapshots

curl "https://<your-server>/api/v2/network-devices/{networkDeviceId}/snapshots" \
  -H "Authorization: Bearer <API_KEY>"

Syncing target snapshot to the latest

curl -X POST "https://<your-server>/api/v2/network-devices/{networkDeviceId}/actions/sync-target-snapshot-with-latest-snapshot" \
  -H "Authorization: Bearer <API_KEY>"

Port management

Individual ports on a network device can be read and configured via the API.

Getting a port

curl "https://<your-server>/api/v2/network-devices/{networkDeviceId}/ports/{portId}" \
  -H "Authorization: Bearer <API_KEY>"

Getting and updating port desired-state config

# Get desired config
curl "https://<your-server>/api/v2/network-devices/{networkDeviceId}/ports/{portId}/config" \
  -H "Authorization: Bearer <API_KEY>"

# Update desired config (staged, applied on next reconcile)
curl -X PATCH "https://<your-server>/api/v2/network-devices/{networkDeviceId}/ports/{portId}/config" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
    "description": "uplink to spine"
  }'

Managing port IP addresses

IP addresses are managed per address family (ipv4 or ipv6):

# List IPv4 addresses on a port
curl "https://<your-server>/api/v2/network-devices/{networkDeviceId}/ports/{portId}/ipv4/addresses" \
  -H "Authorization: Bearer <API_KEY>"

# Add an IPv4 address
curl -X POST "https://<your-server>/api/v2/network-devices/{networkDeviceId}/ports/{portId}/ipv4/addresses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
    "address": "10.0.0.1",
    "prefixLength": 30
  }'

# Replace the full IPv4 address set on a port
curl -X PUT "https://<your-server>/api/v2/network-devices/{networkDeviceId}/ports/{portId}/ipv4/addresses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '[{"address": "10.0.0.1", "prefixLength": 30}]'

# Remove an IPv4 address
curl -X DELETE "https://<your-server>/api/v2/network-devices/{networkDeviceId}/ports/{portId}/ipv4/addresses/{ipId}" \
  -H "Authorization: Bearer <API_KEY>"

Port breakouts (Cumulus)

Port breakouts allow a single physical port to be split into multiple logical interfaces. This feature is currently supported on Cumulus devices.

Listing breakouts

curl "https://<your-server>/api/v2/network-devices/{networkDeviceId}/breakouts" \
  -H "Authorization: Bearer <API_KEY>"

Creating a breakout

curl -X POST "https://<your-server>/api/v2/network-devices/{networkDeviceId}/breakouts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
    "portName": "swp1",
    "groups": [
      {"speed": "10G", "count": 4}
    ]
  }'

Updating a breakout’s staged config

curl -X PATCH "https://<your-server>/api/v2/network-devices/{networkDeviceId}/breakouts/{breakoutId}/config" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
    "groups": [{"speed": "25G", "count": 4}]
  }'

Removing a breakout

curl -X DELETE "https://<your-server>/api/v2/network-devices/{networkDeviceId}/breakouts/{breakoutId}" \
  -H "Authorization: Bearer <API_KEY>"

Virtual functions (SR-IOV)

SR-IOV virtual functions on SmartNIC-capable network devices can be enumerated via the API.

Listing virtual functions on a device

curl "https://<your-server>/api/v2/network-devices/{networkDeviceId}/virtual-functions" \
  -H "Authorization: Bearer <API_KEY>"

Listing virtual functions on a specific port

curl "https://<your-server>/api/v2/network-devices/{networkDeviceId}/ports/{portId}/virtual-functions" \
  -H "Authorization: Bearer <API_KEY>"

Network device vendors

MetalSoft maintains a vendor registry used for SNMP OID group configuration and health-check rules.

Listing vendors

curl "https://<your-server>/api/v2/network-devices/vendors" \
  -H "Authorization: Bearer <API_KEY>"

Getting a vendor

curl "https://<your-server>/api/v2/network-devices/vendors/{vendorId}" \
  -H "Authorization: Bearer <API_KEY>"

Updating vendor SNMP OID groups and health-check rules

curl -X PATCH "https://<your-server>/api/v2/network-devices/vendors/{vendorId}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
    "oidGroups": [...],
    "healthCheckRules": {...}
  }'

Syslog

To disable remote syslog for a network device:

curl -X POST "https://<your-server>/api/v2/network-devices/{networkDeviceId}/actions/syslog-unsubscribe" \
  -H "Authorization: Bearer <API_KEY>"