|
Sometimes all you
need is a away to add a simple object to be reported by your windows
agent, something quick and dirty which lets you execute a program and
return its standard output as a response to a get request, or maybe
extract a value out of some log file generated by some program.
What stands in your way in such situation, is the fact that in order to
extend the windows snmp agent you have to write code in C.
The tcl extension maps the windows snmp extension API to an API in the TCL scripting language. While TCL is not
very popular in the latest years it is not very different from other
scripting languages like perl and PHP, and it is quite easy to to use
it for parsing.
The installation includes a sample mib implementation.
API Documentation
The installation contains a TCL interpreter based on the 8.4.12
release. while this is a fully functional interpreter of the TCL
language, it will not execute correctly commands which request an
invocation at a later time, such as after
and fileevent.
Script file
The code which composes the extension has to reside in a filed named
"snmp.tcl" and which is located in the installation directory of the
extension. It is possible to use the tcl source command to load other file
from this file.
Log file
If there is any error in loading the script file it is written to the
snmp.log file in the installation directory.
Global variables
The installation_directory
variable contains the path to the directory in which the extension was
installed.
Exception handling
As it is with the tcl shell script, the bgerror is called when there is
an unhandled exception.
Configuration functions
Configuring a scalar oid
snmp::scalar {oid type}
This function creates a unique identifier for a scalar oid for which
the
extension is able to respond to get requests.
Inputs:
- oid - the oid of of
the scalar
- type - the type of
information this object contains. Can be one of integer, unsigned, timeticks, ipaddress, oid, counter, gauge, string, counter64.
Returns:
A unique sstring which can be
used
to identify the scalar.
Operation:
This function initialize some
data structures to hold information on the scalar, and registers the
handling of the scalar in the windows snmp agent.
snmp::sconfigure scalar type command
This function configures the script to execute when for a particular
stage of the SNMP request handling.
Inputs:
- scalar- The unique
iidentifier of the scalar as was returned by the snmp::scalar function
- type - The type of
the SNMP request. Can be one of read,
write, test, undo, cleanup.
- command - The
script to run. Any parameter which is after the type parameter is
considered to be part of the command.
Returns:
Nothing.
Operation:
When an SNMP get request is
received for the scalar, the read
command associated with it is being executed, and it returned value
is
being parsed to the proper type of the scalar, and used as the value
returned by the request. If there is no associated read command, or the
command raises an exception or the result can not be parsed into the
scalar type, an SNMP error will be returned for the request.
When an SNMP set request is received for the scalar, the test command
(if one exists) is
executed to verify that the value can be set to the scalar. If the
value returned by the test command indicates that the set might go on,
the write
command is called to
actually do the set.
The undo
command (if one
exists) is being executed when the attempt to set any of the values
being set in the SNMP PDU is rejected or fails. The aim of the command
is to restore the previous state of the object.
The cleanup
command (if one
exists) is executed as the last stage of a set request. Its aim is to
let the implementation free all the resourced which were allocated
during the handling of the set request.
If an exception occurs at any of the read, write, or test commands, an
SNMP error value will be returned for the request.
Configuring a table
snmp::table {oid index1_type [index2_type ...]}
This function creates a unique identifier for a table oid for which the
extension is able to respond to get requests.
Inputs:
- oid - the oid of of
the table
- index1_type ... -
A list of the types of indexes to the table. The list should correspond
to the list of indexes in the MIB. Each value can be one of integer, unsigned, timeticks, ipaddress, oid,
counter, guage, string, implied. The implied value should
be used the string or oid index which are defined to be implied in the
MIB.
Returns:
A unique string which can be used
to identify the table.
Operation:
This function initialize some
data structures to hold information on the table, and registers the
handling of the table in the windows snmp agent.
snmp::column {table column-oid type}
This function creates a unique identifier for a table column for which
the
extension is able to respond to get requests.
Inputs:
- table - The
identifier of the table as was returned by snmp::table
- index-oid - The
number identifying the specific column in the table. This is the last
number in the full oid of the column.
- type - the type of
information the objects in this column contains. Can be one of integer, unsigned, timeticks, ipaddress, oid, counter, gauge, string, counter64.
Returns:
A unique string which can be used
to identify the column.
Operation:
This function initialize some
data structures to hold information on the column.
snmp::cconfigure column type command
This function configures the script to execute when for a particular
stage of the SNMP request handling for objects in the column.
Inputs:
- column- The unique
identifier of the column as was returned by the snmp::column function
- type - The type of
the SNMP request. Can be one of read,
write, test, undo, cleanup.
- command - The
script to run. Any parameter which is after the type parameter is
considered to be part of the command.
Returns:
Nothing.
Operation:
When an SNMP get request is
received for the scalar, the read
command associated with it is being executed, and it returned value
is
being parsed to the proper type of the scalar, and used as the value
returned by the request. If there is no associated read command, or the
command raises an exception or the result can not be parsed into the
scalar type, an SNMP error will be returned for the request.
When an SNMP set request is received for the scalar, the test command
(if one exists) is
executed to verify that the value can be set to the scalar. If the
value returned by the test command indicates that the set might go on,
the write
command is called to
actually do the set.
The undo
command (if one
exists) is being executed when the attempt to set any of the values
being set in the SNMP PDU is rejected or fails. The aim of the command
is to restore the previous state of the object.
The cleanup
command (if one
exists) is executed as the last stage of a set request. Its aim is to
let the implementation free all the resourced which were allocated
during the handling of the set request.
If an exception occurs at any of the read, write, or test commands, an
SNMP error value will be returned for the request.
Manipulating tables
snmp::addrow
$table $index1 [index2 ....]
This function adds a row to a table.
Inputs:
- table - The unique
identifier of the table to which the row is added
- index1 ... - A list
of the values identifying the row in the table. The values should
reflect, in exactly the same order, the values of the actual indexes
declared in the MIB as the indexes of the table.
Returns:
Nothing.
Operation:
For each added row, the objects
of
all of the table columns for this row will handle snmp request by
executing their associated handling scripts.
snmp::deleterow $table $index1 [index2 ....]
This function deletes a row from a table.
Inputs:
- table - The unique
identifier of the table to which the row is added
- index1 ... - A list
of the values identifying the row in the table. The values should
reflect, in exactly the same order, the values of the actual indexes
declared in the MIB as the indexes of the table, the same values used
when adding it.
Returns:
Nothing.
Operation:
An SNMP error code will be
returned for SNMP request which for the objects which belong to the
row.
Response script specifications
Scalar object scripts
read {}
The script which is used to provide the current value of a scalar
object.
Input:
Nothing.
Returns:
The value of the scalar object.
Should raise an exception if the response to the SNMP get which
triggered the execution should be an SNMP error.
write {value}
The script which is used toset a value to a scalar object.
Input:
value
- the value to be
set.
Returns:
An SNMP error code. A value of
zero (no error) indicates that the value was set successfully.
test {value}
The script which is used to test if the scalar can be set to a specific
value.
Input:
value
- the value to be tested.
Returns:
An SNMP error code. A value of
zero (no error) indicates that the value can be set to the scalar.
undo {}
The script which is used to undo any changes which were previously been
done as part of an SNMP set request, due to some failure when setting
other objects in the PDU.
Input:
Nothing.
Returns:
Nothing.
Should raise an exception if for some reason the undo fails. The
exception will cause an SNMP error to be returned to the set operation.
cleanup {}
The script which is called as the last step of handling a set request
in order to release any allocated resources.
Input:
Nothing.
Returns:
Nothing.
Should raise an exception if for some reason the cleanup failes. The
exception will cause an SNMP error to be returned to the set operation.
Table object scripts
read {index1 [index2 ...]}
The script which is used to provide the current value of a cell in row.
Input:
Index1
... - The values of the row
indexes. The values are the same, and in the same order as the values
which were used when the row was added via the snmp::addrow
function.
Returns:
The value of the cell object.
Should raise an exception if the response to the SNMP get which
triggered the execution should be an SNMP error.
write {index1 [index2 ...] value}
The script which is used to set a value to a scalar object.
Input:
Index1
... - The values of the row
indexes. The values are the same, and in the same order as the values
which were used when the row was added via the snmp::addrow
function.
value
- the value to be
set.
Returns:
An SNMP error code. A value of
zero (no error) indicates that the value was set successfully.
test {index1 [index2 ...] value}
The script which is used to test if the scalar can be set to a specific
value.
Input:
Index1
... - The values of the row
indexes. The values are the same, and in the same order as the values
which were used when the row was added via the snmp::addrow
function.
value - the value to be
tested.
Returns:
An SNMP error code. A value of
zero (no error) indicates that the value can be set to the scalar.
undo {index1 [index2 ...]}
The script which is used to undo any changes which were previously been
done as part of an SNMP set request, due to some failure when setting
other objects in the PDU.
Input:
Index1
... - The values of the row
indexes. The values are the same, and in the same order as the values
which were used when the row was added via the snmp::addrow
function.
Returns:
Nothing.
Should raise an exception if for some reason the undo fails. The
exception will cause an SNMP error to be returned to the set operation.
cleanup {index1 [index2 ...]}
The script which is called as the last step of handling a set request
in order to release any allocated resources.
Input:
Index1
... - The values of the row
indexes. The values are the same, and in the same order as the values
which were used when the row was added via the snmp::addrow function.
Returns:
Nothing.
Should raise an exception if for some reason the cleanup failes. The
exception will cause an SNMP error to be returned to the set operation.
License
Although no DRM measure is employed with this software, it is not a
free software except for non profit organizations. If after an
evaluation period, you find this software to be valuable to you please
contact license@marksw.com to arrange paying 20$ for the license.
- You may use this software free of charge for an evaluation
period. The evaluation should not take more then two months.
- Any non profit organization may use this software free of
charge.
- You may not redistribute this software.
The legal bla bla about no warranty etc, is found in the license file
of the installation.
Download
From here
|