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, sysDescr, system object OID, and enterprise OID
• collect printer system status such as printer name, printer status, total page count, counter unit, color capability, black-and-white and color counters, location, model, firmware, serial, vendor, sysDescr, system object OID, and enterprise OID
• collect additional read-only values through globally reusable collection profiles
• collect physical Ethernet and link aggregation interfaces, link state, admin state, speed, aliases, VLANs, and descriptions
• collect near-live receive and transmit rates, utilization, errors, and discards with retained interface history
• 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 informs, update switch-port link state, 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>

Pull and verify the service image:

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

Continue only when the SNMP image verifies successfully and no failed verification message appears. Issue a service-client enrollment token for the SNMP service client in Ordyn, stop any running service container, and enroll the persistent service state:

docker compose stop snmp
printf '%s' '<enrollment-token>' | docker compose run --rm -T --no-deps snmp npm run enroll -- --token-stdin

After enrollment succeeds, start the service:

docker compose up -d snmp

To renew, recover, or replace its service-client certificate, issue a new token and run forced enrollment while the service is stopped:

docker compose stop snmp
printf '%s' '<enrollment-token>' | docker compose run --rm -T --no-deps snmp npm run enroll -- --token-stdin --force

Run docker compose up -d snmp only after forced enrollment succeeds. Do not use docker compose exec for enrollment. 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, interface traffic monitoring, explicitly configured notification 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.

Collection profiles

SNMP collection profiles define optional read-only values that Ordyn should collect or calculate in addition to the standard switch or printer facts.

Collection profiles are global Ordyn resources. They do not belong to a tenant and are available when configuring any switch or printer endpoint. Credential profiles remain tenant-scoped and control how Ordyn authenticates to each device.

Users need the corresponding SNMP read, create, update, or delete permission to view or manage collection profiles.

Create a collection profile

1. Open Services and select the SNMP service.
2. Open the Collection Profiles tab.
3. Select Add collection profile.
4. Enter a name and an optional description.
5. Add the OID and calculated fields you want to display.
6. Save the profile.

An OID field contains:

• Label: the name shown with the collected value
• OID: a numeric OID, with or without a leading dot
• Unit: optional text shown after a reported value, such as pages, °C, or percent
• Enum display mappings: optional raw-value-to-label mappings, such as 1 to Enabled

Each configured OID performs one exact, read-only SNMP query. A collection profile does not walk an OID subtree and cannot change device state. Use scalar or fully indexed OIDs that the target device permits the assigned credentials to read.

A calculated field can sum two or more OID fields from the same profile. Configure its label, optional unit, and source fields. The calculation uses the raw numeric values reported by those fields, before enum display mappings are applied. Calculated fields cannot be used as sources for other calculated fields.

If any source is unavailable or does not report a numeric value, the calculated field is shown as Not reported with an error identifying the source. Missing values are not treated as zero.

OID support and meaning depend on the device. Consult the device documentation or vendor MIB before adding an enterprise OID. The profile stores the label, unit, and display mappings supplied by the user; Ordyn does not infer the meaning of a vendor-specific value.

Assign collection profiles

Select zero or more collection profiles while creating a switch or printer endpoint. Use Edit switch or Edit printer to change the assignments later. The same profile can be assigned to endpoints in different tenants.

Assigned profiles are collected with switch or printer system status. The endpoint overview groups the latest values under the name of each assigned profile.

When an enum display mapping matches a reported value, the overview shows the configured display label instead of the raw value. Values without a matching display mapping are shown directly. Units are shown only for reported values.

One unavailable OID does not prevent the remaining fields from being collected. The unavailable field and any calculation that depends on it are shown as Not reported, while successfully reported fields remain visible.

After a profile is edited, endpoints show Awaiting collection for that profile until a system status collection reports values for the updated definition. The next automatic or manually requested collection refreshes the results.

A collection profile cannot be deleted while it is assigned to an endpoint. Remove all endpoint assignments before deleting it.

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
• optional notification credential profile for traps and informs
• any optional SNMP collection profiles

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
• any optional SNMP collection profiles

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.

Printer collection is read-only. It collects standards-based printer and system facts plus any explicitly assigned collection-profile OIDs, but does not manage printer jobs, toner, trays, or printer configuration.

See Printer Endpoints for printer setup and 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 Service routing from the endpoint action menu and select the Net Node tab 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 Ethernet and IEEE 802.3 link aggregation interfaces and stores the latest observed state. Layer-3 and other virtual interfaces are filtered out so the switch port view stays focused on physical connectivity and aggregates built from physical members.

For each port, Ordyn can store:

• port number and SNMP ifIndex
• interface type, shown as a physical interface or link aggregation group (LAG)
• 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 on every port, including ports labelled as uplinks. When a learned MAC address exists on an endpoint network interface, Ordyn stores the current match for that switch port.

The same endpoint interface can be matched on more than one port, for example on its access port and on an upstream switch uplink. Ordyn selects one match as the primary attachment for endpoint views and traffic. A non-uplink match is preferred whenever one is available; an uplink match becomes primary only when no current non-uplink match exists.

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 primary 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 primary 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.

Link-state notifications

Switches can optionally use SNMP notifications to update port link state shortly after a link changes. Select a Notification credential profile while creating or editing the switch. This selection is independent from the credential profile used for polling; both fields can use the same profile.

A switch receives managed notifications only when a notification credential profile is selected. The switch must also be configured to send notifications to the reachable address and UDP port of its assigned SNMP service client.

Notification profiles support:

• SNMPv1 and SNMPv2c community authentication
• SNMPv3 authNoPriv and authPriv notifications supported by the selected profile
• unacknowledged traps and acknowledged informs

For SNMPv3, configure the same username, security level, authentication protocol and password, and privacy protocol and password on the switch and in the selected Ordyn profile. The switch supplies its authoritative engine ID with a trap. Ordyn maintains the receiver engine identity required by authenticated informs.

One SNMP service client can accept a username only with one set of SNMPv3 security credentials. Switches may reuse a profile or use separate profiles. Ordyn rejects assignments that would use the same username with different credentials on one service client.

Ordyn recognizes the standard linkDown and linkUp notifications. A matching notification updates the port immediately and Ordyn confirms the current operational state with a targeted SNMP read. Port inventory and interface traffic polling also reconcile link state from their observations.

The switch Ports tab shows separate link-up and link-down counts for the previous 24 hours and the time and source of the latest recorded transition. Initial observations, repeated notifications for the same state, and older out-of-order observations do not increase the counts. Link-state transitions are retained for 90 days by default. ORDYN_SNMP_SWITCH_LINK_STATE_EVENT_RETENTION_DAYS changes the retention period.

Uplinks

Uplink ports retain their uplink label while still showing matched downstream endpoints. A match on an uplink means that the endpoint is reachable through that port; it does not necessarily mean the endpoint is directly connected there. Endpoint views continue to use a non-uplink match as the primary attachment whenever one is available.

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.

Interface traffic monitoring

Interface traffic monitoring is optional and is disabled by default for each switch. When enabled, Ordyn requests one counter sample approximately every 60 seconds and calculates receive and transmit rates for the switch interfaces it supports.

Traffic monitoring is periodic rather than a continuous packet-level stream. Slow SNMP responses, an unavailable switch, service-client disconnection, or collection-capacity limits can delay a sample.

Requirements

Before traffic monitoring can be enabled, the switch needs:

• a successful Inventory switch ports result from a service-client version that reports current interface types
• an assigned SNMP service client that has connected and reported interface-traffic support
• an active SNMP v2c or v3 credential profile
• SNMP reachability from the assigned service client to the switch

SNMP v1 credentials can be used for other supported SNMP workflows, but they cannot be used for interface traffic monitoring.

To enable monitoring:

1. Open the switch endpoint.
2. Run Inventory switch ports if the current port inventory requirement is not satisfied.
3. Select Edit switch from the endpoint action menu.
4. Enable Monitor interface traffic.
5. Save the switch.

The form disables the option and explains which requirement is missing when monitoring cannot be enabled. Disabling monitoring does not require a fresh inventory.

Viewing switch-interface traffic requires SNMP read access to the switch. Enabling or disabling monitoring requires permission to update the endpoint and its SNMP configuration. The connected-interface panel on another endpoint follows that endpoint's normal read permission.

Collected interfaces and values

Ordyn collects traffic for:

• physical Ethernet interfaces
• IEEE 802.3 link aggregation interfaces shown as LAG

For each supported interface, Ordyn can show:

• receive and transmit rate in bits per second
• receive and transmit utilization when the switch reports a usable interface speed
• input and output errors since the previous valid sample
• input and output discards since the previous valid sample
• sample time and sample quality
• a collection error when counters are unavailable or invalid

The service prefers 64-bit high-capacity counters and can use 32-bit counters when necessary. High-speed interfaces should expose 64-bit counters. When a 32-bit rollover cannot be distinguished safely from a counter reset, Ordyn establishes a new baseline instead of displaying a potentially incorrect rate.

The first valid sample establishes a baseline. A rate appears after the next valid, newer sample. A gap longer than five minutes, a switch reboot, or an interface counter discontinuity also establishes a new baseline.

Utilization remains unavailable when the switch does not report a usable interface speed. Errors and discards are shown as exact counter differences, even when utilization cannot be calculated.

Current state and graphs

The Ports tab adds current receive rate, transmit rate, and error-plus-discard values to the interface table. In the graphical port view, selecting a port shows its current-state summary and history graph below the port map. New samples appear automatically while the page remains open.

A sample is shown as stale when it is more than about two and a half minutes old. The status can also indicate that Ordyn is establishing a baseline, that counters reset, that counters are unavailable, or that the sample is invalid.

One-minute history is retained for 7 days, five-minute history for 90 days, and hourly history for 1 year. Longer-resolution points average rates and utilization across their time bucket and add the reported error and discard differences.

Traffic on endpoint primary attachments

When Ordyn has selected a primary switch-port match for an endpoint network interface and traffic monitoring is enabled for that switch, the endpoint overview can show the interface's current and historical traffic. The heading shows the switch followed by the port and links to the switch Ports tab. New samples appear automatically. The panel is hidden while traffic monitoring is disabled.

The values represent all traffic on the switch interface. They are not attributed to the individual endpoint. An exclamation icon appears beside the port when it is linked to multiple endpoints or has learned multiple MAC addresses. Hover over or focus the icon to see why the traffic cannot be attributed to one endpoint.

Do not add the traffic from a LAG and all of its physical members to calculate a switch total. A switch can report the same traffic through both the aggregate and member interfaces.

Collection capacity

Each SNMP service client has a Concurrent traffic collections setting. The default is 16; accepted values are 1 through 64.

This setting limits how many switches the service client polls for traffic at the same time. It does not change the 60-second interval. Increase it only when the service-client host and managed network can handle more concurrent SNMP work. Reduce it when devices or network paths are sensitive to parallel polling.

When all collection slots remain busy, later targets wait for capacity. A target that cannot start within its collection cycle skips that cycle, which can make the current sample stale or cause the next sample to establish a new baseline.

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.

LAG interfaces are aggregate and read-only.

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
• only notification credential profiles selected on approved switches assigned to that service client are accepted as trap communities or SNMPv3 users
• only approved endpoints with SNMP configuration assigned to the service client that received the trap are eligible
• trigger rules match the normalized trap OID exactly
• every trigger rule selects either Endpoint Primary Interface or Any Source
• each rule has one cooldown for the complete fan-out, rather than a separate cooldown for each endpoint

Endpoint Primary Interface compares the trap source IP with the primary host interface of eligible endpoints in the automation scope. Endpoint hostnames and secondary interfaces are not compared. If multiple endpoints have the same matching primary IP, Ordyn targets all of them. The stored trap identifies one matched endpoint only when exactly one endpoint matched.

Any Source does not compare the trap source address. It targets every eligible SNMP endpoint in the automation scope that is assigned to the receiving service client. Tenant, folder and descendant-folder, group, and endpoint scopes apply normally. This can start the selected job on many endpoints from one trap, so administrators should use a sufficiently narrow scope and OID.

After a rule starts its fan-out, another matching trap during the cooldown suppresses the whole rule. The configured random delay is selected independently for every target. Normal job assignment, endpoint eligibility, job-disable, validity-window, and active-run coalescing checks still apply to each target.

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

Configure service logging with ORDYN_SNMP_LOG_LEVEL. Supported values are debug, info, warn, and error; the default is info. An unsupported value prevents the service from starting.

At debug, every accepted trap is logged as snmp_trap_received before publication, including the full normalized payload and varbind values. A successful publication also logs snmp_trap_published. Debug output can contain device data and community or SNMPv3 identity information, so enable it only for troubleshooting and handle the logs accordingly.