Macro substitution

Many configuration options may refer to macros that get expanded in the context of running request. That let you make your configuration more compact and dynamic.

The syntax of a macro reference resembles bash variable syntax: dollar sign followed by macro name in braces e.g. ${name}.

System macros

config-dir

Gets expanded to the directory component of snmpfwd process configuration file.

Example:

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

  plugin-id: rewrite
}

SNMP macros

These macros get expanded into a value coming from SNMP message being processed.

snmp-engine-id

SNMP Engine ID value from incoming SNMP request. Should match the snmp-engine-id configured to the SNMP engine instance serving this request.

snmp-transport-domain

Object Identifier matching the snmp-transport-domain value through which current SNMP request was received.

snmp-peer-address

Network address (IPv4/IPv6) from which SNMP message has been received.

snmp-peer-port

Network port number (UDP) from which SNMP message has been received.

snmp-bind-address

Network address (IPv4/IPv6) at which SNMP message has been received. Matches snmp-bind-address configured to the SNMP engine instance serving this request.

snmp-bind-port

Network port number (UDP) at which SNMP message has been received. Matches snmp-bind-address configured to the SNMP engine instance serving this request.

snmp-security-model

SNMP Security Model value from incoming SNMP request. Should match the snmp-security-model configured to the SNMP engine instance serving this request.

snmp-security-level

SNMP Security Level value from incoming SNMP request. Should match the snmp-security-level configured to the SNMP engine instance serving this request.

snmp-security-name

SNMP Security Name value from incoming SNMP request. Should match the snmp-security-name configured to the SNMP engine instance serving this request.

snmp-security-engine-id

SNMP Security Engine ID value from incoming SNMP request.

snmp-context-engine-id

SNMP Context Engine ID value from incoming SNMP request. Should match the snmp-context-id configured to the SNMP engine instance serving this request.

snmp-context-name

SNMP Context Name value from incoming SNMP request. Should match the snmp-context-name configured to the SNMP engine instance serving this request.

Server classification macros

Before passing SNMP message over to the client part, server classifies incoming SNMP message for its own routing purposes. The outcome of server-side classification is available at the client part, so that it could be used for client-side message routing purposes as well.

server-snmp-credentials-id

The snmp-credentials-id value being used for processing the SNMP request.

server-snmp-context-id

The snmp-context-id value being used for processing the SNMP request.

server-snmp-content-id

The snmp-content-id value being used for processing the SNMP request.

server-snmp-peer-id

The snmp-peer-id value being used for processing the SNMP request.

Examples

There is a use-case when you may want to pass SNMP fields from original SNMP query, as received by the server part, towards backend SNMP agent. You could do that by configuring macros to the client part:

snmp-credentials {
    snmp-context-engine-id: ${context-engine-id}
    snmp-context-name: ${context-name}

    snmp-peer-id: manager-123

    ... the rest of SNMP options
}

Transparent SNMP proxy configuration implies sending packets spoofing original network addresses. The spoofing part can be captured by configuring a macro:

snmp-credentials {
    # send from source address of original SNMP request
    snmp-bind-address: ${snmp-peer-address}
    snmp-peer-address: 104.236.166.95:161

    snmp-peer-id: snmplabs-v3-original-source

    ... the rest of SNMP options
}

Warning

For spoofing to succeed snmp-transport-domain types should belong to the same address family e.g. UDP/IPv4 or UDP/IPv6.