306 lines
7.7 KiB
Groff
306 lines
7.7 KiB
Groff
.\"
|
|
.\" 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 <harti@freebsd.org>
|
|
.\"
|
|
.\" 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
|