SNMP discovery

Kind: snmp

Overview

Netdata can automatically discover SNMP-capable devices on your network and generate snmp collector jobs for each one. Configure the IP ranges to scan and the SNMP credentials to try, and the discoverer probes each address, reads basic system information, and produces collector configurations from a set of customisable service rules.

This page covers SNMP-specific setup. For the broader Service Discovery model (discoverer: and services: blocks, rule evaluation order, and the full template helper reference shared by all discoverers), see Service Discovery.

How it works

Each discovery cycle, the discoverer:

1. Iterates every IP in the configured networks[] subnets, in parallel.
2. Probes each IP over UDP/161 using the credential bound to that subnet, walking the standard system MIB (sysDescr, sysName, sysContact, sysLocation, sysObjectID).
3. Caches the result in a status file so re-probing is skipped while device_cache_ttl has not expired.
4. Emits a target per reachable device, exposing .IPAddress, .SysInfo.*, and .Credential.* to the rule engine.
5. Runs the services: rules against each target. The rules render Go templates to produce one (or more) snmp collector job configurations.

The discoverer never queries device-specific OIDs — those are queried later by the snmp collector once the job is created.

Limitations

• Each subnet is capped at 512 IP addresses (a /23 network or smaller). Split larger ranges into multiple networks[] entries.
• Discovery uses UDP/161. The Netdata Agent host must be able to reach that port on every scanned IP, and any device-side ACLs must allow the Netdata host.
• One credential per subnet: each networks[] entry is bound to exactly one credential. There is no automatic credential fallback. To probe the same subnet with multiple credentials, list it twice with different credential values; each device that responds to either credential will appear as a target (with its responding credential exposed via .Credential.*).
• Outbound interface: probes use the host’s default routing. There is no per-pipeline bind-address or VRF option — on multi-homed hosts, configure the OS routing table so the Netdata host reaches each target subnet via the correct interface.
• The discoverer reads only the standard system MIB. Vendor-specific identification (.SysInfo.Vendor, .Category, .Model) is derived from sysObjectID and an enterprise-numbers table; values may be empty or Unknown for devices that are not in that table.
• SNMPv3 engine ID: gosnmp negotiates the engine ID at the start of each probe (one extra round-trip per probe — usually irrelevant unless parallel_scans_per_network is high and the device is rate-limited). Engine IDs are not cached across probes, so devices that rotate engine IDs (rare; some HA pairs do this on failover) are handled transparently.
• Credential storage: community strings and SNMPv3 passphrases are stored in plaintext both in /etc/netdata/go.d/sd/snmp.conf (file-based pipelines) and in the agent’s dynamic-configuration store under /var/lib/netdata/dyncfg/ (UI-managed pipelines). To avoid plaintext credentials on disk in either path, reference them via ${env:VAR} or ${file:/path} (see Secrets Management).

Setup

You can configure the snmp discoverer in two ways:

Prerequisites

Plan your IP ranges and credentials

Decide which subnets to scan and which SNMP credentials apply to each. SNMPv1 and SNMPv2c need a community string. SNMPv3 needs a USM username, security level, and (depending on the level) authentication and privacy passphrases.

Allow UDP/161 reachability

The Netdata Agent host must be able to reach UDP port 161 on every scanned IP. SNMP devices typically restrict which clients can query them — make sure the Netdata host is allowed by any device-side ACLs.

Configuration

Options

The configuration file has two top-level blocks: discoverer: (the options below) and services: (rules that turn discovered devices into snmp collector jobs — see Service Rules).

After editing the file, restart the Netdata Agent to load the updated discovery pipeline.

rescan_interval

Set to 0 to perform a single discovery scan when the agent starts and never rescan. Negative values also disable rescanning.

device_cache_ttl

Set to 0 to never expire cached results — once a device is discovered it is never re-probed (until the agent restarts and the cache is invalidated by configuration changes).

credentials

Each credential has a name (used by networks[].credential) and a version.

Accepted version values: 1, 2, 2c, 3. (2 is an alias for 2c.)

For SNMPv1 and SNMPv2c, set community.

For SNMPv3, set:

• username — USM user name.
• security_level — one of noAuthNoPriv, authNoPriv, authPriv.
• auth_protocol — one of md5, sha (HMAC-SHA-1, RFC 3414), sha224, sha256, sha384, sha512 (HMAC-SHA-2, RFC 7860). Required for authNoPriv and authPriv.
• auth_password — authentication passphrase. Required when auth_protocol is set.
• priv_protocol — one of des, aes (AES-128), aes192, aes256, aes192c, aes256c. The c variants are the Cisco/Reeder draft; check your device’s show snmp user output to pick the matching one. Required for authPriv.
• priv_password — privacy passphrase. Required when priv_protocol is set.
• context_name — only set this if your devices use a non-default SNMPv3 context.

Naming note: the YAML keys are auth_password and priv_password. The same fields are exposed inside service rule templates as .Credential.AuthPassphrase and .Credential.PrivacyPassphrase (the Go struct names). Both refer to the same value.

Avoid plaintext on disk: any of these fields can be sourced from environment variables or files using ${env:VAR_NAME} or ${file:/absolute/path} — see Secrets Management.

networks

Each entry needs subnet (an IP range) and credential (the name of an entry from credentials).

Supported subnet formats (IPv4 and IPv6):

• CIDR — 192.168.1.0/24, 2001:db8::/120
• Range — 10.0.0.1-10.0.0.50, 2001:db8::-2001:db8::ff
• Subnet mask — 192.168.1.0/255.255.255.0
• Single IP — 192.168.1.10, 2001:db8::1

Maximum 512 IPs per subnet entry. Split larger blocks across multiple entries.

For CIDR notation, network and broadcast addresses are excluded (except /31, /32, /127, /128).

via UI

1. Open the Netdata Dynamic Configuration UI.
2. Go to Collectors -> go.d -> ServiceDiscovery -> snmp.
3. Add a new discovery pipeline and give it a name.
4. Fill in the discoverer-specific settings and the service rules.
5. Save the discovery pipeline.

via File

Define the discovery pipeline in /etc/netdata/go.d/sd/snmp.conf.

The file has two top-level blocks: discoverer: (the options above) and services: (rules that turn discovered targets into collector jobs — see Service Rules).

After editing the file, restart the Netdata Agent to load the updated discovery pipeline.

Examples

Single subnet, SNMPv2c

Scan a single /24 with the default public community.

disabled: no
discoverer:
  snmp:
    credentials:
      - name: public-v2c
        version: 2c
        community: public
    networks:
      - subnet: 192.168.1.0/24
        credential: public-v2c
services:
  - id: snmp
    match: '{{ true }}'

Multiple subnets, mixed SNMPv2c and SNMPv3

Mix SNMPv2c on one subnet with SNMPv3 (authPriv) on another. Credentials are referenced from environment variables to keep them out of plaintext on disk.

disabled: no
discoverer:
  snmp:
    rescan_interval: 1h
    credentials:
      - name: public-v2c
        version: 2c
        community: ${env:SNMP_V2C_COMMUNITY}
      - name: secure-v3
        version: 3
        security_level: authPriv
        username: netdata-monitor
        auth_protocol: sha256
        auth_password: ${env:SNMP_V3_AUTH}
        priv_protocol: aes256
        priv_password: ${env:SNMP_V3_PRIV}
    networks:
      - subnet: 192.168.10.0/24
        credential: public-v2c
      - subnet: 10.20.30.0/24
        credential: secure-v3
services:
  - id: snmp
    match: '{{ true }}'

IPv6 subnet

Scan a small IPv6 range with SNMPv2c.

disabled: no
discoverer:
  snmp:
    credentials:
      - name: public-v2c
        version: 2c
        community: public
    networks:
      - subnet: 2001:db8:0:1::/120
        credential: public-v2c
services:
  - id: snmp
    match: '{{ true }}'

Troubleshooting

No devices are discovered

Check the agent log for discoverer=snmp messages. Common causes:

• The configured subnets do not match where your devices live. Verify with ping / arp from the Netdata host.
• UDP port 161 is blocked between the Netdata host and the devices. Test with nc -zu <ip> 161 or snmpwalk -v2c -c <community> <ip> sysDescr.0.
• The credentials do not match what the devices accept. SNMPv3 mismatches commonly produce authentication failure or decryption error log lines.
• A configured subnet exceeds the 512-IP cap and the discoverer rejected it at startup. Look for subnet '...' exceeds maximum size of /23 in the log.

Wrong devices are matched by a rule

Rule order matters — see How rules are evaluated. Place vendor-specific or device-specific rules before the catch-all. If you need to suppress the catch-all for a subset of devices, follow the specific rule with a skip rule (no config_template) keyed on the same condition.

Generated collector jobs fail to start

The discoverer creates jobs but does not run them — the snmp collector does. Check the snmp collector log and the rendered job YAML in the agent’s debug output. Common causes:

• The rendered config_template produces invalid YAML for some discovered field values (for example, unescaped colons in sysName). YAML-quote dynamic values when in doubt.
• Module name mismatch — the rule id (or explicit module: field) does not match snmp.
• SNMPv3 credentials succeeded for system MIB during discovery but the collector cannot read other OIDs (different VACM view); confirm with snmpwalk against the device.