SNMP Metrics Configuration

Atatus Network Monitoring supports collecting device-level metrics over SNMP from routers, switches, firewalls, load balancers, wireless controllers, and other network devices.

This guide provides the full configuration format exactly as supported by the Atatus Infra Agent v4.2.0+, based on the agent’s SNMP configuration schema.

Configuration file path /etc/atatus-infra-agent/conf.d/snmp.d/snmp.yml

Requirements

Component Requirement
Agent Name atatus-infra-agent
Version 4.2.0 or higher
Config Path /etc/atatus-infra-agent/conf.d/snmp.d/snmp.yml
SNMP Versions v1, v2c, v3
SNMP Port UDP 161
Outbound To Atatus HTTPS 443

Configuration Structure

All SNMP configuration belongs inside a metrics: block.

copy
icon/buttons/copy 
metrics:
  - enabled: true
    namespace: atatus.ndm

    tags:
      - env:prod
      - team:network

    snmp:
      init_config:
      instances:
  1. Global Init Config (init_config)

This block defines global SNMP behavior for all devices.

copy
icon/buttons/copy 
metrics:
  - enabled: true
    namespace: atatus.ndm

    snmp:
      init_config:
        enabled: true
        use_device_id_as_hostname: true
        oid_batch_size: 5
        min_collection_interval: 60

        collect_device_metadata: true
        collect_topology: true
        collect_vpn: false

        bulk_max_repetitions: 10
        namespace: atatus.ndm

        ping:
          enabled: true
          count: 2
          interval: 1000
          timeout: 1000
          linux:
            use_raw_socket: true

Global Parameters Explained

Field Description
enabled Enables SNMP globally
use_device_id_as_hostname Generates unique hostnames based on sysObjectID
collect_device_metadata Model, vendor, OS, firmware
collect_topology L2/L3 neighbor discovery
collect_vpn Collects VPN tunnel OIDs
oid_batch_size Number of OIDs per bulk fetch
bulk_max_repetitions SNMP GETBULK repetition count
min_collection_interval Seconds between polls
ping.* ICMP-based reachability check
  1. Monitoring Individual Devices (instances)

Each device is configured as an entry under snmp.instances.

SNMPv2 Example

copy
icon/buttons/copy 
metrics:
  - enabled: true
    namespace: atatus.ndm

    tags:
      - env:prod
      - team:network

    snmp:
      init_config:
        enabled: true
        use_device_id_as_hostname: true

      instances:
        - name: "core-switch-1"
          ip_address: "172.17.0.10"
          port: 161
          namespace: "dc1"

          snmp_version: "2"
          community_string: "public"

          timeout: 2
          retries: 3

          tags:
            - location:dc1
            - role:switch

SNMPv3 Example

copy
icon/buttons/copy 
metrics:
  - enabled: true
    namespace: atatus.ndm

    snmp:
      init_config:
        enabled: true

      instances:
        - name: "firewall-primary"
          ip_address: "172.17.0.20"
          port: 161
          namespace: "dc3"


          snmp_version: "3"

          user: "monitor"
          authProtocol: "SHA256"
          authKey: "authKey123"

          privProtocol: "AES256"
          privKey: "privKey123"

          timeout: 3
          retries: 2

          tags:
            - location:dc3
            - role:firewall
  1. Using Profiles & Global Metrics

You can apply vendor profiles directly:

copy
icon/buttons/copy 
instances:
  - ip_address: "172.17.0.30"
    snmp_version: "2"
    community_string: "public"

    use_global_metrics: true
    profile: "cisco-3850"

    tags:
      - "location:branch"
  1. SNMP Autodiscovery (Subnet-based)

Autodiscovery scans entire subnets and automatically identifies devices using sysObjectID.

SNMPv2 Autodiscovery

copy
icon/buttons/copy 
metrics:
  - enabled: true
    namespace: atatus.ndm

    snmp:
      init_config:
        enabled: true

      instances:
        - name: "subnet-10.10"
          network_address: "10.10.0.0/24"

          snmp_version: "2"
          community_string: "public"

          namespace: "dc3"


          discovery_interval: 3600
          discovery_allowed_failures: 3
          discovery_workers: 100

          tags:
            - env:prod
            - subnet:10.10

SNMPv3 Autodiscovery

copy
icon/buttons/copy 
metrics:
  - enabled: true
    namespace: atatus.ndm

    snmp:
      init_config:
        enabled: true

      instances:
        - name: "firewall-primary"
          ip_address: "172.17.0.20"
          port: 161

          snmp_version: "3"

          user: "monitor"
          authProtocol: "SHA256"
          authKey: "authKey123"

          namespace: "dc3"


          privProtocol: "AES256"
          privKey: "privKey123"

          timeout: 3
          retries: 2

          tags:
            - location:dc3
            - role:firewall

Full Example: SNMPv2 Configuration with Two Locations & Two Subnets

copy
icon/buttons/copy 
metrics:
  - enabled: true
    namespace: atatus.ndm

    tags:
      - env:prod
      - team:network

    snmp:
      # Global SNMP Init Config
      init_config:
        enabled: true
        use_device_id_as_hostname: true
        oid_batch_size: 5
        min_collection_interval: 60
        collect_device_metadata: true
        collect_topology: true
        collect_vpn: false
        bulk_max_repetitions: 10
        namespace: atatus.ndm

        ping:
          enabled: true
          count: 2
          interval: 1000
          timeout: 1000
          linux:
            use_raw_socket: true

      # Device Instances (SNMPv2)
      instances:

        # Location 1: Direct device polling
        - name: "core-switch-dc1"
          ip_address: "172.17.0.10"
          port: 161
          snmp_version: "2"
          community_string: "public"
          namespace: "dc1"

          timeout: 2
          retries: 3

          tags:
            - location:dc1
            - role:switch

        - name: "edge-router-dc1"
          ip_address: "172.17.0.11"
          port: 161
          snmp_version: "2"
          community_string: "public"
          namespace: "dc1"

          timeout: 2
          retries: 3

          tags:
            - location:dc1
            - role:router

        # Location 2: Direct device polling
        - name: "core-switch-dc2"
          ip_address: "10.200.5.10"
          port: 161
          snmp_version: "2"
          community_string: "private"
          namespace: "dc2"

          timeout: 2
          retries: 3

          tags:
            - location:dc2
            - role:switch

        - name: "firewall-dc2"
          ip_address: "10.200.5.11"
          port: 161
          snmp_version: "2"
          community_string: "private"
          namespace: "dc2"


          tags:
            - location:dc2
            - role:firewall

        # Autodiscovery — Subnet Scanning

        # Subnet for Location 1
        - name: "dc1-subnet-scan"
          network_address: "172.17.0.0/24"
          snmp_version: "2"
          community_string: "public"
          namespace: "dc1"


          discovery_interval: 3600
          discovery_allowed_failures: 3
          discovery_workers: 100

          tags:
            - location:dc1
            - subnet:172.17.0.0/24

        # Subnet for Location 2
        - name: "dc2-subnet-scan"
          network_address: "10.200.5.0/24"
          snmp_version: "2"
          community_string: "private"
          namespace: "dc2"


          discovery_interval: 3600
          discovery_allowed_failures: 3
          discovery_workers: 100

          tags:
            - location:dc2
            - subnet:10.200.5.0/24

Restart the Agent

Apply the configuration:

copy
icon/buttons/copy 
sudo systemctl restart atatus-infra-agent