Excluded Modules and Additional Functions

This section contains a list of Python modules and other functions that are not permitted in Snippet Dynamic Applications.

Use the following menu options to navigate the SL1 user interface:

To view a pop-out list of menu options, click the menu icon ().
To view a page containing all of the menu options, click the Advanced menu icon ().

Excluded Python Modules

To maintain security and maximize performance, the following Python modules are not permitted in Snippet Dynamic Applications:

os
os.path
pickle
shelve
platform
thread
threading
dummy_thread
dummy_threading
posix
pwd
spwd
grp
termios
pipes
posixfile
resource
commands
subprocess
signal
popen2
imp

Snippet Functions for Database, SNMP, and CURL Handles

SL1 includes APIs that return database, SNMP, and CURL handles. You must supply a credential ID to the API, and the API returns the handle.

Database Handles

You can use the following method to obtain a database handle:

em7_snippets.dbc_from_cred_id(cred_ID)

The dbc_from_cred_id method takes the following arguments:

cred_ID. Supply a numeric ID for a credential. This is the credential for the database for which you want to retrieve a handle.

The dbc_from_cred_id method can generate three types of exceptions:

If the credential is not a database credential, the method returns the ValueError "Credential Type is not database (2)."
If the credential does not exist, the method returns the ValueError "Credential %s does not exist."
If the API cannot connect to the database, the method will generate a runtime error.

The method returns a cursor that adheres to the specification in the Python DB API 2.0. For information on the methods that are supported by cursors that adhere to the Python DB API 2.0, see http://www.python.org/dev/peps/pep-0249/.

NOTE: The API uses the cursor_wrapper function. The cursor_wrapper allows cursors to use auto-fetch methods.

SNMP Handles

You can use the following method to obtain an SNMP handle:

snmph_from_cred_id(cred_ID, IP, write=False)

The snmph_from_cred_id method takes the following arguments:

cred_ID. Supply a numeric ID for a credential. This is the SNMP credential for which you want to retrieve a handle.
IP. Supply an IP address for the device for which you want to retrieve an SNMP handle.
write=false. Optional argument. Specifies whether the credential is an SNMP write credential. Default value is "false".

The snmph_from_cred_id method can generate two types of exceptions:

If the credential is not an SNMP credential, the API returns the ValueError "Credential Type is not SNMP (1)."
If the credential does not exist, the API returns the ValueError "Credential %s does not exist."

The returned handle supports the following methods:

.get(oid). Takes an SNMP OID as a parameter, returns the response from an SNMP get request. On error, returns None.
.walk(oid). Takes an SNMP OID as a parameter, returns the response from an SNMP walk request. Returns a list of tuples. Each tuple includes the SNMP index and the returned value from an OID in the response.
.set(oid, datatype, value). Takes an SNMP OID, an SNMP datatype, and a value to set as parameters. Performs an SNMP set request on the specified OID using the specified value. Returns the response from the SNMP agent.

cURL Handles

You can use the following method to obtain a cURL handle:

curlh_from_cred_id(cred_ID, IP, hostname, logger=none)

The curlh_from_cred_id method takes the following arguments:

cred_ID. Supply a numeric ID for a credential. This is the CURL credential for which you want to retrieve a handle.
IP. Supply an IP address. The API will replace the %D variable in the credential URL with the IP address.
hostname. Supply a hostname. The API will replace the %N variable in the credential URL with the hostname.

The curlh_from_cred_id method can generate four types of exceptions:

If the credential is not a CURL credential, the API returns the ValueError "Credential Type is not CURL(3)."

If the credential does not exist, the API returns the ValueError "Credential %s does not exist."
If the CURL options are invalid, the API generates a TypeError.
If the CURL options are invalid, the API generates a pycurl.error.

The method returns a cURL object using the pycurl library. For more information about the methods that are supported by cURL objects provided by the pycurl library, see http://pycurl.sourceforge.net/.

Snippet Functions for Polling Nagios Agents

Because command-line system calls are blocked in snippet code, SL1 provides access to the check_nrpe and check_nt command line tools through wrapper functions. The check_nrpe and check_nt tools can be used to poll Nagios agents running on external systems.

For Linux-based external systems, you can use the following method:

em7_snippets.call_nrpe(host, command, arglist, use_ssl, critical_timeout, port, timeout)

The call_nrpe method takes the following arguments:

host. The IP address of the external system.
command. The command option to use. The external system must have the NPRE daemon configured to associate this command option with a specific plug-in command.
arglist. An iterable list of arguments to pass to the command. If this argument is not passed, the default value is "None".
use_ssl. A boolean that specifies whether SSL should be used. If this argument is not passed, the default value is "True".
critical_timeout. A Boolean that specifies whether timeouts should return CRITICAL (critical_timeout=True) or UNKNOWN (critical_timeout=False). If this argument is not passed, the default value is "True".
port. The port that should be used to connect to the external system. If this argument is not passed, the default value is 5666.
timeout. The number of seconds to wait for a response before a timeout occurs. If this argument is not passed, the default value is 10.

For Windows-based external systems, you can use the following method:

em7_snippets.call_nrpe_nt(host, variable, port, password, warning_threshold, critical threshold, params, timeout, unknown_timeout)

The call_nrpe_nt method takes the following arguments:

host. The IP address of the external system.
variable. The variable to use when collecting data from the NSClient service.
port. The port that should be used to connect to the external system. If this argument is not passed, the default value is 1248.
password. The password for the external system. If this argument is not passed, the default value is "None".
warning_threshold. The threshold value to use when determining whether the response should indicate a warning state. If this argument is not passed, the default value is "None".
critical_threshold. The threshold value to use when determining whether the response should indicate a critical state. If this argument is not passed, the default value is "None".
params. Parameters to pass to the external system. If this argument is not passed, the default value is "None".
timeout. The number of seconds to wait for a response before a timeout occurs. If this argument is not passed, the default value is 10.
unknown_timeout. A boolean that specifies whether timeouts should return CRITICAL (unknown_timeout=False) or UNKNOWN (unknown_timeout=True). The default value if this argument is not passed is "False".

Both em7_snippets.call_nrpe and em7_snippets.call_nrpe_nt return the following tuple:

(return code, stdout, stderr)

SL1 does not process the return code, output, or error. The values in the returned tuple are the values returned by the check_nrpe or check_nt command line tool.

Snippet Functions for Performing WMI and WBEM Requests

Because command-line system calls are blocked in snippet code, SL1 provides a wrapper function that provides access to a command line tool for performing WMI and WBEM requests. This wrapper function can be used by snippet code in Performance & Configuration Dynamic Applications.

Both wrapper functions require the parameter cred_details. The cred_details parameter must be a dictionary with the same structure as self.cred_details. If the credential aligned with the Dynamic Application is a Basic/Snippet credential that can be used to perform WMI requests, you can pass self.cred_details in the cred_details parameter. If you are constructing a new dictionary to pass in the cred_details parameter, you must include the following keys:

cred_host. The hostname or IP address of the device for which the snippet is collecting.
cred_port. The TCP port that will be used to connect to the WMI or WBEM agent.
cred_user. The username to use to perform the request.
cred_pwd. The password for the user specified in cred_user.
cred_timeout. The timeout to use for the request.

To perform a WMI request, use the following method:

em7_snippets.wmi_request(did, app_id, ip, cred_details, query, key, delimiter, namespace)

The wmi_request method takes the following arguments:

did. The device ID of the device for which the snippet is collecting. Pass self.did for this parameter.

app_id. The ID for this Dynamic Application. Pass self.app_id for this parameter.
ip. The IP address of the device the method will query. To use the IP address of the device the Dynamic Application is currently collecting from, pass self.ip for this parameter.
cred_details. The credential the method will use to perform the request. You must pass a dictionary with the same structure as self.cred_details.
query. The WMI query to execute.
key. The unique key for each instance (row) returned by the request. This unique key must be a property name, and the request must include that property (column) and return values from that property name (column).
delimiter. When making a request, the command-line utility must specify a string of characters that will be used to separate the values returned in the response. Specify that string of characters in this parameter. The string of characters you pass must not appear in any value that could be included in the response. To use the default delimiter, "$$$", pass "WMI_DELIMITER" in this parameter.
namespace. Specify the namespace for the request.

To perform a WBEM request, use the following method:

em7_snippets.wbem_request(did, app_id, ip, cred_details, query)

The wbem_request method takes the following arguments:

did. The device ID of the device for which the snippet is collecting. Pass self.did for this parameter.
app_id.The ID for this Dynamic Application. Pass self.app_id for this parameter.
ip. The IP address of the device the method will query. To use the IP address of the device the Dynamic Application is currently collecting from, pass self.ip for this parameter.
cred_details. The credential the method will use to perform the request. You must pass a dictionary with the same structure as self.cred_details.
query. The WBEM query to execute.

Both the wmi_request and wbem_request methods return a dictionary:

The keys in the dictionary are the property names (columns) from the response.
Each value in the dictionary is a list of values returned for that property. For WMI requests, the key for each value in the list is the corresponding value returned by the property (column) you specified in the key parameter. For WBEM requests, the key for each value in the list is the corresponding value from the Name property (column).

For example, suppose you requested two properties, Name and Value, and specified Name in the key parameter. Suppose that the response includes the following three rows:

Name	Value
Bulbasaur	Grass
Charmander	Fire
Squirtle	Water

The returned dictionary has the following structure:

{

'Name': {'Bulbasaur':'Bulbasaur', 'Charmander':'Charmander', 'Squirtle':'Squirtle'},

'Value': {'Bulbasaur':'Grass', 'Charmander':'Fire', 'Squirtle':'Water'}

}

Caching Results Between Polling Periods

SL1 includes an API that allows snippets to save values to a cache and make those values available for use in the same snippet in the same Dynamic Application.

This is most useful for storing values between polling periods. For example:

You could store the last collection time between poll periods and use that last collection time during the following poll.
Some APIs, such as the VMware vSphere API, allow you to perform an initial request that includes all available information and then perform subsequent requests that return only the values that have changed since the previous request. You could use the cache_result API to store the results of the initial request and update the results during each subsequent execution of the snippet.
You could use the cache_result API to store a session handle for a SOAP web service.

Caching Values

To instantiate the cache, use the following method:

cache = em7_snippets.cache_api(self)

Each entry in the cache is associated with a key. The key is used to retrieve an entry from the cache. If you are storing only a single object in the cache, you can use the default key, which is created using the ID of the Dynamic Application and the ID of the device for which collection is being performed. You can create a custom key using the following method:

cache.generate_key(app_id=None, did=None, timestamp=None, use_timestamp=True, **kwargs)

The key is generated using the values for Dynamic Application ID, Device ID, current timestamp, and optional custom arguments. To retrieve a value from the cache, the same key must be supplied. You can control the values that are used to generate the key by supplying values for the following arguments when calling the generate_key method:

app_id. The Dynamic Application ID to use instead of the current Dynamic Application ID.
did. The device ID to use instead of the current device ID.
timestamp. The timestamp to use instead of the current timestamp.
use_timestamp. A boolean that controls whether the timestamp will be used to generate the key.
**kwargs. You can specify multiple additional parameters that will be used to generate the key.

You can then use the following method to store values in the cache:

cache.cache_result(result, ttl=None, commit=False, key=None)

The cache_result method takes the following arguments:

result. The object to be cached.
ttl. Optional argument. The default value is None. The number of seconds this value should live in the cache. If you supply the value "0", the object will be cached indefinitely.

commit. Optional argument. The default value is False. Specifies whether you want to save the object to cache immediately. Choices are:

commit=True. Save the object to cache immediately.
commit=False. Do not save the object to cache immediately.

key. Optional argument. The default value is None. Specifies whether to override the cache key. Choices are:

key=None. Accept the default cache key.
key=keyname. Override the cache key and use the specified cache key instead.

If you do not commit a value to the cache using the arguments for the cache_result method, you can use the following method to commit all uncommitted values to the cache:

cache.commit()

Retrieving Cached Values

To retrieve a cached value, you must have instantiated the cache:

cache=em7_snippets.cache_api(self)

You can use the following methods to retrieve a value from the cache:

cache.get(key)

cache.get_multi(keys)

The get method allows you to retrieve a single value from the cache and takes the following argument:

key. Specify the name of the key associated with the object you want to retrieve.

The get_multi method allows you to retrieve multiple values from the cache and takes the following argument:

keys. Specify a list of keys including a key for each object you want to retrieve from the cache.