diff options
Diffstat (limited to 'contrib/bsnmp/lib/bsnmpagent.3')
| -rw-r--r-- | contrib/bsnmp/lib/bsnmpagent.3 | 173 |
1 files changed, 103 insertions, 70 deletions
diff --git a/contrib/bsnmp/lib/bsnmpagent.3 b/contrib/bsnmp/lib/bsnmpagent.3 index d563aa9..6e77635 100644 --- a/contrib/bsnmp/lib/bsnmpagent.3 +++ b/contrib/bsnmp/lib/bsnmpagent.3 @@ -1,4 +1,7 @@ .\" +.\" Copyright (c) 2004-2005 +.\" Hartmut Brandt. +.\" All rights reserved. .\" Copyright (c) 2001-2003 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" All rights reserved. @@ -26,9 +29,9 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Begemot: bsnmp/lib/bsnmpagent.3,v 1.7 2005/02/25 11:55:58 brandt_h Exp $ +.\" $Begemot: bsnmp/lib/bsnmpagent.3,v 1.10 2005/10/04 08:46:49 brandt_h Exp $ .\" -.Dd August 16, 2002 +.Dd October 4, 2005 .Dt BSNMPAGENT 3 .Os .Sh NAME @@ -87,14 +90,15 @@ Begemot SNMP library .Fn snmp_dep_finish "struct snmp_context *ctx" .Sh DESCRIPTION The SNMP library contains routines to easily build SNMP agent applications -that use SNMP versions 1 or 2. Note, however, that it may be even easier to -build an -.Xr snmpd 1 +that use SNMP versions 1 or 2. +Note, however, that it may be even easier to build an +.Xr bsnmpd 1 loadable module, that handles the new MIB (see -.Xr snmpmod 3 ). +.Xr snmpmod 3 ) . .Pp Most of the agent routines operate on a global array that the describes the -complete MIB served by the agent. This array is held in the two variables: +complete MIB served by the agent. +This array is held in the two variables: .Bd -literal -offset indent extern struct snmp_node *tree; extern u_int tree_size; @@ -126,7 +130,8 @@ Base OID of the scalar or table column. .It Va name Name of this variable. .It Va type -Type of this variable. One of: +Type of this variable. +One of: .Bd -literal -offset indent enum snmp_node_type { SNMP_NODE_LEAF = 1, @@ -136,17 +141,20 @@ enum snmp_node_type { .It Va syntax The SNMP syntax of this variable. .It Va op -The user supplied handler for this variable. The handler is called with -the following arguments: +The user supplied handler for this variable. +The handler is called with the following arguments: .Bl -tag -width "ctx" .It Fa ctx A pointer to the context (see below). .Li NULL . .It Fa val -The value to be set or retrieved. For GETNEXT and GETBULK operations the oid in -this value is the current OID. The function (called in this case only for +The value to be set or retrieved. +For GETNEXT and GETBULK operations the oid in +this value is the current OID. +The function (called in this case only for table rows) must find the lexically next existing OID within the same column and -set the oid and value subfields accordingly. If the table column is exhausted the +set the oid and value subfields accordingly. +If the table column is exhausted the function must return .Li SNMP_ERR_NOSUCHNAME . For all other operations the oid in @@ -169,18 +177,20 @@ enum snmp_op { .Ed .El .Pp -The user handler must return an appropiate SNMP v2 error code. If the original +The user handler must return an appropriate SNMP v2 error code. +If the original PDU was a version 1 PDU, the error code is mapped automatically. .It Va flags Currently only the flag .Li SNMP_NODE_CANSET is defined and set for nodes, that can be written or created. .It Va index -This word describes the index for table columns. Each part of the index -takes 4 bits starting at bit 4. Bits 0 to 3 hold the number of index parts. -This arrangment allows for tables with up to seven indexes. Each bit group -contains the syntax for the index part. There are a number of macros to -help in parsing this field: +This word describes the index for table columns. +Each part of the index takes 4 bits starting at bit 4. +Bits 0 to 3 hold the number of index parts. +This arrangement allows for tables with up to seven indexes. +Each bit group contains the syntax for the index part. +There are a number of macros to help in parsing this field: .Bd -literal -offset indent #define SNMP_INDEXES_MAX 7 #define SNMP_INDEX_SHIFT 4 @@ -197,8 +207,9 @@ This field may contain arbitrary data and is not used by the library. The easiest way to construct the node table is .Xr gensnmptree 1 . Note, that one must be careful when changing the tree while executing a SET -operation. Consult the sources for -.Xr snmpd 1 . +operation. +Consult the sources for +.Xr bsnmpd 1 . .Pp The global variable .Va snmp_trace @@ -218,7 +229,8 @@ enum { .Pp Setting a bit to true causes the library to call .Fn snmp_debug -in strategic places with a debug string. The library contains a default +in strategic places with a debug string. +The library contains a default implementation for the debug function that prints a message to standard error. .Pp Many of the functions use a so called context: @@ -234,8 +246,8 @@ struct snmp_context { struct snmp_scratch { void *ptr1; void *ptr2; - u_int32_t int1; - u_int32_t int2; + uint32_t int1; + uint32_t int2; }; .Ed .Pp @@ -243,15 +255,17 @@ The fields are used as follows: .Bl -tag -width ".It Va var_index" .It Va va_index For the node operation callback this is the -index of the variable binding that should be returned if an error occures. -Set by the library. In all other functions this is undefined. +index of the variable binding that should be returned if an error occurs. +Set by the library. +In all other functions this is undefined. .It Va scratch For the node operation callback this is a pointer to a per variable binding -scratch area that can be used to implement the commit and rollback. Set -by the library. +scratch area that can be used to implement the commit and rollback. +Set by the library. .It Va dep In the dependency callback function (see below) this is a pointer to the -current dependency. Set by the library. +current dependency. +Set by the library. .It Va data This is the .Fa data @@ -267,21 +281,24 @@ executes an SNMP GETNEXT operation and the function .Fn snmp_getbulk executes an SNMP GETBULK operation. For all three functions the response PDU is constructed and encoded -on the fly. If everything is ok, the response PDU is returned in +on the fly. +If everything is ok, the response PDU is returned in .Fa resp and .Fa resp_b . The caller must call .Fn snmp_pdu_free -to free the response PDU in this case. One of the following values may be -returned: +to free the response PDU in this case. +One of the following values may be returned: .Bl -tag -width ".It Li SNMP_RET_ERR" .It Li SNMP_RET_OK Operation successful, response PDU may be sent. .It Li SNMP_RET_IGN -Operation failed, no response PDU constructed. Request is ignored. +Operation failed, no response PDU constructed. +Request is ignored. .It Li SNMP_RET_ERR -Error in operation. The error code and index have been set in +Error in operation. +The error code and index have been set in .Fa pdu . No response PDU has been constructed. The caller may construct an error response PDU via @@ -290,47 +307,56 @@ The caller may construct an error response PDU via .Pp The function .Fn snmp_set -executes an SNMP SET operation. The arguments are the same as for the previous -three functions. The operation of this functions is, however, much more complex. +executes an SNMP SET operation. +The arguments are the same as for the previous +three functions. +The operation of this functions is, however, much more complex. .Pp -The SET operation occures in several stages: +The SET operation occurs in several stages: .Bl -enum -offset indent .It For each binding search the corresponding nodes, check that the -variable is writeable and the syntax is ok. The writeable check can be done -only for scalars. For columns it must be done in the node's operation callback -function. +variable is writeable and the syntax is ok. +The writeable check can be done only for scalars. +For columns it must be done in the node's operation callback function. .It For each binding call the node's operation callback with function SNMP_OP_SET. -The callback may create dependencies or finalizers (see below). For simple +The callback may create dependencies or finalizers (see below). +For simple scalars the scratch area may be enough to handle commit and rollback, for -interdependend table columns dependencies may be necessary. +interdependent table columns dependencies may be necessary. .It If the previous step fails at any point, the node's operation callback functions are called for all bindings for which SNMP_OP_SET was executed -with SNMP_OP_ROLLBACK, in the opposite order. This allows all variables to -undo the effect of the SET operation. After this all the dependencies -are freed -and the finalizers are executed with a fail flag of 1. Then the function +with SNMP_OP_ROLLBACK, in the opposite order. +This allows all variables to undo the effect of the SET operation. +After this all the dependencies are freed +and the finalizers are executed with a fail flag of 1. +Then the function returns to the caller with an appropriate error indication. .It If the SET step was successful for all bindings, the dependency callbacks are executed in the order in which the dependencies were created with an -operation of SNMP_DEPOP_COMMIT. If any of the dependencies fails, all the +operation of SNMP_DEPOP_COMMIT. +If any of the dependencies fails, all the committed dependencies are called again in the opposite order -with SNMP_DEPOP_ROLLBACK. Than for all bindings from the last to the first +with SNMP_DEPOP_ROLLBACK. +Than for all bindings from the last to the first the node's operation callback is called with SNMP_OP_ROLLBACK to undo -the effect of SNMP_OP_SET. At the end the dependencies are freed -and the finalizers are called with a fail flag -of 1 and the function returns to the caller with an appropriate error indication. +the effect of SNMP_OP_SET. +At the end the dependencies are freed and the finalizers are called with +a fail flag of 1 and the function returns to the caller with an appropriate +error indication. .It If the dependency commits were successful, for each binding the node's -operation callback is called with SNMP_OP_COMMIT. Any error returned from +operation callback is called with SNMP_OP_COMMIT. +Any error returned from the callbacks is ignored (an error message is generated via .Fn snmp_error ). .It Now the dependencies are freed and the finalizers are called -with a fail flag of 0. For each dependency just before freeing it +with a fail flag of 0. +For each dependency just before freeing it its callback is called with .Li SNMP_DEPOP_FINISH. Then the function returns @@ -338,20 +364,26 @@ Then the function returns .El .Pp There are to mechanisms to help in complex SET operations: dependencies and -finalizers. A dependency is used if several bindings depend on each other. +finalizers. +A dependency is used if several bindings depend on each other. A typical example is the creation of a conceptual row, which requires -the setting of several columns to succeed. A dependency is identified by -two OIDs. In the table case, the first oid is typically the table's base OID -and the second one the index. Both of these can easily be generated from the +the setting of several columns to succeed. +A dependency is identified by +two OIDs. +In the table case, the first oid is typically the table's base OID +and the second one the index. +Both of these can easily be generated from the variables OID with .Fn asn_slice_oid . The function .Fn snmp_dep_lookup tries to find a dependency based on these two OIDs and, if it cannot find one -creates a new one. This means for the table example, that the function +creates a new one. +This means for the table example, that the function returns the same dependency for each of the columns of the same table row. This allows during the SNMP_OP_SET processing to collect all information -about the row into the dependency. The arguments to +about the row into the dependency. +The arguments to .Fn snmp_dep_lookup are: the two OIDs to identify the dependency (they are copied into newly created dependencies), the size of the structure to allocate and @@ -369,16 +401,17 @@ freed correctly. .Pp The function .Fn snmp_make_errresp -makes an error response if an operation has failed. It takes the original -request PDU (it will look only on the error code and index fields), the -buffer containing the original PDU and a buffer for the error PDU. It copies -the bindings field from the original PDUs buffer directly to the response -PDU and thus does not depend on the decodability of this field. It may return -the same values as the operation functions. +makes an error response if an operation has failed. +It takes the original request PDU (it will look only on the error code and +index fields), the buffer containing the original PDU and a buffer for the +error PDU. +It copies the bindings field from the original PDUs buffer directly to +the response PDU and thus does not depend on the decodability of this field. +It may return the same values as the operation functions. .Pp The next four functions allow some parts of the SET operation to be executed. This is only used in -.Xr snmpd 1 +.Xr bsnmpd 1 to implement the configuration as a single transaction. The function .Fn snmp_init_context @@ -395,12 +428,12 @@ The function .Fn snmp_dep_finish executes SNMP_DEPOP_FINISH for all dependencies. .Sh DIAGNOSTICS -If an error occures in any of the function an error indication as described -above is returned. Additionally the functions may call snmp_error on unexected -errors. +If an error occurs in any of the function an error indication as described +above is returned. +Additionally the functions may call snmp_error on unexpected errors. .Sh SEE ALSO .Xr gensnmptree 1 , -.Xr snmpd 1 , +.Xr bsnmpd 1 , .Xr bsnmpclient 3 , .Xr bsnmplib 3 , .Xr snmpmod 3 |
