/contrib/bsnmp/gensnmptree/gensnmptree.1

  1.\"
  2.\" Copyright (c) 2001-2005
  3.\"	Fraunhofer Institute for Open Communication Systems (FhG Fokus).
  4.\"	All rights reserved.
  5.\" Copyright (c) 2006
  6.\"	Hartmut Brandt
  7.\"	All rights reserved.
  8.\"
  9.\" Author: Harti Brandt <harti@FreeBSD.org>
 10.\" 
 11.\" Redistribution and use in source and binary forms, with or without
 12.\" modification, are permitted provided that the following conditions
 13.\" are met:
 14.\" 1. Redistributions of source code must retain the above copyright
 15.\"    notice, this list of conditions and the following disclaimer.
 16.\" 2. Redistributions in binary form must reproduce the above copyright
 17.\"    notice, this list of conditions and the following disclaimer in the
 18.\"    documentation and/or other materials provided with the distribution.
 19.\" 
 20.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 23.\" ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 30.\" SUCH DAMAGE.
 31.\"
 32.\" $Begemot: gensnmptree.1 383 2006-05-30 07:40:49Z brandt_h $
 33.\"
 34.Dd May 26, 2006
 35.Dt GENSNMPTREE 1
 36.Os
 37.Sh NAME
 38.Nm gensnmptree
 39.Nd "generate C and header files from a MIB description file"
 40.Sh SYNOPSIS
 41.Nm
 42.Op Fl dEehlt
 43.Op Fl I Ar directory
 44.Op Fl i Ar infile
 45.Op Fl p Ar prefix
 46.Op Ar name Ar ...
 47.Sh DESCRIPTION
 48The
 49.Nm
 50utility is used to either generate C language tables and header files from
 51a MIB description or to numeric OIDs from MIB descriptions.
 52The first form is used only for maintaining the
 53.Xr bsnmpd 1
 54daemon or for module writers.
 55The second form may be used by SNMP client program writers.
 56.Pp
 57If none of the options
 58.Fl e ,
 59.Fl E
 60or
 61.Fl t
 62are used
 63.Nm
 64reads a MIB description from its standard input and creates two files: a
 65C-file
 66.Ar prefix Ns tree.c
 67containing a table used by
 68.Xr bsnmpd 1
 69during PDU processing
 70and a header file
 71.Ar prefix Ns tree.h
 72containing appropriate declarations of the callback functions used in this
 73table, the table itself and definitions for all enums.
 74.Pp
 75The following options are available:
 76.Bl -tag -width ".Fl E"
 77.It Fl d
 78Switch on debugging.
 79.It Fl E
 80Extract enumerations and bit constructs.
 81In this mode the tool emits
 82a header file that contains for each type given on the command line a
 83C-enum definition and a preprocessor define that may be used to map
 84values to strings.
 85.It Fl e
 86.Nm
 87expects MIB variable names (only the last component) on its command line.
 88It reads a MIB specification from standard input and for each MIB variable
 89name emits three C preprocessor defines on its standard output:
 90.Bl -tag -width ".Va OIDLEN_ Ns Ar Name"
 91.It Va OIDX_ Ns Ar name
 92This define can be used to initialize a
 93.Va struct asn_oid
 94in the following way:
 95.Pp
 96.Dl const struct asn_oid oid_sysDescr = OIDX_sysDescr;
 97.It Va OIDLEN_ Ns Ar name
 98is the length of the OID.
 99.It Va OID_ Ns Ar name
100is the last component of the OID.
101.El
102.It Fl h
103Print a short help page.
104.It Fl I Ar directory
105Add the named directory to the include path just before the standard include
106directories.
107.It Fl i Ar infile
108Read from the named file instead of standard input.
109.It Fl l
110Generate local preprocessor includes.
111This is used for bootstrapping
112.Xr bsnmpd 1 .
113.It Fl t
114Instead of normal output print the resulting tree.
115.It Fl p Ar prefix
116Prefix the file names and the table name with
117.Ar prefix .
118.El
119.Sh MIBS
120The syntax of the MIB description file can formally be specified as follows:
121.Bd -unfilled -offset indent
122 file := top | top file
123
124 top := tree | typedef | include
125
126 tree := head elements ')'
127
128 entry := head ':' index STRING elements ')'
129
130 leaf := head type STRING ACCESS ')'
131
132 column := head type ACCESS ')'
133
134 type := BASETYPE | BASETYPE '|' subtype | enum | bits
135
136 subtype := STRING
137
138 enum := ENUM '(' value ')'
139
140 bits := BITS '(' value ')'
141
142 value := INT STRING | INT STRING value
143
144 head := '(' INT STRING
145
146 elements := EMPTY | elements element
147
148 element := tree | leaf | column
149
150 index := type | index type
151
152 typedef := 'typedef' STRING type
153
154 include := 'include' filespec
155
156 filespec := '"' STRING '"' | '<' STRING '>'
157.Ed
158.Pp
159.Ar BASETYPE
160specifies a SNMP data type and may be one of
161.Bl -bullet -offset indent -compact
162.It
163NULL
164.It
165INTEGER
166.It
167INTEGER32 (same as INTEGER)
168.It
169UNSIGNED32 (same as GAUGE)
170.It
171OCTETSTRING
172.It
173IPADDRESS
174.It
175OID
176.It
177TIMETICKS
178.It
179COUNTER
180.It
181GAUGE
182.It
183COUNTER64
184.El
185.Pp
186.Ar ACCESS
187specifies the accessibility of the MIB variable (which operation can be
188performed) and is one of
189.Bl -bullet -offset indent -compact
190.It
191GET
192.It
193SET
194.El
195.Pp
196.Ar INT
197is a decimal integer and
198.Ar STRING
199is any string starting with a letter or underscore and consisting of
200letters, digits, underscores and minuses, that is not one of the keywords.
201.Pp
202The
203.Ar typedef
204directive associates a type with a single name.
205.Pp
206The
207.Ar include
208directive is replaced by the contents of the named file.
209.Sh EXAMPLES
210The following MIB description describes the system group:
211.Bd -literal -offset indent
212include "tc.def"
213
214typedef AdminStatus ENUM (
215	1 up
216	2 down
217)
218
219(1 internet
220  (2 mgmt
221    (1 mibII
222      (1 system
223        (1 sysDescr OCTETSTRING op_system_group GET)
224        (2 sysObjectId OID op_system_group GET)
225        (3 sysUpTime TIMETICKS op_system_group GET)
226        (4 sysContact OCTETSTRING op_system_group GET SET)
227        (5 sysName OCTETSTRING op_system_group GET SET)
228        (6 sysLocation OCTETSTRING op_system_group GET SET)
229        (7 sysServices INTEGER op_system_group GET)
230        (8 sysORLastChange TIMETICKS op_system_group GET)
231        (9 sysORTable
232          (1 sysOREntry : INTEGER op_or_table
233            (1 sysORIndex INTEGER)
234            (2 sysORID OID GET)
235            (3 sysORDescr OCTETSTRING GET)
236            (4 sysORUpTime TIMETICKS GET)
237        ))
238      )
239    )
240  )
241)
242.Ed
243.Sh SEE ALSO
244.Xr bsnmpd 1
245.Sh AUTHORS
246.An Hartmut Brandt Aq harti@FreeBSD.org