SNMP

ordyn-snmp is the service client used for SNMP-managed switch and printer endpoints.

Ordyn sends signed SNMP work to the selected service client, the service client talks to the device from its local network, and the result is reported back to Ordyn.

The SNMP service can:

• collect switch system status such as name, location, model, firmware, serial, vendor, and sysDescr
• collect printer system status such as printer name, printer status, page count, location, model, firmware, serial, vendor, and sysDescr
• collect physical switch ports, link state, admin state, speed, aliases, VLANs, and descriptions
• collect learned MAC addresses from bridge forwarding tables
• match learned MAC addresses to endpoint network interfaces
• record current endpoint-to-switch-port links and link history
• receive SNMP traps and start jobs through event automation rules
• enable or disable switch ports when the assigned credential profile allows write operations
• update switch port aliases when the assigned credential profile allows write operations

Installation

Checkout the SNMP deployment folder from the Ordyn compose repository:

if [ ! -d /opt/ordyn-compose/.git ]; then
  git clone --filter=blob:none --sparse https://github.com/ordyn-project/compose.git /opt/ordyn-compose
fi
cd /opt/ordyn-compose
git sparse-checkout add snmp

Create the environment file:

cd /opt/ordyn-compose/snmp
cp .env.example .env

Set these values in .env:

ORDYN_SNMP_EDGE_HOST=ordyn-edge.example.com
ORDYN_SNMP_SERVICE_CLIENT_ID=<service-client-id>

Start the service:

docker compose pull
python3 /opt/cosign-docker-verify/verify.py

Continue with docker compose up -d only when the SNMP image verifies successfully and no failed verification message appears.

docker compose up -d

Issue a service-client enrollment token for the SNMP service client in Ordyn. Enroll the service once:

printf '%s' '<enrollment-token>' | docker compose exec -T snmp node dist/index.js enroll --token-stdin

Use the same enrollment command when renewing or recovering the SNMP service-client certificate. See service-client certificate lifetime and renewal.

SNMP does not need public HTTPS ingress. It connects outbound to the assigned Edge service. The compose file maps host UDP 162 to container UDP 9162 for SNMP trap reception.

Credential profiles

SNMP credential profiles are tenant-scoped and can be assigned to switches and printers from the same tenant.

Profiles support:

• SNMP v1 and v2c with a community string
• SNMP v3 with username, security level, authentication protocol, privacy protocol, and the corresponding secrets
• SHA or MD5 authentication for SNMPv3 devices that require those algorithms
• AES or DES privacy for SNMPv3 devices that require those algorithms

Secret fields are stored encrypted in Ordyn and are only sent to the assigned SNMP service client for switch system status, printer system status, port inventory, trap authentication, and port management commands.

A credential profile can be marked as write-enabled. Write access is required before Ordyn offers switch port enable, switch port disable, or switch port alias updates. Read-only profiles can still collect switch system status, printer system status, ports, link state, and learned MAC addresses.

The tenant on a credential profile is fixed after creation. This avoids assigning a profile from one tenant to an SNMP endpoint in another tenant. A credential profile cannot be deleted while it is assigned to one or more switches or printers.

Switch endpoints

Switches are represented as endpoint tree items with kind switch.

Switch endpoints do not enroll and do not run the Ordyn agent. Create them manually with:

• endpoint kind switch
• hostname or management IP in the normal endpoint hostname field
• assigned SNMP service client
• assigned SNMP credential profile

The hostname is the SNMP management address used by ordyn-snmp. There is no separate SNMP management host field.

Switch endpoints appear in the endpoint tree and endpoint table, can be moved through the tree, and can participate in jobs, automations, groups, files, and audit history. Their detail page is switch-focused and exposes the Ports tab for SNMP port inventory.

Use endpoint-kind requirements and dynamic-group rules when a job or automation should only target switches. Agent-only tasks should not be assigned to switch endpoints; SNMP switch tasks only run against endpoints with kind switch.

Printer endpoints

Printers are represented as endpoint tree items with kind printer.

Printer endpoints do not enroll and do not run the Ordyn agent. Create them manually with:

• endpoint kind printer
• hostname or management IP in the normal endpoint hostname field
• assigned SNMP service client
• assigned SNMP credential profile

The hostname is the SNMP management address used by ordyn-snmp. There is no separate printer management host field.

Printer endpoints appear in the endpoint tree and endpoint table. Their detail page is printer-focused and exposes a printer overview with comments and the latest lightweight SNMP facts.

The current printer feature is read-only. It collects generic Printer-MIB and system facts, but does not manage printer jobs, toner, trays, or printer configuration.

See Printer Endpoints for printer setup and the current collected fields.

Connected and active state

SNMP-managed endpoints use different connection semantics than agent endpoints.

Connected means the endpoint's assigned SNMP service client is active and connected to edge. It does not mean the switch or printer itself has an open connection to Ordyn.

Active means Ordyn has a recent successful system status collection for that SNMP-managed endpoint. The freshness window is controlled by the SNMP Switch System Status Freshness setting and defaults to 7200 seconds. The setting name is shared by switches and printers.

This means a switch or printer can show as connected but inactive when the SNMP service client is online, but the endpoint has not returned system status recently or has never returned it successfully.

Ordyn automatically requests system status after a switch or printer is created and then refreshes it in the background. The automatic interval is controlled by the SNMP Switch System Status Interval setting and defaults to 3600 seconds. The setting name is shared by switches and printers.

Network interfaces, IPAM, and net-node probes

Switch and printer endpoints store management connectivity as endpoint network interfaces.

Their overview tabs show the same interface panels used by other endpoint kinds. From there, an operator can edit interface name, IP address, MAC address, primary status, IPAM ignore state, and ICMP/common protocol probe settings.

SNMP-managed endpoint interfaces participate in:

• IPAM address observations
• net-node reachability probes
• switch-port matching when MAC addresses are known

Use Net node routing from the endpoint action menu to choose which net node should probe the endpoint interfaces. If there is no direct endpoint assignment, Ordyn uses the inherited folder or tenant net-node assignment.

Port inventory and mapping

Inventory switch ports collects physical switch ports and stores the latest observed state. Layer-3 or virtual interfaces are filtered out so the switch port view stays focused on ports where endpoint cabling can be represented.

For each port, Ordyn can store:

• port number and SNMP ifIndex
• name, alias, and description
• operational state and admin state
• link speed
• VLAN information when reported by the switch
• learned MAC addresses
• matched endpoint links

Ordyn matches learned MAC addresses to endpoint network interfaces. When a MAC address is observed on a non-uplink switch port and the same MAC exists on an endpoint network interface, Ordyn stores a current endpoint-to-switch-port link.

Current links are shown:

• on the switch Ports tab
• in endpoint network interface details
• in optional endpoint table columns for switch and switch port

Ordyn also records switch port link history. Each history entry keeps the endpoint, network interface, MAC address, switch, port number, port name, VLAN, first observed time, last observed time, and end time. This makes previous port mappings visible even after the endpoint moves or a modular switch port disappears.

If an endpoint network interface changes and the matched MAC address is absent, Ordyn closes the stale switch-port link.

Uplinks

Learned MAC addresses on uplink ports are not linked to endpoints by default. This prevents a trunk or uplink port from incorrectly claiming many downstream devices.

A port is treated as an uplink when:

• the SNMP payload explicitly marks it as an uplink, or
• the port learns at least the configured number of MAC addresses

The learned-MAC threshold is controlled by the SNMP Switch Uplink MAC Threshold setting and defaults to 8.

Port management

Port management requires:

• a switch endpoint
• an assigned SNMP service client that is connected
• an assigned active credential profile
• the credential profile to be write-enabled
• user permission to update SNMP-managed resources

The UI can request a port admin-state change after confirmation. Jobs can do the same with the Set switch port admin state task.

Switches can reject writes even when credentials are valid. For example, a switch may return NoAccess for ifAdminStatus or alias updates. Ordyn records that result in the operation result, audit log, job result, and user notification.

Job steps

SNMP job steps are documented in Available Job Tasks.

The current SNMP tasks are:

• Collect switch system status
• Collect printer system status
• Inventory switch ports
• Set switch port admin state

Switch tasks only apply to switch endpoints. Collect printer system status only applies to printer endpoints.

Trap job triggers

SNMP service clients can receive SNMP traps and start Ordyn jobs through job trigger rules.

Runtime behavior:

• the ordyn-snmp service listens for traps on UDP 9162 by default
• deployments should map host UDP 162 to container UDP 9162
• active SNMP credential profiles for tenants with switches mapped to that SNMP service client are reused as accepted trap communities or SNMPv3 users
• the trap source address must exactly match the switch endpoint hostname or management IP
• the trap must arrive through the switch endpoint's assigned SNMP service client
• trigger rules match the normalized trap OID exactly
• each rule has a cooldown to avoid repeated traps starting jobs too often

Triggered jobs receive trap details under trigger.snmp. The run also has trigger.type set to snmp_trap_received and trigger.source set to snmp. See Variables for the full trigger field list.

Configure the listener with:

• ORDYN_SNMP_TRAP_LISTEN_ENABLED, default true
• ORDYN_SNMP_TRAP_LISTEN_ADDRESS, default 0.0.0.0
• ORDYN_SNMP_TRAP_LISTEN_PORT, default 9162