MIB Smithy

Configuring SNMP Session Parameters

The SNMP Session's configure subcommand is used to configure access parameters such as address, port and community strings, for the session. Each session is initialized with a number of defaults at creation time (see Creating SNMP Sessions) which can be reconfigured using this command or specified at creation. One typically creates a new session for each set of configuration parameters that need to be used simultaneously (for instance, in manging two different agents or two users of the same agent, two sessions are needed). The SDK takes care of such things as SNMPv3 Engine ID Discovery and converting passwords to localized keys as necessary.

Syntax:

• % snmpcmd configure ?option value ...?
• % snmpcmd configure list

Where:

snmpcmd

is the name of session to be configured;

option value

are zero or more option+value pairs specifying configuration parameters and their desired values; and

list

provides an alternate form where the list of option+value pairs are provided in a single argument, allowing many properties to be configured from a list variable or from the output of configure with no arguments. This makes it easy to clone sessions.

Returns:

• With no arguments, returns a dictionary of the session's current configuration.
• Otherwise, returns nothing.

Session Parameters

-address

Equivalent to -remoteaddress.

-alias

Specifies the name an alias of preconfigured options that are to be subsituted in place of the alias in the configure command.

-authpass

Specifies the password to be used when sending or receiving authenticated SNMPv3 messages. The SDK will automatically convert the password to an unlocalized key (-authkey) and localized keys (-authzkey and -locauthzkey), according to the configured Authentication Protocol, using its own Engine ID (for the authoritative role) or when it discovers the agent's Engine ID (for the non-authoritative role). If the Authentication Protocol or Engine ID change, the password will be automatically reconverted and re-localized.

-authkey

Specifies the unlocalized key to be used when sending or receiving authenticated SNMPv3 messages. The SDK will automatically convert the unlocalized key to localized keys (-authzkey and -locauthzkey), according to the configured Authentication Protocol, using its own Engine ID (for the authoritative role) or when it discovers the agent's Engine ID (for the non-authoritative role). If the Authentication Protocol or Engine ID change, the key will be automatically re-localized. Setting this property will reset -authpass to empty.

-authproto

Specifies the Authentication Protocol to use when sending SNMPv3 authNoPriv and authPriv messages if an Authentication Password has been set. If no password is set, the state of this parameter is ignored and all SNMPv3 messages are sent noAuthNoPriv. Accepted values are none, HMAC-SHA-96 and HMAC-MD5-96, or short forms MD5 or SHA (long form recommended).

-authzkey

Specifies the localized key to be used when sending or receiving authenticated SNMPv3 messages in the non-authoritative role. Setting this property will reset -authpass and -authkey properties to empty. See also: -locauthzkey

-community

Specifies both the read and write community strings to the same value. This parameter is equivalent to -readcommunity $comm -writecommunity $comm.

-ctxengineid

Specifies the contextEngineID value to use for SNMPv3 messages. An empty string (default) indicates that the same value as msgAuthoritativeEngineID is to be used for contextEngineID.

-ctxname

Specifies the contextName value to use for SNMPv3 messages.

-db

Specifies the SMI Database to use for resolution of names to OIDs, OIDs to names, types, etc. Valid values are any active SMI Database name (such as smilib1).

-delay

Specifies a delay (in milliseconds) to wait before sending each SNMP message, which may be used to mitigate network congestion issues. Default 0, maximum 300000 (5 minutes).

-engineid

Specifies the SNMPv3 snmpEngineID of the remote SNMP agent. Note that this value may be overwritten automatically in response to a usmStatsUnknownEngineIDs report PDU from the agent.

-localaddress

Sets the address or hostname of the local interface on which to listen for incoming notifications, when configured to do so. When set to an empty string (default) the SDK will listen for notifications on all applicable interfaces.

-localboots

Sets the value of the session's own snmpEngineBoots. This property is used when the session is acting in an authoritative role (e.g. to receive SNMPv3 inform requests).

-localengid

Sets the value of the session's own snmpEngineID. This property is used when the session is acting in an authoritative role (e.g. to receive SNMPv3 inform requests). If set to an empty string, a new unique Engine ID will be generated and assigned to the session.

-localport

Specifies a secondary local port number or service name to bind to for receiving notifications if and when a notification handler is registered using the bind session command.

-localtime

Sets the value of the session's own snmpEngineTime. This property is used when the session is acting in an authoritative role (e.g. to receive SNMPv3 inform requests).

-locauthzkey

Specifies the localized key to be used when sending or receiving authenticated SNMPv3 messages in the authoritative role. Setting this property will reset -authpass and -authkey properties to empty. See also: -authzkey

-locprivzkey

Specifies the localized key to be used when sending or receiving encrypted SNMPv3 messages in the authoritative role. Setting this property will reset -privpass and -privkey properties to empty. See also: -privzkey

-logchannel

Configures channels (such as stdout, stderr or a file handle) to which hex dumps of sent and/or received packets should be output. Setting this property to an empty string disables logging. Setting it to a single channel enables logging to that channel for both sent and received packets. A two-element list can be specified to control logging for sent and received packets separately.

-logcommand

Specifies the name of a callback procedure to be invoked with details about packets sent and received for custom formatting as an alternative to direct printing via -logchannel (see Logging SNMP Messages for callback format).

-port

Equivalent to -remoteport.

-privpass

Specifies the password to be used when sending private (encrypted) SNMPv3 messages. The SDK will automatically convert the password to a localized key internally, according to the configured Privacy Protocol, when it discovers the agent's Engine ID. If the Privacy Protocol or Engine ID change, the password will be automatically reconverted and re-localized.

-privkey

Specifies the unlocalized key to be used when sending or receiving encrypted SNMPv3 messages. The SDK will automatically convert the unlocalized key to localized keys (-privzkey and -locprivzkey), according to the configured Authentication Protocol, using its own Engine ID (for the authoritative role) or when it discovers the agent's Engine ID (for the non-authoritative role). If the Authentication Protocol or Engine ID change, the key will be automatically re-localized. Setting this property will reset -privpass to empty.

-privproto

Specifies the Privacy Protocol to use when sending SNMPv3 authPriv messages if a Privacy Password has been set. If no password is set, the state of this parameter is ignored and all SNMPv3 messages are sent using authNoPriv or noAuthNoPriv depending on whether or not an authentication password has been configured. Accepted values are none, DES/CBC (or synonym CBC-DES), and AES128/CFB.

-privzkey

Specifies the localized key to be used when sending or receiving encrypted SNMPv3 messages in the non-authoritative role. Setting this property will reset -privpass and -privkey properties to empty. See also: -locprivzkey

-readcommunity

Specifies the community string to be used when sending SNMPv1 and SNMPv2c GET, GET-NEXT and GET-BULK requests.

-remoteaddress

Specifies the remote IPv4 or IPv6 address or host name to send requests to. If a host name is specified, the SDK will attempt to resolve the name to an IP address via DNS. An error will result if the hostname does not resolve.

-remoteport

Specifies the remote port number or service name to send requests to. By default, most SNMP agents accept requests on port 161, although many allow the agent to be configured to listen on a different port.

-retries

Specifies the number of attempts that should be made to retransmit requests that have not been received after the first try. If non-zero, then a total of (retries + 1) attempts will be made before signalling a timeout to the script. The SDK can be configured to retry the request up to 30 times.

-straps

Provided with a boolean value, can be used to enable or disable use of the straps/nmtrapd daemon. If disabled, the SDK will attempt to bind directly to port 162 rather than launching or connecting to the daemon when binding notification handlers to that port.

-timeout

Specifies the timeout (in milliseconds) to wait after sending a request before considering the message to have been dropped. The total time that the SDK will wait for a response before signalling a timeout to the script is ((retries + 1) * timeout). The maximum time to wait for a response to an individual attempt is 300000 ms (5 minutes).

-username

Specifies the SNMPv3 User Name to use when sending messages using the User-Based Security Model, regardless of security level.

-version

Specifies the SNMP Version to use for requests. Valid values are SNMPv1, SNMPv2c, SNMPv3, or 1, 2 or 3 (the longer form is recommended).

-window

Specifies the maximum number of pending SNMP requests, which may be used to mitigate network congestion issues. When this limit is reached, further requests will wait for pending requests to complete before being sent and queued. Default 0 (disabled).

-writecommunity

Specifies the community string to be used when sending SNMPv1 and SNMPv2c SET requests.