SNMP Autodiscovery

The SNMP Autodiscovery page configures two related functions: automatic discovery of network devices across your subnets, and the SNMP metrics poller that continuously collects CPU, memory, interface, and LLDP topology data from registered devices.

Autodiscovery Enabled

The toggle in the top-right corner enables or disables the scheduled autodiscovery process globally. When disabled, no automated discovery scans will run, but the SNMP metrics poller continues operating independently.

Discovery Status

The Discovery Status card shows the current state of the autodiscovery process:

• Status indicator — Shows "Discovery in progress..." (with a spinner) during an active scan, or "Idle" when waiting for the next scheduled run.
• Last run — Timestamp of the most recent completed discovery scan.
• Next run — Timestamp of the next scheduled scan based on the configured schedule.
• Schedule — How frequently autodiscovery runs. Options include Every 12 hours and Every 24 hours.

View Log

Opens the discovery log showing the results of the most recent scan. The log details which subnets were scanned, which IPs responded to SNMP, what sysDescr and sysName were returned, and whether each device was newly added or already existed in the inventory.

Run Now

Triggers an immediate discovery scan outside the normal schedule. This is useful after adding new subnets or credentials, or when new devices have been added to the network and you want them registered right away.

How Discovery Works

When a discovery scan runs, the following process occurs for each configured subnet:

1. The discovery service reads all enabled subnets and their assigned SNMP credentials from PostgreSQL.
2. For each IP address in the subnet, the discovery service performs two checks: an ICMP ping and an SNMP GET request for sysDescr (OID 1.3.6.1.2.1.1.1.0) using the subnet's assigned credential.
3. If the SNMP GET succeeds, a second GET retrieves sysName (OID 1.3.6.1.2.1.1.5.0).
4. The service checks if a device with this management IP already exists in the database. If it does, it skips the device. If it's new, a device record is created with the sysName as the device name, sysDescr used to determine the device type, the management IP, and the subnet's assigned site.
5. Newly discovered devices are assigned a role of discovered and their device type is determined by matching the sysDescr against known vendor patterns (Cisco IOS/NX-OS, Arista EOS, Juniper Junos, Palo Alto PAN-OS, Fortinet FortiOS, Linux, etc.).

Discovery results are color-coded based on reachability:

Color	Ping	SNMP GET	Meaning
Green	✓	✓	Fully reachable. Device discovered with complete information.
Yellow	✓	✗	Host is alive but SNMP is not responding. Check that SNMP is enabled on the device and that the correct community string or v3 credentials are configured.
Yellow	✗	✓	Device responds to SNMP but ICMP is blocked. Common on firewalls and hardened devices. The device is discovered normally — only the ping check failed.
Red	✗	✗	Both checks failed. The IP is either unused, the host is down, or both ICMP and SNMP are blocked.

SNMP Metrics Poller

The SNMP Metrics Poller section controls the Go-based polling service that continuously collects metrics from all registered devices.

Status and Controls

• Running / Stopped — Current poller status.
• Start — Start the poller if it's stopped.
• Stop — Stop the poller gracefully.
• Refresh — Refresh the displayed status.

Poll Interval (seconds)

How frequently the poller cycles through all devices. The default is 60 seconds. Each poll cycle, the poller reads the device list from PostgreSQL, matches each device to the appropriate vendor handler based on sysDescr, and collects metrics in parallel using a worker pool.

Click Save Settings to apply a new poll interval. The poller picks up the change on the next cycle without requiring a restart.

Data Source / Metrics Target

Displays the data flow for the poller:

• Data Source: PostgreSQL devices — The poller reads the device inventory and SNMP credentials from PostgreSQL.
• Metrics Target: ClickHouse — Collected metrics are written to ClickHouse in batch inserts for time-series storage and querying.

What the Poller Collects

The Go SNMP poller collects the following data on each poll cycle:

Category	Metrics	Storage
CPU	Utilization percentage (vendor-specific OIDs)	snmp_metrics table
Memory	Used, free, and percentage (vendor-specific)	snmp_metrics table
Interfaces	IFIndex values, In/out octets, packets, errors, discards, speed, admin/oper status	snmp_metrics table
LLDP Topology	Neighbor relationships, remote sysName, remote port	lldp_neighbors table

The poller uses a vendor handler system to select the correct OIDs for each device type. Built-in handlers exist for Cisco IOS/NX-OS, Arista EOS, Juniper Junos, Palo Alto, Fortinet, and Linux/macOS. A generic fallback handler using HOST-RESOURCES-MIB covers unrecognized devices. Custom device profiles can be added via the oids.yaml configuration file without code changes.

SNMP Credentials

The SNMP Credentials section manages the community strings and authentication parameters used for both autodiscovery and polling.

Credential Table

Column	Description
Name	A friendly label for the credential set (e.g., public, production-rw).
Version	The SNMP version — displayed as a badge: V2C (blue) for SNMPv2c, or V3 for SNMPv3.
Created	When the credential was created.
Actions	Delete the credential.

Architecture

Discovery

The discovery engine uses the snmpget CLI tool with SNMPv3 flags to probe each IP in the configured subnets. It queries sysDescr and sysName to identify devices.

Polling

The SNMP poller uses the gosnmp library natively for SNMPv3 sessions. This provides full protocol support without relying on external CLI tools, enabling efficient bulk polling of interface metrics, CPU, memory, and LLDP neighbor data.

Credential Storage

All SNMP credentials (community strings, v3 auth/priv passwords) are encrypted at rest using AES-256-GCM. Credentials are decrypted only in memory at the time of use by the poller and discovery services.

+ Add Credential

Opens a form to create a new SNMP credential. Fields depend on the version selected:

SNMPv2

SNMPv2c:

• Name (required) — Friendly label.
• Community String (required) — The SNMPv2c community string (e.g., public, mySecretCommunity). Encrypted with AES before storage in PostgreSQL — the plaintext community string is never stored at rest.

Credentials can be shared across multiple discovery subnets. A single credential set (e.g., a common community string) can be assigned to several subnets.

SNMPv3 Support in WhiteOwl Networks

Overview

WhiteOwl Networks supports SNMPv3 (User-based Security Model) for both device discovery and polling. SNMPv3 provides authentication and encryption for secure network monitoring, replacing the plaintext community strings used in SNMPv1/v2c.

Supported Authentication Protocols

Protocol	Strength	Notes
MD5	Weak	Legacy support only, not recommended
SHA	Standard	SHA-1, widely supported across vendors
SHA-224	Strong	Requires newer firmware on most platforms
SHA-256	Strong	Recommended minimum for new deployments
SHA-384	Very Strong	Limited vendor support
SHA-512	Very Strong	Limited vendor support

Supported Privacy (Encryption) Protocols

Protocol	Strength	Notes
DES	Weak	56-bit, legacy only — do not use in production
AES-128	Standard	RFC 3826, universally supported
AES-192	Strong	Non-standard extension, check vendor support
AES-256	Strong	Non-standard extension, check vendor support

Recommendation: Use SHA / AES-128 for broadest compatibility. Use SHA-256 / AES-256 where vendor support permits.

Security Levels

Level	Authentication	Encryption	Use Case
noAuthNoPriv	None	None	Testing only — not secure
authNoPriv	Yes	None	Authenticates user but data is readable
authPriv	Yes	Yes	Full security — recommended for production

WhiteOwl automatically selects the security level based on the credentials provided. If both auth and priv passwords are set, it uses authPriv. If only auth is set, it uses authNoPriv.

Configuration

1. Create SNMP Credentials

Navigate to Settings → SNMP → Credentials and click Add Credential:

• Select SNMPv3 as the version
• Enter the username, auth protocol/password, and priv protocol/password
• Use the Test button with a device IP to verify connectivity before saving

2. Configure Network Devices

Example Cisco IOS/IOS-XE configuration:

snmp-server group WHITEOWL v3 priv
snmp-server user whiteowl_monitor WHITEOWL v3 auth sha <auth-password> priv aes 128 <priv-password>
snmp-server contact WhiteOwl NOC
snmp-server location Lab

To restrict SNMP access to the WhiteOwl server:

ip access-list standard SNMP_ACCESS
 permit <whiteowl-server-ip>
snmp-server group WHITEOWL v3 priv access SNMP_ACCESS

3. Assign to Discovery Subnets

In Settings → SNMP → Discovery Subnets, assign the SNMPv3 credential to your subnets. Discovery will use the v3 credentials to scan for devices.

Mixed environments: If you have both v2c and v3 devices on the same subnet, add the subnet twice — once with v2c credentials and once with v3 credentials. The discovery engine handles deduplication automatically.

4. Assign to Devices

Discovered devices inherit the credential from their discovery subnet. Existing devices can be reassigned to a new credential in the device settings.

Vendor Compatibility Notes

Vendor	SHA-256+	AES-256	Notes
Cisco IOS/IOS-XE	✅ 15.x+	✅ Platform dependent	Most common deployment
Cisco NX-OS	✅	✅	Full support
Arista EOS	✅	✅	Full support
Juniper JunOS	✅	✅	Full support
Linux (net-snmp)	✅	✅	Full support via snmpd.conf
Older IOS 12.x	❌ MD5/SHA only	❌ DES/AES-128 only	Consider upgrading

Discovery Subnets

Discovery Subnets define the IP ranges that autodiscovery will scan and link each subnet to a site and SNMP credential.

Subnet Table

Column	Description
Subnet	The CIDR range to scan (e.g., 192.168.100.0/24). Every IP in the range is probed during each discovery cycle.
Site	The site that discovered devices will be assigned to. This determines where devices appear on the geographic map and in site-level filters.
Credential	The SNMP credential used to probe devices in this subnet. The credential's community string or v3 parameters are used for the SNMP GET requests.
Last Discovery	Timestamp of the most recent scan of this subnet.
Status	Whether the subnet is active: Enabled (green) or Disabled. Disabled subnets are skipped during discovery scans.
Actions	Delete the subnet.

+ Add Subnet

Opens a form to register a new discovery subnet:

• Subnet (required) — CIDR notation (e.g., 10.0.1.0/24, 172.16.0.0/16). Larger subnets take longer to scan — a /24 scans 254 IPs, a /16 scans over 65,000.
• Site (required) — Select the site to assign discovered devices to.
• Credential (required) — Select the SNMP credential to use for this subnet.
• Enabled — Whether to include this subnet in scheduled discovery scans.

Large Subnets

Scanning large subnets (e.g., /16 or /8) can take significant time and generate substantial SNMP traffic. For large address spaces, consider breaking them into smaller /24 subnets targeting known device ranges, or increasing the SNMP timeout to accommodate slower responses.

Troubleshooting

"Wrong digest" error during polling:

• Auth password mismatch between WhiteOwl and the device
• Verify credentials using the Test button in the credential modal

Discovery finds 0 devices with v2/v3: Verify that SNMP is enabled on the target devices and that the configured community string or v3 credentials are correct. Test manually from the Chompy server:

snmpget -v2c -c public <device_ip> 1.3.6.1.2.1.1.1.0
- Verify `snmpget` is installed in the discovery container (`net-snmp-tools`)
- Check that the device ACL permits the WhiteOwl server IP
- Verify credentials are correct using the Test button

If this returns a sysDescr, the device is reachable. If it times out, check network connectivity and firewall rules for UDP port 161.

Timeout errors:

• Ensure UDP port 161 is open between WhiteOwl and the target device
• Check SNMP ACLs on the network device
• For high-latency links, the test endpoint allows up to 15 seconds for a response

"No response" from device:

• Confirm the SNMPv3 user exists on the device: show snmp user
• Confirm the group and security level match: show snmp group
• Test from the WhiteOwl server directly: snmpget -v3 -l authPriv -u <user> -a SHA -A <auth-pass> -x AES -X <priv-pass> <device-ip> 1.3.6.1.2.1.1.1.0

Devices discovered but not showing metrics:

Discovered devices need valid SNMP credentials accessible to the poller. The poller resolves credentials by matching each device's management IP against the configured discovery subnets — if a device's IP falls within a subnet, it uses that subnet's credential. Verify the device's IP is covered by an enabled subnet with the correct credential.

Poller showing "Stopped":

Check the Docker container status for the SNMP poller: docker ps | grep snmp-poller. If the container has exited, check logs with docker logs chompy-snmp-poller --tail 100 for errors. Common issues include incorrect ClickHouse or PostgreSQL connection settings.

**Vendor not recognized: **

If a device's sysDescr doesn't match any built-in handler, it falls back to the Generic handler using HOST-RESOURCES-MIB. This may not collect CPU or memory for all device types. Custom OID profiles can be added to oids.yaml to support additional vendors without code changes.