SNMP actor adapter requests and responses with a notification action

The format of the SNMP actor adapter request with a notification action depends on the SNMP version.

When you use a context item as an input for an adapter request, you must enclose the adapter request in the <request-data> elements. However, when you create a static request, <request-data> is not required and the adapter request starts with the <adapterName-adapter-request> element.

BMC recommends that you do not include empty elements in the adapter request because they might cause errors.

The following table describes the common elements for the SNMP actor adapter request with a notification action for SNMPv1, SNMPv2c, and SNMPv3 traps.

Common elements for SNMP actor adapter request with a notification action for SNMPv1, SNMPv2c, and SNMPv3 traps

Element	Description	Required
`<target-host>`	Specifies the host name or the IP address of the target computer that receives the SNMP notification	Yes
`<source-host>`	Specifies the host name or the IP address of the source computer that sends the SNMP notification If you do not provide this value, the host information for the peer on which the adapter request is being executed is used.	No
`<port>`	Specifies the target port for the SNMP notification Default value: 162	No
`<version>`	Specifies the SNMP version to be used Valid values: 1 (default), 2c, 3	No
`<oids>`	Contains the `<oid>` nodes used to specify dynamic values	Yes; even if `<oid>` nodes are not defined
`<oid>`	Contains the name and value pair for the OID (object identifier) notification	Conditional; required if the `<name>`, `<value>`, and `<type>` elements are defined
`<name>`	Specifies the OID reference name used in the adapter response Example: .1.1.4.6.1.2.6.2.5 Note The `<name>`, `<value>`, and `<type>` element group is ignored ifyou do not specify all of the elements in the group and a value for each.	No
`<value>`	Specifies the OID for which information is returned The value of this element depends on the value of the `<type>` element. For example, if the value of the `<type>` element is "integer", `<value>` can be any valid integer. Note The `<name>`,`<value>`, and `<type>` element group is ignored if you do not specify all of the elements in the group and a value for each.	No
`<type>`	Specifies the OID data type Valid values: STRING (default) (Valid value: Any string) INTEGER (Valid value: Any integer) OBJID (Valid value: The value for the `<value>` element, for example, .1.1.4.6.1.2.6.2.5) IPADDRESS (Valid value: A valid IP address, for example, 10.1.10.111) NETWORKADDRESS (Valid value: Any valid IP address, for example, 10.1.10.111) COUNTER (Valid value: Any integer) GAUGE (Valid value: Any integer) UNSIGNED32 (Valid value: Any integer) TIMETICKS (Valid value: Any integer) COUNTER64 (Valid value: Any integer) (The `COUNTER64` value works only for SNMP version 2c and version 3) NULLOBJ (If `<type>` is set to "NULLOBJ", the `<value>` element is not required and is ignored if provided) OPAQUE (Valid value: Any integer) Notes The `<name>`,`<value>`, and `<type>` element group is ignored if you do not specify all of the elements in the group and a value for each. If you provide an incorrect value for `<type>`, the adapter resets the value to STRING, the default value.	No
`<character-set>`	Specifies the supporting CharSet Also called character set, it includes identifiers describing a series of universal characters. Default value: ISO-8859-1	No

The following figure shows an XML sample of the SNMP adapter request with a notification action supporting CharSet.

XML template of the SNMP adapter request with a notification action supporting CharSet


<snmp-adapter-request>
  <target-host>10.128.249.29</target-host>
  <source-host>10.128.249.30</source-host>
  <port>162</port>
  <enterprise>.1.3.6.1.4.1.2021</enterprise>
  <generic>6</generic>
  <specific>100</specific>
  <community>public</community>
  <oids>
    <oid>
      <value>JT</value>
      <name>.1.3.6.1.4.1.2021.3.4.0</name>
      <type>string</type>
    </oid>
    <oid>
      <value>123</value>
      <name>.1.3.6.1.4.1.2021.3.5.0</name>
      <type>integer</type>
    </oid>
  </oids>
  <character-set>shift_jis</character-set>
</snmp-adapter-request>

The following table describes the additional elements for an SNMP actor adapter request with a notification action for an SNMPv1 trap.

Additional elements for an SNMP actor adapter request with a notification action for an SNMPv1 trap

Element	Description	Required
`<community>`	Specifies the SNMP community string	Yes
`<enterprise>`	Specifies the enterprise OID or string Example: An OID starts with ".1.3.6.1.4.1"; however, you can specify any OID that you want.	Yes
`<generic>`	Specifies the generic trap type	Yes
`<specific>`	Specifies the specific trap type (traps for specific MIBs)	Yes

The following figure shows the XML template of the SNMP adapter request with a notification action for an SNMPv1 trap.

XML template of the SNMP adapter request with a notification action for an SNMPv1 trap


<snmp-adapter-request>
   <target-host></target-host>
   <source-host></source-host>
   <port></port>
   <community></community>
   <enterprise></enterprise>
   <generic></generic>
   <specific></specific>
   <oids>
     <oid>
       <name></name>
       <value></value>
       <type></type>
     </oid>
   </oids>
   <character-set></character-set>
</snmp-adapter-request>

The following figure shows an XML sample of the SNMP adapter request with a notification action for an SNMPv1 trap.

XML sample of an SNMP actor adapter request with a notification action for an SNMPv1 trap


<snmp-adapter-request>
    <target-host>host name or IP address</target-host>
    <source-host>host name or IP address</source-host>
    <port>port number</port>
    <community>SNMP community</community>
    <enterprise>the enterprise OID or string</enterprise>
    <generic>generic trap type</generic>
    <specific>specific trap type</specific>
    <oids>
        <oid>
            <name>actual OID</name>
            <value>Value of theOID</value>
            <type>valid OID data type</type>
        </oid>
    </oids>
    <character-set>character set</character-set>
</snmp-adapter-request>

The following table describes the additional elements of an SNMP adapter request with a notification action for an SNMPv2c trap.

Additional elements of an SNMP adapter request with a notification action for an SNMPv2c trap

Element	Description	Required
`<community>`	Specifies the SNMP community string	Yes
`<trap-oid>`	Specifies the object identifier (OID) of the trap or notification being sent	Yes

The following figure shows an XML template of the SNMP adapter request with a notification action for an SNMPv2c trap.

XML template of the SNMP adapter request with a notification action for an SNMPv2c trap


<snmp-adapter-request>
  <version></version>
  <target-host></target-host>
  <source-host></source-host
  <port></port>
  <community></community>
  <version>2c</version>
  <trap-oid></trap-oid>
  <oids>
    <oid>
      <name></name>
      <value></value>
      <type></type>
    </oid>
  </oids>
  <character-set></character-set>
</snmp-adapter-request>

The following figure shows an XML sample of the SNMP adapter request with a notification action for an SNMPv2c trap.

XML sample of the SNMP adapter request with a notification action for an SNMPv2c trap


<snmp-adapter-request>
  <version>2c</version>
  <target-host>10.128.249.29</target-host>
  <source-host>10.128.249.30</source-host>
  <port>162</port>
  <trap-oid>.1.3.6.1.4.1.2021.100</trap-oid>
  <community>public</community>
  <oids>
    <oid>
      <value>JT</value>
      <name>.1.3.6.1.4.1.2021.3.4.0</name>
      <type>string</type>
    </oid>
    <oid>
      <value>123</value>
      <name>.1.3.6.1.4.1.2021.3.5.0</name>
      <type>integer</type>
    </oid>
  </oids>
  <character-set>shift_jis</character-set>
</snmp-adapter-request>

The following table describes the SNMP actor adapter request elements with a notification action for an SNMPv3 trap.

SNMP actor adapter request with a notification action for an SNMPv3 trap elements

Element	Description	Required
`<trap-oid>`	Specifies the object identifier (OID) of the trap or notification being sent	Yes
`<user-name>`	Specifies the user name to authenticate the SNMPv3 request	Yes
`<authentication-protocol>`	Specifies the protocol that is used to encrypt the authentication password Valid values: MD5 (default), SHA	No
`<authentication-password>`	Specifies the password for the specified `<authentication-protocol>` Valid value: Any string; must contain at least eight characters	Conditional; required if `<authentication-protocol>` is used
`<privacy-password>`	Specifies the password used to encrypt the SNMP packet Valid value: Any string; must contain at least eight characters	No
`<engine-id>`	Specifies the engine ID used to authenticate the SNMP request If no engine ID is specified, a random ID is generated. Valid values: 0x (hexadecimal characters: 0-9 and a-f) Valid length: 12 - 66 in steps of 2 Example: 0x1234567890, 0X9987654021	No

Note

SNMPv3 uses User-based Security Model (USM) to authenticate and encrypt the SNMP packet.

The following table describes the types (security modes) of SNMPv3 users.

Types of SNMPv3 users

Security mode	Description
No Authentication No Privacy (`noAuthNoPriv`)	You must provide only auser name to validate the request. No security is implemented.
Authentication No Privacy (`authNoPriv`)	You must provide a user name and an authentication password in the request. The message is authenticated.
Authentication Privacy (`authPriv`)	You must provide a user name, an authentication password, and a privacy password in the request. The message is authenticated and encrypted.

Note

The SNMP adapter supports only DES as a valid protocol when the security mode is authPriv.

The following figure shows an XML sample of the SNMP adapter request with a notification action for an SNMPv3 trap.

XML sample of an SNMP adapter request with a notification action for an SNMPv3 trap


<snmp-adapter-request>
  <version>3</version>
  <target-host>10.128.249.29</target-host>
  <source-host>10.128.249.30</source-host>
  <port>162</port>
  <user-name>traptest1</user-name>
  <authentication-password>mypassword</authentication-password>
  <trap-oid>.1.3.6.1.4.1.2021.100</trap-oid>
  <privacy-password>mypassword</privacy-password>
  <authentication-protocol>sha</authentication-protocol>
  <oids>
    <oid>
      <value>JT</value>
      <name>.1.3.6.1.4.1.2021.3.4.0</name>
      <type>string</type>
    </oid>
    <oid>
      <value>123</value>
      <name>.1.3.6.1.4.1.2021.3.5.0</name>
      <type>integer</type>
    </oid>
  </oids>
  <character-set>shift_jis</character-set>
</snmp-adapter-request>

For SNMPv1, SNMPv2c, and SNMPv3 traps, the SNMP actor adapter returns an adapter response that contains the summary information for the adapter request.

The following table describes the elements of an SNMP actor adapter response to a request with notification action.

Elements of an SNMP actor adapter response to a request with notification action

Element	Description
`<metadata>`	Contains the summary information of the request
`<status>`	Indicates the status of the request execution Valid values: success, error
`<error>`	Contains the error message if an interruption during the execution of a request When the value of the `<status>` element is success, this element will not be present.
`<execution-milliseconds>`	Specifies the duration of the request execution, in milliseconds

The following figure shows an XML sample for the SNMP adapter response with notification action.

XML sample of the SNMP adapter response with notification action


<snmp-adapter-response>
   <metadata>
    <status>success</status>
    <error>Present only with status of 'error'</error>
    <execution-milliseconds>value</execution-milliseconds>
   </metadata>    
</snmp-adapter-response>

The following figure shows an XML sample for the SNMP adapter response with notification action for SNMPv2c trap.

XML sample of the SNMP adapter response with notification action for SNMPv2c trap


<snmp-adapter-response>
  <metadata>
    <status>success</status>
    <execution-milliseconds>20</execution-milliseconds>
  </metadata>
</snmp-adapter-response>

The following figure shows an XML sample for the SNMP adapter response with notification action for SNMPv3 trap.

XML sample of the SNMP adapter response with notification action for SNMPv3 trap


<snmp-adapter-response>
  <metadata>
    <status>success</status>
    <execution-milliseconds>270</execution-milliseconds>
  </metadata>
</snmp-adapter-response>

SNMP actor adapter requests and responses with a notification action

Comments