This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

snmp: Send SNMP traps

1: Converting Cisco syslog messages to clogMessageGenerated SNMP traps

2: snmp() destination options

The snmp() driver sends SNMP traps using the Simple Network Management Protocol version 2c or version 3. Incoming log messages can be converted to SNMP traps, as the fields of the SNMP messages can be customized using AxoSyslog macros.

The snmp() driver is available in AxoSyslog version 3.22 and later.

Note The snmp destination driver currently supports sending SNMP traps only using the UDP transport protocol.

The snmp() driver requires the host(), trap-obj(), and snmp-obj() options to be set, as well as the engine-id() and version() options when using the SNMPv3 protocol. For the list of available optional parameters, see snmp() destination options.

Declaration:

   destination d_snmp {snmp(host() trap-obj() snmp-obj() ...);};

Warning If AxoSyslog cannot resolve the destination hostname during startup, it will try to resolve the hostname again when the next message to be sent as an SNMP trap is received. However, if this name resolution fails, the trap will be dropped.

Note The snmp() destination driver does not generate MARK signals itself, but can receive and forward MARK signals.

Example: Using the snmp() destination driver

The following example defines an SNMP destination that uses the SNMPv2c protocol.

   destination d_snmpv2c{
        snmp(
            version('v2c')
            host('192.168.1.1')
            trap-obj('.1.3.6.1.6.3.1.1.4.1.0', 'Objectid', '.1.3.6.1.4.1.18372.3.1.1.1.2.1')
            snmp-obj('.1.3.6.1.4.1.18372.3.1.1.1.1.1.0', 'Octetstring', 'Test SNMP trap')
            snmp-obj('.1.3.6.1.4.1.18372.3.1.1.1.1.2.0', 'Octetstring', 'admin')
            snmp-obj('.1.3.6.1.4.1.18372.3.1.1.1.1.3.0', 'Ipaddress', '192.168.1.1')
            );
    };

The following example defines an SNMP destination that uses the SNMPv3 protocol and uses macros to fill the values of the SNMP objects.

   destination d_snmpv3{
        snmp(
            version('v3')
            host('192.168.1.1')
            port(162)
            engine-id('0xdeadbeefde')
            auth-username('myusername')
            auth-password('password')
            enc-algorithm('AES')
            enc-password('password')
            trap-obj('.1.3.6.1.6.3.1.1.4.1.0', 'Objectid', '.1.3.6.1.4.1.18372.3.1.1.1.2.1')
            snmp-obj('.1.3.6.1.4.1.18372.3.1.1.1.1.1', 'Octetstring', '${MESSAGE}')
            snmp-obj('.1.3.6.1.4.1.18372.3.1.1.1.1.2', 'Octetstring', 'admin')
            snmp-obj('.1.3.6.1.4.1.18372.3.1.1.1.1.3', 'Ipaddress', '${SOURCEIP}')
            );
    };

1 - Converting Cisco syslog messages to clogMessageGenerated SNMP traps

The AxoSyslog application can convert the syslog messages sent by Cisco devices to Cisco-specific SNMP traps defined by the CISCO-SYSLOG-MIB (enterprises.cisco.ciscoMgmt.ciscoCiscoMIB) is also supported (such traps are also referred to as clogMessageGenerated notifications). That way, the incoming log messages can be forwarded to devices used to process and analyze Cisco-specific SNMP traps. For this to work correctly, the following requirements must be met:

The Source Configuration Library (SCL) must be included in the AxoSyslog configuration file:
```
    @include "scl.conf"
```
The pattern database described in Parsing Cisco-specific message fields with patterndb must be used to parse the incoming log messages.

To accomplish this, AxoSyslog has to use a special pattern database to parse the Cisco-specific syslog messages, because these messages do not comply with the standard syslog formats.

For details on the Cisco-specific SNMP trap format, see CISCO-SYSLOG-MIB.

Parsing Cisco-specific message fields with patterndb

The ${PROGRAM} part of the syslog messages sent by Cisco devices contain not only the program name, but other important protocol information part as well. The ${PROGRAM} of these messages contains the Facility, Severity, and the Mnemonic (the Cisco name) of the message. The following pattern database parses these values and makes them available as the .cisco.Facility, .cisco.Severity, and .cisco.MsgName, respectively. The actual log message is available as .cisco.MsgText.

   <patterndb version="4" pub_date="2011-05-03">
        <ruleset name="cisco snmp ruleset1" xml:id="480de478-d4a6-4a7f-bea4-0c0245d361e3">
            <description>Pattern for Cisco messages having BSD timestamps, for example: Jul 01 2010 00:32:59: %SYS-5-CONFIG_I: Configured from console by console</description>
            <pattern>%@ESTRING:.cisco.Facility:-@@ESTRING:.cisco.Severity:-@@ANYSTRING:.cisco.MsgName@</pattern>
                <rules>
                    <rule xml:id="09944c71-95eb-4bc0-8575-936931d85713" provider="oneidentity" class="system">
                        <patterns>
                            <pattern> @ANYSTRING:.cisco.MsgText@</pattern>
                        </patterns>
                    </rule>
                </rules>
        </ruleset>
        <ruleset name="cisco snmp ruleset2" xml:id="480de478-d4a6-4a7f-bea4-0c0245d361e3">
            <description>Pattern for Cisco messages having cisco-specific timestamps, for example: 18: Jan 22 10:45:44.543: %SYS-5-CONFIG_I: Configured from console by console</description>
            <rules>
                <rule xml:id="09944c71-95eb-4bc0-8575-936931d85714" provider="oneidentity" class="system">
                    <patterns>
                        <pattern>%@ESTRING:.cisco.Facility:-@@ESTRING:.cisco.Severity:-@@ESTRING:.cisco.MsgName::@ @ANYSTRING:.cisco.MsgText@</pattern>
                    </patterns>
                </rule>
            </rules>
        </ruleset>
    </patterndb>

Sending clogMessageGenerated SNMP traps

To send out clogMessageGenerated SNMP traps, use the cisco_snmp() destination driver. The cisco-snmp() destination is actually a modified version of the snmp() destination driver.

Note The cisco-snmp() driver is actually a reusable configuration snippet. For details on using or writing SCLs, see Reusing configuration blocks.

The cisco-snmp() driver has the same requirements and options as the snmp() destination driver, but automatically fills the clogMessageGenerated-specific fields with the data received from parsing the Cisco-specific syslog messages using the pattern database. For details on the , see the <INSTALLDIR>/ share/include/scl/snmp/plugin.conf file.

Declaration:

   destination d_cisco_snmp {cisco-snmp(host(<hostname>));};

Example: Defining a Cisco-specific SNMP destination

The following example defines an SNMP destination that sends out clogMessageGenerated messages using the SNMPv3 protocol.

   destination d_cisco_snmp {cisco-snmp(host("192.168.1.1")
    version("v3")
    engine-id("'0xdeadbeefde'")
    auth-username('myusername')
    auth-password('password')
    enc-password('password'));};

2 - snmp() destination options

This driver sends SNMP traps using the SNMP v2c or v3 protocol.

The snmp() destination has the following options:

auth-algorithm()


Type:	SHA
Default:	SHA

Description: The authentication method to use. Lowercase values (for example, sha) can be used as well.

This option is used with the SNMPv3 protocol.

auth-password()


Type:	string
Default:	empty string

Description: The password used for authentication. If the auth-username() option is set but the auth-password() is empty, AxoSyslog will try to authenticate with an empty password.

This option is used with the SNMPv3 protocol.

auth-username()


Type:	string
Default:	empty string

Description: The username used to authenticate on the SNMP server. If this parameter is set, AxoSyslog will try to authenticate on the SNMP server.

This option is used with the SNMPv3 protocol.

community()


Type:	string
Default:	public

Description: The community string used for SNMPv2c authentication.

This option is used with the SNMPv2c protocol.

enc-algorithm()


Type:	AES
Default:	AES

Description: The encryption method used to encrypt the SNMP traffic. Lowercase values (for example, aes) can be used as well.

This option is used with the SNMPv3 protocol.

enc-password()


Type:	string
Default:

Description: The password used for the encryption. Encryption is used only if the enc-password() is not empty.

This option is used with the SNMPv3 protocol.

engine-id()


Type:	number (hexadecimal number)
Default:

Description: The engine ID is a hexadecimal number at least 10 digits long, starting with 0x. for example, 0xABABABABAB.

This option is a required parameter when using the SNMPv3 protocol.

host()


Type:	hostname or IP address
Default:	n/a

Description: Hostname of the SNMP server.

log-fifo-size()


Type:	number
Default:	Use global setting.

Description: The number of messages that the output queue can store.

port()


Type:	number (port number)
Default:	162

Description: The port number to connect to.

snmp-obj()


Type:	<oid_of_the_object> <type_of_the_object»<value_of_the_object> >
Default:	n/a

Description: The snmp-obj() option can be used to create custom SNMP trap elements. To create a trap element, specify the OID, type, and value of the element in the snmp-obj() option. To send SNMP traps, at least one snmp-obj() option must be defined. The snmp-obj() option requires the following parameters. Note that AxoSyslog does not validate the values of these elements.

<oid_of_the_object>: The object id of the SNMP object, for example, .1.3.6.1.4.1.18372.3.1.1.1.1.1`.
<type_of_the_object>: The type of the object specified as an ASN.1 primitive. One of: Integer, Timeticks, Octetstring, Counter32, Ipaddress, Objectid`. The type names are not case sensitive.
<value_of_the_object>: The value of the object as a string. The macros of AxoSyslog can be used to set these values, making it possible to transfer the content and other metadata from the the syslog message to the SNMP trap. Note that if the value of an Integer, Counter32orTimeticks` object is not a number (for example, is an empty string or other not-number string), AxoSyslog will automatically replace the value with 0. The values of other types of objects are not validated.

Example: Defining SNMP objects

The following are SNMP object definitions:

   snmp-obj('.1.3.6.1.4.1.18372.3.1.1.1.1.3', 'Ipaddress', '192.168.1.1')

   snmp-obj('.1.3.6.1.4.1.18372.3.1.1.1.1.2', 'Octetstring', '${MESSAGE}')

time-zone()


Type:	name of the timezone, or the timezone offset
Default:	unspecified

Description: Convert timestamps to the timezone specified by this option. If this option is not set, then the original timezone information in the message is used. Converting the timezone changes the values of all date-related macros derived from the timestamp, for example, HOUR. For the complete list of such macros, see Date-related macros.

The timezone can be specified by using the name, for example, time-zone("Europe/Budapest")), or as the timezone offset in +/-HH:MM format, for example, +01:00). On Linux and UNIX platforms, the valid timezone names are listed under the /usr/share/zoneinfo directory.

trap-obj()


Type:	<oid_of_the_object> “Objectid”, <value_of_the_object»
Default:	n/a

Description: The trap-obj() is a specialized version of the snmp-obj() option that is used to identify the SNMP trap object. The type of the trap object is always Objectid. The <oid_of_the_object> and the <value_of_the_object»parameters are identical to the respective parameters of the snmp-obj() option. For details on these parameters, see snmp-obj().

Note Using the trap-obj() object is equivalent to using the snmp-obj() with the Objectid type.

version()


Type:	v2c
Default:	v2c

Description: Specifies which version of the SNMP protocol to use.

Note The AxoSyslog application will accept any valid option for the snmp() destination, but will only use the ones relevant to the selected protocol version, any other option will be ignored. For example, if the version("v2c") engine-id("0xABABABABAB") community("mycommunity") options are set, AxoSyslog will accept every option, but process only the community() option, because engine-id() applies only to SNMPv3.