BMC Atrium Orchestrator Content 20.14.02 ... Base adapters SNMP adapter Adapter requests and responses for the SNMP actor adapter

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>

This version of the documentation is no longer supported. However, the documentation is available for your convenience. You will not be able to leave comments.

Last modified by Deepa Bhat on Mar 03, 2013
base_adapters actor snmp

Comments

SNMP actor adapter requests and responses with a get action
SNMP monitor adapter event
© Copyright 2020 BMC Software, Inc.
Legal notices

Powered by Atlassian Confluence and Scroll Viewport

© Copyright 2005-2020 BMC Software, Inc.