Index: stable/7/contrib/bsnmp/gensnmpdef/gensnmpdef.1 =================================================================== --- stable/7/contrib/bsnmp/gensnmpdef/gensnmpdef.1 (revision 211701) +++ stable/7/contrib/bsnmp/gensnmpdef/gensnmpdef.1 (revision 211702) @@ -1,85 +1,85 @@ .\" .\" Copyright (C) 2004-2006 .\" Hartmut Brandt. .\" All rights reserved. .\" -.\" Author: Harti Brandt +.\" Author: Harti Brandt .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Begemot: gensnmpdef.1 383 2006-05-30 07:40:49Z brandt_h $ .\" .Dd May 28, 2006 .Dt GENSNMPDEF 1 .Os .Sh NAME .Nm gensnmpdef .Nd "generate a MIB description file from MIBs" .Sh SYNOPSIS .Nm .Op Fl hEe .Op Fl c Ar cut .Ar name Op Ar ... .Sh DESCRIPTION The .Nm utility is used to create an initial MIB description file from one or more MIBs. The description file must be edited to be actually useful for feeding it into .Xr gensnmptree 1 . .Pp The following options are available: .Bl -tag -width indent .It Fl c Ar cut Specify the number of initial sub-oids that should be omitted from the tree in the output. .Xr gensnmptree 1 automatically adds 1.3.6 in front of all OIDs so the default value of 3 is just correct in most cases. .It Fl E Generate typedefs for named enumerations. These are enumerations defined via the TEXTUAL-CONVENTION macro. The normal tree output is suppressed. .It Fl e Generate typedefs for unnamed enumerations. These are enumerations defined in the SYNTAX clause of an OBJECT-TYPE macro. The name of the enumeration is formed by appending the string .Ql Type to the name of the object. The normal tree output is suppressed. .It Fl h Print a short help text and exit. .El .Pp .Nm does no attempt on sorting the OID tree so in case of complex and non-standard MIBs it is necessary to sort the tree in the resulting definition file by hand. .Sh SEE ALSO .Xr snmpd 1 .Sh AUTHORS -.An Hartmut Brandt Aq harti@freebsd.org +.An Hartmut Brandt Aq harti@FreeBSD.org .Sh BUGS The utility is by no means bullet-proof and may fail for complex or non-standard MIBs. Its output is expected to be edited by hand. Index: stable/7/contrib/bsnmp/gensnmptree/gensnmptree.1 =================================================================== --- stable/7/contrib/bsnmp/gensnmptree/gensnmptree.1 (revision 211701) +++ stable/7/contrib/bsnmp/gensnmptree/gensnmptree.1 (revision 211702) @@ -1,246 +1,246 @@ .\" .\" Copyright (c) 2001-2005 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" All rights reserved. .\" Copyright (c) 2006 .\" Hartmut Brandt .\" All rights reserved. .\" -.\" Author: Harti Brandt +.\" Author: Harti Brandt .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Begemot: gensnmptree.1 383 2006-05-30 07:40:49Z brandt_h $ .\" .Dd May 26, 2006 .Dt GENSNMPTREE 1 .Os .Sh NAME .Nm gensnmptree .Nd "generate C and header files from a MIB description file" .Sh SYNOPSIS .Nm .Op Fl dEehlt .Op Fl I Ar directory .Op Fl i Ar infile .Op Fl p Ar prefix .Op Ar name Ar ... .Sh DESCRIPTION The .Nm utility is used to either generate C language tables and header files from a MIB description or to numeric OIDs from MIB descriptions. The first form is used only for maintaining the .Xr bsnmpd 1 daemon or for module writers. The second form may be used by SNMP client program writers. .Pp If none of the options .Fl e , .Fl E or -.FL t +.Fl t are used .Nm reads a MIB description from its standard input and creates two files: a C-file .Ar prefix Ns tree.c containing a table used by .Xr bsnmpd 1 during PDU processing and a header file .Ar prefix Ns tree.h containing appropriate declarations of the callback functions used in this table, the table itself and definitions for all enums. .Pp The following options are available: .Bl -tag -width ".Fl E" .It Fl d Switch on debugging. .It Fl E Extract enumerations and bit constructs. In this mode the tool emits a header file that contains for each type given on the command line a C-enum definition and a preprocessor define that may be used to map values to strings. .It Fl e .Nm expects MIB variable names (only the last component) on its command line. It reads a MIB specification from standard input and for each MIB variable name emits three C preprocessor defines on its standard output: .Bl -tag -width ".Va OIDLEN_ Ns Ar Name" .It Va OIDX_ Ns Ar name This define can be used to initialize a .Va struct asn_oid in the following way: .Pp .Dl const struct asn_oid oid_sysDescr = OIDX_sysDescr; .It Va OIDLEN_ Ns Ar name is the length of the OID. .It Va OID_ Ns Ar name is the last component of the OID. .El .It Fl h Print a short help page. .It Fl I Ar directory Add the named directory to the include path just before the standard include directories. .It Fl i Ar infile Read from the named file instead of standard input. .It Fl l Generate local preprocessor includes. This is used for bootstrapping .Xr bsnmpd 1 . .It Fl t Instead of normal output print the resulting tree. .It Fl p Ar prefix Prefix the file names and the table name with .Ar prefix . .El .Sh MIBS The syntax of the MIB description file can formally be specified as follows: .Bd -unfilled -offset indent file := top | top file top := tree | typedef | include tree := head elements ')' entry := head ':' index STRING elements ')' leaf := head type STRING ACCESS ')' column := head type ACCESS ')' type := BASETYPE | BASETYPE '|' subtype | enum | bits subtype := STRING enum := ENUM '(' value ')' bits := BITS '(' value ')' value := INT STRING | INT STRING value head := '(' INT STRING elements := EMPTY | elements element element := tree | leaf | column index := type | index type typedef := 'typedef' STRING type include := 'include' filespec filespec := '"' STRING '"' | '<' STRING '>' .Ed .Pp .Ar BASETYPE specifies a SNMP data type and may be one of .Bl -bullet -offset indent -compact .It NULL .It INTEGER .It INTEGER32 (same as INTEGER) .It UNSIGNED32 (same as GAUGE) .It OCTETSTRING .It IPADDRESS .It OID .It TIMETICKS .It COUNTER .It GAUGE .It COUNTER64 .El .Pp .Ar ACCESS specifies the accessibility of the MIB variable (which operation can be performed) and is one of .Bl -bullet -offset indent -compact .It GET .It SET .El .Pp .Ar INT is a decimal integer and .Ar STRING is any string starting with a letter or underscore and consisting of letters, digits, underscores and minuses, that is not one of the keywords. .Pp The .Ar typedef directive associates a type with a single name. .Pp The .Ar include directive is replaced by the contents of the named file. .Sh EXAMPLES The following MIB description describes the system group: .Bd -literal -offset indent include "tc.def" typedef AdminStatus ENUM ( 1 up 2 down ) (1 internet (2 mgmt (1 mibII (1 system (1 sysDescr OCTETSTRING op_system_group GET) (2 sysObjectId OID op_system_group GET) (3 sysUpTime TIMETICKS op_system_group GET) (4 sysContact OCTETSTRING op_system_group GET SET) (5 sysName OCTETSTRING op_system_group GET SET) (6 sysLocation OCTETSTRING op_system_group GET SET) (7 sysServices INTEGER op_system_group GET) (8 sysORLastChange TIMETICKS op_system_group GET) (9 sysORTable (1 sysOREntry : INTEGER op_or_table (1 sysORIndex INTEGER) (2 sysORID OID GET) (3 sysORDescr OCTETSTRING GET) (4 sysORUpTime TIMETICKS GET) )) ) ) ) ) .Ed .Sh SEE ALSO .Xr bsnmpd 1 .Sh AUTHORS -.An Hartmut Brandt Aq harti@freebsd.org +.An Hartmut Brandt Aq harti@FreeBSD.org Index: stable/7/contrib/bsnmp/lib/asn1.3 =================================================================== --- stable/7/contrib/bsnmp/lib/asn1.3 (revision 211701) +++ stable/7/contrib/bsnmp/lib/asn1.3 (revision 211702) @@ -1,492 +1,492 @@ .\" .\" Copyright (c) 2004-2005 .\" Hartmut Brandt. .\" All rights reserved. .\" Copyright (c) 2001-2003 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" All rights reserved. .\" -.\" Author: Harti Brandt +.\" Author: Harti Brandt .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Begemot: bsnmp/lib/asn1.3,v 1.9 2005/10/04 08:46:49 brandt_h Exp $ .\" .Dd October 4, 2005 .Dt ASN1 3 .Os .Sh NAME .Nm asn_get_header , .Nm asn_put_header , .Nm asn_put_temp_header , .Nm asn_commit_header , .Nm asn_get_integer_raw , .Nm asn_get_integer , .Nm asn_put_integer , .Nm asn_get_octetstring_raw , .Nm asn_get_octetstring , .Nm asn_put_octetstring , .Nm asn_get_null_raw , .Nm asn_get_null , .Nm asn_put_null , .Nm asn_put_exception , .Nm asn_get_objid_raw , .Nm asn_get_objid , .Nm asn_put_objid , .Nm asn_get_sequence , .Nm asn_get_ipaddress_raw , .Nm asn_get_ipaddress , .Nm asn_put_ipaddress , .Nm asn_get_uint32_raw , .Nm asn_put_uint32 , .Nm asn_get_counter64_raw , .Nm asn_put_counter64 , .Nm asn_get_timeticks , .Nm asn_put_timeticks , .Nm asn_skip , .Nm asn_slice_oid , .Nm asn_append_oid , .Nm asn_compare_oid , .Nm asn_is_suboid , .Nm asn_oid2str_r , .Nm asn_oid2str .Nd "ASN.1 library for SNMP" .Sh LIBRARY Begemot SNMP library .Pq libbsnmp, -lbsnmp .Sh SYNOPSIS .In bsnmp/asn1.h .Ft enum asn_err .Fn asn_get_header "struct asn_buf *buf" "u_char *type" "asn_len_t *lenp" .Ft enum asn_err .Fn asn_put_header "struct asn_buf *buf" "u_char type" "asn_len_t len" .Ft enum asn_err .Fn asn_put_temp_header "struct asn_buf *buf" "u_char type" "u_char **ptr" .Ft enum asn_err .Fn asn_commit_header "struct asn_buf *buf" "u_char *ptr" .Ft enum asn_err .Fn asn_get_integer_raw "struct asn_buf *buf" "asn_len_t len" "int32_t *res" .Ft enum asn_err .Fn asn_get_integer "struct asn_buf *buf" "int32_t *res" .Ft enum asn_err .Fn asn_put_integer "struct asn_buf *buf" "int32_t arg" .Ft enum asn_err .Fn asn_get_octetstring_raw "struct asn_buf *buf" "asn_len_t len" "u_char *out" "u_int *outsize" .Ft enum asn_err .Fn asn_get_octetstring "struct asn_buf *buf" "u_char *out" "u_int *outsize" .Ft enum asn_err .Fn asn_put_octetstring "struct asn_buf *buf" "const u_char *str" "u_int strsize" .Ft enum asn_err .Fn asn_get_null_raw "struct asn_buf *buf" "asn_len_t len" .Ft enum asn_err .Fn asn_get_null "struct asn_buf *buf" .Ft enum asn_err .Fn asn_put_null "struct asn_buf *buf" .Ft enum asn_err .Fn asn_put_exception "struct asn_buf *buf" "u_int type" .Ft enum asn_err .Fn asn_get_objid_raw "struct asn_buf *buf" "asn_len_t len" "struct asn_oid *oid" .Ft enum asn_err .Fn asn_get_objid "struct asn_buf *buf" "struct asn_oid *oid" .Ft enum asn_err .Fn asn_put_objid "struct asn_buf *buf" "const struct asn_oid *oid" .Ft enum asn_err .Fn asn_get_sequence "struct asn_buf *buf" "asn_len_t *lenp" .Ft enum asn_err .Fn asn_get_ipaddress_raw "struct asn_buf *buf" "asn_len_t len" "u_char *ipa" .Ft enum asn_err .Fn asn_get_ipaddress "struct asn_buf *buf" "u_char *ipa" .Ft enum asn_err .Fn asn_put_ipaddress "struct asn_buf *buf" "const u_char *ipa" .Ft enum asn_err .Fn asn_get_uint32_raw "struct asn_buf *buf" "asn_len_t len" "u_int32_t *res" .Ft enum asn_err .Fn asn_put_uint32 "struct asn_buf *buf" "u_char type" "u_int32_t val" .Ft enum asn_err .Fn asn_get_counter64_raw "struct asn_buf *buf" "asn_len_t len" "u_int64_t *res" .Ft enum asn_err .Fn asn_put_counter64 "struct asn_buf *buf" "u_int64_t val" .Ft enum asn_err .Fn asn_get_timeticks "struct asn_buf *buf" "u_int32_t *valp" .Ft enum asn_err .Fn asn_put_timeticks "struct asn_buf *buf" "u_int32_t val" .Ft enum asn_err .Fn asn_skip "struct asn_buf *buf" "asn_len_t len" .Ft void .Fn asn_slice_oid "struct asn_oid *dest" "const struct asn_oid *src" "u_int from" "u_int to" .Ft void .Fn asn_append_oid "struct asn_oid *to" "const struct asn_oid *from" .Ft int .Fn asn_compare_oid "const struct asn_oid *oid1" "const struct asn_oid *oid2" .Ft int .Fn asn_is_suboid "const struct asn_oid *oid1" "const struct asn_oid *oid2" .Ft char * .Fn asn_oid2str_r "const struct asn_oid *oid" "char *buf" .Ft char * .Fn asn_oid2str "const struct asn_oid *oid" .Sh DESCRIPTION The ASN.1 library contains routines to handle ASN.1 encoding for SNMP. It supports only the restricted form of ASN.1 as required by SNMP. There are two basic structures used throughout the library: .Bd -literal -offset indent /* these restrictions are in the SMI */ #define ASN_MAXID 0xffffffff #define ASN_MAXOIDLEN 128 /* type of subidentifiers */ typedef u_int32_t asn_subid_t; struct asn_oid { u_int len; asn_subid_t subs[ASN_MAXOIDLEN]; }; .Ed .Pp This structure represents an OID with the restrictions defined in the SNMP SMI. .Fa len holds the current length of the OID and .Fa subs holds the elements of the OID. .Bd -literal -offset indent struct asn_buf { union { u_char *ptr; const u_char *cptr; } asn_u; size_t asn_len; }; #define asn_cptr asn_u.cptr #define asn_ptr asn_u.ptr .Ed .Pp This structure is used to encode and decode ASN.1. It describes the output buffer for encoding routines and the input buffer for decoding routines. For encoding .Fa asn_len holds the number of remaining free octets in the buffer. The first free byte is pointed to by .Fa asn_ptr . For decoding .Fa asn_len holds the number of remaining bytes to decode. The next byte to decode is pointed to by .Fa asn_cptr . .Pp Most of the functions return an error code .Fa "enum asn_error" : .Bd -literal -offset indent enum asn_err { /* conversion was ok */ ASN_ERR_OK = 0, /* conversion failed and stopped */ ASN_ERR_FAILED = 1 | 0x1000, /* length field bad, value skipped */ ASN_ERR_BADLEN = 2, /* out of buffer, stopped */ ASN_ERR_EOBUF = 3 | 0x1000, /* length ok, but value is out of range */ ASN_ERR_RANGE = 4, /* not the expected tag, stopped */ ASN_ERR_TAG = 5 | 0x1000, }; #define ASN_ERR_STOPPED(E) (((E) & 0x1000) != 0) .Ed .Pp If .Fn ASN_ERR_STOPPED returns true, the error was fatal and processing has stopped at the point of error. .Pp The function .Fn asn_get_header reads the next header from the input octet stream. It returns the tag in the variable pointed to by .Fa type (note that only single byte tags are supported) and the decoded length field in the value pointed to by .Fa lenp (this is restricted to a unsigned 32-bit value). All errors in this function are fatal and stop processing. .Pp The function .Fn asn_put_header writes an ASN.1 header. .Fa type is the tag to write and is restricted to one byte tags (i.e., tags lesser or equal than 0x30). .Fa len is the length of the value and is restricted to 16-bit. .Pp The functions .Fn asn_put_temp_header and .Fn asn_commit_header are used to write a header when the length of the value is not known in advance, for example, for sequences. .Fn asn_put_temp_header writes a header with the given tag .Fa type and space for the maximum supported length field and sets the pointer pointed to by .Fa ptr to the begin of this length field. This pointer must then be fed into .Fn asn_commit_header directly after writing the value to the buffer. The function will compute the length, insert it into the right place and shift the value if the resulting length field is shorter than the estimated one. .Pp The function .Fn asn_get_integer_raw is used to decode a signed integer value (32-bit). It assumes, that the header of the integer has been decoded already. .Fa len is the length obtained from the ASN.1 header and the integer will be returned in the value pointed to by .Fa res . .Pp The function .Fn asn_get_integer decodes a complete 32-bit signed integer including the header. If the tag is wrong .Li ASN_ERR_TAG is returned. The function .Fn asn_put_integer encodes a 32-bit signed integer. .Pp The function .Fn asn_get_octetstring_raw decodes the value field of an ASN.1 octet string. The length obtained from the header must be fed into the .Fa len argument and .Fa out must point to a buffer to receive the octet string. On entry to the function .Fa outsize must point to the size of the buffer. On exit .Fa outsize will point to the number of octets decoded (if no error occurs this will be equal to .Fa len ). The function .Fn asn_get_octetstring decodes an octetstring including the header. .Fa out must point to a buffer to receive the string, .Fa outsize must point to the size of the buffer. On exit of the function .Fa outsize will point to the number of octets decoded. The function .Fn asn_put_octetstring encodes an octetstring (including the header). .Fa str points to the string to encode and .Fa strsize is the length of the string (the string may contain embedded .Li NUL Ns s). .Pp The function .Fn asn_get_null_raw decodes a null value. .Fa len is the length obtained from the header and must be 0. The function .Fn asn_get_null decodes a null including the header and the function .Fn asn_put_null encodes a null. .Pp The function .Fn asn_put_exception is used to encode an SNMPv2 exception. The exception type is .Fa type . .Pp The function .Fn asn_get_objid_raw is used to decode an OID value. .Fa len must be the value length obtained from the header and .Fa oid will receive the decoded OID. The function .Fn asn_get_objid decodes a complete OID (including the header) and the function .Fn asn_put_objid encodes a complete OID. .Pp The function .Fn asn_get_sequence decodes a sequence header. The length of the sequence value will be stored in the value pointed to by .Fa lenp . .Pp The function .Fn asn_get_ipaddress_raw decodes an IP address value. .Fa len is the length from the header and must be 4. .Fa ipa will receive the decoded IP address and must point to a buffer of at least four bytes. The function .Fn asn_get_ipaddress decodes a complete IP address (including the header) and .Fn asn_put_ipaddress encodes an IP address. .Pp The function .Fn asn_get_uint32_raw decodes an unsigned 32-bit integer value. .Fa len is the length from the header and .Fa res will get the decoded value. The function .Fn asn_put_uint32 encodes an unsigned 32-bit integer value and inserts the tag given in .Fa type into the header. .Pp The function .Fn asn_get_counter64_raw decodes an unsigned 64-bit integer value. .Fa len must be the value length from the header. The resulting value is stored into the variable pointed to by .Fa res . The function .Fn asn_put_counter64 encodes a complete unsigned 64-bit value. .Pp The function .Fn asn_get_timeticks decodes an ASN.1 object of type .Li TIMETICKS and the function .Fn asn_put_timeticks encodes such an object. .Pp The function .Fn asn_skip can be used to skip .Fa len bytes in the input buffer. .Pp The function .Fn asn_slice_oid splits a part out from an OID. It takes all the subids from the OID pointed to by .Fa src starting with the subid at position .Fa from (the first subid being subid 0) up to, but not including, subid .Fa to and generates a new OID in .Fa dest . If .Fa to is less or equal to .Fa from the resulting OID will have a length of zero. .Pp The function .Fn asn_append_oid appends the OID .Fa from to the OID .Fa to given that the resulting OID is not too long. If the maximum length is exceeded the result is undefined. .Pp The function .Fn asn_compare_oid compares two oids and returns the values .Li -1 , .Li 0 or .Li +1 when .Fa oid1 is lesser than, equal, or larger than .Fa oid2 resp. .Pp The function .Fn asn_is_suboid returns 1 if .Fa oid1 is equal to the leading part of .Fa oid2 . It returns 0 otherwise. .Pp The function .Fn asn_oid2str_r makes a printable string from .Fa oid . The buffer pointed to by .Fa str must be large enough to hold the result. The constant .Li ASN_OIDSTRLEN is defined to be the length of the maximum string generated by this function (including the trailing NUL). The function .Fn asn_oid2str makes a printable string from .Fa oid into a private buffer that is overwritten by each call. .Sh DIAGNOSTICS When an error occurs in any of the function the function pointed to by the global pointer .Bd -literal -offset indent extern void (*asn_error)(const struct asn_buf *, const char *, ...); .Ed .Pp is called with the current buffer (this may be .Li NULL ) and a .Xr printf 3 style format string. There is a default error handler in the library that prints a message starting with .Sq ASN.1: followed by the error message and an optional dump of the buffer. .Sh SEE ALSO .Xr gensnmptree 1 , .Xr bsnmpd 1 , .Xr bsnmpagent 3 , .Xr bsnmpclient 3 , .Xr bsnmplib 3 .Sh STANDARDS This implementation conforms to the applicable IETF RFCs and ITU-T recommendations. .Sh AUTHORS -.An Hartmut Brandt Aq harti@freebsd.org +.An Hartmut Brandt Aq harti@FreeBSD.org Index: stable/7/contrib/bsnmp/lib/bsnmpagent.3 =================================================================== --- stable/7/contrib/bsnmp/lib/bsnmpagent.3 (revision 211701) +++ stable/7/contrib/bsnmp/lib/bsnmpagent.3 (revision 211702) @@ -1,444 +1,444 @@ .\" .\" Copyright (c) 2004-2005 .\" Hartmut Brandt. .\" All rights reserved. .\" Copyright (c) 2001-2003 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" All rights reserved. .\" -.\" Author: Harti Brandt +.\" Author: Harti Brandt .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Begemot: bsnmp/lib/bsnmpagent.3,v 1.10 2005/10/04 08:46:49 brandt_h Exp $ .\" .Dd October 4, 2005 .Dt BSNMPAGENT 3 .Os .Sh NAME .Nm bsnmpagent , .Nm snmp_depop_t , .Nm snmp_op_t , .Nm tree , .Nm tree_size , .Nm snmp_trace , .Nm snmp_debug , .Nm snmp_get , .Nm snmp_getnext , .Nm snmp_getbulk , .Nm snmp_set , .Nm snmp_make_errresp , .Nm snmp_dep_lookup , .Nm snmp_init_context , .Nm snmp_dep_commit , .Nm snmp_dep_rollback , .Nm snmp_dep_finish .Nd "SNMP agent library" .Sh LIBRARY Begemot SNMP library .Pq libbsnmp, -lbsnmp .Sh SYNOPSIS .In asn1.h .In snmp.h .In snmpagent.h .Ft typedef int .Fn (*snmp_depop_t) "struct snmp_context *ctx" "struct snmp_dependency *dep" "enum snmp_depop op" .Ft typedef int .Fn (*snmp_op_t) "struct snmp_context *ctx" "struct snmp_value *val" "u_int len" "u_int idx" "enum snmp_op op" .Vt extern struct snmp_node *tree ; .Vt extern u_int tree_size ; .Vt extern u_int snmp_trace ; .Vt extern void (*snmp_debug)(const char *fmt, ...) ; .Ft enum snmp_ret .Fn snmp_get "struct snmp_pdu *pdu" "struct asn_buf *resp_b" "struct snmp_pdu *resp" "void *data" .Ft enum snmp_ret .Fn snmp_getnext "struct snmp_pdu *pdu" "struct asn_buf *resp_b" "struct snmp_pdu *resp" "void *data" .Ft enum snmp_ret .Fn snmp_getbulk "struct snmp_pdu *pdu" "struct asn_buf *resp_b" "struct snmp_pdu *resp" "void *data" .Ft enum snmp_ret .Fn snmp_set "struct snmp_pdu *pdu" "struct asn_buf *resp_b" "struct snmp_pdu *resp" "void *data" .Ft enum snmp_ret .Fn snmp_make_errresp "const struct snmp_pdu *pdu" "struct asn_buf *req_b" "struct asn_buf *resp_b" .Ft struct snmp_dependency * .Fn snmp_dep_lookup "struct snmp_context *ctx" "const struct asn_oid *base" "const struct asn_oid *idx" "size_t alloc" "snmp_depop_t func" .Ft struct snmp_context * .Fn snmp_init_context "void" .Ft int .Fn snmp_dep_commit "struct snmp_context *ctx" .Ft int .Fn snmp_dep_rollback "struct snmp_context *ctx" .Ft void .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 bsnmpd 1 loadable module, that handles the new MIB (see .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: .Bd -literal -offset indent extern struct snmp_node *tree; extern u_int tree_size; .Ed .Pp The elements of the array are of type .Vt struct snmp_node : .Bd -literal -offset indent typedef int (*snmp_op_t)(struct snmp_context *, struct snmp_value *, u_int, u_int, enum snmp_op); struct snmp_node { struct asn_oid oid; const char *name; /* name of the leaf */ enum snmp_node_type type; /* type of this node */ enum snmp_syntax syntax; snmp_op_t op; u_int flags; u_int32_t index; /* index data */ void *data; /* application data */ void *tree_data; /* application data */ }; .Ed .Pp The fields of this structure are described below. .Bl -tag -width "syntax" .It Va oid Base OID of the scalar or table column. .It Va name Name of this variable. .It Va type Type of this variable. One of: .Bd -literal -offset indent enum snmp_node_type { SNMP_NODE_LEAF = 1, SNMP_NODE_COLUMN }; .Ed .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: .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 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 function must return .Li SNMP_ERR_NOSUCHNAME . For all other operations the oid in .Fa val is the oid to fetch or set. .It Fa len The length of the base oid without index. .It Fa idx For table columns this is the index expression from the node (see below). .It Fa op This is the operation to execute, one of: .Bd -literal -offset indent enum snmp_op { SNMP_OP_GET = 1, SNMP_OP_GETNEXT, SNMP_OP_SET, SNMP_OP_COMMIT, SNMP_OP_ROLLBACK, }; .Ed .El .Pp 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 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 #define SNMP_INDEX_MASK 0xf #define SNMP_INDEX_COUNT(V) ((V) & SNMP_INDEX_MASK) #define SNMP_INDEX(V,I) \e (((V) >> (((I) + 1) * SNMP_INDEX_SHIFT)) & \e SNMP_INDEX_MASK) .Ed .It Va data This field may contain arbitrary data and is not used by the library. .El .Pp 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 bsnmpd 1 . .Pp The global variable .Va snmp_trace together with the function pointed to by .Va snmp_debug help in debugging the library and the agent. .Va snmp_trace is a bit mask with the following bits: .Bd -literal -offset indent enum { SNMP_TRACE_GET, SNMP_TRACE_GETNEXT, SNMP_TRACE_SET, SNMP_TRACE_DEPEND, SNMP_TRACE_FIND, }; .Ed .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 implementation for the debug function that prints a message to standard error. .Pp Many of the functions use a so called context: .Bd -literal -offset indent struct snmp_context { u_int var_index; struct snmp_scratch *scratch; struct snmp_dependency *dep; void *data; /* user data */ enum snmp_ret code; /* return code */ }; struct snmp_scratch { void *ptr1; void *ptr2; uint32_t int1; uint32_t int2; }; .Ed .Pp 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 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. .It Va dep In the dependency callback function (see below) this is a pointer to the current dependency. Set by the library. .It Va data This is the .Fa data argument from the call to the library and is not used by the library. .El .Pp The next three functions execute different kinds of GET requests. The function .Fn snmp_get executes an SNMP GET operation, the function .Fn snmp_getnext 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 .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: .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. .It Li SNMP_RET_ERR 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 .Fn snmp_make_errresp . .El .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. .Pp 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. .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 scalars the scratch area may be enough to handle commit and rollback, for 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 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 committed dependencies are called again in the opposite order 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. .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 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 its callback is called with .Li SNMP_DEPOP_FINISH. Then the function returns .Li SNMP_ERR_OK . .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. 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 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 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 .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 the dependency callback. .Pp When all SNMP_OP_SET operations have succeeded the dependencies are executed. At this stage the dependency callback has all information about the given table row that was available in this SET PDU and can operate accordingly. .Pp It is guaranteed that each dependency callback is executed at minimum once - with an operation of .Li SNMP_OP_ROLLBACK . This ensures that all dynamically allocated resources in a callback can be 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. .Pp The next four functions allow some parts of the SET operation to be executed. This is only used in .Xr bsnmpd 1 to implement the configuration as a single transaction. The function .Fn snmp_init_context creates and initializes a context. The function .Fn snmp_dep_commit executes SNMP_DEPOP_COMMIT for all dependencies in the context stopping at the first error. The function .Fn snmp_dep_rollback executes SNMP_DEPOP_ROLLBACK starting at the previous of the current dependency in the context. The function .Fn snmp_dep_finish executes SNMP_DEPOP_FINISH for all dependencies. .Sh DIAGNOSTICS 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 bsnmpd 1 , .Xr bsnmpclient 3 , .Xr bsnmplib 3 , .Xr snmpmod 3 .Sh STANDARDS This implementation conforms to the applicable IETF RFCs and ITU-T recommendations. .Sh AUTHORS -.An Hartmut Brandt Aq harti@freebsd.org +.An Hartmut Brandt Aq harti@FreeBSD.org Index: stable/7/contrib/bsnmp/lib/bsnmpclient.3 =================================================================== --- stable/7/contrib/bsnmp/lib/bsnmpclient.3 (revision 211701) +++ stable/7/contrib/bsnmp/lib/bsnmpclient.3 (revision 211702) @@ -1,658 +1,658 @@ .\" .\" Copyright (c) 2004-2005 .\" Hartmut Brandt. .\" All rights reserved. .\" Copyright (c) 2001-2003 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" All rights reserved. .\" -.\" Author: Harti Brandt +.\" Author: Harti Brandt .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Begemot: bsnmp/lib/bsnmpclient.3,v 1.12 2005/10/04 08:46:50 brandt_h Exp $ .\" .Dd October 4, 2005 .Dt BSNMPCLIENT 3 .Os .Sh NAME .Nm snmp_client , .Nm snmp_send_cb_f , .Nm snmp_timeout_cb_f , .Nm snmp_timeout_start_f , .Nm snmp_timeout_stop_f , .Nm snmp_open , .Nm snmp_close , .Nm snmp_pdu_create , .Nm snmp_add_binding , .Nm snmp_pdu_check , .Nm snmp_pdu_send , .Nm snmp_oid_append , .Nm snmp_parse_server , .Nm snmp_receive , .Nm snmp_table_cb_f , .Nm snmp_table_fetch , .Nm snmp_table_fetch_async , .Nm snmp_dialog .Nd "SNMP client library" .Sh LIBRARY Begemot SNMP library .Pq libbsnmp, -lbsnmp .Sh SYNOPSIS .In asn1.h .In snmp.h .In snmpclient.h .Ft typedef void .Fn (*snmp_send_cb_f) "struct snmp_pdu *req" "struct snmp_pdu *resp" "void *uarg" .Ft typedef void .Fn (*snmp_timeout_cb_f) "void *uarg" .Ft typedef void * .Fn (*snmp_timeout_start_f) "struct timeval *timeout" "snmp_timeout_cb_f callback" "void *uarg" .Ft typedef void .Fn (*snmp_timeout_stop_f) "void *timeout_id" .Vt extern struct snmp_client snmp_client ; .Ft void .Fn snmp_client_init "struct snmp_client *client" .Ft int .Fn snmp_client_set_host "struct snmp_client *client" "const char *host" .Ft int .Fn snmp_client_set_port "struct snmp_client *client" "const char *port" .Ft int .Fn snmp_open "const char *host" "const char *port" "const char *read_community" "const char *write_community" .Ft void .Fn snmp_close "void" .Ft void .Fn snmp_pdu_create "struct snmp_pdu *pdu" "u_int op" .Ft int .Fn snmp_add_binding "struct snmp_pdu *pdu" "..." .Ft int .Fn snmp_pdu_check "const struct snmp_pdu *req" "const struct snmp_pdu *resp" .Ft int32_t .Fn snmp_pdu_send "struct snmp_pdu *pdu" "snmp_send_cb_f func" "void *uarg" .Ft int .Fn snmp_oid_append "struct asn_oid *oid" "const char *fmt" "..." .Ft int .Fn snmp_parse_server "struct snmp_client *sc" "const char *str" .Ft int .Fn snmp_receive "int blocking" .Ft typedef void .Fn (*snmp_table_cb_f) "void *list" "void *arg" "int res" .Ft int .Fn snmp_table_fetch "const struct snmp_table *descr" "void *list" .Ft int .Fn snmp_table_fetch_async "const struct snmp_table *descr" "void *list" "snmp_table_cb_f callback" "void *uarg" .Ft int .Fn snmp_dialog "struct snmp_pdu *req" "struct snmp_pdu *resp" .Sh DESCRIPTION The SNMP library contains routines to easily build SNMP client applications that use SNMP versions 1 or 2. Most of the routines use a .Vt struct snmp_client : .Bd -literal -offset indent struct snmp_client { enum snmp_version version; int trans; /* transport type to use */ /* these two are read-only for the application */ char *cport; /* port number as string */ char *chost; /* host name or IP address as string */ char read_community[SNMP_COMMUNITY_MAXLEN + 1]; char write_community[SNMP_COMMUNITY_MAXLEN + 1]; struct timeval timeout; u_int retries; int dump_pdus; size_t txbuflen; size_t rxbuflen; int fd; int32_t next_reqid; int32_t max_reqid; int32_t min_reqid; char error[SNMP_STRERROR_LEN]; snmp_timeout_start_f timeout_start; snmp_timeout_stop_f timeout_stop; /* private */ char local_path[sizeof(SNMP_LOCAL_PATH)]; }; .Ed .Pp The fields of this structure are described below. .Bl -tag -width "timeout_start" .It Va version This is the version of SNMP to use. See .Xr bsnmplib 3 for applicable values. The default version is .Li SNMP_V2c . .It Va trans If this is .Dv SNMP_TRANS_LOC_DGRAM a local datagram socket is used. If it is .Dv SNMP_TRANS_LOC_STREAM a local stream socket is used. For .Dv SNMP_TRANS_UDP a UDP socket is created. It uses the .Va chost field as the path to the server's socket for local sockets. .It Va cport The SNMP agent's UDP port number. This may be a symbolic port number (from .Pa /etc/services ) or a numeric port number. If this field is .Li NULL (the default) the standard SNMP port is used. This field should not be changed directly but rather by calling .Fn snmp_client_set_port . .It Va chost The SNMP agent's host name, IP address or .Ux domain socket path name. If this is .Li NULL (the default) .Li localhost is assumed. This field should not be changed directly but rather through calling .Fn snmp_client_set_host . .It Va read_community This is the community name to be used for all requests except SET requests. The default is .Sq public . .It Va write_community The community name to be used for SET requests. The default is .Sq private . .It Va timeout The maximum time to wait for responses to requests. If the time elapses, the request is resent up to .Va retries times. The default is 3 seconds. .It Va retries Number of times a request PDU is to be resent. If set to 0, the request is sent only once. The default is 3 retransmissions. .It Va dump_pdus If set to a non-zero value all received and sent PDUs are dumped via .Xr snmp_pdu_dump 3 . The default is not to dump PDUs. .It Va txbuflen The encoding buffer size to be allocated for transmitted PDUs. The default is 10000 octets. .It Va rxbuflen The decoding buffer size to be allocated for received PDUs. This is the size of the maximum PDU that can be received. The default is 10000 octets. .It Va fd After calling .Fn snmp_open this is the file socket file descriptor used for sending and receiving PDUs. .It Va next_reqid The request id of the next PDU to send. Used internal by the library. .It Va max_reqid The maximum request id to use for outgoing PDUs. The default is .Li INT32_MAX . .It Va min_reqid The minimum request id to use for outgoing PDUs. Request ids are allocated linearily starting at .Va min_reqid up to .Va max_reqid . .It Va error If an error happens, this field is set to a printable string describing the error. .It Va timeout_start This field must point to a function setting up a one shot timeout. After the timeout has elapsed, the given callback function must be called with the user argument. The .Fn timeout_start function must return a .Vt void * identifying the timeout. .It Va timeout_stop This field must be set to a function that stops a running timeout. The function will be called with the return value of the corresponding .Fn timeout_start function. .It Va local_path If in local socket mode, the name of the clients socket. Not needed by the application. .El .Pp In the current implementation there is a global variable .Pp .D1 Vt extern struct snmp_client snmp_client ; .Pp that is used by all the library functions. The first call into the library must be a call to .Fn snmp_client_init to initialize this global variable to the default values. After this call and before calling .Fn snmp_open the fields of the variable may be modified by the user. The modification of the .Va chost and .Va cport fields should be done only via the functions .Fn snmp_client_set_host and .Fn snmp_client_set_port . .Pp The function .Fn snmp_open creates a UDP or .Ux domain socket and connects it to the agent's IP address and port. If any of the arguments of the call is not .Li NULL the corresponding field in the global .Va snmp_client is set from the argument. Otherwise the values that are already in that variable are used. The function .Fn snmp_close closes the socket, stops all timeouts and frees all dynamically allocated resources. .Pp The next three functions are used to create request PDUs. The function .Fn snmp_pdu_create initializes a PDU of type .Va op . It does not allocate space for the PDU itself. This is the responsibility of the caller. .Fn snmp_add_binding adds bindings to the PDU and returns the (zero based) index of the first new binding. The arguments are pairs of pointer to the OIDs and syntax constants, terminated by a NULL. The call .Bd -literal -offset indent snmp_add_binding(&pdu, &oid1, SNMP_SYNTAX_INTEGER, &oid2, SNMP_SYNTAX_OCTETSTRING, NULL); .Ed .Pp adds two new bindings to the PDU and returns the index of the first one. It is the responsibility of the caller to set the value part of the binding if necessary. The functions returns -1 if the maximum number of bindings is exhausted. The function .Fn snmp_oid_append can be used to construct variable OIDs for requests. It takes a pointer to an .Vt struct asn_oid that is to be constructed, a format string, and a number of arguments the type of which depends on the format string. The format string is interpreted character by character in the following way: .Bl -tag -width ".It Li ( Va N Ns Li )" .It Li i This format expects an argument of type .Vt asn_subid_t and appends this as a single integer to the OID. .It Li a This format expects an argument of type .Vt struct in_addr and appends to four parts of the IP address to the OID. .It Li s This format expects an argument of type .Vt const char * and appends the length of the string (as computed by .Xr strlen 3 ) and each of the characters in the string to the OID. .It Li ( Va N Ns Li ) This format expects no argument. .Va N must be a decimal number and is stored into an internal variable .Va size . .It Li b This format expects an argument of type .Vt const char * and appends .Va size characters from the string to the OID. The string may contain .Li NUL characters. .It Li c This format expects two arguments: one of type .Vt size_t and one of type .Vt const u_char * . The first argument gives the number of bytes to append to the OID from the string pointed to by the second argument. .El .Pp The function .Fn snmp_pdu_check may be used to check a response PDU. A number of checks are performed (error code, equal number of bindings, syntaxes and values for SET PDUs). The function returns +1 if everything is ok, 0 if a NOSUCHNAME or similar error was detected, -1 if the response PDU had fatal errors and -2 if .Fa resp is .Li NULL (a timeout occurred). .Pp The function .Fn snmp_pdu_send encodes and sends the given PDU. It records the PDU together with the callback and user pointers in an internal list and arranges for retransmission if no response is received. When a response is received or the retransmission count is exceeded the callback .Fa func is called with the orignal request PDU, the response PDU and the user argument .Fa uarg . If the retransmit count is exceeded, .Fa func is called with the original request PDU, the response pointer set to .Li NULL and the user argument .Fa uarg . The caller should not free the request PDU until the callback function is called. The callback function must free the request PDU and the response PDU (if not .Li NULL ). .Pp The function .Fn snmp_receive tries to receive a PDU. If the argument is zero, the function polls to see whether a packet is available, if the argument is non-zero, the function blocks until the next packet is received. The packet is delivered via the usual callback mechanism (non-response packets are silently dropped). The function returns 0, if a packet was received and successfully dispatched, -1 if an error occurred or no packet was available (in polling mode). .Pp The next two functions are used to retrieve tables from SNMP agents. They use the following input structure, that describes the table: .Bd -literal -offset indent struct snmp_table { struct asn_oid table; struct asn_oid last_change; u_int max_iter; size_t entry_size; u_int index_size; uint64_t req_mask; struct snmp_table_entry { asn_subid_t subid; enum snmp_syntax syntax; off_t offset; } entries[]; }; .Ed .Pp The fields of this structure have the following meaning: .Bl -tag -width "last_change" .It Va table This is the base OID of the table. .It Va last_change Some tables have a scalar variable of type TIMETICKS attached to them, that holds the time when the table was last changed. This OID should be the OID of this variable (without the \&.0 index). When the table is retrieved with multiple GET requests, and the variable changes between two request, the table fetch is restarted. .It Va max_iter Maximum number of tries to fetch the table. .It Va entry_size The table fetching routines return a list of structures one for each table row. This variable is the size of one structure and used to .Xr malloc 3 the structure. .It Va index_size This is the number of index columns in the table. .It Va req_mask This is a bit mask with a 1 for each table column that is required. Bit 0 corresponds to the first element (index 0) in the array .Va entries , bit 1 to the second (index 1) and so on. SNMP tables may be sparse. For sparse columns the bit should not be set. If the bit for a given column is set and the column value cannot be retrieved for a given row, the table fetch is restarted assuming that the table is currently being modified by the agent. The bits for the index columns are ignored. .It Va entries This is a variable sized array of column descriptors. This array is terminated by an element with syntax .Li SNMP_SYNTAX_NULL . The first .Va index_size elements describe all the index columns of the table, the rest are normal columns. If for the column at .Ql entries[N] the expression .Ql req_mask & (1 << N) yields true, the column is considered a required column. The fields of this the array elements have the following meaning: .Bl -tag -width "syntax" .It Va subid This is the OID subid of the column. This is ignored for index entries. Index entries are decoded according to the .Va syntax field. .It Va syntax This is the syntax of the column or index. A syntax of .Li SNMP_SYNTAX_NULL terminates the array. .It Va offset This is the starting offset of the value of the column in the return structures. This field can be set with the ISO-C .Fn offsetof macro. .El .El .Pp Both table fetching functions return TAILQ (see .Xr queue 3 ) of structures--one for each table row. These structures must start with a .Fn TAILQ_ENTRY and a .Vt uint64_t and are allocated via .Xr malloc 3 . The .Fa list argument of the table functions must point to a .Fn TAILQ_HEAD . The .Vt uint64_t fields, usually called .Va found is used to indicate which of the columns have been found for the given row. It is encoded like the .Fa req_mask field. .Pp The function .Fn snmp_table_fetch synchronously fetches the given table. If everything is ok 0 is returned. Otherwise the function returns -1 and sets an appropriate error string. The function .Fn snmp_table_fetch_async fetches the tables asynchronously. If either the entire table is fetch, or an error occurs the callback function .Fa callback is called with the callers arguments .Fa list and .Fa uarg and a parameter that is either 0 if the table was fetched, or -1 if there was an error. The function itself returns -1 if it could not initialize fetching of the table. .Pp The following table description is used to fetch the ATM interface table: .Bd -literal -offset indent /* * ATM interface table */ struct atmif { TAILQ_ENTRY(atmif) link; uint64_t found; int32_t index; u_char *ifname; size_t ifnamelen; uint32_t node_id; uint32_t pcr; int32_t media; uint32_t vpi_bits; uint32_t vci_bits; uint32_t max_vpcs; uint32_t max_vccs; u_char *esi; size_t esilen; int32_t carrier; }; TAILQ_HEAD(atmif_list, atmif); /* list of all ATM interfaces */ struct atmif_list atmif_list; static const struct snmp_table atmif_table = { OIDX_begemotAtmIfTable, OIDX_begemotAtmIfTableLastChange, 2, sizeof(struct atmif), 1, 0x7ffULL, { { 0, SNMP_SYNTAX_INTEGER, offsetof(struct atmif, index) }, { 1, SNMP_SYNTAX_OCTETSTRING, offsetof(struct atmif, ifname) }, { 2, SNMP_SYNTAX_GAUGE, offsetof(struct atmif, node_id) }, { 3, SNMP_SYNTAX_GAUGE, offsetof(struct atmif, pcr) }, { 4, SNMP_SYNTAX_INTEGER, offsetof(struct atmif, media) }, { 5, SNMP_SYNTAX_GAUGE, offsetof(struct atmif, vpi_bits) }, { 6, SNMP_SYNTAX_GAUGE, offsetof(struct atmif, vci_bits) }, { 7, SNMP_SYNTAX_GAUGE, offsetof(struct atmif, max_vpcs) }, { 8, SNMP_SYNTAX_GAUGE, offsetof(struct atmif, max_vccs) }, { 9, SNMP_SYNTAX_OCTETSTRING, offsetof(struct atmif, esi) }, { 10, SNMP_SYNTAX_INTEGER, offsetof(struct atmif, carrier) }, { 0, SNMP_SYNTAX_NULL, 0 } } }; \&... if (snmp_table_fetch(&atmif_table, &atmif_list) != 0) errx(1, "AtmIf table: %s", snmp_client.error); \&... .Ed .Pp The function .Fn snmp_dialog is used to execute a synchonuous dialog with the agent. The request PDU .Fa req is sent and the function blocks until the response PDU is received. Note, that asynchonuous receives are handled (i.e. callback functions of other send calls or table fetches may be called while in the function). The response PDU is returned in .Fa resp . If no response could be received after all timeouts and retries, the function returns -1. If a response was received 0 is returned. .Pp The function .Fn snmp_parse_server is used to parse an SNMP server specification string and fill in the fields of a .Vt struct snmp_client . The syntax of a server specification is .Pp .D1 [trans::][community@][server][:port] .Pp where .Va trans is the transport name (one of udp, stream or dgram), .Va community is the string to be used for both the read and the write community, .Va server is the server's host name in case of UDP and the path name in case of a local socket, and .Va port is the port in case of UDP transport. The function returns 0 in the case of success and return -1 and sets the error string in case of an error. .Sh DIAGNOSTICS If an error occurs in any of the function an error indication as described above is returned. Additionally the function sets a printable error string in the .Va error filed of .Va snmp_client . .Sh SEE ALSO .Xr gensnmptree 1 , .Xr bsnmpd 1 , .Xr bsnmpagent 3 , .Xr bsnmplib 3 .Sh STANDARDS This implementation conforms to the applicable IETF RFCs and ITU-T recommendations. .Sh AUTHORS -.An Hartmut Brandt Aq harti@freebsd.org +.An Hartmut Brandt Aq harti@FreeBSD.org .An Kendy Kutzner Aq kutzner@fokus.gmd.de Index: stable/7/contrib/bsnmp/lib/bsnmplib.3 =================================================================== --- stable/7/contrib/bsnmp/lib/bsnmplib.3 (revision 211701) +++ stable/7/contrib/bsnmp/lib/bsnmplib.3 (revision 211702) @@ -1,305 +1,305 @@ .\" .\" Copyright (c) 2004-2005 .\" Hartmut Brandt. .\" All rights reserved. .\" Copyright (c) 2001-2003 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" All rights reserved. .\" -.\" Author: Harti Brandt +.\" Author: Harti Brandt .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Begemot: bsnmp/lib/bsnmplib.3,v 1.9 2005/10/04 08:46:51 brandt_h Exp $ .\" .Dd October 4, 2005 .Dt BSNMPLIB 3 .Os .Sh NAME .Nm snmp_value_free , .Nm snmp_value_parse , .Nm snmp_value_copy , .Nm snmp_pdu_free , .Nm snmp_code snmp_pdu_decode , .Nm snmp_code snmp_pdu_encode , .Nm snmp_pdu_dump , .Nm TRUTH_MK , .Nm TRUTH_GET , .Nm TRUTH_OK .Nd "SNMP decoding and encoding library" .Sh LIBRARY Begemot SNMP library .Pq libbsnmp, -lbsnmp .Sh SYNOPSIS .In bsnmp/asn1.h .In bsnmp/snmp.h .Ft void .Fn snmp_value_free "struct snmp_value *value" .Ft int .Fn snmp_value_parse "const char *buf" "enum snmp_syntax" "union snmp_values *value" .Ft int .Fn snmp_value_copy "struct snmp_value *to" "const struct snmp_value *from" .Ft void .Fn snmp_pdu_free "struct snmp_pdu *value" .Ft enum snmp_code .Fn snmp_pdu_decode "struct asn_buf *buf" "struct snmp_pdu *pdu" "int32_t *ip" .Ft enum snmp_code .Fn snmp_pdu_encode "struct snmp_pdu *pdu" "struct asn_buf *buf" .Ft void .Fn snmp_pdu_dump "const struct snmp_pdu *pdu" .Ft int .Fn TRUTH_MK "F" .Ft int .Fn TRUTH_GET "T" .Ft int .Fn TRUTH_OK "T" .Sh DESCRIPTION The SNMP library contains routines to handle SNMP version 1 and 2 PDUs. There are two basic structures used throughout the library: .Bd -literal -offset indent struct snmp_value { struct asn_oid var; enum snmp_syntax syntax; union snmp_values { int32_t integer;/* also integer32 */ struct { u_int len; u_char *octets; } octetstring; struct asn_oid oid; u_char ipaddress[4]; uint32_t uint32; /* also gauge32, counter32, unsigned32, timeticks */ uint64_t counter64; } v; }; .Ed .Pp This structure represents one variable binding from an SNMP PDU. The field .Fa var is the ASN.1 of the variable that is bound. .Fa syntax contains either the syntax code of the value or an exception code for SNMPv2 and may be one of: .Bd -literal -offset indent enum snmp_syntax { SNMP_SYNTAX_NULL = 0, SNMP_SYNTAX_INTEGER, /* == INTEGER32 */ SNMP_SYNTAX_OCTETSTRING, SNMP_SYNTAX_OID, SNMP_SYNTAX_IPADDRESS, SNMP_SYNTAX_COUNTER, SNMP_SYNTAX_GAUGE, /* == UNSIGNED32 */ SNMP_SYNTAX_TIMETICKS, /* v2 additions */ SNMP_SYNTAX_COUNTER64, /* exceptions */ SNMP_SYNTAX_NOSUCHOBJECT, SNMP_SYNTAX_NOSUCHINSTANCE, SNMP_SYNTAX_ENDOFMIBVIEW, }; .Ed The field .Fa v holds the actual value depending on .Fa syntax . Note, that if .Fa syntax is .Li SNMP_SYNTAX_OCTETSTRING and .Fa v.octetstring.len is not zero, .Fa v.octetstring.octets points to a string allocated by .Xr malloc 3 . .Pp .Bd -literal -offset indent #define SNMP_COMMUNITY_MAXLEN 128 #define SNMP_MAX_BINDINGS 100 struct snmp_pdu { char community[SNMP_COMMUNITY_MAXLEN + 1]; enum snmp_version version; u_int type; /* trap only */ struct asn_oid enterprise; u_char agent_addr[4]; int32_t generic_trap; int32_t specific_trap; u_int32_t time_stamp; /* others */ int32_t request_id; int32_t error_status; int32_t error_index; /* fixes for encoding */ u_char *outer_ptr; u_char *pdu_ptr; u_char *vars_ptr; struct snmp_value bindings[SNMP_MAX_BINDINGS]; u_int nbindings; }; .Ed This structure contains a decoded SNMP PDU. .Fa version is one of .Bd -literal -offset indent enum snmp_version { SNMP_Verr = 0, SNMP_V1 = 1, SNMP_V2c, }; .Ed and .Fa type is the type of the PDU. .Pp The function .Fn snmp_value_free is used to free all the dynamic allocated contents of an SNMP value. It does not free the structure pointed to by .Fa value itself. .Pp The function .Fn snmp_value_parse parses the ASCII representation of an SNMP value into its binary form. This function is mainly used by the configuration file reader of .Xr bsnmpd 1 . .Pp The function .Fn snmp_value_copy makes a deep copy of the value pointed to by .Fa from to the structure pointed to by .Fa to . It assumes that .Fa to is uninitialized and will overwrite its previous contents. It does not itself allocate the structure pointed to by .Fa to . .Pp The function .Fn snmp_pdu_free frees all the dynamically allocated components of the PDU. It does not itself free the structure pointed to by .Fa pdu . .Pp The function .Fn snmp_pdu_decode decodes the PDU pointed to by .Fa buf and stores the result into .Fa pdu . If an error occurs in a variable binding the (1 based) index of this binding is stored in the variable pointed to by .Fa ip . .Pp The function .Fn snmp_pdu_encode encodes the PDU .Fa pdu into the an octetstring in buffer .Fa buf . .Pp The function .Fn snmp_pdu_dump dumps the PDU in a human readable form by calling .Fn snmp_printf . .Pp The function .Fn TRUTH_MK takes a C truth value (zero or non-zero) and makes an SNMP truth value (2 or 1). The function .Fn TRUTH_GET takes an SNMP truth value and makes a C truth value (0 or 1). The function .Fn TRUTH_OK checks, whether its argument is a legal SNMP truth value. .Sh DIAGNOSTICS When an error occurs in any of the function the function pointed to by the global pointer .Bd -literal -offset indent extern void (*snmp_error)(const char *, ...); .Ed .Pp with a .Xr printf 3 style format string. There is a default error handler in the library that prints a message starting with .Sq SNMP: followed by the error message to standard error. .Pp The function pointed to by .Bd -literal -offset indent extern void (*snmp_printf)(const char *, ...); .Ed .Pp is called by the .Fn snmp_pdu_dump function. The default handler is .Xr printf 3 . .Sh ERRORS .Fn snmp_pdu_decode will return one of the following return codes: .Bl -tag -width Er .It Bq Er SNMP_CODE_OK Success. .It Bq Er SNMP_CODE_FAILED The ASN.1 coding was wrong. .It Bq Er SNMP_CODE_BADLEN A variable binding value had a wrong length field. .It Bq Er SNMP_CODE_OORANGE A variable binding value was out of the allowed range. .It Bq Er SNMP_CODE_BADVERS The PDU is of an unsupported version. .It Bq Er SNMP_CODE_BADENQ There was an ASN.1 value with an unsupported tag. .El .Pp .Fn snmp_pdu_encode will return one of the following return codes: .Bl -tag -width Er .It Bq Er SNMP_CODE_OK Success. .It Bq Er SNMP_CODE_FAILED Encoding failed. .El .Sh SEE ALSO .Xr gensnmptree 1 , .Xr bsnmpd 1 , .Xr bsnmpagent 3 , .Xr bsnmpclient 3 , .Xr bsnmplib 3 .Sh STANDARDS This implementation conforms to the applicable IETF RFCs and ITU-T recommendations. .Sh AUTHORS -.An Hartmut Brandt Aq harti@freebsd.org +.An Hartmut Brandt Aq harti@FreeBSD.org Index: stable/7/contrib/bsnmp/snmp_mibII/snmp_mibII.3 =================================================================== --- stable/7/contrib/bsnmp/snmp_mibII/snmp_mibII.3 (revision 211701) +++ stable/7/contrib/bsnmp/snmp_mibII/snmp_mibII.3 (revision 211702) @@ -1,366 +1,366 @@ .\" .\" Copyright (c) 2004-2005 .\" Hartmut Brandt .\" All rights reserved. .\" Copyright (c) 2001-2003 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" All rights reserved. .\" -.\" Author: Harti Brandt +.\" Author: Harti Brandt .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Begemot: bsnmp/snmp_mibII/snmp_mibII.3,v 1.10 2005/10/04 08:46:52 brandt_h Exp $ .\" .Dd October 4, 2005 .Dt SNMP_MIBII 3 .Os .Sh NAME .Nm mibII , .Nm mibif_notify_f , .Nm mib_netsock , .Nm mib_if_set_dyn , .Nm mib_refresh_iflist , .Nm mib_find_if , .Nm mib_find_if_sys , .Nm mib_find_if_name , .Nm mib_first_if , .Nm mib_next_if , .Nm mib_register_newif , .Nm mib_unregister_newif , .Nm mib_fetch_ifmib , .Nm mib_if_admin , .Nm mib_find_ifa , .Nm mib_first_ififa , .Nm mib_next_ififa , .Nm mib_ifstack_create , .Nm mib_ifstack_delete , .Nm mib_find_rcvaddr , .Nm mib_rcvaddr_create , .Nm mib_rcvaddr_delete , .Nm mibif_notify , .Nm mibif_unnotify .Nd "mib-2 module for bsnmpd." .Sh LIBRARY .Pq begemotSnmpdModulePath."mibII" = "@MODPATH@snmp_mibII.so" .Sh SYNOPSIS .In bsnmp/snmpmod.h .In bsnmp/snmp_mibII.h .Ft typedef void .Fn (*mibif_notify_f) "struct mibif *ifp" "enum mibif_notify event" "void *uarg" .Vt extern int mib_netsock ; .Ft void .Fn mib_if_set_dyn "const char *ifname" .Ft void .Fn mib_refresh_iflist "void" .Ft struct mibif * .Fn mib_find_if "u_int ifindex" .Ft struct mibif * .Fn mib_find_if_sys "u_int sysindex" .Ft struct mibif * .Fn mib_find_if_name "const char *ifname" .Ft struct mibif * .Fn mib_first_if "void" .Ft struct mibif * .Fn mib_next_if "const struct mibif *ifp" .Ft int .Fn mib_register_newif "int (*func)(struct mibif *)" "const struct lmodule *mod" .Ft void .Fn mib_unregister_newif "const struct lmodule *mod" .Ft int .Fn mib_fetch_ifmib "struct mibif *ifp" .Ft int .Fn mib_if_admin "struct mibif *ifp" "int up" .Ft struct mibifa * .Fn mib_find_ifa "struct in_addr ipa" .Ft struct mibifa * .Fn mib_first_ififa "const struct mibif *ifp" .Ft struct mibifa * .Fn mib_next_ififa "struct mibifa *ifa" .Ft int .Fn mib_ifstack_create "const struct mibif *lower" "const struct mibif *upper" .Ft void .Fn mib_ifstack_delete "const struct mibif *lower" "const struct mibif *upper" .Ft struct mibrcvaddr * .Fn mib_find_rcvaddr "u_int ifindex" "const u_char *addr" "size_t addrlen" .Ft struct mibrcvaddr * .Fn mib_rcvaddr_create "struct mibif *ifp" "const u_char *addr" "size_t addrlen" .Ft void .Fn mib_rcvaddr_delete "struct mibrcvaddr *addr" .Ft void * .Fn mibif_notify "struct mibif *ifp" "const struct lmodule *mod" "mibif_notify_f func" "void *uarg" .Ft void .Fn mibif_unnotify "void *reg" .Sh DESCRIPTION The .Nm snmp_mibII module implements parts of the internet standard MIB-2. Most of the relevant MIBs are implemented. Some of the tables are restricted to be read-only instead of read-write. The exact current implementation can be found in .Pa @DEFPATH@mibII_tree.def . The module also exports a number of functions and global variables for use by other modules, that need to handle network interfaces. This man page describes these functions. .Ss DIRECT NETWORK ACCESS The .Nm module opens a socket that is used to execute all network related .Xr ioctl 2 functions. This socket is globally available under the name .Va mib_netsock . .Ss NETWORK INTERFACES The .Nm module handles a list of all currently existing network interfaces. It allows other modules to handle their own interface lists with special information by providing a mechanism to register to events that change the interface list (see below). The basic data structure is the interface structure: .Bd -literal -offset indent struct mibif { TAILQ_ENTRY(mibif) link; u_int flags; u_int index; /* logical ifindex */ u_int sysindex; char name[IFNAMSIZ]; char descr[256]; struct ifmibdata mib; uint64_t mibtick; void *specmib; size_t specmiblen; u_char *physaddr; u_int physaddrlen; int has_connector; int trap_enable; uint64_t counter_disc; mibif_notify_f xnotify; void *xnotify_data; const struct lmodule *xnotify_mod; struct asn_oid spec_oid; }; .Ed .Pp The .Nm module tries to implement the semantic if .Va ifIndex as described in RFC-2863. This RFC states, that an interface indexes may not be reused. That means, for example, if .Pa tun is a synthetic interface type and the system creates the interface .Pa tun0 , destroys this interfaces and again creates a .Pa tun 0 , then these interfaces must have different interface indexes, because in fact they are different interfaces. If, on the other hand, there is a hardware interface .Pa xl0 and this interface disappears, because its driver is unloaded and appears again, because the driver is loaded again, the interface index must stay the same. .Nm implements this by differentiating between real and synthetic (dynamic) interfaces. An interface type can be declared dynamic by calling the function .Fn mib_if_set_dyn with the name if the interface type (for example .Qq tun ). For real interfaces, the module keeps the mapping between the interface name and its .Va ifIndex in a special list, if the interface is unloaded. For dynamic interfaces a new .Va ifIndex is generated each time the interface comes into existence. This means, that the interface index as seen by SNMP is not the same index as used by the system. The SNMP .Va ifIndex is held in field .Va index , the system's interface index is .Va sysindex . .Pp A call to .Nm mib_refresh_iflist causes the entire interface list to be re-created. .Pp The interface list can be traversed with the functions .Fn mib_first_if and .Fn mib_next_if . Be sure not to change the interface list while traversing the list with these two calls. .Pp There are three functions to find an interface by name or index. .Fn mib_find_if finds an interface by searching for an SNMP .Va ifIndex , .Fn mib_find_if_sys finds an interface by searching for a system interface index and .Fn mib_find_if_name finds an interface by looking for an interface name. Each of the function returns .Li NULL if the interface cannot be found. .Pp The function .Fn mib_fetch_ifmib causes the interface MIB to be refreshed from the kernel. .Pp The function .Fn mib_if_admin can be used to change the interface administrative state to up (argument is 1) or down (argument is 0). .Ss INTERFACE EVENTS A module can register itself to receive a notification when a new entry is created in the interface list. This is done by calling .Fn mib_register_newif . A module can register only one function, a second call to .Fn mib_register_newif causes the registration to be overwritten. The registration can be removed with a call to .Fn mib_unregister_newif . It is unregistered automatically, when the registering module is unloaded. .Pp A module can also register to events on a specific interface. This is done by calling .Fn mibif_notify . This causes the given callback .Fa func to be called with the interface pointer, a notification code and the user argument .Fa uarg when any of the following events occur: .Bl -tag -width "XXXXX" .It Li MIBIF_NOTIFY_DESTROY The interface is destroyed. .El .Pp This mechanism can be used to implement interface type specific MIB parts in other modules. The registration can be removed with .Fn mib_unnotify which the return value from .Fa mib_notify . Any notification registration is removed automatically when the interface is destroyed or the registering module is unloaded. .Em Note that only one module can register to any given interface . .Ss INTERFACE ADDRESSES The .Nm module handles a table of interface IP-addresses. These addresses are held in a .Bd -literal -offset indent struct mibifa { TAILQ_ENTRY(mibifa) link; struct in_addr inaddr; struct in_addr inmask; struct in_addr inbcast; struct asn_oid index; u_int ifindex; u_int flags; }; .Ed .Pp The (ordered) list of IP-addresses on a given interface can be traversed by calling .Fn mib_first_ififa and .Fn mib_next_ififa . The list should not be considered read-only. .Ss INTERFACE RECEIVE ADDRESSES The internet MIB-2 contains a table of interface receive addresses. These addresses are handled in: .Bd -literal -offset indent struct mibrcvaddr { TAILQ_ENTRY(mibrcvaddr) link; struct asn_oid index; u_int ifindex; u_char addr[ASN_MAXOIDLEN]; size_t addrlen; u_int flags; }; enum { MIBRCVADDR_VOLATILE = 0x00000001, MIBRCVADDR_BCAST = 0x00000002, MIBRCVADDR_HW = 0x00000004, }; .Ed .Pp Note, that the assignment of .Li MIBRCVADDR_BCAST is based on a list of known interface types. The flags should be handled by modules implementing interface type specific MIBs. .Pp A receive address can be created with .Fn mib_rcvaddr_create and deleted with .Fn mib_rcvaddr_delete . This needs to be done only for addresses that are not automatically handled by the system. .Pp A receive address can be found with .Fn mib_find_rcvaddr . .Ss INTERFACE STACK TABLE The .Nm module maintains also the interface stack table. Because for complex stacks, there is no system supported generic way of getting this information, interface type specific modules need to help setting up stack entries. The .Nm module handles only the top and bottom entries. .Pp A table entry is created with .Fn mib_ifstack_create and deleted with .Fn mib_ifstack_delete . Both functions need the pointers to the interfaces. Entries are automatically deleted if any of the interfaces of the entry is destroyed. The functions handle both the stack table and the reverse stack table. .Sh FILES .Bl -tag -width ".It Pa @DEFPATH@mibII_tree.def" -compact .It Pa @DEFPATH@mibII_tree.def The description of the MIB tree implemented by .Nm . .It Pa /usr/local/share/snmp/mibs .It Pa @MIBSPATH@ The various internet MIBs. .El .Sh SEE ALSO .Xr gensnmptree 1 , .Xr snmpmod 3 .Sh STANDARDS This implementation conforms to the applicable IETF RFCs. .Sh AUTHORS -.An Hartmut Brandt Aq harti@freebsd.org +.An Hartmut Brandt Aq harti@FreeBSD.org Index: stable/7/contrib/bsnmp/snmpd/bsnmpd.1 =================================================================== --- stable/7/contrib/bsnmp/snmpd/bsnmpd.1 (revision 211701) +++ stable/7/contrib/bsnmp/snmpd/bsnmpd.1 (revision 211702) @@ -1,276 +1,274 @@ .\" .\" Copyright (c) 2004-2005 .\" Hartmut Brandt. .\" All rights reserved. .\" Copyright (c) 2001-2003 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" All rights reserved. .\" -.\" Author: Harti Brandt +.\" Author: Harti Brandt .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Begemot: bsnmp/snmpd/bsnmpd.1,v 1.12 2006/02/27 09:50:03 brandt_h Exp $ .\" -.Dd February 27, 2006 +.Dd August 16, 2010 .Dt BSNMPD 1 .Os .Sh NAME .Nm bsnmpd .Nd "simple and extensible SNMP daemon" .Sh SYNOPSIS .Nm .Op Fl dh .Op Fl c Ar file .Op Fl D Ar options .Op Fl I Ar paths .Op Fl l Ar prefix .Op Fl m Ar variable Ns Op = Ns Ar value .Op Fl p Ar file .Sh DESCRIPTION The .Nm -daemon server the internet SNMP (Simple Network Management Protocol). +daemon serves the internet SNMP (Simple Network Management Protocol). It is intended to serve only the absolute basic MIBs and implement all other MIBs through loadable modules. In this way the .Nm can be used in unexpected ways. .Pp The options are as follows: .Bl -tag -width ".It Fl D Ar options" .It Fl d -This option is used for debugging -.Nm -and causes it not to daemonize itself. +Do not daemonize. +Used for debugging. .It Fl h -This option prints a short usage message. +Print a short usage message. .It Fl c Ar file Use .Ar file as configuration file instead of the standard one. .It Fl D Ar options Debugging options are specified with a .Fl o flag followed by a comma separated string of options. The following options are available. .Bl -tag -width ".It Cm trace Ns Cm = Ns Cm level" .It Cm dump -This option causes all sent and received PDUs to be dumped to the terminal. +Dump all sent and received PDUs to the terminal. .It Cm events -This causes the debugging level of the event library (see +Set the debugging level of the event library (see .Xr eventlib 3 ) -to be set to 10. +to 10. .It Cm trace Ns Cm = Ns Cm level -This option causes the snmp library trace flag to be set to the specified +Set the snmp library trace flag to the specified value. The value can be specified in the usual C-syntax for numbers. .El .It Fl I Ar paths -This option specifies a colon separated list of directories to search for -configuration include files. +Specify a colon separated list of directories to search for configuration +include files. The default is .Pa /etc:/usr/etc/:/usr/local/etc . These paths are only searched for include specified within <> parentheses. .It Fl l Ar prefix -The +Use .Ar prefix -is used as the default basename for the pid and the configuration files. +as the default basename for the pid and the configuration files. .It Fl m Ar variable Ns Op = Ns Ar value Define a configuration variable. .It Fl p Ar file Specify an alternate pid file instead of the default one. .El .Sh CONFIGURATION -The .Nm reads its configuration from either the default or the user specified configuration file. The configuration file consists of the following types of lines: .Bl -bullet -offset indent .It variable assignments .It section separators .It include directives .It MIB variable assignments .El .Pp If a line is too long it can be continued on the next line by ending it with a backslash. Empty lines and lines in which the first non-blank character is a .Dq # sign are ignored. .Pp All MIB variable assignments of the entire configuration (including nested configuration files) are handled as one transaction, i.e., as if they arrived in a single SET PDU. Any failure during the initial configuration read causes .Nm to exit. A failure during the configuration read caused by a module load causes the loading of the module to fail. .Pp The configuration is read during initialization of .Nm , when a module is loaded and when .Nm receives a SIGHUP. .Ss VARIABLE ASSIGNMENTS Variable assignments can take one of two forms: .Bd -unfilled -offset indent variable := string variable ?= string .Ed .Pp The string reaches from the first non-blank character after the equal sign until the first new line or .Dq # character. In the first case the string is assigned to the variable unconditionally, in the second case the variable is only assigned if it does not exist yet. .Pp Variable names must begin with a letter or underscore and contain only letters, digits or underscores. .Ss SECTION SEPARATORS The configuration consists of named sections. The MIB variable assignments in the section named .Dq snmpd are executed only during initial setup or when .Nm receives a SIGHUP. All other sections are executed when either a module with the same name as the section is loaded or .Nm receives a SIGHUP and that module is already loaded. The default section at the start of the configuration is .Dq snmpd . One can switch to another section with the syntax .Bd -unfilled -offset indent %secname .Ed .Pp Where .Ar secname is the name of the section. The same .Ar secname can be used in more than one place in the configuration. All of these parts are collected into one section. .Ss INCLUDE DIRECTIVES Another configuration file can be included into the current one with the include directive that takes one of two forms: .Bd -unfilled -offset indent \&.include "file" \&.include <"file"> .Ed .Pp The first form causes the file to be searched in the current directory, the second form causes the file to be searched in the directories specified in the system include path. Nesting depth is only restricted by available memory. .Ss MIB VARIABLE ASSIGNMENTS A MIB variable is assigned with the syntax .Bd -unfilled -offset indent oid [ suboids ] = value .Ed .Pp .Va oid is the name of the variable to be set. Only the last component of the entire name is used here. If the variable is a scalar, the index (.0) is automatically appended and need not to be specified. If the variable is a table column, the index .Pq Va suboids must be specified. The index consist of elements each separated from the previous one by a dot. Elements may be either numbers, strings or hostnames enclosed in [] brackets. If the element is a number it is appended to the current oid. If the element is a string, its length and the .Tn ASCII code of each of its characters are appended to the current oid. If the element is a hostname, the IP address of the host is looked up and the four elements of the IP address are appended to the oid. .Pp -For example a oid of +For example, an oid of .Bd -unfilled -offset indent myvariable.27.foooll.[localhost]."&^!" .Ed .Pp results in the oid .Bd -unfilled -offset indent myvariable.27.6.102.111.111.111.108.108.127.0.0.1.38.94.33 .Ed .Pp The value of the assignment may be either empty, a string or a number. If a string starts with a letter or an underscore and consists only of letters, digits, underscores and minus signs, it can be written without quotes. In all other cases the string must be enclosed in double quotes. .Sh SUBSTITUTIONS A variable substitution is written as .Bd -unfilled -offset indent $(variable) .Ed .Pp where .Ar variable is the name of the variable to substitute. Using an undefined variable is considered an error. .Sh FILES .Bl -tag -width ".It Pa /var/run/ Ns Ao Ar prefix Ac Ns \&.pid" -compact .It Pa /etc/ Ns Ao Ar prefix Ac Ns \&.config Default configuration file, where the default .Aq prefix is .Dq snmpd . .It Pa /var/run/ Ns Ao Ar prefix Ac Ns \&.pid Default pid file. .It Pa /etc:/usr/etc/:/usr/local/etc -This is the default search path for system include files. +Default search path for system include files. .It Pa @MIBSPATH@FOKUS-MIB.txt .It Pa @MIBSPATH@BEGEMOT-MIB.txt .It Pa @MIBSPATH@BEGEMOT-SNMPD.txt -The definitions for the MIBs implemented in the daemon. +Definitions for the MIBs implemented in the daemon. .It Pa /etc/hosts.allow, /etc/hosts.deny -Access controls that should be enforced by TCP wrappers should be defined here. +Access controls that should be enforced by TCP wrappers are defined here. Further details are described in .Xr hosts_access 5 . .El .Sh SEE ALSO .Xr gensnmptree 1 , .Xr hosts_access 5 .Sh STANDARDS The .Nm conforms to the applicable IETF RFCs. .Sh AUTHORS -.An Hartmut Brandt Aq harti@freebsd.org +.An Hartmut Brandt Aq harti@FreeBSD.org .Sh BUGS Sure. Index: stable/7/contrib/bsnmp/snmpd/snmpmod.3 =================================================================== --- stable/7/contrib/bsnmp/snmpd/snmpmod.3 (revision 211701) +++ stable/7/contrib/bsnmp/snmpd/snmpmod.3 (revision 211702) @@ -1,928 +1,929 @@ .\" .\" Copyright (c) 2004-2005 .\" Hartmut Brandt. .\" All rights reserved. .\" Copyright (c) 2001-2003 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" All rights reserved. .\" -.\" Author: Harti Brandt +.\" Author: Harti Brandt .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Begemot: bsnmp/snmpd/snmpmod.3,v 1.14 2005/10/04 13:30:35 brandt_h Exp $ .\" .Dd February 27, 2006 .Dt SNMPMOD 3 .Os .Sh NAME .Nm INSERT_OBJECT_OID_LINK_INDEX , .Nm INSERT_OBJECT_INT_LINK_INDEX , .Nm FIND_OBJECT_OID_LINK_INDEX , .Nm NEXT_OBJECT_OID_LINK_INDEX , .Nm FIND_OBJECT_INT_LINK_INDEX , .Nm NEXT_OBJECT_INT_LINK_INDEX , .Nm INSERT_OBJECT_OID_LINK , .Nm INSERT_OBJECT_INT_LINK , .Nm FIND_OBJECT_OID_LINK , .Nm NEXT_OBJECT_OID_LINK , .Nm FIND_OBJECT_INT_LINK , .Nm NEXT_OBJECT_INT_LINK , .Nm INSERT_OBJECT_OID , .Nm INSERT_OBJECT_INT , .Nm FIND_OBJECT_OID , .Nm FIND_OBJECT_INT , .Nm NEXT_OBJECT_OID , .Nm NEXT_OBJECT_INT , .Nm this_tick , .Nm start_tick , .Nm get_ticks , .Nm systemg , .Nm comm_define , .Nm community , .Nm oid_zeroDotZero , .Nm reqid_allocate , .Nm reqid_next , .Nm reqid_base , .Nm reqid_istype , .Nm reqid_type , .Nm timer_start , .Nm timer_start_repeat , .Nm timer_stop , .Nm fd_select , .Nm fd_deselect , .Nm fd_suspend , .Nm fd_resume , .Nm or_register , .Nm or_unregister , .Nm buf_alloc , .Nm buf_size , .Nm snmp_input_start , .Nm snmp_input_finish , .Nm snmp_output , .Nm snmp_send_port , .Nm snmp_send_trap , .Nm string_save , .Nm string_commit , .Nm string_rollback , .Nm string_get , .Nm string_get_max , .Nm string_free , .Nm ip_save , .Nm ip_rollback , .Nm ip_commit , .Nm ip_get , .Nm oid_save , .Nm oid_rollback , .Nm oid_commit , .Nm oid_get , .Nm index_decode , .Nm index_compare , .Nm index_compare_off , .Nm index_append , .Nm index_append_off .Nd "SNMP daemon loadable module interface" .Sh LIBRARY Begemot SNMP library .Pq libbsnmp, -lbsnmp .Sh SYNOPSIS .In bsnmp/snmpmod.h .Fn INSERT_OBJECT_OID_LINK_INDEX "PTR" "LIST" "LINK" "INDEX" .Fn INSERT_OBJECT_INT_LINK_INDEX "PTR" "LIST" "LINK" "INDEX" .Fn FIND_OBJECT_OID_LINK_INDEX "LIST" "OID" "SUB" "LINK" "INDEX" .Fn FIND_OBJECT_INT_LINK_INDEX "LIST" "OID" "SUB" "LINK" "INDEX" .Fn NEXT_OBJECT_OID_LINK_INDEX "LIST" "OID" "SUB" "LINK" "INDEX" .Fn NEXT_OBJECT_INT_LINK_INDEX "LIST" "OID" "SUB" "LINK" "INDEX" .Fn INSERT_OBJECT_OID_LINK "PTR" "LIST" "LINK" .Fn INSERT_OBJECT_INT_LINK "PTR" "LIST" "LINK" .Fn FIND_OBJECT_OID_LINK "LIST" "OID" "SUB" "LINK" .Fn FIND_OBJECT_INT_LINK "LIST" "OID" "SUB" "LINK" .Fn NEXT_OBJECT_OID_LINK "LIST" "OID" "SUB" "LINK" .Fn NEXT_OBJECT_INT_LINK "LIST" "OID" "SUB" "LINK" .Fn INSERT_OBJECT_OID "PTR" "LIST" .Fn INSERT_OBJECT_INT "PTR" "LIST" .Fn FIND_OBJECT_OID "LIST" "OID" "SUB" .Fn FIND_OBJECT_INT "LIST" "OID" "SUB" .Fn NEXT_OBJECT_OID "LIST" "OID" "SUB" .Fn NEXT_OBJECT_INT "LIST" "OID" "SUB" .Vt extern uint64_t this_tick ; .Vt extern uint64_t start_tick ; .Ft uint64_t .Fn get_ticks "void" .Vt extern struct systemg systemg ; .Ft u_int .Fn comm_define "u_int priv" "const char *descr" "struct lmodule *mod" "const char *str" .Ft const char * .Fn comm_string "u_int comm" .Vt extern u_int community ; .Vt extern const struct asn_oid oid_zeroDotZero ; .Ft u_int .Fn reqid_allocate "int size" "struct lmodule *mod" .Ft int32_t .Fn reqid_next "u_int type" .Ft int32_t .Fn reqid_base "u_int type" .Ft int .Fn reqid_istype "int32_t reqid" "u_int type" .Ft u_int .Fn reqid_type "int32_t reqid" .Ft void * .Fn timer_start "u_int ticks" "void (*func)(void *)" "void *uarg" "struct lmodule *mod" .Ft void * .Fn timer_start_repeat "u_int ticks" "u_int repeat_ticks" "void (*func)(void *)" "void *uarg" "struct lmodule *mod" .Ft void .Fn timer_stop "void *timer_id" .Ft void * .Fn fd_select "int fd" "void (*func)(int, void *)" "void *uarg" "struct lmodule *mod" .Ft void .Fn fd_deselect "void *fd_id" .Ft void .Fn fd_suspend "void *fd_id" .Ft int .Fn fd_resume "void *fd_id" .Ft u_int .Fn or_register "const struct asn_oid *oid" "const char *descr" "struct lmodule *mod" .Ft void .Fn or_unregister "u_int or_id" .Ft void * .Fn buf_alloc "int tx" .Ft size_t .Fn buf_size "int tx" .Ft enum snmpd_input_err .Fo snmp_input_start .Fa "const u_char *buf" "size_t len" "const char *source" .Fa "struct snmp_pdu *pdu" "int32_t *ip" "size_t *pdulen" .Fc .Ft enum snmpd_input_err .Fo snmp_input_finish .Fa "struct snmp_pdu *pdu" "const u_char *rcvbuf" .Fa "size_t rcvlen" "u_char *sndbuf" "size_t *sndlen" "const char *source" .Fa "enum snmpd_input_err ierr" "int32_t ip" "void *data" .Fc .Ft void .Fo snmp_output .Fa "struct snmp_pdu *pdu" "u_char *sndbuf" "size_t *sndlen" .Fa "const char *dest" .Fc .Ft void .Fo snmp_send_port .Fa "void *trans" "const struct asn_oid *port" .Fa "struct snmp_pdu *pdu" "const struct sockaddr *addr" "socklen_t addrlen" .Fc .Ft void .Fn snmp_send_trap "const struct asn_oid *oid" "..." .Ft int .Fn string_save "struct snmp_value *val" "struct snmp_context *ctx" "ssize_t req_size" "u_char **strp" .Ft void .Fn string_commit "struct snmp_context *ctx" .Ft void .Fn string_rollback "struct snmp_context *ctx" "u_char **strp" .Ft int .Fn string_get "struct snmp_value *val" "const u_char *str" "ssize_t len" .Ft int .Fn string_get_max "struct snmp_value *val" "const u_char *str" "ssize_t len" "size_t maxlen" .Ft void .Fn string_free "struct snmp_context *ctx" .Ft int .Fn ip_save "struct snmp_value *val" "struct snmp_context *ctx" "u_char *ipa" .Ft void .Fn ip_rollback "struct snmp_context *ctx" "u_char *ipa" .Ft void .Fn ip_commit "struct snmp_context *ctx" .Ft int .Fn ip_get "struct snmp_value *val" "u_char *ipa" .Ft int .Fn oid_save "struct snmp_value *val" "struct snmp_context *ctx" "struct asn_oid *oid" .Ft void .Fn oid_rollback "struct snmp_context *ctx" "struct asn_oid *oid" .Ft void .Fn oid_commit "struct snmp_context *ctx" .Ft int .Fn oid_get "struct snmp_value *val" "const struct asn_oid *oid" .Ft int .Fn index_decode "const struct asn_oid *oid" "u_int sub" "u_int code" "..." .Ft int .Fn index_compare "const struct asn_oid *oid1" "u_int sub" "const struct asn_oid *oid2" .Ft int .Fn index_compare_off "const struct asn_oid *oid1" "u_int sub" "const struct asn_oid *oid2" "u_int off" .Ft void .Fn index_append "struct asn_oid *dst" "u_int sub" "const struct asn_oid *src" .Ft void .Fn index_append_off "struct asn_oid *dst" "u_int sub" "const struct asn_oid *src" "u_int off" .Sh DESCRIPTION The .Xr bsnmpd 1 SNMP daemon implements a minimal MIB which consists of the system group, part of the SNMP MIB, a private configuration MIB, a trap destination table, a UDP port table, a community table, a module table, a statistics group and a debugging group. All other MIBs are support through loadable modules. This allows .Xr bsnmpd 1 to use for task, that are not the classical SNMP task. .Ss MODULE LOADING AND UNLOADING Modules are loaded by writing to the module table. This table is indexed by a string, that identifies the module to the daemon. This identifier is used to select the correct configuration section from the configuration files and to identify resources allocated to this module. A row in the module table is created by writing a string of non-zero length to the .Va begemotSnmpdModulePath column. This string must be the complete path to the file containing the module. A module can be unloaded by writing a zero length string to the path column of an existing row. .Pp Modules may depend on each other an hence must be loaded in the correct order. The dependencies are listed in the corresponding manual pages. .Pp Upon loading a module the SNMP daemon expects the module file to a export a global symbol .Va config . This symbol should be a variable of type .Vt struct snmp_module : .Bd -literal -offset indent typedef enum snmpd_proxy_err (*proxy_err_f)(struct snmp_pdu *, void *, const struct asn_oid *, const struct sockaddr *, socklen_t, enum snmpd_input_err, int32_t); struct snmp_module { const char *comment; int (*init)(struct lmodule *, int argc, char *argv[]); int (*fini)(void); void (*idle)(void); void (*dump)(void); void (*config)(void); void (*start)(void); proxy_err_f proxy; const struct snmp_node *tree; u_int tree_size; void (*loading)(const struct lmodule *, int); }; .Ed .Pp This structure must be statically initialized and its fields have the following functions: .Bl -tag -width ".It Va tree_size" .It Va comment This is a string that will be visible in the module table. It should give some hint about the function of this module. .It Va init This function is called upon loading the module. The module pointer should be stored by the module because it is needed in other calls and the argument vector will contain the arguments to this module from the daemons command line. This function should return 0 if everything is ok or an UNIX error code (see .Xr errno 3 ) . Once the function returns 0, the .Va fini function is called when the module is unloaded. .It Va fini The module is unloaded. This gives the module a chance to free resources that are not automatically freed. Be sure to free all memory, because daemons tend to run very long. This function pointer may be .Li NULL if it is not needed. .It Va idle If this function pointer is not .Li NULL , the function pointed to by it is called whenever the daemon is going to wait for an event. Try to avoid using this feature. .It Va dump Whenever the daemon receives a .Li SIGUSR1 it dumps it internal state via .Xr syslog 3 . If the .Va dump field is not .Li NULL it is called by the daemon to dump the state of the module. .It Va config Whenever the daemon receives a .Li SIGHUP signal it re-reads its configuration file. If the .Va config field is not .Li NULL it is called after reading the configuration file to give the module a chance to adapt to the new configuration. .It Va start If not .Li NULL this function is called after successful loading and initializing the module to start its actual operation. .It Va proxy If the daemon receives a PDU and that PDU has a community string whose community was registered by this module and .Va proxy is not .Li NULL than this function is called to handle the PDU. .It Va tree This is a pointer to the node array for the MIB tree implemented by this module. .It Va tree_size This is the number of nodes in .Va tree . .It Va loading If this pointer is not .Li NULL it is called whenever another module was loaded or unloaded. It gets a pointer to that module and a flag that is 0 for unloading and 1 for loading. .El .Pp When everything is ok, the daemon merges the module's MIB tree into its current global tree, calls the modules .Fn init function. If this function returns an error, the modules MIB tree is removed from the global one and the module is unloaded. If initialization is successful, the modules .Fn start function is called. After it returns the .Fn loaded functions of all modules (including the loaded one) are called. .Pp When the module is unloaded, its MIB tree is removed from the global one, the communities, request id ranges, running timers and selected file descriptors are released, the .Fn fini function is called, the module file is unloaded and the .Fn loaded functions of all other modules are called. .Ss IMPLEMENTING TABLES There are a number of macros designed to help implementing SNMP tables. A problem while implementing a table is the support for the GETNEXT operator. The GETNEXT operation has to find out whether, given an arbitrary OID, the lessest table row, that has an OID higher than the given OID. The easiest way to do this is to keep the table as an ordered list of structures each one of which contains an OID that is the index of the table row. This allows easy removal, insertion and search. .Pp The helper macros assume, that the table is organized as a TAILQ (see .Xr queue 3 and each structure contains a .Vt struct asn_oid that is used as index. For simple tables with only a integer or unsigned index, an alternate form of the macros is available, that presume the existence of an integer or unsigned field as index field. .Pp The macros have name of the form .Bd -literal -offset indent {INSERT,FIND,NEXT}_OBJECT_{OID,INT}[_LINK[_INDEX]] .Ed .Pp The .Fn INSERT_* macros are used in the SET operation to insert a new table row into the table. The .Fn FIND_* macros are used in the GET operation to find a specific row in the table. The .Fn NEXT_* macros are used in the GETNEXT operation to find the next row in the table. The last two macros return a pointer to the row structure if a row is found, .Li NULL otherwise. The macros .Fn *_OBJECT_OID_* assume the existence of a .Vt struct asn_oid that is used as index, the macros .Fn *_OBJECT_INT_* assume the existence of an unsigned integer field that is used as index. .Pp The macros .Fn *_INDEX allow the explicit naming of the index field in the parameter .Fa INDEX , whereas the other macros assume that this field is named .Va index . The macros .Fn *_LINK_* allow the explicit naming of the link field of the tail queues, the others assume that the link field is named .Va link . Explicitly naming the link field may be necessary if the same structures are held in two or more different tables. .Pp The arguments to the macros are as follows: .Bl -tag -width "INDEX" .It Fa PTR A pointer to the new structure to be inserted into the table. .It Fa LIST A pointer to the tail queue head. .It Fa LINK The name of the link field in the row structure. .It Fa INDEX The name of the index field in the row structure. .It Fa OID Must point to the .Va var field of the .Fa value argument to the node operation callback. This is the OID to search for. .It Fa SUB This is the index of the start of the table index in the OID pointed to by .Fa OID . This is usually the same as the .Fa sub argument to the node operation callback. .El .Ss DAEMON TIMESTAMPS The variable .Va this_tick contains the tick (there are 100 SNMP ticks in a second) when the current PDU processing was started. The variable .Va start_tick contains the tick when the daemon was started. The function .Fn get_ticks returns the current tick. The number of ticks since the daemon was started is .Bd -literal -offset indent get_ticks() - start_tick .Ed .Ss THE SYSTEM GROUP The scalar fields of the system group are held in the global variable .Va systemg : .Bd -literal -offset indent struct systemg { u_char *descr; struct asn_oid object_id; u_char *contact; u_char *name; u_char *location; uint32_t services; uint32_t or_last_change; }; .Ed .Ss COMMUNITIES The SNMP daemon implements a community table. On recipte of a request message the community string in that message is compared to each of the community strings in that table, if a match is found, the global variable .Va community is set to the community identifier for that community. Community identifiers are unsigned integers. For the three standard communities there are three constants defined: .Bd -literal -offset indent #define COMM_INITIALIZE 0 #define COMM_READ 1 #define COMM_WRITE 2 .Ed .Pp .Va community is set to .Li COMM_INITIALIZE while the assignments in the configuration file are processed. To .Li COMM_READ or .Li COMM_WRITE when the community strings for the read-write or read-only community are found in the incoming PDU. .Pp Modules can define additional communities. This may be necessary to provide transport proxying (a PDU received on one communication link is proxied to another link) or to implement non-UDP access points to SNMP. A new community is defined with the function .Fn comm_define . It takes the following parameters: .Bl -tag -width ".It Fa descr" .It Fa priv This is an integer identifying the community to the module. Each module has its own namespace with regard to this parameter. The community table is indexed with the module name and this identifier. .It Fa descr This is a string providing a human readable description of the community. It is visible in the community table. .It Fa mod This is the module defining the community. .It Fa str This is the initial community string. .El .Pp The function returns a globally unique community identifier. If a PDU is received who's community string matches, this identifier is set into the global .Va community . .Pp The function .Fn comm_string returns the current community string for the given community. .Pp All communities defined by a module are automatically released when the module is unloaded. .Ss WELL KNOWN OIDS The global variable .Va oid_zeroDotZero contains the OID 0.0. .Ss REQUEST ID RANGES For modules that implement SNMP client functions besides SNMP agent functions it may be necessary to identify SNMP requests by their identifier to allow easier routing of responses to the correct sub-system. Request id ranges -provide a way to aquire globally non-overlapping sub-ranges of the entire +provide a way to acquire globally non-overlapping sub-ranges of the entire 31-bit id range. .Pp A request id range is allocated with .Fn reqid_allocate . The arguments are: the size of the range and the module allocating the range. For example, the call .Bd -literal -offset indent id = reqid_allocate(1000, module); .Ed .Pp allocates a range of 1000 request ids. The function returns the request id range identifier or 0 if there is not enough identifier space. The function .Fn reqid_base returns the lowest request id in the given range. .Pp Request id are allocated starting at the lowest one linear throughout the range. If the client application may have a lot of outstanding request the range must be large enough so that an id is not reused until it is really expired. .Fn reqid_next returns the sequentially next id in the range. .Pp The function .Fn reqid_istype checks whether the request id .Fa reqid -is withing the range identified by +is within the range identified by .Fa type . The function .Fn reqid_type returns the range identifier for the given .Fa reqid or 0 if the request id is in none of the ranges. .Ss TIMERS The SNMP daemon supports an arbitrary number of timers with SNMP tick granularity. The function .Fn timer_start arranges for the callback .Fa func to be called with the argument .Fa uarg after .Fa ticks SNMP ticks have expired. .Fa mod is the module that starts the timer. These timers are one-shot, they are not restarted. Repeatable timers are started with .Fn timer_start_repeat which takes an additional argument .Fa repeat_ticks . The argument .Fa ticks gives the number of ticks until the first execution of the callback, while .Fa repeat_ticks is the number of ticks between invocations of the callback. Note, that currently the number of initial ticks silently may be set identical to the number of ticks between callback invocations. The function returns a timer identifier that can be used to stop the timer via .Fn timer_stop . If a module is unloaded all timers started by the module that have not expired yet are stopped. .Ss FILE DESCRIPTOR SUPPORT A module may need to get input from socket file descriptors without blocking the daemon (for example to implement alternative SNMP transports). .Pp The function .Fn fd_select causes the callback function .Fa func to be called with the file descriptor .Fa fd and the user argument .Fa uarg whenever the file descriptor .Fa fd can be read or has a close condition. If the file descriptor is not in non-blocking mode, it is set to non-blocking mode. If the callback is not needed anymore, .Fn fd_deselect may be called with the value returned from .Fn fd_select . All file descriptors selected by a module are automatically deselected when the module is unloaded. .Pp To temporarily suspend the file descriptor registration .Fn fd_suspend can be called. This also causes the file descriptor to be switched back to blocking mode if it was blocking prior the call to .Fn fd_select . This is necessary to do synchronous input on a selected socket. The effect of .Fn fd_suspend can be undone with .Fn fd_resume . .Ss OBJECT RESOURCES The system group contains an object resource table. A module may create an entry in this table by calling .Fn or_register with the .Fa oid to be registered, a textual description in .Fa str and a pointer to the module .Fa mod . The registration can be removed with .Fn or_unregister . All registrations of a module are automatically removed if the module is unloaded. .Ss TRANSMIT AND RECEIVE BUFFERS A buffer is allocated via .Fn buf_alloc . The argument must be 1 for transmit and 0 for receive buffers. The function may return .Li NULL if there is no memory available. The current buffersize can be obtained with .Fn buf_size . .Sh PROCESSING PDUS For modules that need to do their own PDU processing (for example for proxying) the following functions are available: .Pp Function .Fn snmp_input_start decodes the PDU, searches the community, and sets the global .Va this_tick . It returns one of the following error codes: .Bl -tag -width ".It Er SNMPD_INPUT_VALBADLEN" .It Er SNMPD_INPUT_OK Everything ok, continue with processing. .It Er SNMPD_INPUT_FAILED The PDU could not be decoded, has a wrong version or an unknown community string. .It Er SNMPD_INPUT_VALBADLEN A SET PDU had a value field in a binding with a wrong length field in an ASN.1 header. .It Er SNMPD_INPUT_VALRANGE A SET PDU had a value field in a binding with a value that is out of range for the given ASN.1 type. .It Er SNMPD_INPUT_VALBADENC A SET PDU had a value field in a binding with wrong ASN.1 encoding. .It Er SNMPD_INPUT_TRUNC The buffer appears to contain a valid begin of a PDU, but is too short. For streaming transports this means that the caller must save what he already has and trying to obtain more input and reissue this input to the function. For datagram transports this means that part of the datagram was lost and the input should be ignored. .El .Pp The function .Fn snmp_input_finish does the other half of processing: if .Fn snmp_input_start did not return OK, tries to construct an error response. If the start was OK, it calls the correct function from .Xr bsnmpagent 3 to execute the request and depending on the outcome constructs a response or error response PDU or ignores the request PDU. It returns either .Er SNMPD_INPUT_OK or .Er SNMPD_INPUT_FAILED . In the first case a response PDU was constructed and should be sent. .Pp The function .Fn snmp_output takes a PDU and encodes it. .Pp The function .Fn snmp_send_port takes a PDU, encodes it and sends it through the given port (identified by the transport and the index in the port table) to the given address. .Pp The function .Fn snmp_send_trap sends a trap to all trap destinations. The arguments are the .Fa oid identifying the trap and a NULL-terminated list of .Vt struct snmp_value pointers that are to be inserted into the trap binding list. .Ss SIMPLE ACTION SUPPORT For simple scalar variables that need no dependencies a number of support functions is available to handle the set, commit, rollback and get. .Pp The following functions are used for OCTET STRING scalars, either NUL terminated or not: .Bl -tag -width "XXXXXXXXX" .It Fn string_save should be called for SNMP_OP_SET. .Fa value and .Fa ctx are the resp\&.\& arguments to the node callback. .Fa valp is a pointer to the pointer that holds the current value and .Fa req_size should be -1 if any size of the string is acceptable or a number larger or equal zero if the string must have a specific size. The function saves the old value in the scratch area (note, that any initial value must have been allocated by .Xr malloc 3 ) , allocates a new string, copies over the new value, NUL-terminates it and sets the new current value. .It Fn string_commit simply frees the saved old value in the scratch area. .It Fn string_rollback frees the new value, and puts back the old one. .It Fn string_get is used for GET or GETNEXT. The function .It Fn string_get_max can be used instead of -.Nf stringto ensure that the returned string has a certain maximum length. +.Fn string_get +to ensure that the returned string has a certain maximum length. If .Fa len is -1, the length is computed via .Xr strlen 3 from the current string value. If the current value is NULL, a OCTET STRING of zero length is returned. .It Fn string_free must be called if either rollback or commit fails to free the saved old value. .El .Pp The following functions are used to process scalars of type IP-address: .Bl -tag -width "XXXXXXXXX" .It Fn ip_save Saves the current value in the scratch area and sets the new value from .Fa valp . .It Fn ip_commit Does nothing. .It Fn ip_rollback Restores the old IP address from the scratch area. .It Fn ip_get Retrieves the IP current address. .El .Pp The following functions handle OID-typed variables: .Bl -tag -width "XXXXXXXXX" .It Fn oid_save Saves the current value in the scratch area by allocating a .Vt struct asn_oid with .Xr malloc 3 and sets the new value from .Fa oid . .It Fn oid_commit Frees the old value in the scratch area. .It Fn oid_rollback Restores the old OID from the scratch area and frees the old OID. .It Fn oid_get Retrieves the OID .El .Ss TABLE INDEX HANDLING The following functions help in handling table indexes: .Bl -tag -width "XXXXXXXXX" .It Fn index_decode Decodes the index part of the OID. The parameter .Fa oid must be a pointer to the .Va var field of the .Fa value argument of the node callback. The .Fa sub argument must be the index of the start of the index in the OID (this is the .Fa sub argument to the node callback). .Fa code is the index expression (parameter .Fa idx to the node callback). These parameters are followed by parameters depending on the syntax of the index elements as follows: .Bl -tag -width ".It Li OCTET STRING" .It Li INTEGER .Vt int32_t * expected as argument. .It Li COUNTER64 .Vt uint64_t * expected as argument. Note, that this syntax is illegal for indexes. .It Li OCTET STRING A .Vt u_char ** and a .Vt size_t * expected as arguments. A buffer is allocated to hold the decoded string. .It Li OID A .Vt struct asn_oid * is expected as argument. .It Li IP ADDRESS A .Vt u_int8_t * expected as argument that points to a buffer of at least four byte. .It Li COUNTER, GAUGE, TIMETICKS A .Vt u_int32_t expected. .It Li NULL No argument expected. .El .It Fn index_compare compares the current variable with an OID. .Fa oid1 and .Fa sub come from the node callback arguments .Fa value->var and .Fa sub resp. .Fa oid2 is the OID to compare to. The function returns -1, 0, +1 when the variable is lesser, equal, higher to the given OID. .Fa oid2 must contain only the index part of the table column. .It Fn index_compare_off is equivalent to .Fn index_compare except that it takes an additional parameter .Fa off that causes it to ignore the first .Fa off components of both indexes. .It Fn index_append appends OID .Fa src beginning at position .Fa sub to .Fa dst . .It Fn index_append_off appends OID .Fa src beginning at position .Fa off to .Fa dst beginning at position .Fa sub + .Fa off . .El .Sh SEE ALSO .Xr gensnmptree 1 , .Xr bsnmpd 1 , .Xr bsnmpagent 3 , .Xr bsnmpclient 3 , .Xr bsnmplib 3 .Sh STANDARDS This implementation conforms to the applicable IETF RFCs and ITU-T recommendations. .Sh AUTHORS -.An Hartmut Brandt Aq harti@freebsd.org +.An Hartmut Brandt Aq harti@FreeBSD.org Index: stable/7/contrib/bsnmp =================================================================== --- stable/7/contrib/bsnmp (revision 211701) +++ stable/7/contrib/bsnmp (revision 211702) Property changes on: stable/7/contrib/bsnmp ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/contrib/bsnmp:r205078,208483,211401-211402,211404 Index: stable/8/contrib/bsnmp/gensnmpdef/gensnmpdef.1 =================================================================== --- stable/8/contrib/bsnmp/gensnmpdef/gensnmpdef.1 (revision 211701) +++ stable/8/contrib/bsnmp/gensnmpdef/gensnmpdef.1 (revision 211702) @@ -1,85 +1,85 @@ .\" .\" Copyright (C) 2004-2006 .\" Hartmut Brandt. .\" All rights reserved. .\" -.\" Author: Harti Brandt +.\" Author: Harti Brandt .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Begemot: gensnmpdef.1 383 2006-05-30 07:40:49Z brandt_h $ .\" .Dd May 28, 2006 .Dt GENSNMPDEF 1 .Os .Sh NAME .Nm gensnmpdef .Nd "generate a MIB description file from MIBs" .Sh SYNOPSIS .Nm .Op Fl hEe .Op Fl c Ar cut .Ar name Op Ar ... .Sh DESCRIPTION The .Nm utility is used to create an initial MIB description file from one or more MIBs. The description file must be edited to be actually useful for feeding it into .Xr gensnmptree 1 . .Pp The following options are available: .Bl -tag -width indent .It Fl c Ar cut Specify the number of initial sub-oids that should be omitted from the tree in the output. .Xr gensnmptree 1 automatically adds 1.3.6 in front of all OIDs so the default value of 3 is just correct in most cases. .It Fl E Generate typedefs for named enumerations. These are enumerations defined via the TEXTUAL-CONVENTION macro. The normal tree output is suppressed. .It Fl e Generate typedefs for unnamed enumerations. These are enumerations defined in the SYNTAX clause of an OBJECT-TYPE macro. The name of the enumeration is formed by appending the string .Ql Type to the name of the object. The normal tree output is suppressed. .It Fl h Print a short help text and exit. .El .Pp .Nm does no attempt on sorting the OID tree so in case of complex and non-standard MIBs it is necessary to sort the tree in the resulting definition file by hand. .Sh SEE ALSO .Xr snmpd 1 .Sh AUTHORS -.An Hartmut Brandt Aq harti@freebsd.org +.An Hartmut Brandt Aq harti@FreeBSD.org .Sh BUGS The utility is by no means bullet-proof and may fail for complex or non-standard MIBs. Its output is expected to be edited by hand. Index: stable/8/contrib/bsnmp/gensnmptree/gensnmptree.1 =================================================================== --- stable/8/contrib/bsnmp/gensnmptree/gensnmptree.1 (revision 211701) +++ stable/8/contrib/bsnmp/gensnmptree/gensnmptree.1 (revision 211702) @@ -1,246 +1,246 @@ .\" .\" Copyright (c) 2001-2005 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" All rights reserved. .\" Copyright (c) 2006 .\" Hartmut Brandt .\" All rights reserved. .\" -.\" Author: Harti Brandt +.\" Author: Harti Brandt .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Begemot: gensnmptree.1 383 2006-05-30 07:40:49Z brandt_h $ .\" .Dd May 26, 2006 .Dt GENSNMPTREE 1 .Os .Sh NAME .Nm gensnmptree .Nd "generate C and header files from a MIB description file" .Sh SYNOPSIS .Nm .Op Fl dEehlt .Op Fl I Ar directory .Op Fl i Ar infile .Op Fl p Ar prefix .Op Ar name Ar ... .Sh DESCRIPTION The .Nm utility is used to either generate C language tables and header files from a MIB description or to numeric OIDs from MIB descriptions. The first form is used only for maintaining the .Xr bsnmpd 1 daemon or for module writers. The second form may be used by SNMP client program writers. .Pp If none of the options .Fl e , .Fl E or -.FL t +.Fl t are used .Nm reads a MIB description from its standard input and creates two files: a C-file .Ar prefix Ns tree.c containing a table used by .Xr bsnmpd 1 during PDU processing and a header file .Ar prefix Ns tree.h containing appropriate declarations of the callback functions used in this table, the table itself and definitions for all enums. .Pp The following options are available: .Bl -tag -width ".Fl E" .It Fl d Switch on debugging. .It Fl E Extract enumerations and bit constructs. In this mode the tool emits a header file that contains for each type given on the command line a C-enum definition and a preprocessor define that may be used to map values to strings. .It Fl e .Nm expects MIB variable names (only the last component) on its command line. It reads a MIB specification from standard input and for each MIB variable name emits three C preprocessor defines on its standard output: .Bl -tag -width ".Va OIDLEN_ Ns Ar Name" .It Va OIDX_ Ns Ar name This define can be used to initialize a .Va struct asn_oid in the following way: .Pp .Dl const struct asn_oid oid_sysDescr = OIDX_sysDescr; .It Va OIDLEN_ Ns Ar name is the length of the OID. .It Va OID_ Ns Ar name is the last component of the OID. .El .It Fl h Print a short help page. .It Fl I Ar directory Add the named directory to the include path just before the standard include directories. .It Fl i Ar infile Read from the named file instead of standard input. .It Fl l Generate local preprocessor includes. This is used for bootstrapping .Xr bsnmpd 1 . .It Fl t Instead of normal output print the resulting tree. .It Fl p Ar prefix Prefix the file names and the table name with .Ar prefix . .El .Sh MIBS The syntax of the MIB description file can formally be specified as follows: .Bd -unfilled -offset indent file := top | top file top := tree | typedef | include tree := head elements ')' entry := head ':' index STRING elements ')' leaf := head type STRING ACCESS ')' column := head type ACCESS ')' type := BASETYPE | BASETYPE '|' subtype | enum | bits subtype := STRING enum := ENUM '(' value ')' bits := BITS '(' value ')' value := INT STRING | INT STRING value head := '(' INT STRING elements := EMPTY | elements element element := tree | leaf | column index := type | index type typedef := 'typedef' STRING type include := 'include' filespec filespec := '"' STRING '"' | '<' STRING '>' .Ed .Pp .Ar BASETYPE specifies a SNMP data type and may be one of .Bl -bullet -offset indent -compact .It NULL .It INTEGER .It INTEGER32 (same as INTEGER) .It UNSIGNED32 (same as GAUGE) .It OCTETSTRING .It IPADDRESS .It OID .It TIMETICKS .It COUNTER .It GAUGE .It COUNTER64 .El .Pp .Ar ACCESS specifies the accessibility of the MIB variable (which operation can be performed) and is one of .Bl -bullet -offset indent -compact .It GET .It SET .El .Pp .Ar INT is a decimal integer and .Ar STRING is any string starting with a letter or underscore and consisting of letters, digits, underscores and minuses, that is not one of the keywords. .Pp The .Ar typedef directive associates a type with a single name. .Pp The .Ar include directive is replaced by the contents of the named file. .Sh EXAMPLES The following MIB description describes the system group: .Bd -literal -offset indent include "tc.def" typedef AdminStatus ENUM ( 1 up 2 down ) (1 internet (2 mgmt (1 mibII (1 system (1 sysDescr OCTETSTRING op_system_group GET) (2 sysObjectId OID op_system_group GET) (3 sysUpTime TIMETICKS op_system_group GET) (4 sysContact OCTETSTRING op_system_group GET SET) (5 sysName OCTETSTRING op_system_group GET SET) (6 sysLocation OCTETSTRING op_system_group GET SET) (7 sysServices INTEGER op_system_group GET) (8 sysORLastChange TIMETICKS op_system_group GET) (9 sysORTable (1 sysOREntry : INTEGER op_or_table (1 sysORIndex INTEGER) (2 sysORID OID GET) (3 sysORDescr OCTETSTRING GET) (4 sysORUpTime TIMETICKS GET) )) ) ) ) ) .Ed .Sh SEE ALSO .Xr bsnmpd 1 .Sh AUTHORS -.An Hartmut Brandt Aq harti@freebsd.org +.An Hartmut Brandt Aq harti@FreeBSD.org Index: stable/8/contrib/bsnmp/lib/asn1.3 =================================================================== --- stable/8/contrib/bsnmp/lib/asn1.3 (revision 211701) +++ stable/8/contrib/bsnmp/lib/asn1.3 (revision 211702) @@ -1,492 +1,492 @@ .\" .\" Copyright (c) 2004-2005 .\" Hartmut Brandt. .\" All rights reserved. .\" Copyright (c) 2001-2003 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" All rights reserved. .\" -.\" Author: Harti Brandt +.\" Author: Harti Brandt .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Begemot: bsnmp/lib/asn1.3,v 1.9 2005/10/04 08:46:49 brandt_h Exp $ .\" .Dd October 4, 2005 .Dt ASN1 3 .Os .Sh NAME .Nm asn_get_header , .Nm asn_put_header , .Nm asn_put_temp_header , .Nm asn_commit_header , .Nm asn_get_integer_raw , .Nm asn_get_integer , .Nm asn_put_integer , .Nm asn_get_octetstring_raw , .Nm asn_get_octetstring , .Nm asn_put_octetstring , .Nm asn_get_null_raw , .Nm asn_get_null , .Nm asn_put_null , .Nm asn_put_exception , .Nm asn_get_objid_raw , .Nm asn_get_objid , .Nm asn_put_objid , .Nm asn_get_sequence , .Nm asn_get_ipaddress_raw , .Nm asn_get_ipaddress , .Nm asn_put_ipaddress , .Nm asn_get_uint32_raw , .Nm asn_put_uint32 , .Nm asn_get_counter64_raw , .Nm asn_put_counter64 , .Nm asn_get_timeticks , .Nm asn_put_timeticks , .Nm asn_skip , .Nm asn_slice_oid , .Nm asn_append_oid , .Nm asn_compare_oid , .Nm asn_is_suboid , .Nm asn_oid2str_r , .Nm asn_oid2str .Nd "ASN.1 library for SNMP" .Sh LIBRARY Begemot SNMP library .Pq libbsnmp, -lbsnmp .Sh SYNOPSIS .In bsnmp/asn1.h .Ft enum asn_err .Fn asn_get_header "struct asn_buf *buf" "u_char *type" "asn_len_t *lenp" .Ft enum asn_err .Fn asn_put_header "struct asn_buf *buf" "u_char type" "asn_len_t len" .Ft enum asn_err .Fn asn_put_temp_header "struct asn_buf *buf" "u_char type" "u_char **ptr" .Ft enum asn_err .Fn asn_commit_header "struct asn_buf *buf" "u_char *ptr" .Ft enum asn_err .Fn asn_get_integer_raw "struct asn_buf *buf" "asn_len_t len" "int32_t *res" .Ft enum asn_err .Fn asn_get_integer "struct asn_buf *buf" "int32_t *res" .Ft enum asn_err .Fn asn_put_integer "struct asn_buf *buf" "int32_t arg" .Ft enum asn_err .Fn asn_get_octetstring_raw "struct asn_buf *buf" "asn_len_t len" "u_char *out" "u_int *outsize" .Ft enum asn_err .Fn asn_get_octetstring "struct asn_buf *buf" "u_char *out" "u_int *outsize" .Ft enum asn_err .Fn asn_put_octetstring "struct asn_buf *buf" "const u_char *str" "u_int strsize" .Ft enum asn_err .Fn asn_get_null_raw "struct asn_buf *buf" "asn_len_t len" .Ft enum asn_err .Fn asn_get_null "struct asn_buf *buf" .Ft enum asn_err .Fn asn_put_null "struct asn_buf *buf" .Ft enum asn_err .Fn asn_put_exception "struct asn_buf *buf" "u_int type" .Ft enum asn_err .Fn asn_get_objid_raw "struct asn_buf *buf" "asn_len_t len" "struct asn_oid *oid" .Ft enum asn_err .Fn asn_get_objid "struct asn_buf *buf" "struct asn_oid *oid" .Ft enum asn_err .Fn asn_put_objid "struct asn_buf *buf" "const struct asn_oid *oid" .Ft enum asn_err .Fn asn_get_sequence "struct asn_buf *buf" "asn_len_t *lenp" .Ft enum asn_err .Fn asn_get_ipaddress_raw "struct asn_buf *buf" "asn_len_t len" "u_char *ipa" .Ft enum asn_err .Fn asn_get_ipaddress "struct asn_buf *buf" "u_char *ipa" .Ft enum asn_err .Fn asn_put_ipaddress "struct asn_buf *buf" "const u_char *ipa" .Ft enum asn_err .Fn asn_get_uint32_raw "struct asn_buf *buf" "asn_len_t len" "u_int32_t *res" .Ft enum asn_err .Fn asn_put_uint32 "struct asn_buf *buf" "u_char type" "u_int32_t val" .Ft enum asn_err .Fn asn_get_counter64_raw "struct asn_buf *buf" "asn_len_t len" "u_int64_t *res" .Ft enum asn_err .Fn asn_put_counter64 "struct asn_buf *buf" "u_int64_t val" .Ft enum asn_err .Fn asn_get_timeticks "struct asn_buf *buf" "u_int32_t *valp" .Ft enum asn_err .Fn asn_put_timeticks "struct asn_buf *buf" "u_int32_t val" .Ft enum asn_err .Fn asn_skip "struct asn_buf *buf" "asn_len_t len" .Ft void .Fn asn_slice_oid "struct asn_oid *dest" "const struct asn_oid *src" "u_int from" "u_int to" .Ft void .Fn asn_append_oid "struct asn_oid *to" "const struct asn_oid *from" .Ft int .Fn asn_compare_oid "const struct asn_oid *oid1" "const struct asn_oid *oid2" .Ft int .Fn asn_is_suboid "const struct asn_oid *oid1" "const struct asn_oid *oid2" .Ft char * .Fn asn_oid2str_r "const struct asn_oid *oid" "char *buf" .Ft char * .Fn asn_oid2str "const struct asn_oid *oid" .Sh DESCRIPTION The ASN.1 library contains routines to handle ASN.1 encoding for SNMP. It supports only the restricted form of ASN.1 as required by SNMP. There are two basic structures used throughout the library: .Bd -literal -offset indent /* these restrictions are in the SMI */ #define ASN_MAXID 0xffffffff #define ASN_MAXOIDLEN 128 /* type of subidentifiers */ typedef u_int32_t asn_subid_t; struct asn_oid { u_int len; asn_subid_t subs[ASN_MAXOIDLEN]; }; .Ed .Pp This structure represents an OID with the restrictions defined in the SNMP SMI. .Fa len holds the current length of the OID and .Fa subs holds the elements of the OID. .Bd -literal -offset indent struct asn_buf { union { u_char *ptr; const u_char *cptr; } asn_u; size_t asn_len; }; #define asn_cptr asn_u.cptr #define asn_ptr asn_u.ptr .Ed .Pp This structure is used to encode and decode ASN.1. It describes the output buffer for encoding routines and the input buffer for decoding routines. For encoding .Fa asn_len holds the number of remaining free octets in the buffer. The first free byte is pointed to by .Fa asn_ptr . For decoding .Fa asn_len holds the number of remaining bytes to decode. The next byte to decode is pointed to by .Fa asn_cptr . .Pp Most of the functions return an error code .Fa "enum asn_error" : .Bd -literal -offset indent enum asn_err { /* conversion was ok */ ASN_ERR_OK = 0, /* conversion failed and stopped */ ASN_ERR_FAILED = 1 | 0x1000, /* length field bad, value skipped */ ASN_ERR_BADLEN = 2, /* out of buffer, stopped */ ASN_ERR_EOBUF = 3 | 0x1000, /* length ok, but value is out of range */ ASN_ERR_RANGE = 4, /* not the expected tag, stopped */ ASN_ERR_TAG = 5 | 0x1000, }; #define ASN_ERR_STOPPED(E) (((E) & 0x1000) != 0) .Ed .Pp If .Fn ASN_ERR_STOPPED returns true, the error was fatal and processing has stopped at the point of error. .Pp The function .Fn asn_get_header reads the next header from the input octet stream. It returns the tag in the variable pointed to by .Fa type (note that only single byte tags are supported) and the decoded length field in the value pointed to by .Fa lenp (this is restricted to a unsigned 32-bit value). All errors in this function are fatal and stop processing. .Pp The function .Fn asn_put_header writes an ASN.1 header. .Fa type is the tag to write and is restricted to one byte tags (i.e., tags lesser or equal than 0x30). .Fa len is the length of the value and is restricted to 16-bit. .Pp The functions .Fn asn_put_temp_header and .Fn asn_commit_header are used to write a header when the length of the value is not known in advance, for example, for sequences. .Fn asn_put_temp_header writes a header with the given tag .Fa type and space for the maximum supported length field and sets the pointer pointed to by .Fa ptr to the begin of this length field. This pointer must then be fed into .Fn asn_commit_header directly after writing the value to the buffer. The function will compute the length, insert it into the right place and shift the value if the resulting length field is shorter than the estimated one. .Pp The function .Fn asn_get_integer_raw is used to decode a signed integer value (32-bit). It assumes, that the header of the integer has been decoded already. .Fa len is the length obtained from the ASN.1 header and the integer will be returned in the value pointed to by .Fa res . .Pp The function .Fn asn_get_integer decodes a complete 32-bit signed integer including the header. If the tag is wrong .Li ASN_ERR_TAG is returned. The function .Fn asn_put_integer encodes a 32-bit signed integer. .Pp The function .Fn asn_get_octetstring_raw decodes the value field of an ASN.1 octet string. The length obtained from the header must be fed into the .Fa len argument and .Fa out must point to a buffer to receive the octet string. On entry to the function .Fa outsize must point to the size of the buffer. On exit .Fa outsize will point to the number of octets decoded (if no error occurs this will be equal to .Fa len ). The function .Fn asn_get_octetstring decodes an octetstring including the header. .Fa out must point to a buffer to receive the string, .Fa outsize must point to the size of the buffer. On exit of the function .Fa outsize will point to the number of octets decoded. The function .Fn asn_put_octetstring encodes an octetstring (including the header). .Fa str points to the string to encode and .Fa strsize is the length of the string (the string may contain embedded .Li NUL Ns s). .Pp The function .Fn asn_get_null_raw decodes a null value. .Fa len is the length obtained from the header and must be 0. The function .Fn asn_get_null decodes a null including the header and the function .Fn asn_put_null encodes a null. .Pp The function .Fn asn_put_exception is used to encode an SNMPv2 exception. The exception type is .Fa type . .Pp The function .Fn asn_get_objid_raw is used to decode an OID value. .Fa len must be the value length obtained from the header and .Fa oid will receive the decoded OID. The function .Fn asn_get_objid decodes a complete OID (including the header) and the function .Fn asn_put_objid encodes a complete OID. .Pp The function .Fn asn_get_sequence decodes a sequence header. The length of the sequence value will be stored in the value pointed to by .Fa lenp . .Pp The function .Fn asn_get_ipaddress_raw decodes an IP address value. .Fa len is the length from the header and must be 4. .Fa ipa will receive the decoded IP address and must point to a buffer of at least four bytes. The function .Fn asn_get_ipaddress decodes a complete IP address (including the header) and .Fn asn_put_ipaddress encodes an IP address. .Pp The function .Fn asn_get_uint32_raw decodes an unsigned 32-bit integer value. .Fa len is the length from the header and .Fa res will get the decoded value. The function .Fn asn_put_uint32 encodes an unsigned 32-bit integer value and inserts the tag given in .Fa type into the header. .Pp The function .Fn asn_get_counter64_raw decodes an unsigned 64-bit integer value. .Fa len must be the value length from the header. The resulting value is stored into the variable pointed to by .Fa res . The function .Fn asn_put_counter64 encodes a complete unsigned 64-bit value. .Pp The function .Fn asn_get_timeticks decodes an ASN.1 object of type .Li TIMETICKS and the function .Fn asn_put_timeticks encodes such an object. .Pp The function .Fn asn_skip can be used to skip .Fa len bytes in the input buffer. .Pp The function .Fn asn_slice_oid splits a part out from an OID. It takes all the subids from the OID pointed to by .Fa src starting with the subid at position .Fa from (the first subid being subid 0) up to, but not including, subid .Fa to and generates a new OID in .Fa dest . If .Fa to is less or equal to .Fa from the resulting OID will have a length of zero. .Pp The function .Fn asn_append_oid appends the OID .Fa from to the OID .Fa to given that the resulting OID is not too long. If the maximum length is exceeded the result is undefined. .Pp The function .Fn asn_compare_oid compares two oids and returns the values .Li -1 , .Li 0 or .Li +1 when .Fa oid1 is lesser than, equal, or larger than .Fa oid2 resp. .Pp The function .Fn asn_is_suboid returns 1 if .Fa oid1 is equal to the leading part of .Fa oid2 . It returns 0 otherwise. .Pp The function .Fn asn_oid2str_r makes a printable string from .Fa oid . The buffer pointed to by .Fa str must be large enough to hold the result. The constant .Li ASN_OIDSTRLEN is defined to be the length of the maximum string generated by this function (including the trailing NUL). The function .Fn asn_oid2str makes a printable string from .Fa oid into a private buffer that is overwritten by each call. .Sh DIAGNOSTICS When an error occurs in any of the function the function pointed to by the global pointer .Bd -literal -offset indent extern void (*asn_error)(const struct asn_buf *, const char *, ...); .Ed .Pp is called with the current buffer (this may be .Li NULL ) and a .Xr printf 3 style format string. There is a default error handler in the library that prints a message starting with .Sq ASN.1: followed by the error message and an optional dump of the buffer. .Sh SEE ALSO .Xr gensnmptree 1 , .Xr bsnmpd 1 , .Xr bsnmpagent 3 , .Xr bsnmpclient 3 , .Xr bsnmplib 3 .Sh STANDARDS This implementation conforms to the applicable IETF RFCs and ITU-T recommendations. .Sh AUTHORS -.An Hartmut Brandt Aq harti@freebsd.org +.An Hartmut Brandt Aq harti@FreeBSD.org Index: stable/8/contrib/bsnmp/lib/bsnmpagent.3 =================================================================== --- stable/8/contrib/bsnmp/lib/bsnmpagent.3 (revision 211701) +++ stable/8/contrib/bsnmp/lib/bsnmpagent.3 (revision 211702) @@ -1,444 +1,444 @@ .\" .\" Copyright (c) 2004-2005 .\" Hartmut Brandt. .\" All rights reserved. .\" Copyright (c) 2001-2003 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" All rights reserved. .\" -.\" Author: Harti Brandt +.\" Author: Harti Brandt .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Begemot: bsnmp/lib/bsnmpagent.3,v 1.10 2005/10/04 08:46:49 brandt_h Exp $ .\" .Dd October 4, 2005 .Dt BSNMPAGENT 3 .Os .Sh NAME .Nm bsnmpagent , .Nm snmp_depop_t , .Nm snmp_op_t , .Nm tree , .Nm tree_size , .Nm snmp_trace , .Nm snmp_debug , .Nm snmp_get , .Nm snmp_getnext , .Nm snmp_getbulk , .Nm snmp_set , .Nm snmp_make_errresp , .Nm snmp_dep_lookup , .Nm snmp_init_context , .Nm snmp_dep_commit , .Nm snmp_dep_rollback , .Nm snmp_dep_finish .Nd "SNMP agent library" .Sh LIBRARY Begemot SNMP library .Pq libbsnmp, -lbsnmp .Sh SYNOPSIS .In asn1.h .In snmp.h .In snmpagent.h .Ft typedef int .Fn (*snmp_depop_t) "struct snmp_context *ctx" "struct snmp_dependency *dep" "enum snmp_depop op" .Ft typedef int .Fn (*snmp_op_t) "struct snmp_context *ctx" "struct snmp_value *val" "u_int len" "u_int idx" "enum snmp_op op" .Vt extern struct snmp_node *tree ; .Vt extern u_int tree_size ; .Vt extern u_int snmp_trace ; .Vt extern void (*snmp_debug)(const char *fmt, ...) ; .Ft enum snmp_ret .Fn snmp_get "struct snmp_pdu *pdu" "struct asn_buf *resp_b" "struct snmp_pdu *resp" "void *data" .Ft enum snmp_ret .Fn snmp_getnext "struct snmp_pdu *pdu" "struct asn_buf *resp_b" "struct snmp_pdu *resp" "void *data" .Ft enum snmp_ret .Fn snmp_getbulk "struct snmp_pdu *pdu" "struct asn_buf *resp_b" "struct snmp_pdu *resp" "void *data" .Ft enum snmp_ret .Fn snmp_set "struct snmp_pdu *pdu" "struct asn_buf *resp_b" "struct snmp_pdu *resp" "void *data" .Ft enum snmp_ret .Fn snmp_make_errresp "const struct snmp_pdu *pdu" "struct asn_buf *req_b" "struct asn_buf *resp_b" .Ft struct snmp_dependency * .Fn snmp_dep_lookup "struct snmp_context *ctx" "const struct asn_oid *base" "const struct asn_oid *idx" "size_t alloc" "snmp_depop_t func" .Ft struct snmp_context * .Fn snmp_init_context "void" .Ft int .Fn snmp_dep_commit "struct snmp_context *ctx" .Ft int .Fn snmp_dep_rollback "struct snmp_context *ctx" .Ft void .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 bsnmpd 1 loadable module, that handles the new MIB (see .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: .Bd -literal -offset indent extern struct snmp_node *tree; extern u_int tree_size; .Ed .Pp The elements of the array are of type .Vt struct snmp_node : .Bd -literal -offset indent typedef int (*snmp_op_t)(struct snmp_context *, struct snmp_value *, u_int, u_int, enum snmp_op); struct snmp_node { struct asn_oid oid; const char *name; /* name of the leaf */ enum snmp_node_type type; /* type of this node */ enum snmp_syntax syntax; snmp_op_t op; u_int flags; u_int32_t index; /* index data */ void *data; /* application data */ void *tree_data; /* application data */ }; .Ed .Pp The fields of this structure are described below. .Bl -tag -width "syntax" .It Va oid Base OID of the scalar or table column. .It Va name Name of this variable. .It Va type Type of this variable. One of: .Bd -literal -offset indent enum snmp_node_type { SNMP_NODE_LEAF = 1, SNMP_NODE_COLUMN }; .Ed .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: .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 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 function must return .Li SNMP_ERR_NOSUCHNAME . For all other operations the oid in .Fa val is the oid to fetch or set. .It Fa len The length of the base oid without index. .It Fa idx For table columns this is the index expression from the node (see below). .It Fa op This is the operation to execute, one of: .Bd -literal -offset indent enum snmp_op { SNMP_OP_GET = 1, SNMP_OP_GETNEXT, SNMP_OP_SET, SNMP_OP_COMMIT, SNMP_OP_ROLLBACK, }; .Ed .El .Pp 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 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 #define SNMP_INDEX_MASK 0xf #define SNMP_INDEX_COUNT(V) ((V) & SNMP_INDEX_MASK) #define SNMP_INDEX(V,I) \e (((V) >> (((I) + 1) * SNMP_INDEX_SHIFT)) & \e SNMP_INDEX_MASK) .Ed .It Va data This field may contain arbitrary data and is not used by the library. .El .Pp 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 bsnmpd 1 . .Pp The global variable .Va snmp_trace together with the function pointed to by .Va snmp_debug help in debugging the library and the agent. .Va snmp_trace is a bit mask with the following bits: .Bd -literal -offset indent enum { SNMP_TRACE_GET, SNMP_TRACE_GETNEXT, SNMP_TRACE_SET, SNMP_TRACE_DEPEND, SNMP_TRACE_FIND, }; .Ed .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 implementation for the debug function that prints a message to standard error. .Pp Many of the functions use a so called context: .Bd -literal -offset indent struct snmp_context { u_int var_index; struct snmp_scratch *scratch; struct snmp_dependency *dep; void *data; /* user data */ enum snmp_ret code; /* return code */ }; struct snmp_scratch { void *ptr1; void *ptr2; uint32_t int1; uint32_t int2; }; .Ed .Pp 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 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. .It Va dep In the dependency callback function (see below) this is a pointer to the current dependency. Set by the library. .It Va data This is the .Fa data argument from the call to the library and is not used by the library. .El .Pp The next three functions execute different kinds of GET requests. The function .Fn snmp_get executes an SNMP GET operation, the function .Fn snmp_getnext 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 .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: .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. .It Li SNMP_RET_ERR 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 .Fn snmp_make_errresp . .El .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. .Pp 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. .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 scalars the scratch area may be enough to handle commit and rollback, for 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 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 committed dependencies are called again in the opposite order 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. .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 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 its callback is called with .Li SNMP_DEPOP_FINISH. Then the function returns .Li SNMP_ERR_OK . .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. 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 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 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 .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 the dependency callback. .Pp When all SNMP_OP_SET operations have succeeded the dependencies are executed. At this stage the dependency callback has all information about the given table row that was available in this SET PDU and can operate accordingly. .Pp It is guaranteed that each dependency callback is executed at minimum once - with an operation of .Li SNMP_OP_ROLLBACK . This ensures that all dynamically allocated resources in a callback can be 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. .Pp The next four functions allow some parts of the SET operation to be executed. This is only used in .Xr bsnmpd 1 to implement the configuration as a single transaction. The function .Fn snmp_init_context creates and initializes a context. The function .Fn snmp_dep_commit executes SNMP_DEPOP_COMMIT for all dependencies in the context stopping at the first error. The function .Fn snmp_dep_rollback executes SNMP_DEPOP_ROLLBACK starting at the previous of the current dependency in the context. The function .Fn snmp_dep_finish executes SNMP_DEPOP_FINISH for all dependencies. .Sh DIAGNOSTICS 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 bsnmpd 1 , .Xr bsnmpclient 3 , .Xr bsnmplib 3 , .Xr snmpmod 3 .Sh STANDARDS This implementation conforms to the applicable IETF RFCs and ITU-T recommendations. .Sh AUTHORS -.An Hartmut Brandt Aq harti@freebsd.org +.An Hartmut Brandt Aq harti@FreeBSD.org Index: stable/8/contrib/bsnmp/lib/bsnmpclient.3 =================================================================== --- stable/8/contrib/bsnmp/lib/bsnmpclient.3 (revision 211701) +++ stable/8/contrib/bsnmp/lib/bsnmpclient.3 (revision 211702) @@ -1,658 +1,658 @@ .\" .\" Copyright (c) 2004-2005 .\" Hartmut Brandt. .\" All rights reserved. .\" Copyright (c) 2001-2003 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" All rights reserved. .\" -.\" Author: Harti Brandt +.\" Author: Harti Brandt .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Begemot: bsnmp/lib/bsnmpclient.3,v 1.12 2005/10/04 08:46:50 brandt_h Exp $ .\" .Dd October 4, 2005 .Dt BSNMPCLIENT 3 .Os .Sh NAME .Nm snmp_client , .Nm snmp_send_cb_f , .Nm snmp_timeout_cb_f , .Nm snmp_timeout_start_f , .Nm snmp_timeout_stop_f , .Nm snmp_open , .Nm snmp_close , .Nm snmp_pdu_create , .Nm snmp_add_binding , .Nm snmp_pdu_check , .Nm snmp_pdu_send , .Nm snmp_oid_append , .Nm snmp_parse_server , .Nm snmp_receive , .Nm snmp_table_cb_f , .Nm snmp_table_fetch , .Nm snmp_table_fetch_async , .Nm snmp_dialog .Nd "SNMP client library" .Sh LIBRARY Begemot SNMP library .Pq libbsnmp, -lbsnmp .Sh SYNOPSIS .In asn1.h .In snmp.h .In snmpclient.h .Ft typedef void .Fn (*snmp_send_cb_f) "struct snmp_pdu *req" "struct snmp_pdu *resp" "void *uarg" .Ft typedef void .Fn (*snmp_timeout_cb_f) "void *uarg" .Ft typedef void * .Fn (*snmp_timeout_start_f) "struct timeval *timeout" "snmp_timeout_cb_f callback" "void *uarg" .Ft typedef void .Fn (*snmp_timeout_stop_f) "void *timeout_id" .Vt extern struct snmp_client snmp_client ; .Ft void .Fn snmp_client_init "struct snmp_client *client" .Ft int .Fn snmp_client_set_host "struct snmp_client *client" "const char *host" .Ft int .Fn snmp_client_set_port "struct snmp_client *client" "const char *port" .Ft int .Fn snmp_open "const char *host" "const char *port" "const char *read_community" "const char *write_community" .Ft void .Fn snmp_close "void" .Ft void .Fn snmp_pdu_create "struct snmp_pdu *pdu" "u_int op" .Ft int .Fn snmp_add_binding "struct snmp_pdu *pdu" "..." .Ft int .Fn snmp_pdu_check "const struct snmp_pdu *req" "const struct snmp_pdu *resp" .Ft int32_t .Fn snmp_pdu_send "struct snmp_pdu *pdu" "snmp_send_cb_f func" "void *uarg" .Ft int .Fn snmp_oid_append "struct asn_oid *oid" "const char *fmt" "..." .Ft int .Fn snmp_parse_server "struct snmp_client *sc" "const char *str" .Ft int .Fn snmp_receive "int blocking" .Ft typedef void .Fn (*snmp_table_cb_f) "void *list" "void *arg" "int res" .Ft int .Fn snmp_table_fetch "const struct snmp_table *descr" "void *list" .Ft int .Fn snmp_table_fetch_async "const struct snmp_table *descr" "void *list" "snmp_table_cb_f callback" "void *uarg" .Ft int .Fn snmp_dialog "struct snmp_pdu *req" "struct snmp_pdu *resp" .Sh DESCRIPTION The SNMP library contains routines to easily build SNMP client applications that use SNMP versions 1 or 2. Most of the routines use a .Vt struct snmp_client : .Bd -literal -offset indent struct snmp_client { enum snmp_version version; int trans; /* transport type to use */ /* these two are read-only for the application */ char *cport; /* port number as string */ char *chost; /* host name or IP address as string */ char read_community[SNMP_COMMUNITY_MAXLEN + 1]; char write_community[SNMP_COMMUNITY_MAXLEN + 1]; struct timeval timeout; u_int retries; int dump_pdus; size_t txbuflen; size_t rxbuflen; int fd; int32_t next_reqid; int32_t max_reqid; int32_t min_reqid; char error[SNMP_STRERROR_LEN]; snmp_timeout_start_f timeout_start; snmp_timeout_stop_f timeout_stop; /* private */ char local_path[sizeof(SNMP_LOCAL_PATH)]; }; .Ed .Pp The fields of this structure are described below. .Bl -tag -width "timeout_start" .It Va version This is the version of SNMP to use. See .Xr bsnmplib 3 for applicable values. The default version is .Li SNMP_V2c . .It Va trans If this is .Dv SNMP_TRANS_LOC_DGRAM a local datagram socket is used. If it is .Dv SNMP_TRANS_LOC_STREAM a local stream socket is used. For .Dv SNMP_TRANS_UDP a UDP socket is created. It uses the .Va chost field as the path to the server's socket for local sockets. .It Va cport The SNMP agent's UDP port number. This may be a symbolic port number (from .Pa /etc/services ) or a numeric port number. If this field is .Li NULL (the default) the standard SNMP port is used. This field should not be changed directly but rather by calling .Fn snmp_client_set_port . .It Va chost The SNMP agent's host name, IP address or .Ux domain socket path name. If this is .Li NULL (the default) .Li localhost is assumed. This field should not be changed directly but rather through calling .Fn snmp_client_set_host . .It Va read_community This is the community name to be used for all requests except SET requests. The default is .Sq public . .It Va write_community The community name to be used for SET requests. The default is .Sq private . .It Va timeout The maximum time to wait for responses to requests. If the time elapses, the request is resent up to .Va retries times. The default is 3 seconds. .It Va retries Number of times a request PDU is to be resent. If set to 0, the request is sent only once. The default is 3 retransmissions. .It Va dump_pdus If set to a non-zero value all received and sent PDUs are dumped via .Xr snmp_pdu_dump 3 . The default is not to dump PDUs. .It Va txbuflen The encoding buffer size to be allocated for transmitted PDUs. The default is 10000 octets. .It Va rxbuflen The decoding buffer size to be allocated for received PDUs. This is the size of the maximum PDU that can be received. The default is 10000 octets. .It Va fd After calling .Fn snmp_open this is the file socket file descriptor used for sending and receiving PDUs. .It Va next_reqid The request id of the next PDU to send. Used internal by the library. .It Va max_reqid The maximum request id to use for outgoing PDUs. The default is .Li INT32_MAX . .It Va min_reqid The minimum request id to use for outgoing PDUs. Request ids are allocated linearily starting at .Va min_reqid up to .Va max_reqid . .It Va error If an error happens, this field is set to a printable string describing the error. .It Va timeout_start This field must point to a function setting up a one shot timeout. After the timeout has elapsed, the given callback function must be called with the user argument. The .Fn timeout_start function must return a .Vt void * identifying the timeout. .It Va timeout_stop This field must be set to a function that stops a running timeout. The function will be called with the return value of the corresponding .Fn timeout_start function. .It Va local_path If in local socket mode, the name of the clients socket. Not needed by the application. .El .Pp In the current implementation there is a global variable .Pp .D1 Vt extern struct snmp_client snmp_client ; .Pp that is used by all the library functions. The first call into the library must be a call to .Fn snmp_client_init to initialize this global variable to the default values. After this call and before calling .Fn snmp_open the fields of the variable may be modified by the user. The modification of the .Va chost and .Va cport fields should be done only via the functions .Fn snmp_client_set_host and .Fn snmp_client_set_port . .Pp The function .Fn snmp_open creates a UDP or .Ux domain socket and connects it to the agent's IP address and port. If any of the arguments of the call is not .Li NULL the corresponding field in the global .Va snmp_client is set from the argument. Otherwise the values that are already in that variable are used. The function .Fn snmp_close closes the socket, stops all timeouts and frees all dynamically allocated resources. .Pp The next three functions are used to create request PDUs. The function .Fn snmp_pdu_create initializes a PDU of type .Va op . It does not allocate space for the PDU itself. This is the responsibility of the caller. .Fn snmp_add_binding adds bindings to the PDU and returns the (zero based) index of the first new binding. The arguments are pairs of pointer to the OIDs and syntax constants, terminated by a NULL. The call .Bd -literal -offset indent snmp_add_binding(&pdu, &oid1, SNMP_SYNTAX_INTEGER, &oid2, SNMP_SYNTAX_OCTETSTRING, NULL); .Ed .Pp adds two new bindings to the PDU and returns the index of the first one. It is the responsibility of the caller to set the value part of the binding if necessary. The functions returns -1 if the maximum number of bindings is exhausted. The function .Fn snmp_oid_append can be used to construct variable OIDs for requests. It takes a pointer to an .Vt struct asn_oid that is to be constructed, a format string, and a number of arguments the type of which depends on the format string. The format string is interpreted character by character in the following way: .Bl -tag -width ".It Li ( Va N Ns Li )" .It Li i This format expects an argument of type .Vt asn_subid_t and appends this as a single integer to the OID. .It Li a This format expects an argument of type .Vt struct in_addr and appends to four parts of the IP address to the OID. .It Li s This format expects an argument of type .Vt const char * and appends the length of the string (as computed by .Xr strlen 3 ) and each of the characters in the string to the OID. .It Li ( Va N Ns Li ) This format expects no argument. .Va N must be a decimal number and is stored into an internal variable .Va size . .It Li b This format expects an argument of type .Vt const char * and appends .Va size characters from the string to the OID. The string may contain .Li NUL characters. .It Li c This format expects two arguments: one of type .Vt size_t and one of type .Vt const u_char * . The first argument gives the number of bytes to append to the OID from the string pointed to by the second argument. .El .Pp The function .Fn snmp_pdu_check may be used to check a response PDU. A number of checks are performed (error code, equal number of bindings, syntaxes and values for SET PDUs). The function returns +1 if everything is ok, 0 if a NOSUCHNAME or similar error was detected, -1 if the response PDU had fatal errors and -2 if .Fa resp is .Li NULL (a timeout occurred). .Pp The function .Fn snmp_pdu_send encodes and sends the given PDU. It records the PDU together with the callback and user pointers in an internal list and arranges for retransmission if no response is received. When a response is received or the retransmission count is exceeded the callback .Fa func is called with the orignal request PDU, the response PDU and the user argument .Fa uarg . If the retransmit count is exceeded, .Fa func is called with the original request PDU, the response pointer set to .Li NULL and the user argument .Fa uarg . The caller should not free the request PDU until the callback function is called. The callback function must free the request PDU and the response PDU (if not .Li NULL ). .Pp The function .Fn snmp_receive tries to receive a PDU. If the argument is zero, the function polls to see whether a packet is available, if the argument is non-zero, the function blocks until the next packet is received. The packet is delivered via the usual callback mechanism (non-response packets are silently dropped). The function returns 0, if a packet was received and successfully dispatched, -1 if an error occurred or no packet was available (in polling mode). .Pp The next two functions are used to retrieve tables from SNMP agents. They use the following input structure, that describes the table: .Bd -literal -offset indent struct snmp_table { struct asn_oid table; struct asn_oid last_change; u_int max_iter; size_t entry_size; u_int index_size; uint64_t req_mask; struct snmp_table_entry { asn_subid_t subid; enum snmp_syntax syntax; off_t offset; } entries[]; }; .Ed .Pp The fields of this structure have the following meaning: .Bl -tag -width "last_change" .It Va table This is the base OID of the table. .It Va last_change Some tables have a scalar variable of type TIMETICKS attached to them, that holds the time when the table was last changed. This OID should be the OID of this variable (without the \&.0 index). When the table is retrieved with multiple GET requests, and the variable changes between two request, the table fetch is restarted. .It Va max_iter Maximum number of tries to fetch the table. .It Va entry_size The table fetching routines return a list of structures one for each table row. This variable is the size of one structure and used to .Xr malloc 3 the structure. .It Va index_size This is the number of index columns in the table. .It Va req_mask This is a bit mask with a 1 for each table column that is required. Bit 0 corresponds to the first element (index 0) in the array .Va entries , bit 1 to the second (index 1) and so on. SNMP tables may be sparse. For sparse columns the bit should not be set. If the bit for a given column is set and the column value cannot be retrieved for a given row, the table fetch is restarted assuming that the table is currently being modified by the agent. The bits for the index columns are ignored. .It Va entries This is a variable sized array of column descriptors. This array is terminated by an element with syntax .Li SNMP_SYNTAX_NULL . The first .Va index_size elements describe all the index columns of the table, the rest are normal columns. If for the column at .Ql entries[N] the expression .Ql req_mask & (1 << N) yields true, the column is considered a required column. The fields of this the array elements have the following meaning: .Bl -tag -width "syntax" .It Va subid This is the OID subid of the column. This is ignored for index entries. Index entries are decoded according to the .Va syntax field. .It Va syntax This is the syntax of the column or index. A syntax of .Li SNMP_SYNTAX_NULL terminates the array. .It Va offset This is the starting offset of the value of the column in the return structures. This field can be set with the ISO-C .Fn offsetof macro. .El .El .Pp Both table fetching functions return TAILQ (see .Xr queue 3 ) of structures--one for each table row. These structures must start with a .Fn TAILQ_ENTRY and a .Vt uint64_t and are allocated via .Xr malloc 3 . The .Fa list argument of the table functions must point to a .Fn TAILQ_HEAD . The .Vt uint64_t fields, usually called .Va found is used to indicate which of the columns have been found for the given row. It is encoded like the .Fa req_mask field. .Pp The function .Fn snmp_table_fetch synchronously fetches the given table. If everything is ok 0 is returned. Otherwise the function returns -1 and sets an appropriate error string. The function .Fn snmp_table_fetch_async fetches the tables asynchronously. If either the entire table is fetch, or an error occurs the callback function .Fa callback is called with the callers arguments .Fa list and .Fa uarg and a parameter that is either 0 if the table was fetched, or -1 if there was an error. The function itself returns -1 if it could not initialize fetching of the table. .Pp The following table description is used to fetch the ATM interface table: .Bd -literal -offset indent /* * ATM interface table */ struct atmif { TAILQ_ENTRY(atmif) link; uint64_t found; int32_t index; u_char *ifname; size_t ifnamelen; uint32_t node_id; uint32_t pcr; int32_t media; uint32_t vpi_bits; uint32_t vci_bits; uint32_t max_vpcs; uint32_t max_vccs; u_char *esi; size_t esilen; int32_t carrier; }; TAILQ_HEAD(atmif_list, atmif); /* list of all ATM interfaces */ struct atmif_list atmif_list; static const struct snmp_table atmif_table = { OIDX_begemotAtmIfTable, OIDX_begemotAtmIfTableLastChange, 2, sizeof(struct atmif), 1, 0x7ffULL, { { 0, SNMP_SYNTAX_INTEGER, offsetof(struct atmif, index) }, { 1, SNMP_SYNTAX_OCTETSTRING, offsetof(struct atmif, ifname) }, { 2, SNMP_SYNTAX_GAUGE, offsetof(struct atmif, node_id) }, { 3, SNMP_SYNTAX_GAUGE, offsetof(struct atmif, pcr) }, { 4, SNMP_SYNTAX_INTEGER, offsetof(struct atmif, media) }, { 5, SNMP_SYNTAX_GAUGE, offsetof(struct atmif, vpi_bits) }, { 6, SNMP_SYNTAX_GAUGE, offsetof(struct atmif, vci_bits) }, { 7, SNMP_SYNTAX_GAUGE, offsetof(struct atmif, max_vpcs) }, { 8, SNMP_SYNTAX_GAUGE, offsetof(struct atmif, max_vccs) }, { 9, SNMP_SYNTAX_OCTETSTRING, offsetof(struct atmif, esi) }, { 10, SNMP_SYNTAX_INTEGER, offsetof(struct atmif, carrier) }, { 0, SNMP_SYNTAX_NULL, 0 } } }; \&... if (snmp_table_fetch(&atmif_table, &atmif_list) != 0) errx(1, "AtmIf table: %s", snmp_client.error); \&... .Ed .Pp The function .Fn snmp_dialog is used to execute a synchonuous dialog with the agent. The request PDU .Fa req is sent and the function blocks until the response PDU is received. Note, that asynchonuous receives are handled (i.e. callback functions of other send calls or table fetches may be called while in the function). The response PDU is returned in .Fa resp . If no response could be received after all timeouts and retries, the function returns -1. If a response was received 0 is returned. .Pp The function .Fn snmp_parse_server is used to parse an SNMP server specification string and fill in the fields of a .Vt struct snmp_client . The syntax of a server specification is .Pp .D1 [trans::][community@][server][:port] .Pp where .Va trans is the transport name (one of udp, stream or dgram), .Va community is the string to be used for both the read and the write community, .Va server is the server's host name in case of UDP and the path name in case of a local socket, and .Va port is the port in case of UDP transport. The function returns 0 in the case of success and return -1 and sets the error string in case of an error. .Sh DIAGNOSTICS If an error occurs in any of the function an error indication as described above is returned. Additionally the function sets a printable error string in the .Va error filed of .Va snmp_client . .Sh SEE ALSO .Xr gensnmptree 1 , .Xr bsnmpd 1 , .Xr bsnmpagent 3 , .Xr bsnmplib 3 .Sh STANDARDS This implementation conforms to the applicable IETF RFCs and ITU-T recommendations. .Sh AUTHORS -.An Hartmut Brandt Aq harti@freebsd.org +.An Hartmut Brandt Aq harti@FreeBSD.org .An Kendy Kutzner Aq kutzner@fokus.gmd.de Index: stable/8/contrib/bsnmp/lib/bsnmplib.3 =================================================================== --- stable/8/contrib/bsnmp/lib/bsnmplib.3 (revision 211701) +++ stable/8/contrib/bsnmp/lib/bsnmplib.3 (revision 211702) @@ -1,305 +1,305 @@ .\" .\" Copyright (c) 2004-2005 .\" Hartmut Brandt. .\" All rights reserved. .\" Copyright (c) 2001-2003 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" All rights reserved. .\" -.\" Author: Harti Brandt +.\" Author: Harti Brandt .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Begemot: bsnmp/lib/bsnmplib.3,v 1.9 2005/10/04 08:46:51 brandt_h Exp $ .\" .Dd October 4, 2005 .Dt BSNMPLIB 3 .Os .Sh NAME .Nm snmp_value_free , .Nm snmp_value_parse , .Nm snmp_value_copy , .Nm snmp_pdu_free , .Nm snmp_code snmp_pdu_decode , .Nm snmp_code snmp_pdu_encode , .Nm snmp_pdu_dump , .Nm TRUTH_MK , .Nm TRUTH_GET , .Nm TRUTH_OK .Nd "SNMP decoding and encoding library" .Sh LIBRARY Begemot SNMP library .Pq libbsnmp, -lbsnmp .Sh SYNOPSIS .In bsnmp/asn1.h .In bsnmp/snmp.h .Ft void .Fn snmp_value_free "struct snmp_value *value" .Ft int .Fn snmp_value_parse "const char *buf" "enum snmp_syntax" "union snmp_values *value" .Ft int .Fn snmp_value_copy "struct snmp_value *to" "const struct snmp_value *from" .Ft void .Fn snmp_pdu_free "struct snmp_pdu *value" .Ft enum snmp_code .Fn snmp_pdu_decode "struct asn_buf *buf" "struct snmp_pdu *pdu" "int32_t *ip" .Ft enum snmp_code .Fn snmp_pdu_encode "struct snmp_pdu *pdu" "struct asn_buf *buf" .Ft void .Fn snmp_pdu_dump "const struct snmp_pdu *pdu" .Ft int .Fn TRUTH_MK "F" .Ft int .Fn TRUTH_GET "T" .Ft int .Fn TRUTH_OK "T" .Sh DESCRIPTION The SNMP library contains routines to handle SNMP version 1 and 2 PDUs. There are two basic structures used throughout the library: .Bd -literal -offset indent struct snmp_value { struct asn_oid var; enum snmp_syntax syntax; union snmp_values { int32_t integer;/* also integer32 */ struct { u_int len; u_char *octets; } octetstring; struct asn_oid oid; u_char ipaddress[4]; uint32_t uint32; /* also gauge32, counter32, unsigned32, timeticks */ uint64_t counter64; } v; }; .Ed .Pp This structure represents one variable binding from an SNMP PDU. The field .Fa var is the ASN.1 of the variable that is bound. .Fa syntax contains either the syntax code of the value or an exception code for SNMPv2 and may be one of: .Bd -literal -offset indent enum snmp_syntax { SNMP_SYNTAX_NULL = 0, SNMP_SYNTAX_INTEGER, /* == INTEGER32 */ SNMP_SYNTAX_OCTETSTRING, SNMP_SYNTAX_OID, SNMP_SYNTAX_IPADDRESS, SNMP_SYNTAX_COUNTER, SNMP_SYNTAX_GAUGE, /* == UNSIGNED32 */ SNMP_SYNTAX_TIMETICKS, /* v2 additions */ SNMP_SYNTAX_COUNTER64, /* exceptions */ SNMP_SYNTAX_NOSUCHOBJECT, SNMP_SYNTAX_NOSUCHINSTANCE, SNMP_SYNTAX_ENDOFMIBVIEW, }; .Ed The field .Fa v holds the actual value depending on .Fa syntax . Note, that if .Fa syntax is .Li SNMP_SYNTAX_OCTETSTRING and .Fa v.octetstring.len is not zero, .Fa v.octetstring.octets points to a string allocated by .Xr malloc 3 . .Pp .Bd -literal -offset indent #define SNMP_COMMUNITY_MAXLEN 128 #define SNMP_MAX_BINDINGS 100 struct snmp_pdu { char community[SNMP_COMMUNITY_MAXLEN + 1]; enum snmp_version version; u_int type; /* trap only */ struct asn_oid enterprise; u_char agent_addr[4]; int32_t generic_trap; int32_t specific_trap; u_int32_t time_stamp; /* others */ int32_t request_id; int32_t error_status; int32_t error_index; /* fixes for encoding */ u_char *outer_ptr; u_char *pdu_ptr; u_char *vars_ptr; struct snmp_value bindings[SNMP_MAX_BINDINGS]; u_int nbindings; }; .Ed This structure contains a decoded SNMP PDU. .Fa version is one of .Bd -literal -offset indent enum snmp_version { SNMP_Verr = 0, SNMP_V1 = 1, SNMP_V2c, }; .Ed and .Fa type is the type of the PDU. .Pp The function .Fn snmp_value_free is used to free all the dynamic allocated contents of an SNMP value. It does not free the structure pointed to by .Fa value itself. .Pp The function .Fn snmp_value_parse parses the ASCII representation of an SNMP value into its binary form. This function is mainly used by the configuration file reader of .Xr bsnmpd 1 . .Pp The function .Fn snmp_value_copy makes a deep copy of the value pointed to by .Fa from to the structure pointed to by .Fa to . It assumes that .Fa to is uninitialized and will overwrite its previous contents. It does not itself allocate the structure pointed to by .Fa to . .Pp The function .Fn snmp_pdu_free frees all the dynamically allocated components of the PDU. It does not itself free the structure pointed to by .Fa pdu . .Pp The function .Fn snmp_pdu_decode decodes the PDU pointed to by .Fa buf and stores the result into .Fa pdu . If an error occurs in a variable binding the (1 based) index of this binding is stored in the variable pointed to by .Fa ip . .Pp The function .Fn snmp_pdu_encode encodes the PDU .Fa pdu into the an octetstring in buffer .Fa buf . .Pp The function .Fn snmp_pdu_dump dumps the PDU in a human readable form by calling .Fn snmp_printf . .Pp The function .Fn TRUTH_MK takes a C truth value (zero or non-zero) and makes an SNMP truth value (2 or 1). The function .Fn TRUTH_GET takes an SNMP truth value and makes a C truth value (0 or 1). The function .Fn TRUTH_OK checks, whether its argument is a legal SNMP truth value. .Sh DIAGNOSTICS When an error occurs in any of the function the function pointed to by the global pointer .Bd -literal -offset indent extern void (*snmp_error)(const char *, ...); .Ed .Pp with a .Xr printf 3 style format string. There is a default error handler in the library that prints a message starting with .Sq SNMP: followed by the error message to standard error. .Pp The function pointed to by .Bd -literal -offset indent extern void (*snmp_printf)(const char *, ...); .Ed .Pp is called by the .Fn snmp_pdu_dump function. The default handler is .Xr printf 3 . .Sh ERRORS .Fn snmp_pdu_decode will return one of the following return codes: .Bl -tag -width Er .It Bq Er SNMP_CODE_OK Success. .It Bq Er SNMP_CODE_FAILED The ASN.1 coding was wrong. .It Bq Er SNMP_CODE_BADLEN A variable binding value had a wrong length field. .It Bq Er SNMP_CODE_OORANGE A variable binding value was out of the allowed range. .It Bq Er SNMP_CODE_BADVERS The PDU is of an unsupported version. .It Bq Er SNMP_CODE_BADENQ There was an ASN.1 value with an unsupported tag. .El .Pp .Fn snmp_pdu_encode will return one of the following return codes: .Bl -tag -width Er .It Bq Er SNMP_CODE_OK Success. .It Bq Er SNMP_CODE_FAILED Encoding failed. .El .Sh SEE ALSO .Xr gensnmptree 1 , .Xr bsnmpd 1 , .Xr bsnmpagent 3 , .Xr bsnmpclient 3 , .Xr bsnmplib 3 .Sh STANDARDS This implementation conforms to the applicable IETF RFCs and ITU-T recommendations. .Sh AUTHORS -.An Hartmut Brandt Aq harti@freebsd.org +.An Hartmut Brandt Aq harti@FreeBSD.org Index: stable/8/contrib/bsnmp/snmp_mibII/snmp_mibII.3 =================================================================== --- stable/8/contrib/bsnmp/snmp_mibII/snmp_mibII.3 (revision 211701) +++ stable/8/contrib/bsnmp/snmp_mibII/snmp_mibII.3 (revision 211702) @@ -1,366 +1,366 @@ .\" .\" Copyright (c) 2004-2005 .\" Hartmut Brandt .\" All rights reserved. .\" Copyright (c) 2001-2003 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" All rights reserved. .\" -.\" Author: Harti Brandt +.\" Author: Harti Brandt .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Begemot: bsnmp/snmp_mibII/snmp_mibII.3,v 1.10 2005/10/04 08:46:52 brandt_h Exp $ .\" .Dd October 4, 2005 .Dt SNMP_MIBII 3 .Os .Sh NAME .Nm mibII , .Nm mibif_notify_f , .Nm mib_netsock , .Nm mib_if_set_dyn , .Nm mib_refresh_iflist , .Nm mib_find_if , .Nm mib_find_if_sys , .Nm mib_find_if_name , .Nm mib_first_if , .Nm mib_next_if , .Nm mib_register_newif , .Nm mib_unregister_newif , .Nm mib_fetch_ifmib , .Nm mib_if_admin , .Nm mib_find_ifa , .Nm mib_first_ififa , .Nm mib_next_ififa , .Nm mib_ifstack_create , .Nm mib_ifstack_delete , .Nm mib_find_rcvaddr , .Nm mib_rcvaddr_create , .Nm mib_rcvaddr_delete , .Nm mibif_notify , .Nm mibif_unnotify .Nd "mib-2 module for bsnmpd." .Sh LIBRARY .Pq begemotSnmpdModulePath."mibII" = "@MODPATH@snmp_mibII.so" .Sh SYNOPSIS .In bsnmp/snmpmod.h .In bsnmp/snmp_mibII.h .Ft typedef void .Fn (*mibif_notify_f) "struct mibif *ifp" "enum mibif_notify event" "void *uarg" .Vt extern int mib_netsock ; .Ft void .Fn mib_if_set_dyn "const char *ifname" .Ft void .Fn mib_refresh_iflist "void" .Ft struct mibif * .Fn mib_find_if "u_int ifindex" .Ft struct mibif * .Fn mib_find_if_sys "u_int sysindex" .Ft struct mibif * .Fn mib_find_if_name "const char *ifname" .Ft struct mibif * .Fn mib_first_if "void" .Ft struct mibif * .Fn mib_next_if "const struct mibif *ifp" .Ft int .Fn mib_register_newif "int (*func)(struct mibif *)" "const struct lmodule *mod" .Ft void .Fn mib_unregister_newif "const struct lmodule *mod" .Ft int .Fn mib_fetch_ifmib "struct mibif *ifp" .Ft int .Fn mib_if_admin "struct mibif *ifp" "int up" .Ft struct mibifa * .Fn mib_find_ifa "struct in_addr ipa" .Ft struct mibifa * .Fn mib_first_ififa "const struct mibif *ifp" .Ft struct mibifa * .Fn mib_next_ififa "struct mibifa *ifa" .Ft int .Fn mib_ifstack_create "const struct mibif *lower" "const struct mibif *upper" .Ft void .Fn mib_ifstack_delete "const struct mibif *lower" "const struct mibif *upper" .Ft struct mibrcvaddr * .Fn mib_find_rcvaddr "u_int ifindex" "const u_char *addr" "size_t addrlen" .Ft struct mibrcvaddr * .Fn mib_rcvaddr_create "struct mibif *ifp" "const u_char *addr" "size_t addrlen" .Ft void .Fn mib_rcvaddr_delete "struct mibrcvaddr *addr" .Ft void * .Fn mibif_notify "struct mibif *ifp" "const struct lmodule *mod" "mibif_notify_f func" "void *uarg" .Ft void .Fn mibif_unnotify "void *reg" .Sh DESCRIPTION The .Nm snmp_mibII module implements parts of the internet standard MIB-2. Most of the relevant MIBs are implemented. Some of the tables are restricted to be read-only instead of read-write. The exact current implementation can be found in .Pa @DEFPATH@mibII_tree.def . The module also exports a number of functions and global variables for use by other modules, that need to handle network interfaces. This man page describes these functions. .Ss DIRECT NETWORK ACCESS The .Nm module opens a socket that is used to execute all network related .Xr ioctl 2 functions. This socket is globally available under the name .Va mib_netsock . .Ss NETWORK INTERFACES The .Nm module handles a list of all currently existing network interfaces. It allows other modules to handle their own interface lists with special information by providing a mechanism to register to events that change the interface list (see below). The basic data structure is the interface structure: .Bd -literal -offset indent struct mibif { TAILQ_ENTRY(mibif) link; u_int flags; u_int index; /* logical ifindex */ u_int sysindex; char name[IFNAMSIZ]; char descr[256]; struct ifmibdata mib; uint64_t mibtick; void *specmib; size_t specmiblen; u_char *physaddr; u_int physaddrlen; int has_connector; int trap_enable; uint64_t counter_disc; mibif_notify_f xnotify; void *xnotify_data; const struct lmodule *xnotify_mod; struct asn_oid spec_oid; }; .Ed .Pp The .Nm module tries to implement the semantic if .Va ifIndex as described in RFC-2863. This RFC states, that an interface indexes may not be reused. That means, for example, if .Pa tun is a synthetic interface type and the system creates the interface .Pa tun0 , destroys this interfaces and again creates a .Pa tun 0 , then these interfaces must have different interface indexes, because in fact they are different interfaces. If, on the other hand, there is a hardware interface .Pa xl0 and this interface disappears, because its driver is unloaded and appears again, because the driver is loaded again, the interface index must stay the same. .Nm implements this by differentiating between real and synthetic (dynamic) interfaces. An interface type can be declared dynamic by calling the function .Fn mib_if_set_dyn with the name if the interface type (for example .Qq tun ). For real interfaces, the module keeps the mapping between the interface name and its .Va ifIndex in a special list, if the interface is unloaded. For dynamic interfaces a new .Va ifIndex is generated each time the interface comes into existence. This means, that the interface index as seen by SNMP is not the same index as used by the system. The SNMP .Va ifIndex is held in field .Va index , the system's interface index is .Va sysindex . .Pp A call to .Nm mib_refresh_iflist causes the entire interface list to be re-created. .Pp The interface list can be traversed with the functions .Fn mib_first_if and .Fn mib_next_if . Be sure not to change the interface list while traversing the list with these two calls. .Pp There are three functions to find an interface by name or index. .Fn mib_find_if finds an interface by searching for an SNMP .Va ifIndex , .Fn mib_find_if_sys finds an interface by searching for a system interface index and .Fn mib_find_if_name finds an interface by looking for an interface name. Each of the function returns .Li NULL if the interface cannot be found. .Pp The function .Fn mib_fetch_ifmib causes the interface MIB to be refreshed from the kernel. .Pp The function .Fn mib_if_admin can be used to change the interface administrative state to up (argument is 1) or down (argument is 0). .Ss INTERFACE EVENTS A module can register itself to receive a notification when a new entry is created in the interface list. This is done by calling .Fn mib_register_newif . A module can register only one function, a second call to .Fn mib_register_newif causes the registration to be overwritten. The registration can be removed with a call to .Fn mib_unregister_newif . It is unregistered automatically, when the registering module is unloaded. .Pp A module can also register to events on a specific interface. This is done by calling .Fn mibif_notify . This causes the given callback .Fa func to be called with the interface pointer, a notification code and the user argument .Fa uarg when any of the following events occur: .Bl -tag -width "XXXXX" .It Li MIBIF_NOTIFY_DESTROY The interface is destroyed. .El .Pp This mechanism can be used to implement interface type specific MIB parts in other modules. The registration can be removed with .Fn mib_unnotify which the return value from .Fa mib_notify . Any notification registration is removed automatically when the interface is destroyed or the registering module is unloaded. .Em Note that only one module can register to any given interface . .Ss INTERFACE ADDRESSES The .Nm module handles a table of interface IP-addresses. These addresses are held in a .Bd -literal -offset indent struct mibifa { TAILQ_ENTRY(mibifa) link; struct in_addr inaddr; struct in_addr inmask; struct in_addr inbcast; struct asn_oid index; u_int ifindex; u_int flags; }; .Ed .Pp The (ordered) list of IP-addresses on a given interface can be traversed by calling .Fn mib_first_ififa and .Fn mib_next_ififa . The list should not be considered read-only. .Ss INTERFACE RECEIVE ADDRESSES The internet MIB-2 contains a table of interface receive addresses. These addresses are handled in: .Bd -literal -offset indent struct mibrcvaddr { TAILQ_ENTRY(mibrcvaddr) link; struct asn_oid index; u_int ifindex; u_char addr[ASN_MAXOIDLEN]; size_t addrlen; u_int flags; }; enum { MIBRCVADDR_VOLATILE = 0x00000001, MIBRCVADDR_BCAST = 0x00000002, MIBRCVADDR_HW = 0x00000004, }; .Ed .Pp Note, that the assignment of .Li MIBRCVADDR_BCAST is based on a list of known interface types. The flags should be handled by modules implementing interface type specific MIBs. .Pp A receive address can be created with .Fn mib_rcvaddr_create and deleted with .Fn mib_rcvaddr_delete . This needs to be done only for addresses that are not automatically handled by the system. .Pp A receive address can be found with .Fn mib_find_rcvaddr . .Ss INTERFACE STACK TABLE The .Nm module maintains also the interface stack table. Because for complex stacks, there is no system supported generic way of getting this information, interface type specific modules need to help setting up stack entries. The .Nm module handles only the top and bottom entries. .Pp A table entry is created with .Fn mib_ifstack_create and deleted with .Fn mib_ifstack_delete . Both functions need the pointers to the interfaces. Entries are automatically deleted if any of the interfaces of the entry is destroyed. The functions handle both the stack table and the reverse stack table. .Sh FILES .Bl -tag -width ".It Pa @DEFPATH@mibII_tree.def" -compact .It Pa @DEFPATH@mibII_tree.def The description of the MIB tree implemented by .Nm . .It Pa /usr/local/share/snmp/mibs .It Pa @MIBSPATH@ The various internet MIBs. .El .Sh SEE ALSO .Xr gensnmptree 1 , .Xr snmpmod 3 .Sh STANDARDS This implementation conforms to the applicable IETF RFCs. .Sh AUTHORS -.An Hartmut Brandt Aq harti@freebsd.org +.An Hartmut Brandt Aq harti@FreeBSD.org Index: stable/8/contrib/bsnmp/snmpd/bsnmpd.1 =================================================================== --- stable/8/contrib/bsnmp/snmpd/bsnmpd.1 (revision 211701) +++ stable/8/contrib/bsnmp/snmpd/bsnmpd.1 (revision 211702) @@ -1,276 +1,274 @@ .\" .\" Copyright (c) 2004-2005 .\" Hartmut Brandt. .\" All rights reserved. .\" Copyright (c) 2001-2003 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" All rights reserved. .\" -.\" Author: Harti Brandt +.\" Author: Harti Brandt .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Begemot: bsnmp/snmpd/bsnmpd.1,v 1.12 2006/02/27 09:50:03 brandt_h Exp $ .\" -.Dd February 27, 2006 +.Dd August 16, 2010 .Dt BSNMPD 1 .Os .Sh NAME .Nm bsnmpd .Nd "simple and extensible SNMP daemon" .Sh SYNOPSIS .Nm .Op Fl dh .Op Fl c Ar file .Op Fl D Ar options .Op Fl I Ar paths .Op Fl l Ar prefix .Op Fl m Ar variable Ns Op = Ns Ar value .Op Fl p Ar file .Sh DESCRIPTION The .Nm -daemon server the internet SNMP (Simple Network Management Protocol). +daemon serves the internet SNMP (Simple Network Management Protocol). It is intended to serve only the absolute basic MIBs and implement all other MIBs through loadable modules. In this way the .Nm can be used in unexpected ways. .Pp The options are as follows: .Bl -tag -width ".It Fl D Ar options" .It Fl d -This option is used for debugging -.Nm -and causes it not to daemonize itself. +Do not daemonize. +Used for debugging. .It Fl h -This option prints a short usage message. +Print a short usage message. .It Fl c Ar file Use .Ar file as configuration file instead of the standard one. .It Fl D Ar options Debugging options are specified with a .Fl o flag followed by a comma separated string of options. The following options are available. .Bl -tag -width ".It Cm trace Ns Cm = Ns Cm level" .It Cm dump -This option causes all sent and received PDUs to be dumped to the terminal. +Dump all sent and received PDUs to the terminal. .It Cm events -This causes the debugging level of the event library (see +Set the debugging level of the event library (see .Xr eventlib 3 ) -to be set to 10. +to 10. .It Cm trace Ns Cm = Ns Cm level -This option causes the snmp library trace flag to be set to the specified +Set the snmp library trace flag to the specified value. The value can be specified in the usual C-syntax for numbers. .El .It Fl I Ar paths -This option specifies a colon separated list of directories to search for -configuration include files. +Specify a colon separated list of directories to search for configuration +include files. The default is .Pa /etc:/usr/etc/:/usr/local/etc . These paths are only searched for include specified within <> parentheses. .It Fl l Ar prefix -The +Use .Ar prefix -is used as the default basename for the pid and the configuration files. +as the default basename for the pid and the configuration files. .It Fl m Ar variable Ns Op = Ns Ar value Define a configuration variable. .It Fl p Ar file Specify an alternate pid file instead of the default one. .El .Sh CONFIGURATION -The .Nm reads its configuration from either the default or the user specified configuration file. The configuration file consists of the following types of lines: .Bl -bullet -offset indent .It variable assignments .It section separators .It include directives .It MIB variable assignments .El .Pp If a line is too long it can be continued on the next line by ending it with a backslash. Empty lines and lines in which the first non-blank character is a .Dq # sign are ignored. .Pp All MIB variable assignments of the entire configuration (including nested configuration files) are handled as one transaction, i.e., as if they arrived in a single SET PDU. Any failure during the initial configuration read causes .Nm to exit. A failure during the configuration read caused by a module load causes the loading of the module to fail. .Pp The configuration is read during initialization of .Nm , when a module is loaded and when .Nm receives a SIGHUP. .Ss VARIABLE ASSIGNMENTS Variable assignments can take one of two forms: .Bd -unfilled -offset indent variable := string variable ?= string .Ed .Pp The string reaches from the first non-blank character after the equal sign until the first new line or .Dq # character. In the first case the string is assigned to the variable unconditionally, in the second case the variable is only assigned if it does not exist yet. .Pp Variable names must begin with a letter or underscore and contain only letters, digits or underscores. .Ss SECTION SEPARATORS The configuration consists of named sections. The MIB variable assignments in the section named .Dq snmpd are executed only during initial setup or when .Nm receives a SIGHUP. All other sections are executed when either a module with the same name as the section is loaded or .Nm receives a SIGHUP and that module is already loaded. The default section at the start of the configuration is .Dq snmpd . One can switch to another section with the syntax .Bd -unfilled -offset indent %secname .Ed .Pp Where .Ar secname is the name of the section. The same .Ar secname can be used in more than one place in the configuration. All of these parts are collected into one section. .Ss INCLUDE DIRECTIVES Another configuration file can be included into the current one with the include directive that takes one of two forms: .Bd -unfilled -offset indent \&.include "file" \&.include <"file"> .Ed .Pp The first form causes the file to be searched in the current directory, the second form causes the file to be searched in the directories specified in the system include path. Nesting depth is only restricted by available memory. .Ss MIB VARIABLE ASSIGNMENTS A MIB variable is assigned with the syntax .Bd -unfilled -offset indent oid [ suboids ] = value .Ed .Pp .Va oid is the name of the variable to be set. Only the last component of the entire name is used here. If the variable is a scalar, the index (.0) is automatically appended and need not to be specified. If the variable is a table column, the index .Pq Va suboids must be specified. The index consist of elements each separated from the previous one by a dot. Elements may be either numbers, strings or hostnames enclosed in [] brackets. If the element is a number it is appended to the current oid. If the element is a string, its length and the .Tn ASCII code of each of its characters are appended to the current oid. If the element is a hostname, the IP address of the host is looked up and the four elements of the IP address are appended to the oid. .Pp -For example a oid of +For example, an oid of .Bd -unfilled -offset indent myvariable.27.foooll.[localhost]."&^!" .Ed .Pp results in the oid .Bd -unfilled -offset indent myvariable.27.6.102.111.111.111.108.108.127.0.0.1.38.94.33 .Ed .Pp The value of the assignment may be either empty, a string or a number. If a string starts with a letter or an underscore and consists only of letters, digits, underscores and minus signs, it can be written without quotes. In all other cases the string must be enclosed in double quotes. .Sh SUBSTITUTIONS A variable substitution is written as .Bd -unfilled -offset indent $(variable) .Ed .Pp where .Ar variable is the name of the variable to substitute. Using an undefined variable is considered an error. .Sh FILES .Bl -tag -width ".It Pa /var/run/ Ns Ao Ar prefix Ac Ns \&.pid" -compact .It Pa /etc/ Ns Ao Ar prefix Ac Ns \&.config Default configuration file, where the default .Aq prefix is .Dq snmpd . .It Pa /var/run/ Ns Ao Ar prefix Ac Ns \&.pid Default pid file. .It Pa /etc:/usr/etc/:/usr/local/etc -This is the default search path for system include files. +Default search path for system include files. .It Pa @MIBSPATH@FOKUS-MIB.txt .It Pa @MIBSPATH@BEGEMOT-MIB.txt .It Pa @MIBSPATH@BEGEMOT-SNMPD.txt -The definitions for the MIBs implemented in the daemon. +Definitions for the MIBs implemented in the daemon. .It Pa /etc/hosts.allow, /etc/hosts.deny -Access controls that should be enforced by TCP wrappers should be defined here. +Access controls that should be enforced by TCP wrappers are defined here. Further details are described in .Xr hosts_access 5 . .El .Sh SEE ALSO .Xr gensnmptree 1 , .Xr hosts_access 5 .Sh STANDARDS The .Nm conforms to the applicable IETF RFCs. .Sh AUTHORS -.An Hartmut Brandt Aq harti@freebsd.org +.An Hartmut Brandt Aq harti@FreeBSD.org .Sh BUGS Sure. Index: stable/8/contrib/bsnmp/snmpd/snmpmod.3 =================================================================== --- stable/8/contrib/bsnmp/snmpd/snmpmod.3 (revision 211701) +++ stable/8/contrib/bsnmp/snmpd/snmpmod.3 (revision 211702) @@ -1,928 +1,929 @@ .\" .\" Copyright (c) 2004-2005 .\" Hartmut Brandt. .\" All rights reserved. .\" Copyright (c) 2001-2003 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" All rights reserved. .\" -.\" Author: Harti Brandt +.\" Author: Harti Brandt .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Begemot: bsnmp/snmpd/snmpmod.3,v 1.14 2005/10/04 13:30:35 brandt_h Exp $ .\" .Dd February 27, 2006 .Dt SNMPMOD 3 .Os .Sh NAME .Nm INSERT_OBJECT_OID_LINK_INDEX , .Nm INSERT_OBJECT_INT_LINK_INDEX , .Nm FIND_OBJECT_OID_LINK_INDEX , .Nm NEXT_OBJECT_OID_LINK_INDEX , .Nm FIND_OBJECT_INT_LINK_INDEX , .Nm NEXT_OBJECT_INT_LINK_INDEX , .Nm INSERT_OBJECT_OID_LINK , .Nm INSERT_OBJECT_INT_LINK , .Nm FIND_OBJECT_OID_LINK , .Nm NEXT_OBJECT_OID_LINK , .Nm FIND_OBJECT_INT_LINK , .Nm NEXT_OBJECT_INT_LINK , .Nm INSERT_OBJECT_OID , .Nm INSERT_OBJECT_INT , .Nm FIND_OBJECT_OID , .Nm FIND_OBJECT_INT , .Nm NEXT_OBJECT_OID , .Nm NEXT_OBJECT_INT , .Nm this_tick , .Nm start_tick , .Nm get_ticks , .Nm systemg , .Nm comm_define , .Nm community , .Nm oid_zeroDotZero , .Nm reqid_allocate , .Nm reqid_next , .Nm reqid_base , .Nm reqid_istype , .Nm reqid_type , .Nm timer_start , .Nm timer_start_repeat , .Nm timer_stop , .Nm fd_select , .Nm fd_deselect , .Nm fd_suspend , .Nm fd_resume , .Nm or_register , .Nm or_unregister , .Nm buf_alloc , .Nm buf_size , .Nm snmp_input_start , .Nm snmp_input_finish , .Nm snmp_output , .Nm snmp_send_port , .Nm snmp_send_trap , .Nm string_save , .Nm string_commit , .Nm string_rollback , .Nm string_get , .Nm string_get_max , .Nm string_free , .Nm ip_save , .Nm ip_rollback , .Nm ip_commit , .Nm ip_get , .Nm oid_save , .Nm oid_rollback , .Nm oid_commit , .Nm oid_get , .Nm index_decode , .Nm index_compare , .Nm index_compare_off , .Nm index_append , .Nm index_append_off .Nd "SNMP daemon loadable module interface" .Sh LIBRARY Begemot SNMP library .Pq libbsnmp, -lbsnmp .Sh SYNOPSIS .In bsnmp/snmpmod.h .Fn INSERT_OBJECT_OID_LINK_INDEX "PTR" "LIST" "LINK" "INDEX" .Fn INSERT_OBJECT_INT_LINK_INDEX "PTR" "LIST" "LINK" "INDEX" .Fn FIND_OBJECT_OID_LINK_INDEX "LIST" "OID" "SUB" "LINK" "INDEX" .Fn FIND_OBJECT_INT_LINK_INDEX "LIST" "OID" "SUB" "LINK" "INDEX" .Fn NEXT_OBJECT_OID_LINK_INDEX "LIST" "OID" "SUB" "LINK" "INDEX" .Fn NEXT_OBJECT_INT_LINK_INDEX "LIST" "OID" "SUB" "LINK" "INDEX" .Fn INSERT_OBJECT_OID_LINK "PTR" "LIST" "LINK" .Fn INSERT_OBJECT_INT_LINK "PTR" "LIST" "LINK" .Fn FIND_OBJECT_OID_LINK "LIST" "OID" "SUB" "LINK" .Fn FIND_OBJECT_INT_LINK "LIST" "OID" "SUB" "LINK" .Fn NEXT_OBJECT_OID_LINK "LIST" "OID" "SUB" "LINK" .Fn NEXT_OBJECT_INT_LINK "LIST" "OID" "SUB" "LINK" .Fn INSERT_OBJECT_OID "PTR" "LIST" .Fn INSERT_OBJECT_INT "PTR" "LIST" .Fn FIND_OBJECT_OID "LIST" "OID" "SUB" .Fn FIND_OBJECT_INT "LIST" "OID" "SUB" .Fn NEXT_OBJECT_OID "LIST" "OID" "SUB" .Fn NEXT_OBJECT_INT "LIST" "OID" "SUB" .Vt extern uint64_t this_tick ; .Vt extern uint64_t start_tick ; .Ft uint64_t .Fn get_ticks "void" .Vt extern struct systemg systemg ; .Ft u_int .Fn comm_define "u_int priv" "const char *descr" "struct lmodule *mod" "const char *str" .Ft const char * .Fn comm_string "u_int comm" .Vt extern u_int community ; .Vt extern const struct asn_oid oid_zeroDotZero ; .Ft u_int .Fn reqid_allocate "int size" "struct lmodule *mod" .Ft int32_t .Fn reqid_next "u_int type" .Ft int32_t .Fn reqid_base "u_int type" .Ft int .Fn reqid_istype "int32_t reqid" "u_int type" .Ft u_int .Fn reqid_type "int32_t reqid" .Ft void * .Fn timer_start "u_int ticks" "void (*func)(void *)" "void *uarg" "struct lmodule *mod" .Ft void * .Fn timer_start_repeat "u_int ticks" "u_int repeat_ticks" "void (*func)(void *)" "void *uarg" "struct lmodule *mod" .Ft void .Fn timer_stop "void *timer_id" .Ft void * .Fn fd_select "int fd" "void (*func)(int, void *)" "void *uarg" "struct lmodule *mod" .Ft void .Fn fd_deselect "void *fd_id" .Ft void .Fn fd_suspend "void *fd_id" .Ft int .Fn fd_resume "void *fd_id" .Ft u_int .Fn or_register "const struct asn_oid *oid" "const char *descr" "struct lmodule *mod" .Ft void .Fn or_unregister "u_int or_id" .Ft void * .Fn buf_alloc "int tx" .Ft size_t .Fn buf_size "int tx" .Ft enum snmpd_input_err .Fo snmp_input_start .Fa "const u_char *buf" "size_t len" "const char *source" .Fa "struct snmp_pdu *pdu" "int32_t *ip" "size_t *pdulen" .Fc .Ft enum snmpd_input_err .Fo snmp_input_finish .Fa "struct snmp_pdu *pdu" "const u_char *rcvbuf" .Fa "size_t rcvlen" "u_char *sndbuf" "size_t *sndlen" "const char *source" .Fa "enum snmpd_input_err ierr" "int32_t ip" "void *data" .Fc .Ft void .Fo snmp_output .Fa "struct snmp_pdu *pdu" "u_char *sndbuf" "size_t *sndlen" .Fa "const char *dest" .Fc .Ft void .Fo snmp_send_port .Fa "void *trans" "const struct asn_oid *port" .Fa "struct snmp_pdu *pdu" "const struct sockaddr *addr" "socklen_t addrlen" .Fc .Ft void .Fn snmp_send_trap "const struct asn_oid *oid" "..." .Ft int .Fn string_save "struct snmp_value *val" "struct snmp_context *ctx" "ssize_t req_size" "u_char **strp" .Ft void .Fn string_commit "struct snmp_context *ctx" .Ft void .Fn string_rollback "struct snmp_context *ctx" "u_char **strp" .Ft int .Fn string_get "struct snmp_value *val" "const u_char *str" "ssize_t len" .Ft int .Fn string_get_max "struct snmp_value *val" "const u_char *str" "ssize_t len" "size_t maxlen" .Ft void .Fn string_free "struct snmp_context *ctx" .Ft int .Fn ip_save "struct snmp_value *val" "struct snmp_context *ctx" "u_char *ipa" .Ft void .Fn ip_rollback "struct snmp_context *ctx" "u_char *ipa" .Ft void .Fn ip_commit "struct snmp_context *ctx" .Ft int .Fn ip_get "struct snmp_value *val" "u_char *ipa" .Ft int .Fn oid_save "struct snmp_value *val" "struct snmp_context *ctx" "struct asn_oid *oid" .Ft void .Fn oid_rollback "struct snmp_context *ctx" "struct asn_oid *oid" .Ft void .Fn oid_commit "struct snmp_context *ctx" .Ft int .Fn oid_get "struct snmp_value *val" "const struct asn_oid *oid" .Ft int .Fn index_decode "const struct asn_oid *oid" "u_int sub" "u_int code" "..." .Ft int .Fn index_compare "const struct asn_oid *oid1" "u_int sub" "const struct asn_oid *oid2" .Ft int .Fn index_compare_off "const struct asn_oid *oid1" "u_int sub" "const struct asn_oid *oid2" "u_int off" .Ft void .Fn index_append "struct asn_oid *dst" "u_int sub" "const struct asn_oid *src" .Ft void .Fn index_append_off "struct asn_oid *dst" "u_int sub" "const struct asn_oid *src" "u_int off" .Sh DESCRIPTION The .Xr bsnmpd 1 SNMP daemon implements a minimal MIB which consists of the system group, part of the SNMP MIB, a private configuration MIB, a trap destination table, a UDP port table, a community table, a module table, a statistics group and a debugging group. All other MIBs are support through loadable modules. This allows .Xr bsnmpd 1 to use for task, that are not the classical SNMP task. .Ss MODULE LOADING AND UNLOADING Modules are loaded by writing to the module table. This table is indexed by a string, that identifies the module to the daemon. This identifier is used to select the correct configuration section from the configuration files and to identify resources allocated to this module. A row in the module table is created by writing a string of non-zero length to the .Va begemotSnmpdModulePath column. This string must be the complete path to the file containing the module. A module can be unloaded by writing a zero length string to the path column of an existing row. .Pp Modules may depend on each other an hence must be loaded in the correct order. The dependencies are listed in the corresponding manual pages. .Pp Upon loading a module the SNMP daemon expects the module file to a export a global symbol .Va config . This symbol should be a variable of type .Vt struct snmp_module : .Bd -literal -offset indent typedef enum snmpd_proxy_err (*proxy_err_f)(struct snmp_pdu *, void *, const struct asn_oid *, const struct sockaddr *, socklen_t, enum snmpd_input_err, int32_t); struct snmp_module { const char *comment; int (*init)(struct lmodule *, int argc, char *argv[]); int (*fini)(void); void (*idle)(void); void (*dump)(void); void (*config)(void); void (*start)(void); proxy_err_f proxy; const struct snmp_node *tree; u_int tree_size; void (*loading)(const struct lmodule *, int); }; .Ed .Pp This structure must be statically initialized and its fields have the following functions: .Bl -tag -width ".It Va tree_size" .It Va comment This is a string that will be visible in the module table. It should give some hint about the function of this module. .It Va init This function is called upon loading the module. The module pointer should be stored by the module because it is needed in other calls and the argument vector will contain the arguments to this module from the daemons command line. This function should return 0 if everything is ok or an UNIX error code (see .Xr errno 3 ) . Once the function returns 0, the .Va fini function is called when the module is unloaded. .It Va fini The module is unloaded. This gives the module a chance to free resources that are not automatically freed. Be sure to free all memory, because daemons tend to run very long. This function pointer may be .Li NULL if it is not needed. .It Va idle If this function pointer is not .Li NULL , the function pointed to by it is called whenever the daemon is going to wait for an event. Try to avoid using this feature. .It Va dump Whenever the daemon receives a .Li SIGUSR1 it dumps it internal state via .Xr syslog 3 . If the .Va dump field is not .Li NULL it is called by the daemon to dump the state of the module. .It Va config Whenever the daemon receives a .Li SIGHUP signal it re-reads its configuration file. If the .Va config field is not .Li NULL it is called after reading the configuration file to give the module a chance to adapt to the new configuration. .It Va start If not .Li NULL this function is called after successful loading and initializing the module to start its actual operation. .It Va proxy If the daemon receives a PDU and that PDU has a community string whose community was registered by this module and .Va proxy is not .Li NULL than this function is called to handle the PDU. .It Va tree This is a pointer to the node array for the MIB tree implemented by this module. .It Va tree_size This is the number of nodes in .Va tree . .It Va loading If this pointer is not .Li NULL it is called whenever another module was loaded or unloaded. It gets a pointer to that module and a flag that is 0 for unloading and 1 for loading. .El .Pp When everything is ok, the daemon merges the module's MIB tree into its current global tree, calls the modules .Fn init function. If this function returns an error, the modules MIB tree is removed from the global one and the module is unloaded. If initialization is successful, the modules .Fn start function is called. After it returns the .Fn loaded functions of all modules (including the loaded one) are called. .Pp When the module is unloaded, its MIB tree is removed from the global one, the communities, request id ranges, running timers and selected file descriptors are released, the .Fn fini function is called, the module file is unloaded and the .Fn loaded functions of all other modules are called. .Ss IMPLEMENTING TABLES There are a number of macros designed to help implementing SNMP tables. A problem while implementing a table is the support for the GETNEXT operator. The GETNEXT operation has to find out whether, given an arbitrary OID, the lessest table row, that has an OID higher than the given OID. The easiest way to do this is to keep the table as an ordered list of structures each one of which contains an OID that is the index of the table row. This allows easy removal, insertion and search. .Pp The helper macros assume, that the table is organized as a TAILQ (see .Xr queue 3 and each structure contains a .Vt struct asn_oid that is used as index. For simple tables with only a integer or unsigned index, an alternate form of the macros is available, that presume the existence of an integer or unsigned field as index field. .Pp The macros have name of the form .Bd -literal -offset indent {INSERT,FIND,NEXT}_OBJECT_{OID,INT}[_LINK[_INDEX]] .Ed .Pp The .Fn INSERT_* macros are used in the SET operation to insert a new table row into the table. The .Fn FIND_* macros are used in the GET operation to find a specific row in the table. The .Fn NEXT_* macros are used in the GETNEXT operation to find the next row in the table. The last two macros return a pointer to the row structure if a row is found, .Li NULL otherwise. The macros .Fn *_OBJECT_OID_* assume the existence of a .Vt struct asn_oid that is used as index, the macros .Fn *_OBJECT_INT_* assume the existence of an unsigned integer field that is used as index. .Pp The macros .Fn *_INDEX allow the explicit naming of the index field in the parameter .Fa INDEX , whereas the other macros assume that this field is named .Va index . The macros .Fn *_LINK_* allow the explicit naming of the link field of the tail queues, the others assume that the link field is named .Va link . Explicitly naming the link field may be necessary if the same structures are held in two or more different tables. .Pp The arguments to the macros are as follows: .Bl -tag -width "INDEX" .It Fa PTR A pointer to the new structure to be inserted into the table. .It Fa LIST A pointer to the tail queue head. .It Fa LINK The name of the link field in the row structure. .It Fa INDEX The name of the index field in the row structure. .It Fa OID Must point to the .Va var field of the .Fa value argument to the node operation callback. This is the OID to search for. .It Fa SUB This is the index of the start of the table index in the OID pointed to by .Fa OID . This is usually the same as the .Fa sub argument to the node operation callback. .El .Ss DAEMON TIMESTAMPS The variable .Va this_tick contains the tick (there are 100 SNMP ticks in a second) when the current PDU processing was started. The variable .Va start_tick contains the tick when the daemon was started. The function .Fn get_ticks returns the current tick. The number of ticks since the daemon was started is .Bd -literal -offset indent get_ticks() - start_tick .Ed .Ss THE SYSTEM GROUP The scalar fields of the system group are held in the global variable .Va systemg : .Bd -literal -offset indent struct systemg { u_char *descr; struct asn_oid object_id; u_char *contact; u_char *name; u_char *location; uint32_t services; uint32_t or_last_change; }; .Ed .Ss COMMUNITIES The SNMP daemon implements a community table. On recipte of a request message the community string in that message is compared to each of the community strings in that table, if a match is found, the global variable .Va community is set to the community identifier for that community. Community identifiers are unsigned integers. For the three standard communities there are three constants defined: .Bd -literal -offset indent #define COMM_INITIALIZE 0 #define COMM_READ 1 #define COMM_WRITE 2 .Ed .Pp .Va community is set to .Li COMM_INITIALIZE while the assignments in the configuration file are processed. To .Li COMM_READ or .Li COMM_WRITE when the community strings for the read-write or read-only community are found in the incoming PDU. .Pp Modules can define additional communities. This may be necessary to provide transport proxying (a PDU received on one communication link is proxied to another link) or to implement non-UDP access points to SNMP. A new community is defined with the function .Fn comm_define . It takes the following parameters: .Bl -tag -width ".It Fa descr" .It Fa priv This is an integer identifying the community to the module. Each module has its own namespace with regard to this parameter. The community table is indexed with the module name and this identifier. .It Fa descr This is a string providing a human readable description of the community. It is visible in the community table. .It Fa mod This is the module defining the community. .It Fa str This is the initial community string. .El .Pp The function returns a globally unique community identifier. If a PDU is received who's community string matches, this identifier is set into the global .Va community . .Pp The function .Fn comm_string returns the current community string for the given community. .Pp All communities defined by a module are automatically released when the module is unloaded. .Ss WELL KNOWN OIDS The global variable .Va oid_zeroDotZero contains the OID 0.0. .Ss REQUEST ID RANGES For modules that implement SNMP client functions besides SNMP agent functions it may be necessary to identify SNMP requests by their identifier to allow easier routing of responses to the correct sub-system. Request id ranges -provide a way to aquire globally non-overlapping sub-ranges of the entire +provide a way to acquire globally non-overlapping sub-ranges of the entire 31-bit id range. .Pp A request id range is allocated with .Fn reqid_allocate . The arguments are: the size of the range and the module allocating the range. For example, the call .Bd -literal -offset indent id = reqid_allocate(1000, module); .Ed .Pp allocates a range of 1000 request ids. The function returns the request id range identifier or 0 if there is not enough identifier space. The function .Fn reqid_base returns the lowest request id in the given range. .Pp Request id are allocated starting at the lowest one linear throughout the range. If the client application may have a lot of outstanding request the range must be large enough so that an id is not reused until it is really expired. .Fn reqid_next returns the sequentially next id in the range. .Pp The function .Fn reqid_istype checks whether the request id .Fa reqid -is withing the range identified by +is within the range identified by .Fa type . The function .Fn reqid_type returns the range identifier for the given .Fa reqid or 0 if the request id is in none of the ranges. .Ss TIMERS The SNMP daemon supports an arbitrary number of timers with SNMP tick granularity. The function .Fn timer_start arranges for the callback .Fa func to be called with the argument .Fa uarg after .Fa ticks SNMP ticks have expired. .Fa mod is the module that starts the timer. These timers are one-shot, they are not restarted. Repeatable timers are started with .Fn timer_start_repeat which takes an additional argument .Fa repeat_ticks . The argument .Fa ticks gives the number of ticks until the first execution of the callback, while .Fa repeat_ticks is the number of ticks between invocations of the callback. Note, that currently the number of initial ticks silently may be set identical to the number of ticks between callback invocations. The function returns a timer identifier that can be used to stop the timer via .Fn timer_stop . If a module is unloaded all timers started by the module that have not expired yet are stopped. .Ss FILE DESCRIPTOR SUPPORT A module may need to get input from socket file descriptors without blocking the daemon (for example to implement alternative SNMP transports). .Pp The function .Fn fd_select causes the callback function .Fa func to be called with the file descriptor .Fa fd and the user argument .Fa uarg whenever the file descriptor .Fa fd can be read or has a close condition. If the file descriptor is not in non-blocking mode, it is set to non-blocking mode. If the callback is not needed anymore, .Fn fd_deselect may be called with the value returned from .Fn fd_select . All file descriptors selected by a module are automatically deselected when the module is unloaded. .Pp To temporarily suspend the file descriptor registration .Fn fd_suspend can be called. This also causes the file descriptor to be switched back to blocking mode if it was blocking prior the call to .Fn fd_select . This is necessary to do synchronous input on a selected socket. The effect of .Fn fd_suspend can be undone with .Fn fd_resume . .Ss OBJECT RESOURCES The system group contains an object resource table. A module may create an entry in this table by calling .Fn or_register with the .Fa oid to be registered, a textual description in .Fa str and a pointer to the module .Fa mod . The registration can be removed with .Fn or_unregister . All registrations of a module are automatically removed if the module is unloaded. .Ss TRANSMIT AND RECEIVE BUFFERS A buffer is allocated via .Fn buf_alloc . The argument must be 1 for transmit and 0 for receive buffers. The function may return .Li NULL if there is no memory available. The current buffersize can be obtained with .Fn buf_size . .Sh PROCESSING PDUS For modules that need to do their own PDU processing (for example for proxying) the following functions are available: .Pp Function .Fn snmp_input_start decodes the PDU, searches the community, and sets the global .Va this_tick . It returns one of the following error codes: .Bl -tag -width ".It Er SNMPD_INPUT_VALBADLEN" .It Er SNMPD_INPUT_OK Everything ok, continue with processing. .It Er SNMPD_INPUT_FAILED The PDU could not be decoded, has a wrong version or an unknown community string. .It Er SNMPD_INPUT_VALBADLEN A SET PDU had a value field in a binding with a wrong length field in an ASN.1 header. .It Er SNMPD_INPUT_VALRANGE A SET PDU had a value field in a binding with a value that is out of range for the given ASN.1 type. .It Er SNMPD_INPUT_VALBADENC A SET PDU had a value field in a binding with wrong ASN.1 encoding. .It Er SNMPD_INPUT_TRUNC The buffer appears to contain a valid begin of a PDU, but is too short. For streaming transports this means that the caller must save what he already has and trying to obtain more input and reissue this input to the function. For datagram transports this means that part of the datagram was lost and the input should be ignored. .El .Pp The function .Fn snmp_input_finish does the other half of processing: if .Fn snmp_input_start did not return OK, tries to construct an error response. If the start was OK, it calls the correct function from .Xr bsnmpagent 3 to execute the request and depending on the outcome constructs a response or error response PDU or ignores the request PDU. It returns either .Er SNMPD_INPUT_OK or .Er SNMPD_INPUT_FAILED . In the first case a response PDU was constructed and should be sent. .Pp The function .Fn snmp_output takes a PDU and encodes it. .Pp The function .Fn snmp_send_port takes a PDU, encodes it and sends it through the given port (identified by the transport and the index in the port table) to the given address. .Pp The function .Fn snmp_send_trap sends a trap to all trap destinations. The arguments are the .Fa oid identifying the trap and a NULL-terminated list of .Vt struct snmp_value pointers that are to be inserted into the trap binding list. .Ss SIMPLE ACTION SUPPORT For simple scalar variables that need no dependencies a number of support functions is available to handle the set, commit, rollback and get. .Pp The following functions are used for OCTET STRING scalars, either NUL terminated or not: .Bl -tag -width "XXXXXXXXX" .It Fn string_save should be called for SNMP_OP_SET. .Fa value and .Fa ctx are the resp\&.\& arguments to the node callback. .Fa valp is a pointer to the pointer that holds the current value and .Fa req_size should be -1 if any size of the string is acceptable or a number larger or equal zero if the string must have a specific size. The function saves the old value in the scratch area (note, that any initial value must have been allocated by .Xr malloc 3 ) , allocates a new string, copies over the new value, NUL-terminates it and sets the new current value. .It Fn string_commit simply frees the saved old value in the scratch area. .It Fn string_rollback frees the new value, and puts back the old one. .It Fn string_get is used for GET or GETNEXT. The function .It Fn string_get_max can be used instead of -.Nf stringto ensure that the returned string has a certain maximum length. +.Fn string_get +to ensure that the returned string has a certain maximum length. If .Fa len is -1, the length is computed via .Xr strlen 3 from the current string value. If the current value is NULL, a OCTET STRING of zero length is returned. .It Fn string_free must be called if either rollback or commit fails to free the saved old value. .El .Pp The following functions are used to process scalars of type IP-address: .Bl -tag -width "XXXXXXXXX" .It Fn ip_save Saves the current value in the scratch area and sets the new value from .Fa valp . .It Fn ip_commit Does nothing. .It Fn ip_rollback Restores the old IP address from the scratch area. .It Fn ip_get Retrieves the IP current address. .El .Pp The following functions handle OID-typed variables: .Bl -tag -width "XXXXXXXXX" .It Fn oid_save Saves the current value in the scratch area by allocating a .Vt struct asn_oid with .Xr malloc 3 and sets the new value from .Fa oid . .It Fn oid_commit Frees the old value in the scratch area. .It Fn oid_rollback Restores the old OID from the scratch area and frees the old OID. .It Fn oid_get Retrieves the OID .El .Ss TABLE INDEX HANDLING The following functions help in handling table indexes: .Bl -tag -width "XXXXXXXXX" .It Fn index_decode Decodes the index part of the OID. The parameter .Fa oid must be a pointer to the .Va var field of the .Fa value argument of the node callback. The .Fa sub argument must be the index of the start of the index in the OID (this is the .Fa sub argument to the node callback). .Fa code is the index expression (parameter .Fa idx to the node callback). These parameters are followed by parameters depending on the syntax of the index elements as follows: .Bl -tag -width ".It Li OCTET STRING" .It Li INTEGER .Vt int32_t * expected as argument. .It Li COUNTER64 .Vt uint64_t * expected as argument. Note, that this syntax is illegal for indexes. .It Li OCTET STRING A .Vt u_char ** and a .Vt size_t * expected as arguments. A buffer is allocated to hold the decoded string. .It Li OID A .Vt struct asn_oid * is expected as argument. .It Li IP ADDRESS A .Vt u_int8_t * expected as argument that points to a buffer of at least four byte. .It Li COUNTER, GAUGE, TIMETICKS A .Vt u_int32_t expected. .It Li NULL No argument expected. .El .It Fn index_compare compares the current variable with an OID. .Fa oid1 and .Fa sub come from the node callback arguments .Fa value->var and .Fa sub resp. .Fa oid2 is the OID to compare to. The function returns -1, 0, +1 when the variable is lesser, equal, higher to the given OID. .Fa oid2 must contain only the index part of the table column. .It Fn index_compare_off is equivalent to .Fn index_compare except that it takes an additional parameter .Fa off that causes it to ignore the first .Fa off components of both indexes. .It Fn index_append appends OID .Fa src beginning at position .Fa sub to .Fa dst . .It Fn index_append_off appends OID .Fa src beginning at position .Fa off to .Fa dst beginning at position .Fa sub + .Fa off . .El .Sh SEE ALSO .Xr gensnmptree 1 , .Xr bsnmpd 1 , .Xr bsnmpagent 3 , .Xr bsnmpclient 3 , .Xr bsnmplib 3 .Sh STANDARDS This implementation conforms to the applicable IETF RFCs and ITU-T recommendations. .Sh AUTHORS -.An Hartmut Brandt Aq harti@freebsd.org +.An Hartmut Brandt Aq harti@FreeBSD.org Index: stable/8/contrib/bsnmp =================================================================== --- stable/8/contrib/bsnmp (revision 211701) +++ stable/8/contrib/bsnmp (revision 211702) Property changes on: stable/8/contrib/bsnmp ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/contrib/bsnmp:r205078,208483,211401-211402,211404