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