SNMP Responder configuration#

SNMP Responder daemon is essentially a versatile SNMP agent listening on one or many network endpoints and maintaining one or more instances of MIB trees.

Basic configuration strategy could be:

Global options#

config-version#

Configuration file language version. Currently recognized version is 2.

program-name#

Program name to consume this configuration file. The only valid value is snmpresponderd.

SNMP agents options#

snmp-engine-id#

SNMP engine identifier that creates a new, independent instance of SNMP engine. All other SNMP settings scoped within this snmp-engine-id apply to this SNMP engine instance.

An instance of SNMP Command Responder can have many independent SNMP engine instances running concurrently.

Example:

{
    snmp-engine-id: 0x0102030405070809

    ... other SNMP settings for this SNMP engine
}
{
    snmp-engine-id: 0x090807060504030201

    ... other SNMP settings for this SNMP engine
}

snmp-transport-domain#

Creates listening network socket of specified type under given name (OID).

Transport type is determined by the OID prefix, while the whole OID is identified by the endpoint ID.

Recognized transport types i.e. OID prefixes are:

  • UDP/IPv4 - 1.3.6.1.6.1.1

  • UDP/IPv6 - 1.3.6.1.2.1.100.1.2

Any integer value can serve as OID suffix.

Examples:

snmp-transport-domain: 1.3.6.1.6.1.1.123
snmp-bind-address: 127.0.0.1:5555

Where 1.3.6.1.6.1.1 identifies UDP-over-IPv4 transport and 123 identifies transport endpoint listening at IPv4 address 127.0.0.1, UDP port 5555.

snmp-transport-domain: 1.3.6.1.2.1.100.1.2.123
snmp-bind-address: [::1]:5555

Here 1.3.6.1.2.1.100.1.2 identifies UDP-over-IPv6 transport and 123 identifies transport endpoint listening at IPv6 address ::1, UDP port 5555.

snmp-transport-options#

Enable advanced networking options. Valid values are:

  • transparent-proxy - enables source IP spoofing for SNMP responses and allows reception of SNMP requests destined to any IP address even if no such IP interface is present on the system

  • virtual-interface - makes SNMP responses originating from the same IP network interface where the SNMP request has come to

The transparent-proxy option can be used to serve many SNMP agents on the IPs that do not actually exist on the network.

Note

Additional network configuration (perhaps policy routing) is required on the network to make SNMP request packets reaching the host where SNMP Command Responder is running and accepting them by the host.

snmp-bind-address#

Listen for SNMP packets at this network address. Example:

udp-listener-123 {
    snmp-transport-domain: 1.3.6.1.6.1.1.200
    snmp-bind-address: 127.0.0.1:161
    snmp-credentials-id: agent-10
}

Note

If you want response SNMP messages to have source address of the SNMP request destination address (as opposed to primary network interface address when snmp-bind-address is set to 0.0.0.0), make sure to enable the snmp-transport-options-option = virtual-interface option.

snmp-security-model#

SNMP version to use. Valid values are:

  • 1 - SNMP v1

  • 2 - SNMP v2c

  • 3 - SNMP v3

snmp-security-level#

SNMPv3 security level to use. Valid values are

  • 1 - no message authentication and encryption

  • 2 - do message authentication, do not do encryption

  • 3 - do both authentication and encryption

snmp-security-name#

Identifier that logically groups SNMP configuration settings together.

Note

Must be unique within SNMP engine instance (e.g. snmp-engine-id-option).

snmp-security-engine-id#

The authoritative (security) SNMPv3 Engine ID to use when receiving SNMPv3 messages from SNMP peers. For receiving SNMP Commands, it is not necessary to specify snmp-security-engine-id engine ID, as snmp-engine-id might suffice.

Example:

{
    snmp-security-engine-id: 0x0102030405070809
}

snmp-community-name#

SNMP community string for SNMP v1/v2c.

snmp-usm-user#

SNMPv3 USM username.

snmp-usm-auth-protocol#

SNMPv3 message authentication protocol to use. Valid values are:

ID

Algorithm

Reference

NONE

RFC3414

MD5

HMAC MD5

RFC3414

SHA

HMAC SHA-1 128

RFC3414

SHA224

HMAC SHA-2 224

RFC7860

SHA256

HMAC SHA-2 256

RFC7860

SHA384

HMAC SHA-2 384

RFC7860

SHA512

HMAC SHA-2 512

RFC7860

snmp-usm-auth-key#

SNMPv3 message authentication key.

Note

Must be 8 or more characters.

snmp-usm-priv-protocol#

SNMPv3 message encryption protocol to use. Valid values are:

ID

Algorithm

Reference

NONE

RFC3414

DES

DES

RFC3414

AES

AES CFB 128

RFC3826

AES192

AES CFB 192

RFC Draft

AES256

AES CFB 256

RFC Draft

AES192BLMT

AES CFB 192 Blumenthal

RFC Draft

AES256BLMT

AES CFB 256 Blumenthal

RFC Draft

3DES

Triple DES EDE

RFC Draft

snmp-usm-priv-key#

SNMPv3 message encryption key.

Note

Must be 8 or more characters.

snmp-credentials-id#

Unique identifier of a collection of SNMP configuration options. Used to assign specific SNMP configuration to a particular SNMP entity. Can also be used to share the same SNMP configuration among multiple SNMP entities.

This option can contain SNMP macros.

Example:

my-snmpv3-user {
  snmp-security-level: 3
  snmp-security-name: test-user

  snmp-usm-user: test-user
  snmp-usm-auth-protocol: 1.3.6.1.6.3.10.1.1.2
  snmp-usm-auth-key: authkey1
  snmp-usm-priv-protocol: 1.3.6.1.6.3.10.1.2.2
  snmp-usm-priv-key: privkey1

  snmp-transport-domain: 1.3.6.1.6.1.1.200
  snmp-bind-address: 127.0.0.1:161

  snmp-credentials-id: snmpv3-agent-at-localhost
}

Plugin options#

The plugin options instantiate a plugin file with specific configuration options and assign an identifier to it. You can have many differently configured instances of the same plugin module in the system.

plugin-modules-path-list#

Directory search path for plugin modules.

This option can reference config-dir macro.

plugin-module#

Plugin module file name to load and run (without .py).

plugin-options#

Plugin-specific configuration option to pass to plugin.

This option can reference config-dir macro.

plugin-id#

Unique identifier of a plugin module (plugin-module-option) and its options (plugin-options-option).

This option can reference config-dir macro.

The plugin-id identifier is typically used to invoke plugin in the course of SNMP message processing.

Example:

rewrite-plugin {
  plugin-module: rewrite
  plugin-options: config=${config-dir}/plugins/rewrite.conf

  plugin-id: rewrite
}

logging-plugin {
  plugin-module: logger
  plugin-options: config=/etc/snmpfwd/plugins/logger.conf

  plugin-id: logger
}

MIB trees#

SNMP Command Responder can build one or more trees of MIB objects read from MIB modules. The SNMP commands will be executed against one of the MIB trees as selected by system configuration.

Note

With classical SNMP agent, SNMP context is likely to be used for similar purpose, however SNMP Command Responder is a bit more flexible as practically any aspect of SNMP command could be used for MIB tree selection.

mib-text-search-path-list#

List of URIs where SNMP Command responder should search for ASN.1 MIBs on which the MIBs being served depend on.

mib-code-modules-pattern-list#

List of regular expressions denoting filesystem paths where SNMP Command Responder should search for MIB modules expressed in pysnmp MIB/SMI data model. The matching modules will be loaded, executed and brought on-line by SNMP Command Responder and served to SNMP managers.

managed-objects-group {
  mib-text-search-path-list: http://mibs.pysnmp.com/asn1/
  mib-code-modules-pattern-list: ${config-dir}/managed-objects/.*py[co]?

  mib-tree-id: managed-objects-1
}

Note

Refer to MIB implementation chapter for information on how to prepare MIB implementation module.

mib-code-packages-pattern-list#

List of regular expressions matching the files residing in the Python package extending the snmpresponder.mibs entry point.

SNMP Command Responder will discover such packages, import the extensions they announce and walk through the files it finds under the top-level package directory. Matching files will be treated as MIB modules expressed in pysnmp MIB/SMI data model i.e. loaded, executed and brought on-line by SNMP Command Responder and served to SNMP managers.

managed-objects-group {
  mib-text-search-path-list: http://mibs.pysnmp.com/asn1/
  mib-code-packages-pattern-list: examples\..*

  mib-tree-id: managed-objects-1
}

Note

Refer to MIB implementation chapter for information on how to prepare MIB implementation module.

mib-tree-id#

Unique identifier of a MIB tree instance. It’s used solely for SNMP message routing.

mib-tree-group {

    mib-text-search-path-list: http://mibs.pysnmp.com/asn1/

    network-mibs {
        mib-code-modules-pattern-list: conf/generic/managed-objects/(IF-MIB|UDP-MIB).py

        mib-tree-id: network-mibs
    }

    host-mibs {
        mib-code-modules-pattern-list: conf/generic/managed-objects/HOST.*MIB.py

        mib-tree-id: host-mibs
    }
}

Note

Refer to MIB implementation chapter for information on how to prepare MIB implementation module.

SNMP context matching#

snmp-context-engine-id-pattern#

A regular expression matching SNMPv3 messages by SNMP context engine ID.

snmp-context-name-pattern#

A regular expression matching SNMPv3 messages by SNMP context name.

snmp-context-id#

Unique identifier of a collection of SNMP context configuration options. Used for matching SNMP context options in inbound SNMP messages (e.g. snmp-context-engine-id-pattern-option, snmp-context-name-pattern-option) for message routing purposes.

This option can contain SNMP macros.

Example:

context-group {
  snmp-context-engine-id-pattern: .*?
  snmp-context-name-pattern: .*?

  snmp-context-id: any-context
}

SNMP PDU contents matching#

snmp-pdu-type-pattern#

A regular expression matching SNMPv3 messages by SNMP PDU type. Recognized PDU types are: GET, SET, GETNEXT and GETBULK.

content-group {
  snmp-pdu-type-pattern: (GET|GETNEXT)
  snmp-content-id: get-content
}

snmp-pdu-oid-prefix-pattern-list#

List of regular expressions matching OIDs in SNMP PDU var-binds.

snmp-content-id#

Unique identifier of a collection of SNMP content matching options. Used for matching the contents of inbound SNMP messages (e.g. snmp-pdu-type-pattern-option, snmp-pdu-oid-prefix-pattern-list-option) for message routing purposes.

This option can contain SNMP macros.

Example:

content-group {
  write-pdu-group {
    snmp-pdu-type-pattern: SET
    snmp-content-id: set-content
  }

  oid-subtree-group {
    snmp-pdu-oid-prefix-pattern-list: 1\.3\.6\.1\.2\.1\.2\..*?
    snmp-content-id: oid-subtree-content
  }

  others {
    snmp-content-id: any-content
  }
}

Network peers matching#

snmp-peer-address-pattern-list#

List of regular expressions matching source transport endpoints of SNMP message.

snmp-bind-address-pattern-list#

List of regular expressions matching destination transport endpoints of SNMP message.

Note

If you want to receive SNMP messages at secondary network interfaces and be able to match them, make sure you enable the snmp-transport-options-option = virtual-interface.

snmp-peer-id#

Unique identifier matching pairs of source and destination SNMP transport endpoints. Most importantly, snmp-bind-address-pattern-list-option and snmp-peer-address-pattern-list-option as well as snmp-transport-domain-option. The snmp-peer-id is typically used for message routing purposes.

This option can contain SNMP macros.

Example:

peers-group {
  snmp-transport-domain: 1.3.6.1.6.1.1.100
  snmp-peer-address-pattern-list: 10\.113\..*?
  snmp-bind-address-pattern-list: 127\.0\.0\.[2-3]:[0-9]+?

  snmp-peer-id: 101
}

Message routing#

The purpose of these settings is to determine:

  • plugin ID to pass SNMP message through

  • MIB tree ID to apply SNMP message onto

This is done by searching for a combination of matching IDs.

matching-snmp-context-id-list#

Evaluates to True if incoming SNMP message matches at least one of snmp-context-id-option in the list.

matching-snmp-content-id-list#

Evaluates to True if incoming SNMP message matches at least one of snmp-content-id-option in the list.

matching-snmp-credentials-id-list#

Evaluates to True if snmp-credentials-id-option used for processing incoming SNMP message is present in the list.

matching-snmp-peer-id-list#

Evaluates to True if incoming SNMP message originates from and arrived at one of the snmp-peer-id-option in the list.

using-plugin-id-list#

Invoke each of the plugin-id-option in the list in order passing request and response SNMP PDUs from one plugin to the other.

Plugins may modify the message in any way and even block it from further propagation in which case SNMP message will be dropped.

using-mib-tree-id#

Unique identifier matching a group of matching-* identifiers. Specifically, these are: matching-snmp-context-id-list-option, matching-snmp-content-id-list-option, matching-snmp-credentials-id-list-option and matching-snmp-peer-id-list-option.

Incoming (and possibly modified) SNMP message will be forwarded to each mib-tree-id-option present in the list.

Example:

routing-map {
  matching-snmp-context-id-list: any-context
  matching-snmp-content-id-list: any-content

  route-1 {
    matching-snmp-credentials-id-list: config-1 config-2 config-121
    matching-snmp-content-id-list: if-subtree-content
    matching-snmp-peer-id-list: 100 111

    using-plugin-id-list: logger rewrite
    using-mib-tree-id: host-mib
  }
}