Appearance
SNMP
Use the SNMP service to inventory switches and printers, monitor switch ports and traffic, and automate work in response to SNMP traps. Install it on a host that can reach the managed devices and the assigned Edge service.
Create an SNMP service client in Ordyn and copy its ID before installing the service. Prepare Docker and image verification on the host.
Installation
Checkout the SNMP deployment folder from the Ordyn compose repository:
bash
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 snmpCreate the environment file:
bash
cd /opt/ordyn-compose/snmp
cp .env.example .envSet these values in .env:
dotenv
ORDYN_SNMP_EDGE_HOST=ordyn-edge.example.com
ORDYN_SNMP_SERVICE_CLIENT_ID=<service-client-id>Pull and verify the service image:
bash
docker compose pull
python3 /opt/cosign-docker-verify/verify.pyContinue 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:
bash
docker compose stop snmp
printf '%s' '<enrollment-token>' | docker compose run --rm -T --no-deps snmp npm run enroll -- --token-stdinAfter enrollment succeeds, start the service:
bash
docker compose up -d snmpTo renew, recover, or replace its service-client certificate, issue a new token and run forced enrollment while the service is stopped:
bash
docker compose stop snmp
printf '%s' '<enrollment-token>' | docker compose run --rm -T --no-deps snmp npm run enroll -- --token-stdin --forceRun 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
Create a credential profile in the same tenant as the switches or printers that will use it. Use a community string for SNMP v1/v2c, or the device's username, security level, authentication, and privacy settings for SNMP v3.
Enable writes only for profiles used to change switch port state or aliases. The device must also allow those operations. Remove endpoint assignments before deleting a profile.
Collection profiles
Collection profiles add read-only device values to standard switch or printer status. They are reusable across tenants.
Create a collection profile
Under Services > SNMP > Collection Profiles, create a profile and add fields with a label, numeric OID, and optional unit. Enum mappings can translate values into labels, such as 1 to Enabled.
Use scalar or fully indexed OIDs from the device's documentation or vendor MIB. Collection profiles query exact OIDs; they do not walk subtrees or change the device.
Calculated fields can sum two or more OID fields in the same profile. They use raw numeric values before display mappings. Calculated fields cannot reference other calculated fields. A missing or nonnumeric source produces Not reported, rather than counting as zero.
Keep value history
Enable Keep history on numeric OID or calculated fields to retain new observations for 90 days. History starts with subsequent collections; existing readings are not imported. Collection follows the shared switch and printer system-status interval, which defaults to one hour.
Click a tracked value in the endpoint overview to open its history chart, latest value, minimum, maximum, and average. Use View history to browse retained measurements, including removed fields. Failed or missing readings leave gaps. Counter values show cumulative readings, not rates.
Changing a measurement's OID, unit, or calculation starts a separate series. Label changes preserve its history. Disabled or removed fields and unassigned or deleted profiles remain available in endpoint history until their observations expire. Deleting the endpoint deletes its history.
Assign collection profiles
Assign profiles when creating or editing a switch or printer. Values refresh with system status collection and appear in the endpoint overview. After editing a profile, collect status again to see results for the new definition. A failed field does not hide successful values.
Remove assignments before deleting a profile.
Switch endpoints
Create a switch endpoint with its management hostname or IP address, SNMP service client, and credential profile. Add collection profiles as needed. Switches do not need an Ordyn Agent.
Run Inventory switch ports to collect physical and link aggregation interfaces. Target switch jobs with endpoint-kind requirements or groups so agent-only tasks are not assigned to switches.
Printer endpoints
Create a printer endpoint with its management address, SNMP service client, and credential profile. Printer collection is read-only; it does not manage print jobs or printer configuration. See Printer Endpoints.
Connected and active state
Connected means the assigned SNMP service is connected. Active means the device has returned system status recently. A connected but inactive device may be unreachable even though its service is working.
Status is collected automatically. Adjust the SNMP Switch System Status Interval and Freshness settings if needed; these apply to both switches and printers and default to one and two hours respectively.
Network interfaces, IPAM, and net-node probes
Configure endpoint interfaces with IP and MAC addresses for IPAM, reachability probes, and switch-port matching. Assign a Net node through Service routing, or inherit the folder or tenant route.
Port inventory and mapping
Port inventory shows connectivity, VLANs, and learned MAC addresses. Matching MAC addresses link ports to endpoint network interfaces. Inspect the current attachment from either endpoint or switch, and use link history to investigate moves.
An endpoint may appear on both an access port and an upstream switch port. Ordyn prefers a non-uplink match as the primary attachment.
Link-state notifications
To receive link changes, select a notification credential profile on the switch and configure the device to send traps or informs to its assigned SNMP service on UDP 162. Notification credentials can differ from polling credentials.
Use matching community or SNMPv3 security settings on the device and in Ordyn. One SNMP service cannot use the same SNMPv3 username with different credentials across its switches.
Standard linkDown and linkUp notifications update port status. Use the switch's port history to investigate repeated link changes. Link-state transitions are retained for 90 days by default; administrators can change ORDYN_SNMP_SWITCH_LINK_STATE_EVENT_RETENTION_DAYS.
Uplinks
An uplink match means an endpoint is reachable through that port, not necessarily directly attached. Ordyn recognizes reported uplinks and ports that learn at least the configured MAC threshold. SNMP Switch Uplink MAC Threshold defaults to eight addresses.
Interface traffic monitoring
Enable Monitor interface traffic on a switch after a successful port inventory. It requires SNMP v2c or v3 credentials, a compatible connected service, and network access to the switch.
Monitoring samples physical Ethernet and link aggregation interfaces about once a minute. Use rates, utilization, errors, and discards to investigate congestion or link problems. It is not packet capture.
A rate needs two valid samples. Reboots, counter resets, or long gaps require another baseline. Utilization is unavailable when the device does not report a usable interface speed. Delayed or failed collections can leave stale readings.
History is retained at one-minute resolution for seven days, five-minute resolution for 90 days, and hourly resolution for one year.
Traffic on endpoint primary attachments
An endpoint's traffic view shows measurements from its primary switch-port attachment. These include all traffic on the port, including traffic from other devices. Do not add a LAG's traffic to all its member ports; the same traffic may appear in both.
Collection capacity
Increase Concurrent traffic collections only when the service host and network can support more parallel polling. The default is 16 switches. Reducing it can help sensitive devices, but insufficient capacity may leave gaps in readings.
Port management
Use a write-enabled credential profile and a connected SNMP service to enable or disable physical ports or change aliases. LAG interfaces are read-only. A device can reject writes even when reads succeed; check the operation result if a change fails.
Job steps
Use SNMP job tasks for recurring status collection, port inventory, or port changes.
Trap job triggers
Create an automation matching the trap OID and select its source policy:
Endpoint Primary Interfacetargets endpoints whose primary interface IP matches the trap source.Any Sourcetargets eligible SNMP endpoints in the automation scope assigned to the receiving service. Use a narrow scope because one trap can start work on many endpoints.
A cooldown suppresses repeated triggers for the whole rule. Jobs can use trigger.snmp values; see trigger variables.
The provided deployment maps host UDP 162 to container UDP 9162. Set ORDYN_SNMP_TRAP_LISTEN_ENABLED, ORDYN_SNMP_TRAP_LISTEN_ADDRESS, or ORDYN_SNMP_TRAP_LISTEN_PORT when customizing the listener.
For troubleshooting, temporarily set ORDYN_SNMP_LOG_LEVEL=debug. Logs can contain device and credential identity information; handle them as sensitive data.