This chapter contains the following sections:
A receivelet is a library that allows Enterprise Manager to receive external notifications sent by third-party network elements. These are notifications that are asynchronously sent and without any requests from the Management Agent.
Usually, the Management Agent data retrieval mechanism is based on a polling model, that is, modular libraries, called fetchlets. Fetchlets collect values of various metrics from their managed targets on a regular basis. The Management Agent then compares the gathered data with user-defined thresholds and generates events when the thresholds were met.
Receivelets are a more efficient way of dealing with these metrics. It depends on the ability of the managed target to detect the condition for its own events, and then communicate with Enterprise Manager only when an event occurs. When this communication happens, the Management Agent uses receivelets to receive the information.
You can use receivelets as a quicker way to get alerts on data that will be eventually collected via fetchlets. You can also use receivelets as a way to send both alerts and data, or just alerts for cases where there is no real data chart associated with the alert.
A receivelet is not a substitute for a fetchlet, but it is another way of collecting data. It is more for immediacy of notification compared to periodic polling that the fetchlet offers. Therefore, if you can fetch data, then use fetchlets to get that data. However, if your server is capable of sending you events or data at a cost lower than that associated with fetchlets, then use receivelets.
A receivelet may be tightly coupled to a particular type of managed target, or may be useful to a broad range of potential targets.
The SNMP receivelet is offered with Enterprise Manager as described in the following section.
An SNMP receivelet allows you to receive SNMP trap notifications from third-party network elements, and translate them into a form compatible with Oracle Management Service (OMS).
While monitoring third-party entities in your managed environment, if the third-party entity wants to send a notification to Enterprise Manager, then the SNMP agent of that third-party entity sends a notification to the Management Agent. These notifications are in the form of SNMP traps that get triggered asynchronously and without any requests from the Management Agent.
Since these traps are based on SNMP, the Management Agent uses SNMP receivelets to receive and translate these SNMP traps into a form compatible with OMS.
When the SNMP traps are received, the SNMP receivelet extracts information pertaining to those object identifiers (OIDs) that are defined in the <PushDescriptor> section of the target type metadata file only. For more information about the target type metadata file, see Section 3.3, "Creating the Target Type Metadata File".
When a customer wants to manage a network element using the SNMP receivelet, they must configure the element's SNMP agent to send traps to the responsible Management Agent's SNMP receivelet. When the SNMP receivelet receives such traps, it translates them to an Enterprise Manager format (such as an event or datapoint based on the push descriptor information), and stores that information (in XML files) in the upload directory. The Upload Manager checks for such new files in the upload directory, and then uploads those files to OMS. Then Enterprise Manager accesses OMS to extract the collected information and displays it to the user.
To receive SNMP traps, you have to make some configuration settings at the Management Agent side and at SNMP target agent side.
This enables the SNMP targets to send SNMP traps to the SNMP receivelet. When the SNMP traps are received, the SNMP receivelet uses the Push Descriptor properties, such as MatchAgentAddr, MatchEnterprise, and so on, to identify the target and metric for which the traps belongs. Then the SNMP receivelet uses the Push Descriptor properties, such as Eventmetric-column or Eventmetric-columnOID, SeverityCode, and so on, to convert the traps into an event. When this happens, the SNMP receivelet uploads the converted event to the Management Repository and it is now available in the Cloud Control console.
Configuration Settings Required at the Management Agent Side
By default, the SNMP receivelet listens over UDP on the same port as that of the Management Agent. However, if you want to use a different listening port for the SNMP receivelet, then add the SnmpRecvletListenNIC(=8002) entry to the emd.properties file.
Configuration Settings Required at SNMP Target Agent Side
Configure the SNMP target agent to send its traps to the SNMP target agent's host name and port.
Table 19-1 SNMP Receivelet Input Parameters
| Parameter | Type | Description | Use |
|---|---|---|---|
|
MatchEnterprise |
String |
Note: For Push Descriptors that intend to match SNMPv1 traps only. OID used to define the trap being sent. Note: If MatchEnterprise is present, then you must include MatchGenericTrap and MatchSpecificTrap also. |
Required (SNMPv1) |
|
MatchGenericTrap |
String |
Code for a generic SNMP trap. |
Required (SNMPv1) |
|
MatchSpecificTrap |
String |
Trap defined in a MIB (not one of the generic traps), the ID assigned in that MIB. |
Required (SNMPv1) |
|
MatchTrapOID |
String |
Note: For Push Descriptors that intend to match SNMPv2 or SNMPv3 traps. For an SNMPv2 or SNMPv3 trap, this is the OID assigned to the NOTIFICATION-TYPE in the MIB definition of the trap. |
Required (SNMPv2, SNMPv3) |
|
MatchAgentAddr |
String |
IP address of the generating SNMP agent, as sent in the trap. |
Required |
|
MatchVarBind |
String |
If this parameter is present, its value is an OID. If a trap is received that matches the other Match* parameters, it still must have this OID on its received varbind list. Otherwise, it will not generate an Enterprise Manager event or datapoint. |
Optional |
|
UseCredential |
String |
Specifies credential use. If it is set to TRUE, then the receivelet will accept SNMPv3 traps using a set of target SNMPv3Creds sent to the receivelet as a CredentialRef. Also, if UseCredential is set, then the string property "hostname" and the numeric property "PORT" must be specified; their values will be used for engine-id discovery. |
Optional |
|
Eventmetric-column |
String |
Specifies that, on receiving this trap, the receivelet must generate a severity on this metric column. The value of metric-column must be the value of this parameter. (This case is useful where the expected values of the Enterprise Manager metric are not the same as the triggering SNMP variable.) |
Required, if events have to be generated. However, if Eventmetric-columnOID is provided, then this is not required. |
|
Eventmetric-columnOID |
String |
Specifies that, on receiving this trap, the receivelet must generate a severity on this metric column. The value of the metric column should be taken from the varbind in the trap with an OID equal to the value of this parameter. |
Required, if events have to be generated. However, if Eventmetric-column is provided, then this is not required. |
|
SeverityCode |
String |
Specifies the level at which the severity must be generated. The value of this parameter must be 'CRITICAL', 'WARNING', or 'CLEAR'. Note: SeverityCode or SeverityCodeOID must be present if events are to be generated when the trap is received. However, if the Push Descriptor intends to generate a metric datapoint (and specifies one or more Datametric-columnOID properties), then it must not have a SeverityCode or SeverityCodeOID property. |
Required. However, if SeverityCodeOID is provided, or the Push Descriptor is generating a metric datapoint, then this is not required. |
|
SeverityCodeOID |
String |
Specifies the level at which the severity should be generated. If the varbind in the trap with OID equal to the value of this parameter is one of the strings 'CRITICAL', 'WARNING', or 'CLEAR', then the severity must be generated at that level; otherwise, no severity must be generated. (This parameter is only used if you are designing a trap exclusively for use with Enterprise Manager, but can be useful in this case.) Note: SeverityCode or SeverityCodeOID must be present if events are to be generated when the trap is received. However, if the Push Descriptor intends to generate a metric datapoint (and specifies one or more Datametric-columnOID properties), then it must not have a SeverityCode or SeverityCodeOID property. |
Required. However, if SeverityCode is provided, or the PushDescriptor is generating a metric datapoint, then this is not required. |
|
Datametric-columnOID |
String |
Specifies that, on receiving this trap, the receivelet must generate a datapoint on the metric, for which the value of this metric column should be taken from the varbind in the trap with OID equal to the value of this parameter. (An SNMP Push Descriptor can have many Data* parameters, in which case a single row will be returned, with all specified columns populated from the appropriate varbind in the trap. An SNMP Push Descriptor cannot have both a Data* parameter and a Severity* parameter, nor can it have multiple Severity* parameters.) |
Required, if datapoints have to be generated. |
|
Keymetric-columnOID |
String |
Severity or datapoint generated by this Push Descriptor should contain a key-value for this metric column. The key-value should be taken from the varbind in the trap with OID equal to the value of this parameter. For every key-column in the metric definition, there must be a Key* parameter in the Push Descriptor. |
Optional |
|
Contextmetric-columnOID |
String |
If the Push Descriptor generates a severity, then the severity must contain a value for this metric column in its event context. The value should be taken from the varbind in the trap with OID equal to the value of this parameter. If the Push Descriptor generates a datapoint, then this parameter is ignored. |
Optional. This can be used for severities only. |
The following example shows how a trap from a vendor-specific router looks like.
Example: Trap from a Vendor-Specific Router
ascendLinkDown TRAP-TYPE ENTERPRISE ascend VARIABLES { ifIndex, ifAdminStatus, ifOperStatus, ifType, ifName } DESCRIPTION "This trap is in addition to the generic linkDown trap defined in RFC1215. This trap provides additional information such as ifAdminStatus, ifOerStatus, ifName, slotIfSlotIndex, slotIfItemIndex. This is an Alarm class trap and it can be enabled/disabled via alarmEnabled and/or ascendLinkDownTrapEnabled in trap profile. This trap is sent only if rfc1215 linkDown trap is generated." ::= 50
The following example shows how the trap will be received by the Management Agent. Note that <x> in this example is the value of ifIndex that identifies the particular interface that's having problems.
Example: Trap Received by the Management Agent
Message: version: 0 community: 'public' Trap-PDU: enterprise: enterprises.ascend (1.3.6.1.4.1.529) agent-addr: 138.2.204.10 generic-trap: 6 specific-trap: 50 time-stamp: <timestamp from router's sysUptime> variable-bindings: Name: ifIndex.<x> (1.3.6.1.2.1.2.2.1.1.<x>) Type: INTEGER Value: <x> Name: ifAdminStatus.<x> (1.3.6.1.2.1.2.2.1.7.<x>) Type: INTEGER Value: up (1) Name: ifOperStatus.<x> (1.3.6.1.2.1.2.2.1.8.<x>) Type: INTEGER Value: down (2) Name: ifType.<x> (1.3.6.1.2.1.2.2.1.3.<x>) Type: INTEGER Value: iso88023-csmacd (7) Name: ifName.<x> (1.3.6.1.2.1.2.2.1.31.<x>) Type: DisplayString Value: 'eth0'
The following example shows how the metric can be defined in the target type metadata file.
Example: Metric Defined in the Target Type Metadata File
<Metric NAME="interfaces" TYPE="TABLE"> <TableDescriptor> <ColumnDescriptor NAME="name" TYPE="STRING" IS_KEY="TRUE"/> <ColumnDescriptor NAME="type" TYPE="NUMBER" IS_KEY="FALSE"/> <ColumnDescriptor NAME="status" TYPE="NUMBER" IS_KEY="FALSE"/> <ColumnDescriptor NAME="configured_status" TYPE="NUMBER" IS_KEY="FALSE"/> </TableDescriptor> </Metric>
The following example shows how the push descriptor can be defined in the target type metadata file to trigger a severity.
Example: Push Descriptor in the Target Type Metadata File For Triggering a Severity
<PushDescriptor RECVLET_ID="SNMPTrap"> <Property NAME="MatchEnterprise" SCOPE="GLOBAL">1.3.6.1.4.1.529</Property> <Property NAME="MatchGenericTrap" SCOPE="GLOBAL">6</Property> <Property NAME="MatchSpecificTrap" SCOPE="GLOBAL">50</Property> <Property NAME="MatchAgentAddr" SCOPE="INSTANCE">AdminAddress</Property> <Property NAME="SeverityStatusOID" SCOPE="GLOBAL">1.3.6.1.2.1.2.2.1.8</Property> <Property NAME="KeyNameOID" SCOPE="GLOBAL">1.3.6.1.2.1.2.2.1.31</Property> <Property NAME="ContextTypeOID" SCOPE="GLOBAL">1.3.6.1.2.1.2.2.1.3</Property> <Property NAME="ContextConfigured_statusOID" SCOPE="GLOBAL">1.3.6.1.2.1.2.2.1.7</Property> <Property NAME="SeverityCode" SCOPE="GLOBAL">CRITICAL</Property> <CredentialRef NAME="monCreds">monCredentials</CredentialRef> </PushDescriptor>
The following example shows how the push descriptor can be defined in the target type metadata file to trigger a datapoint, which would specify the reporting of data on the same trap, with ifName as the key-column and the other three as data columns.
Example: Push Descriptor in the Target Type Metadata File For Triggering a Datapoint
<PushDescriptor RECVLET_ID="SNMPTrap"> <Property NAME="MatchEnterprise" SCOPE="GLOBAL">1.3.6.1.4.1.529</Property> <Property NAME="MatchGenericTrap" SCOPE="GLOBAL">6</Property> <Property NAME="MatchSpecificTrap" SCOPE="GLOBAL">50</Property> <Property NAME="MatchAgentAddr" SCOPE="INSTANCE">AdminAddress</Property> <Property NAME="KeyNameOID" SCOPE="GLOBAL">1.3.6.1.2.1.2.2.1.31</Property> <Property NAME="DataStatusOID" SCOPE="GLOBAL">1.3.6.1.2.1.2.2.1.8</Property> <Property NAME="DataTypeOID" SCOPE="GLOBAL">1.3.6.1.2.1.2.2.1.3</Property> <Property NAME="DataConfigured_statusOID" SCOPE="GLOBAL">1.3.6.1.2.1.2.2.1.7</Property> <CredentialRef NAME="monCreds">monCredentials</CredentialRef> </PushDescriptor>
To Receive SNMPV2 Notifications
The following example shows how the push descriptor can be defined in the target type metadata file to trigger a severity:
Example: Push Descriptor in the Target Type Metadata File For Triggering a Severity
<PushDescriptor RECVLET_ID="SNMPTrap"> <Property NAME="MatchTrapOID" SCOPE="GLOBAL">1.3.6.1.4.1.529.50</Property> <Property NAME="MatchAgentAddr" SCOPE="INSTANCE">AdminAddress</Property> <Property NAME="SeverityStatusOID" SCOPE="GLOBAL">1.3.6.1.2.1.2.2.1.8</Property> <Property NAME="KeyNameOID" SCOPE="GLOBAL">1.3.6.1.2.1.2.2.1.31</Property> <Property NAME="ContextTypeOID" SCOPE="GLOBAL">1.3.6.1.2.1.2.2.1.3</Property> <Property NAME="ContextConfigured_statusOID" SCOPE="GLOBAL">1.3.6.1.2.1.2.2.1.7</Property> <Property NAME="SeverityCode" SCOPE="GLOBAL">CRITICAL</Property> <CredentialRef NAME="monCreds">monCredentials</CredentialRef> </PushDescriptor>
The following example shows how the push descriptor can be defined in the target type metadata file to trigger a datapoint, which would specify the reporting of data on the same trap, with ifName as the key-column and the other three as data columns.
Example: Push Descriptor in the Target Type Metadata File For Triggering a Datapoint
<PushDescriptor RECVLET_ID="SNMPTrap"> <Property NAME="MatchEnterprise" SCOPE="GLOBAL">1.3.6.1.4.1.529</Property> <Property NAME="MatchGenericTrap" SCOPE="GLOBAL">6</Property> <Property NAME="MatchSpecificTrap" SCOPE="GLOBAL">50</Property> <Property NAME="MatchAgentAddr" SCOPE="INSTANCE">AdminAddress</Property> <Property NAME="KeyNameOID" SCOPE="GLOBAL">1.3.6.1.2.1.2.2.1.31</Property> <Property NAME="DataStatusOID" SCOPE="GLOBAL">1.3.6.1.2.1.2.2.1.8</Property> <Property NAME="DataTypeOID" SCOPE="GLOBAL">1.3.6.1.2.1.2.2.1.3</Property> <Property NAME="DataConfigured_statusOID" SCOPE="GLOBAL">1.3.6.1.2.1.2.2.1.7</Property> <CredentialRef NAME="monCreds">monCredentials</CredentialRef> </PushDescriptor>
To Receive SNMPV3 Notifications
The following example shows how the push descriptor can be defined in the target type metadata file to trigger a severity.
Example: Push Descriptor in the Target Type Metadata File For Triggering a Severity
<PushDescriptor RECVLET_ID="SNMPTrap"> <Property NAME="MatchTrapOID" SCOPE="GLOBAL">1.3.6.1.4.1.529.50</Property> <Property NAME="MatchAgentAddr" SCOPE="INSTANCE">AdminAddress</Property> <Property NAME="SeverityStatusOID" SCOPE="GLOBAL">1.3.6.1.2.1.2.2.1.8</Property> <Property NAME="KeyNameOID" SCOPE="GLOBAL">1.3.6.1.2.1.2.2.1.31</Property> <Property NAME="ContextTypeOID" SCOPE="GLOBAL">1.3.6.1.2.1.2.2.1.3</Property> <Property NAME="ContextConfigured_statusOID" SCOPE="GLOBAL">1.3.6.1.2.1.2.2.1.7</Property> <Property NAME="SeverityCode" SCOPE="GLOBAL">CRITICAL</Property> <Property NAME="hostname" SCOPE="INSTANCE">snmpHost</Property> <Property NAME="PORT" SCOPE="INSTANCE">snmpPort</Property> <CredentialRef NAME="monCreds">monCredentials</CredentialRef> </PushDescriptor>
The following example shows how the push descriptor can be defined in the target type metadata file to trigger a datapoint, which would specify the reporting of data on the same trap, with ifName as the key-column and the other three as data columns.
Example: Push Descriptor in the Target Type Metadata File For Triggering a Datapoint
<PushDescriptor RECVLET_ID="SNMPTrap"> <Property NAME="MatchEnterprise" SCOPE="GLOBAL">1.3.6.1.4.1.529</Property> <Property NAME="MatchGenericTrap" SCOPE="GLOBAL">6</Property> <Property NAME="MatchSpecificTrap" SCOPE="GLOBAL">50</Property> <Property NAME="MatchAgentAddr" SCOPE="INSTANCE">AdminAddress</Property> <Property NAME="KeyNameOID" SCOPE="GLOBAL">1.3.6.1.2.1.2.2.1.31</Property> <Property NAME="DataStatusOID" SCOPE="GLOBAL">1.3.6.1.2.1.2.2.1.8</Property> <Property NAME="DataTypeOID" SCOPE="GLOBAL">1.3.6.1.2.1.2.2.1.3</Property> <Property NAME="DataConfigured_statusOID" SCOPE="GLOBAL">1.3.6.1.2.1.2.2.1.7</Property> <Property NAME="hostname" SCOPE="INSTANCE">snmpHost</Property> <Property NAME="PORT" SCOPE="INSTANCE">snmpPort</Property> <CredentialRef NAME="monCreds">monCredentials</CredentialRef> </PushDescriptor>
The following example shows how the monCredentials is defined in target type metadata file
Example: monCredentials in the Target Type Metadata File
<CredentialInfo> <CredentialSet NAME="monCredentials" USAGE="MONITORING"> <AllowedCredType TYPE="SNMPV1Creds" /> <AllowedCredType TYPE="SNMPV3Creds" /> </CredentialSet> </CredentialInfo>
SNMPV1Creds or SNMPV3Creds values for the respective targets must be set from the Cloud Control console by selecting Setup, then Security, and then Monitoring Credentials.
To receive an SNMPV1 trap or SNMPV2 Notification, the user must choose SNMPV1Creds. Choosing SNMPV1Creds will ask for ”Community String” parameter value. Appropriate community string values need to be set by the user.
To receive an SNMPV3 Notification, the user must choose SNMPV3Creds. Choosing SNMPV3Creds will ask for ”UserName”, ”Auth Password”, ”Auth Protocol” and ”Privacy Password” parameter values. The user must set the required values according to the secLevel they want to use.
Example: SNMV1 Trap Received by the Management Agent
Message: version: 0 community: 'public' Trap-PDU: enterprise: enterprises.ascend (1.3.6.1.4.1.529) agent-addr: 138.2.204.10 generic-trap: 6 specific-trap: 50 time-stamp: <timestamp from router's sysUptime> variable-bindings: Name: ifIndex.<x> (1.3.6.1.2.1.2.2.1.1.<x>) Type: INTEGER Value: <x> Name: ifAdminStatus.<x> (1.3.6.1.2.1.2.2.1.7.<x>) Type: INTEGER Value: up (1) Name: ifOperStatus.<x> (1.3.6.1.2.1.2.2.1.8.<x>) Type: INTEGER Value: down (2) Name: ifType.<x> (1.3.6.1.2.1.2.2.1.3.<x>) Type: INTEGER Value: iso88023-csmacd (7) Name: ifName.<x> (1.3.6.1.2.1.2.2.1.31.<x>) Type: DisplayString Value: 'eth0'
Example: SNMV2/SNMPV3 Notification Received by the Management Agent
Message: Recevied from address 138.2.204.10 (ip address from UDP layer) version: 1 (or 3 i.e 1 for snmpv2 and 3 for snmpv3 notification) Security params : (community if SNMPV2, SNMPV3 security params if SNMPV3) Trap-PDU: variable-bindings: Name: sysUpTime.0 (.1.3.6.1.2.1.1.3.0) Type: INTEGER Value: 43053404 Name: snmpTrapOID.0 (1.3.6.1.6.3.1.1.4.1.0) Type: Object Identifier Value: 1.3.6.1.4.1.529.50 Name: ifAdminStatus.<x> (1.3.6.1.2.1.2.2.1.7.<x>) Type: INTEGER Value: up (1) Name: ifOperStatus.<x> (1.3.6.1.2.1.2.2.1.8.<x>) Type: INTEGER Value: down (2) Name: ifType.<x> (1.3.6.1.2.1.2.2.1.3.<x>) Type: INTEGER Value: iso88023-csmacd (7) Name: ifName.<x> (1.3.6.1.2.1.2.2.1.31.<x>) Type: DisplayString Value: 'eth0'
The target type metadata file can have multiple metrics with push descriptor definitions. Also, a single metric can have multiple push descriptors attached.
For event format, ensure that your push descriptor defines only one Event* parameter indicating one metric column as described in Table 19-1. The event push descriptor can have one or more Context* parameters to indicate additional metric column values to send as part of an AlertContext.
For datapoint format, ensure that your push descriptor defines one or more Data* properties as described in Table 19-1 and demonstrated in the Push Descriptor in the Target Type Metadata File For Triggering a Datapoint example and the Push Descriptor in the Target Type Metadata File For Triggering a Datapoint example in this chapter.