Server configuration#

Server part acts as the SNMP agent side of the SNMP proxy system. It is normally linked with one or more clients via trunks.

Basic configuration strategy for the server part is:

Global options#

config-version#

Configuration file language version. Currently recognized version is 2.

program-name#

Program name to consume this configuration file. Valid values are snmpfwd-client and snmpfwd-server.

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.

A single instance of SNMP Proxy Forwarder server or client 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
}

Note

There is no correlation between snmp-engine-id configured at server and client parts of SNMP Proxy Forwarder. They can be the same or differ in any way.

snmp-transport-domain#

Configures two things at once:

  • type of network transport (UDP/IPv4 or UDP/IPv6)

  • instance of network connection endpoint to refer SNMP agent/manager to

Transport type is determined by OID prefix, while endpoint instance - by OID suffix

Recognized 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 SNMP request-response communication at any IP address, even if such IP interface does not exist at this system

  • virtual-interface - enables SNMP request-response communication via a secondary IP interface and learns actual destination IP address used by the Manager regardless of the one we are bound to

The transparent-proxy option effectively hides SNMP Proxy Forwarder from SNMP agents giving them an illusion that they communicate directly with SNMP managers.

See also client-side configuration.

Note

Additional network configuration is required on the network to make SNMP request packets reaching the host where SNMP Proxy Forwarder 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-server-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).

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.

However, it is absolutely essential to configure snmp-security-engine-id matching SNMP engine ID of the SNMP entity sending SNMPv3 TRAP (known as authoritative SNMP engine). The reason is that TRAP is a unidirectional message what makes automatic SNMP engine ID discovery impossible.

Example:

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

Warning

SNMPv3 TRAP reception will not work unless SNMP engine ID of the authoritative SNMP engine is configured as snmp-security-engine-id.

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.

Note

Client-side plugins are also available.

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-server-option) and its options (plugin-options-server-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
}

Trunking options#

Trunk is a persistent TCP connection between SNMP Proxy Forwarder parts maintained for the purpose of relaying SNMP messages.

trunk-bind-address#

Local IPv4 or IPv6 network endpoint address to bind trunk connection to.

trunk-peer-address#

Remote IPv4 or IPv6 network endpoint address to connect to when establishing trunk connection.

trunk-ping-period#

Enables trunk keep alive communication every N seconds. Trunk is terminated and re-established if trunking peer fails to acknowledge the keep alive message within the N seconds time period.

The value of 0 disables trunk keep alive messaging.

Note

Each side of the trunk can monitor trunk connection independently of its peer guided by its own trunk-ping-period option.

trunk-connection-mode#

Trunk connection mode: client or server. Determines the originator of the trunk connection. When in client mode, actively tries to establish and maintain running connection with a peer. When in server mode, opens TCP port and listens at it for client connections.

Note

There is no correlation between SNMP entity and trunk connection roles.

trunk-crypto-key#

Shared secret key used for trunk connection encryption. Missing option disables trunk encryption.

Note

The key must be the same at both client and server for trunking link between them to establish.

trunk-id#

Unique identifier of a single trunk connection. Client trunks determine trunk-id, server-mode connections learn trunk-id from connecting clients.

trunking-group {
  trunk-crypto-key: 1234567890

  connect-over-ipv6 {
    trunk-bind-address: [::1]
    trunk-peer-address: [::1]:30301
    trunk-connection-mode: client

    trunk-id: servertrunk
  }

  listen-on-ipv4 {
    trunk-bind-address: 127.0.0.1:30201
    trunk-connection-mode: server

    trunk-id: <discover>
  }
}

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-server-option, snmp-context-name-pattern-server-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, GETBULK, TRAPv1, TRAPv2 (the latter is also applicable for SNMPv3).

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-server-option, snmp-pdu-oid-prefix-pattern-list-server-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-server-option = virtual-interface.

snmp-peer-id#

Unique identifier matching pairs of source and destination SNMP transport endpoints. Most importantly, snmp-bind-address-pattern-list-server-option and snmp-peer-address-pattern-list-server-option as well as snmp-transport-domain-server-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

  • trunk ID to pass SNMP message to

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-server-option in the list.

matching-snmp-content-id-list#

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

matching-snmp-credentials-id-list#

Evaluates to True if snmp-credentials-id-server-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-server-option in the list.

using-plugin-id-list#

Invoke each of the plugin-id-server-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-trunk-id-list#

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

Incoming (and possibly modified) SNMP message will be forwarded to each trunk-id-server-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-trunk-id-list: clienttrunk
  }
}