SnmpApp

SNMP Application Configuration

The N2SVCD SNMP Application listens for inbound SNMP requests and sends outbound SNMP event traps on behalf of other applications.

For SNMP requests received, the SNMP Application queries other applications and prepares responses.

Note that the only security model supported is the USM model defined in RFC 3414, and only SNMP version 3 messages are supported by this application. When forwarding SNMP messages from other applications, the SNMP Application functions as the USM Authoritative SNMP Engine.

Note that the SNMP Application is only required if you wish to process incoming SNMP requests. If an SNMP Application is not available, other components will send SNMP traps as per the global SNMP configuration.

See the N2SVCD Configuration Overview for more information on how the SNMP Application interacts with other components.

A sample minimal configuration for an SNMP Application instance might be:

<?xml version="1.0" encoding="utf-8"?>
<n2svcd>
  ...
  <applications>
    ...
    <application name="SNMP" module="SnmpApp">
      <include><lib>../apps/snmp/lib</lib></include>
      <parameters />
      <config>
        <groups>
          <group name="group1"/>
        </groups>

        <users>
          <user username="user1" group="group1"/>
        </users>

        <views>
          <view name="view1"/>
        </views>

        <accesses>
          <access group="group1" read_view="view1"/>
        </accesses>
      </config>
    </application>
    ...
  </application>
  ...
</n2svcd>

This configuration will:

• Start an SNMP server listening using the default address localhost:161,
• Have a single user user1 that cannot decrypt nor authenticate any messages,
• Not differentiate between any received SNMP context,
• Allow access to all read functions for the defined user, and
• Forbid access to all write functions for the defined user.

Configuration Details

The application element attributes for a SNMP Application instance may include the below.

For details of the various parameter types used, refer to Common Configuration.

Note that it may be necessary to increase the SNMP application’s admin_alloc application configuration parameter to account for the additional administrative messaging caused by proxying alarms.

SNMP Groups Definition

The SNMP groups definition is a simple list of the available groups for SNMP users to belong to. Only one group is permitted per user, as per RFC 3415. An example configuration might be:

<?xml version="1.0" encoding="utf-8"?>
<n2svcd>
  ...
  <applications>
    ...
    <application name="SNMP" module="SnmpApp">
      ...
      <config>
        ...
        <groups>
          <group name="group1"/>
          <group name="group2"/>
        </groups>
      </config>
    </application>
    ...
  </application>
  ...
</n2svcd>

The following parameters are available for each group within the groups configuration:

SNMP Users Definition

Users that can access the SNMP Application from inbound messages must be defined to allow access to available functions.

All users exist only against the SNMP Application engine ID as the authoritative SNMP engine.

An example configuration might be:

<?xml version="1.0" encoding="utf-8"?>
<n2svcd>
  ...
  <applications>
    ...
    <application name="SNMP" module="SnmpApp">
      ...
      <config>
        ...
        <users>
          <user name="no_security_user"
                group="group1"/>
          <user name="auth_only_user"
                group="group2"
                auth_key="0183c5b0eefb85b6dd3181a787219bc5">
          </user>
          <user name="privacy_user" 
                group="group3"
                auth_password="maplesyrup"
                auth_alg="des"
                privacy_password="treacle">
          </user>
        </users>
      </config>
    </application>
    ...
  </application>
  ...
</n2svcd>

The following parameters are available for each user within the users configuration:

Note that:

• As per RFC 3414, a zero-length username is permitted for discovery purposes. Such a user has no other permissions and may not be defined manually.
• Users defined within the users configuration block are used for inbound messages and associated responses only. The user for outbound messages is taken preferentially from the global SNMP configuration or SNMP application user configuration.

SNMP Views Definition

The SNMP views definition is an array of the available views for SNMP accesses. An example configuration might be:

<?xml version="1.0" encoding="utf-8"?>
<n2svcd>
  ...
  <applications>
    ...
    <application name="SNMP" module="SnmpApp">
      ...
      <config>
        ...
        <views>
          <view name="view1">
            <exclude subtree="1.2.3.4"/>
          </view>
          <view name="view2">
            <include subtree="1.2.3.4.*"/>
            <exclude subtree="1.2.3.4.5"/>
            <exclude subtree="1.2.3.4.6"/>
          </view>
        </views>
      </config>
    </application>
    ...
  </application>
  ...
</n2svcd>

The following parameters are available for each view within the views configuration:

Note that a view without any include or exclude element will be treated as though it has a single include element of *, i.e. a view inclusion that includes all possible OIDs.

SNMP View Inclusion/Exclusion

All SNMP views may have zero or more explicit inclusions or exclusions via configuration of include or exclude elements, respectively.

By default, a view will have full visibility of all available MIB OIDs. However:

• if one or more include elements are configured, visibility will be limited to just the scope of the included elements.
• if one or more exclude elements are configured, any included elements will have the excluded elements removed.

Exclusions may be configured regardless of whether any inclusions are defined.

Note that for defining inclusions and exclusions for views:

• A shorter OID request than in an include is not allowed (e.g. a request of 1.2 with include of 1.2.3)
• A longer OID request than in an include is allowed when a trailing wildcard is present and disallowed otherwise (e.g. a request of 1.2.3 with include of 1.2.*/1.2 respectively)
• A shorter OID request than in an exclude is allowed (e.g. a request of 1.2 with exclude of 1.2.3)
• A longer OID request than in an exclude is not allowed when a trailing wildcard is present and allowed otherwise (e.g. a request of 1.2.3 with exclude of 1.2.*/1.2 respectively)

Note that for explicit view control of individual scalar OIDs, 0 must be appended to the OID as per RFC 3781.

SNMP Accesses Definition

SNMP accesses are used to determine the appropriate security options to apply when receiving inbound SNMP messages.

When matching an access to an inbound message, a modified form of the method defined in RFC 3415 in the ASN.1 definition of vacmAccessTable is used:

1. Identify all accesses that match the group of the received user, have authentication and/or privacy equal to or higher than the message security, and have a matching context (potentially as a prefix).
2. If only one access matches, use it.
3. If any accesses fully match the context received, discard any others.
4. Discard any accesses with shorter contexts than the longest matched context.
5. Select the first access with the highest authentication and/or privacy security.

<?xml version="1.0" encoding="utf-8"?>
<n2svcd>
  ...
  <applications>
    ...
    <application name="SNMP" module="SnmpApp">
      ...
      <config>
        ...
        <accesses>
          <access group="group1" read_view="view1"/>
          <access group="group1"
                  context="n2svcd"
                  prefix="0"
                  auth="1"
                  priv="0"
                  read_view="view2"
                  write_view="view3"/>
        </accesses>
      </config>
    </application>
    ...
  </application>
  ...
</n2svcd>

The following parameters are available for each access within the accesses configuration:

Note that:

• auth and priv together set the minimum message security level that is required for access, as per RFC 3415.
• No empty (“default”) context is created by default (see RFC 3415). This may be explicitly specified, either as a prefix (functioning as a catch-all) or as a discrete match.

SNMP Engine Mappings

Each N2SVCD application has its own SNMP context engine ID, either set automatically as described in the SNMP trap configuration or manually overridden per-application. Because each N2SVCD application does not expose a listening SNMP port, the SNMP Application is used to broker inbound requests to these applications accordingly.

Default engine IDs may be automatically added to the mappings if configured to do so.

Whenever an SNMP message is received, the engine ID mapping table is checked first for a matching engine and context value before attempting to match to an automatic identifier (without examining context). The first result found via either method is used to attempt to route the message to the applicable application.

If no match can be made, the message will be rejected unless the application is configured to query all applications.

This mapping table is used solely for the PDU context engine ID. The RFC 3414 authoritative engine ID is checked against engine ID configuration.

Note that requests (other than get-next) containing SNMP proxy OIDs are always handled by the receiving SNMP application directly and are never sent to other applications. Information for such OIDs is always taken from the engine mappings table, including any automatically-configured engine IDs.

<?xml version="1.0" encoding="utf-8"?>
<n2svcd>
  ...
  <applications>
    ...
    <application name="SNMP" module="SnmpApp">
      ...
      <config>
        ...
        <engine_mappings>
          <mapping id="8000dcdc0457616c6b65722d342e6e3273766364"
                   app="Watchdog"/>
          <mapping id="8000dcdc0457616c6b65722d342e6e3511223316"
                   context="*"
                   app="N2IWF*"/>
        </engine_mappings>
      </config>
    </application>
    ...
  </application>
  ...
</n2svcd>

The following parameters are available for each mapping within the engine_mappings configuration:

Application names in the app parameter may be configured in one of three ways to affect how incoming messages are routed:

1. With no suffix, e.g. Application. Incoming messages matching this engine ID would be sent to all repeated applications, i.e. Application:0 .. Application:n.
2. With an explicit index, e.g. Application:0. Incoming messages matching this engine ID would be sent to only the matching application instance, i.e. Application:0.
3. With a wildcard suffix, e.g. Application*. Incoming messages matching this engine ID would be sent to all applications, including repeated applications, matching the pattern, i.e. not only Applicaiton:0 .. Application:n but also, say, ApplicationX:0 .. ApplicationX:n.

In some cases, even if multiple application instances are matched for a request, it will be limited to only the last match (application names are sorted prior to matching). This occurs when:

1. The PDU type is get-next, or
2. An OID value type that is not a countable values (e.g. integer-value) is present within the variable bindings.

Receiving applications are free to respond to SNMP requests with arbitrary information. When only a single application instance receives a request, its response will be used verbatim. However, if multiple applications respond to a request:

• The value format type for each variable binding is selected in the following order:
  1. valueless type unSpecified
  2. valueless type noSuchObject
  3. valueless type noSuchInstance
  4. any value-holding type (e.g. integer-value)
  5. valueless type endOfMibView
• When variable binding types hold values (e.g. integer-value), the first value type received will set the expected value type. Any subsequent responses received with value-holding types that do not match will be discarded.
• The first application response received with a non-zero number of variable bindings will set both the number of expected bindings and the OID for each. Any subsequent responses received with inconsistent variable binding counts or OIDs will be discarded.
• When variable binding types hold countable values (e.g. integer-value), the counts for each will be added together at each discrete index in the variable bindings. Note that should the same OID be present at a different index, its value will not be added together with other index positions.
• When variable binding types hold uncountable values (e.g. string-value), only the first response for each variable binding value will be used.

Message Handling

In addition to the common Application management messages, the SNMP Application uses the following messages:

• !SNMP-S-REQUEST messages (!SNMP-S-REQUEST inbound)
• !SNMP-S-RESPONSE messages (!SNMP-S-RESPONSE outbound)
• !SNMP-C-REQUEST messages (!SNMP-C-REQUEST outbound)