Chapter 25. The SNMP Gateway

By using the SNMP gateway, ConfD makes SNMP data available through the management interfaces (such as CLI and NETCONF). The idea is that ConfD can co-exist with external SNMP agents on the device, and use SNMP (in the simplest case it will be SNMP over the loopback interface) to retrieve data from the agents, and present it over e.g. NETCONF.

What is needed to access the data provided by an SNMP agent is the MIB files defining the data. The MIB modules are translated into read-only YANG modules, using the standard mapping defined in http://www.ietf.org/rfc/rfc6643.txt. After compiling the YANG files, as described in earlier chapters, ConfD can load the resulting .fxs files and can then provide data from the SNMP agent through the various ConfD interfaces (CLI, NETCONF, etc.).

The gateway supports SNMP v1 and v2c when it communicates with the SNMP agent. SNMP v2c is preferred over v1, since it is more efficient.

In the ConfD configuration file confd.conf, the location of SNMP agents and characteristics of the communication with them can be specified with the /confdConfig/snmpgw element. An example is shown below:

<snmpgw>
  <enabled>true</enabled>
  <trapPort>5000</trapPort>
  <agent>
    <name>a1</name>
    <subscriptionId>id1</subscriptionId>
    <forwardNotifStream>stream1</forwardNotifStream>
    <enabled>true</enabled>
    <community>private</community>
    <version>v2c</version>
    <timeout>PT2S</timeout>
    <ip>127.0.0.1</ip>
    <port>161</port>
    <module>ONE-MIB</module>
    <module>TWO-MIB</module>
  </agent>
  <agent>
    <name>a2</name>
    <subscriptionId>id2</subscriptionId>
    <enabled>true</enabled>
    <community>private</community>
    <version>v2c</version>
    <timeout>PT2S</timeout>
    <ip>192.168.1.12</ip>
    <port>161</port>
    <module>THIRD-MIB</module>
  </agent>
</snmpgw>

Each /confdConfig/snmpgw/agent element is called an SNMP agent configuration element. It has to have a unique name (mainly for error reporting), and relates a subset of the configuration to a particular SNMP agent. The element module, which can be present multiple times, specifies which MIBs the agent implements. Each such MIB must be converted to YANG and compiled into an .fxs file.

The subscriptionId, forwardNotifStream and trapPort elements are described in the section Receiving and Forwarding Notifications.

The default value for the enabled element is true. If the value is false, this agent element is disregarded.

The possible values for the SNMP protocol version are v1 and v2c. v2c is preferred.

The /confdConfig/snmpgw/agent/timeout element has the type xs:duration. Timeout when communicating with the SNMP agent produces an error, and the ConfD operation is aborted.

In addition to the community element, which only allows for the specification of Unicode community strings, the element community_bin can be used for specifying arbitrary community strings, in the hexadecimal format xs:hexBinary. For example, <community_bin>004103</community_bin> specifies a string with three bytes; 0x00, 0x41 and 0x03. If both community_bin and community are given, the latter is ignored.

Each MIB is converted to YANG using confdc with the parameter --mib2yang-std. Then the resulting YANG module is compiled using confdc with the parameters -c --snmpgw.

$ confdc --mib2yang-std -o IF-MIB.yang IF-MIB.mib
$ confdc -c --snmpgw -o IF-MIB.fxs IF-MIB.yang

For the purpose of forwarding SNMP notifications (also called traps) from external agents to a user application, the SNMP gateway can be made to listen for notifications on the port indicated by the element /confdConfig/snmpgw/trapPort. If this element is not present, listening for notifications is disabled.

Only SNMPv2 notifications are handled.

Each agent configuration element may have a child element subscriptionId (of type xs:token). When a notification arrives, its sender (IP address and port) is compared with the agent configuration elements in an attempt to determine a subscriptionId. If a subscription id is found, and any application has subscribed to that subscription id, the notification is sent to it. A given ip/port pair should be handled by at most one subscriptionId, otherwise the confd.conf file is rejected.

To register its interest in notification reception, the application should call the function confd_register_notification_sub_snmp_cb(). Example:

int recv_snmp(struct confd_notification_ctx *nctx, char *notif,
              struct confd_snmp_varbind *vb, int n,
              confd_value_t *srcaddr, u_int16_t srcport)
{
    ...
}

int main()
{
    ...

    struct confd_daemon_ctx *dctx;
    struct confd_notification_sub_snmp_cb snmpcb;

    dctx = confd_init_daemon(dname, debuglevel, stderr);
    [ connect control and worker sockets ]
    strcpy(snmpcb.sub_id, "id1");
    snmpcb.recv = recv_snmp;
    confd_register_notification_sub_snmp_cb(dctx, &snmpcb);
    confd_register_done(dctx);

    ...
}

"id1" here is the subscription id. The function recv_snmp() will be called when a notification arrives:

notif is the name of the notification, if it can be obtained from the notification id (if the relevant MIB is loaded into the agent, or a YANG notification with the corresponding value for smiv2:oid is declared in a loaded module), otherwise the empty string. srcaddr/srcport are the IP address and port of the notification's (immediate) sender. The notification id appears in second position among the variables, and a timestamp in first position, as they should in a well-formed notification.

One thing an application may want to do with a received notification is to forward it somewhere else. See Section 17.2.15, “Notifications” for how to do that.

Instead of, or in addition to, the subscriptionId, an agent configuration element may have a forwardNotifStream child element. If present, this must correspond to a notification stream that doesn't implement replay support externally. (I.e. it must either use built-in replay support, or not offer replay.) When notifications arrive on the trap port, and a forwarding notification stream is set for the agent, the loaded yang modules will be search for a notification corresponding to the OID of the received notification, and if such a notification type exists, the received notification will be translated to that type and sent out on the forwarding stream. Unknown notifications will be dropped, as will unknown varbinds in otherwise recognized notifications.

In the following example, we assume that there exist a MIB OUR-MIB.mib and we wish to translate into a ConfD .fxs file so that we can use ConfD to access the MIB data. The example is very small; real-life MIBs are likely to also depend on several standard MIBs.

The following steps produce the file that ConfD needs (namely, OUR-MIB.fxs):

$ confdc --mib2yang-std -o OUR-MIB.yang OUR-MIB.mib
$ confdc -c --snmpgw OUR-MIB.yang