1.\"
2.\" Copyright (c) 2004-2005
3.\" Hartmut Brandt.
4.\" All rights reserved.
5.\" Copyright (c) 2001-2003
6.\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
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: bsnmp/snmpd/snmpmod.3,v 1.14 2005/10/04 13:30:35 brandt_h Exp $
33.\"
| 1.\"
2.\" Copyright (c) 2004-2005
3.\" Hartmut Brandt.
4.\" All rights reserved.
5.\" Copyright (c) 2001-2003
6.\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
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: bsnmp/snmpd/snmpmod.3,v 1.14 2005/10/04 13:30:35 brandt_h Exp $
33.\"
|
34.Dd February 27, 2006
| 34.Dd September 9, 2010
|
35.Dt SNMPMOD 3
36.Os
37.Sh NAME
38.Nm INSERT_OBJECT_OID_LINK_INDEX ,
39.Nm INSERT_OBJECT_INT_LINK_INDEX ,
40.Nm FIND_OBJECT_OID_LINK_INDEX ,
41.Nm NEXT_OBJECT_OID_LINK_INDEX ,
42.Nm FIND_OBJECT_INT_LINK_INDEX ,
43.Nm NEXT_OBJECT_INT_LINK_INDEX ,
44.Nm INSERT_OBJECT_OID_LINK ,
45.Nm INSERT_OBJECT_INT_LINK ,
46.Nm FIND_OBJECT_OID_LINK ,
47.Nm NEXT_OBJECT_OID_LINK ,
48.Nm FIND_OBJECT_INT_LINK ,
49.Nm NEXT_OBJECT_INT_LINK ,
50.Nm INSERT_OBJECT_OID ,
51.Nm INSERT_OBJECT_INT ,
52.Nm FIND_OBJECT_OID ,
53.Nm FIND_OBJECT_INT ,
54.Nm NEXT_OBJECT_OID ,
55.Nm NEXT_OBJECT_INT ,
56.Nm this_tick ,
57.Nm start_tick ,
58.Nm get_ticks ,
59.Nm systemg ,
60.Nm comm_define ,
61.Nm community ,
62.Nm oid_zeroDotZero ,
| 35.Dt SNMPMOD 3
36.Os
37.Sh NAME
38.Nm INSERT_OBJECT_OID_LINK_INDEX ,
39.Nm INSERT_OBJECT_INT_LINK_INDEX ,
40.Nm FIND_OBJECT_OID_LINK_INDEX ,
41.Nm NEXT_OBJECT_OID_LINK_INDEX ,
42.Nm FIND_OBJECT_INT_LINK_INDEX ,
43.Nm NEXT_OBJECT_INT_LINK_INDEX ,
44.Nm INSERT_OBJECT_OID_LINK ,
45.Nm INSERT_OBJECT_INT_LINK ,
46.Nm FIND_OBJECT_OID_LINK ,
47.Nm NEXT_OBJECT_OID_LINK ,
48.Nm FIND_OBJECT_INT_LINK ,
49.Nm NEXT_OBJECT_INT_LINK ,
50.Nm INSERT_OBJECT_OID ,
51.Nm INSERT_OBJECT_INT ,
52.Nm FIND_OBJECT_OID ,
53.Nm FIND_OBJECT_INT ,
54.Nm NEXT_OBJECT_OID ,
55.Nm NEXT_OBJECT_INT ,
56.Nm this_tick ,
57.Nm start_tick ,
58.Nm get_ticks ,
59.Nm systemg ,
60.Nm comm_define ,
61.Nm community ,
62.Nm oid_zeroDotZero ,
|
| 63.Nm oid_usmUnknownEngineIDs ,
64.Nm oid_usmNotInTimeWindows ,
|
63.Nm reqid_allocate ,
64.Nm reqid_next ,
65.Nm reqid_base ,
66.Nm reqid_istype ,
67.Nm reqid_type ,
68.Nm timer_start ,
69.Nm timer_start_repeat ,
70.Nm timer_stop ,
71.Nm fd_select ,
72.Nm fd_deselect ,
73.Nm fd_suspend ,
74.Nm fd_resume ,
75.Nm or_register ,
76.Nm or_unregister ,
77.Nm buf_alloc ,
78.Nm buf_size ,
79.Nm snmp_input_start ,
80.Nm snmp_input_finish ,
81.Nm snmp_output ,
82.Nm snmp_send_port ,
83.Nm snmp_send_trap ,
84.Nm string_save ,
85.Nm string_commit ,
86.Nm string_rollback ,
87.Nm string_get ,
88.Nm string_get_max ,
89.Nm string_free ,
90.Nm ip_save ,
91.Nm ip_rollback ,
92.Nm ip_commit ,
93.Nm ip_get ,
94.Nm oid_save ,
95.Nm oid_rollback ,
96.Nm oid_commit ,
97.Nm oid_get ,
98.Nm index_decode ,
99.Nm index_compare ,
100.Nm index_compare_off ,
101.Nm index_append ,
| 65.Nm reqid_allocate ,
66.Nm reqid_next ,
67.Nm reqid_base ,
68.Nm reqid_istype ,
69.Nm reqid_type ,
70.Nm timer_start ,
71.Nm timer_start_repeat ,
72.Nm timer_stop ,
73.Nm fd_select ,
74.Nm fd_deselect ,
75.Nm fd_suspend ,
76.Nm fd_resume ,
77.Nm or_register ,
78.Nm or_unregister ,
79.Nm buf_alloc ,
80.Nm buf_size ,
81.Nm snmp_input_start ,
82.Nm snmp_input_finish ,
83.Nm snmp_output ,
84.Nm snmp_send_port ,
85.Nm snmp_send_trap ,
86.Nm string_save ,
87.Nm string_commit ,
88.Nm string_rollback ,
89.Nm string_get ,
90.Nm string_get_max ,
91.Nm string_free ,
92.Nm ip_save ,
93.Nm ip_rollback ,
94.Nm ip_commit ,
95.Nm ip_get ,
96.Nm oid_save ,
97.Nm oid_rollback ,
98.Nm oid_commit ,
99.Nm oid_get ,
100.Nm index_decode ,
101.Nm index_compare ,
102.Nm index_compare_off ,
103.Nm index_append ,
|
102.Nm index_append_off
| 104.Nm index_append_off,
105.Nm bsnmpd_get_usm_stats,
106.Nm bsnmpd_reset_usm_stats,
107.Nm usm_first_user,
108.Nm usm_next_user,
109.Nm usm_find_user,
110.Nm usm_new_user,
111.Nm usm_delete_user,
112.Nm usm_flush_users,
113.Nm usm_user
|
103.Nd "SNMP daemon loadable module interface"
104.Sh LIBRARY
105Begemot SNMP library
106.Pq libbsnmp, -lbsnmp
107.Sh SYNOPSIS
108.In bsnmp/snmpmod.h
109.Fn INSERT_OBJECT_OID_LINK_INDEX "PTR" "LIST" "LINK" "INDEX"
110.Fn INSERT_OBJECT_INT_LINK_INDEX "PTR" "LIST" "LINK" "INDEX"
111.Fn FIND_OBJECT_OID_LINK_INDEX "LIST" "OID" "SUB" "LINK" "INDEX"
112.Fn FIND_OBJECT_INT_LINK_INDEX "LIST" "OID" "SUB" "LINK" "INDEX"
113.Fn NEXT_OBJECT_OID_LINK_INDEX "LIST" "OID" "SUB" "LINK" "INDEX"
114.Fn NEXT_OBJECT_INT_LINK_INDEX "LIST" "OID" "SUB" "LINK" "INDEX"
115.Fn INSERT_OBJECT_OID_LINK "PTR" "LIST" "LINK"
116.Fn INSERT_OBJECT_INT_LINK "PTR" "LIST" "LINK"
117.Fn FIND_OBJECT_OID_LINK "LIST" "OID" "SUB" "LINK"
118.Fn FIND_OBJECT_INT_LINK "LIST" "OID" "SUB" "LINK"
119.Fn NEXT_OBJECT_OID_LINK "LIST" "OID" "SUB" "LINK"
120.Fn NEXT_OBJECT_INT_LINK "LIST" "OID" "SUB" "LINK"
121.Fn INSERT_OBJECT_OID "PTR" "LIST"
122.Fn INSERT_OBJECT_INT "PTR" "LIST"
123.Fn FIND_OBJECT_OID "LIST" "OID" "SUB"
124.Fn FIND_OBJECT_INT "LIST" "OID" "SUB"
125.Fn NEXT_OBJECT_OID "LIST" "OID" "SUB"
126.Fn NEXT_OBJECT_INT "LIST" "OID" "SUB"
127.Vt extern uint64_t this_tick ;
128.Vt extern uint64_t start_tick ;
129.Ft uint64_t
130.Fn get_ticks "void"
131.Vt extern struct systemg systemg ;
132.Ft u_int
133.Fn comm_define "u_int priv" "const char *descr" "struct lmodule *mod" "const char *str"
134.Ft const char *
135.Fn comm_string "u_int comm"
136.Vt extern u_int community ;
137.Vt extern const struct asn_oid oid_zeroDotZero ;
138.Ft u_int
139.Fn reqid_allocate "int size" "struct lmodule *mod"
140.Ft int32_t
141.Fn reqid_next "u_int type"
142.Ft int32_t
143.Fn reqid_base "u_int type"
144.Ft int
145.Fn reqid_istype "int32_t reqid" "u_int type"
146.Ft u_int
147.Fn reqid_type "int32_t reqid"
148.Ft void *
149.Fn timer_start "u_int ticks" "void (*func)(void *)" "void *uarg" "struct lmodule *mod"
150.Ft void *
151.Fn timer_start_repeat "u_int ticks" "u_int repeat_ticks" "void (*func)(void *)" "void *uarg" "struct lmodule *mod"
152.Ft void
153.Fn timer_stop "void *timer_id"
154.Ft void *
155.Fn fd_select "int fd" "void (*func)(int, void *)" "void *uarg" "struct lmodule *mod"
156.Ft void
157.Fn fd_deselect "void *fd_id"
158.Ft void
159.Fn fd_suspend "void *fd_id"
160.Ft int
161.Fn fd_resume "void *fd_id"
162.Ft u_int
163.Fn or_register "const struct asn_oid *oid" "const char *descr" "struct lmodule *mod"
164.Ft void
165.Fn or_unregister "u_int or_id"
166.Ft void *
167.Fn buf_alloc "int tx"
168.Ft size_t
169.Fn buf_size "int tx"
170.Ft enum snmpd_input_err
171.Fo snmp_input_start
172.Fa "const u_char *buf" "size_t len" "const char *source"
173.Fa "struct snmp_pdu *pdu" "int32_t *ip" "size_t *pdulen"
174.Fc
175.Ft enum snmpd_input_err
176.Fo snmp_input_finish
177.Fa "struct snmp_pdu *pdu" "const u_char *rcvbuf"
178.Fa "size_t rcvlen" "u_char *sndbuf" "size_t *sndlen" "const char *source"
179.Fa "enum snmpd_input_err ierr" "int32_t ip" "void *data"
180.Fc
181.Ft void
182.Fo snmp_output
183.Fa "struct snmp_pdu *pdu" "u_char *sndbuf" "size_t *sndlen"
184.Fa "const char *dest"
185.Fc
186.Ft void
187.Fo snmp_send_port
188.Fa "void *trans" "const struct asn_oid *port"
189.Fa "struct snmp_pdu *pdu" "const struct sockaddr *addr" "socklen_t addrlen"
190.Fc
191.Ft void
192.Fn snmp_send_trap "const struct asn_oid *oid" "..."
193.Ft int
194.Fn string_save "struct snmp_value *val" "struct snmp_context *ctx" "ssize_t req_size" "u_char **strp"
195.Ft void
196.Fn string_commit "struct snmp_context *ctx"
197.Ft void
198.Fn string_rollback "struct snmp_context *ctx" "u_char **strp"
199.Ft int
200.Fn string_get "struct snmp_value *val" "const u_char *str" "ssize_t len"
201.Ft int
202.Fn string_get_max "struct snmp_value *val" "const u_char *str" "ssize_t len" "size_t maxlen"
203.Ft void
204.Fn string_free "struct snmp_context *ctx"
205.Ft int
206.Fn ip_save "struct snmp_value *val" "struct snmp_context *ctx" "u_char *ipa"
207.Ft void
208.Fn ip_rollback "struct snmp_context *ctx" "u_char *ipa"
209.Ft void
210.Fn ip_commit "struct snmp_context *ctx"
211.Ft int
212.Fn ip_get "struct snmp_value *val" "u_char *ipa"
213.Ft int
214.Fn oid_save "struct snmp_value *val" "struct snmp_context *ctx" "struct asn_oid *oid"
215.Ft void
216.Fn oid_rollback "struct snmp_context *ctx" "struct asn_oid *oid"
217.Ft void
218.Fn oid_commit "struct snmp_context *ctx"
219.Ft int
220.Fn oid_get "struct snmp_value *val" "const struct asn_oid *oid"
221.Ft int
222.Fn index_decode "const struct asn_oid *oid" "u_int sub" "u_int code" "..."
223.Ft int
224.Fn index_compare "const struct asn_oid *oid1" "u_int sub" "const struct asn_oid *oid2"
225.Ft int
226.Fn index_compare_off "const struct asn_oid *oid1" "u_int sub" "const struct asn_oid *oid2" "u_int off"
227.Ft void
228.Fn index_append "struct asn_oid *dst" "u_int sub" "const struct asn_oid *src"
229.Ft void
230.Fn index_append_off "struct asn_oid *dst" "u_int sub" "const struct asn_oid *src" "u_int off"
| 114.Nd "SNMP daemon loadable module interface"
115.Sh LIBRARY
116Begemot SNMP library
117.Pq libbsnmp, -lbsnmp
118.Sh SYNOPSIS
119.In bsnmp/snmpmod.h
120.Fn INSERT_OBJECT_OID_LINK_INDEX "PTR" "LIST" "LINK" "INDEX"
121.Fn INSERT_OBJECT_INT_LINK_INDEX "PTR" "LIST" "LINK" "INDEX"
122.Fn FIND_OBJECT_OID_LINK_INDEX "LIST" "OID" "SUB" "LINK" "INDEX"
123.Fn FIND_OBJECT_INT_LINK_INDEX "LIST" "OID" "SUB" "LINK" "INDEX"
124.Fn NEXT_OBJECT_OID_LINK_INDEX "LIST" "OID" "SUB" "LINK" "INDEX"
125.Fn NEXT_OBJECT_INT_LINK_INDEX "LIST" "OID" "SUB" "LINK" "INDEX"
126.Fn INSERT_OBJECT_OID_LINK "PTR" "LIST" "LINK"
127.Fn INSERT_OBJECT_INT_LINK "PTR" "LIST" "LINK"
128.Fn FIND_OBJECT_OID_LINK "LIST" "OID" "SUB" "LINK"
129.Fn FIND_OBJECT_INT_LINK "LIST" "OID" "SUB" "LINK"
130.Fn NEXT_OBJECT_OID_LINK "LIST" "OID" "SUB" "LINK"
131.Fn NEXT_OBJECT_INT_LINK "LIST" "OID" "SUB" "LINK"
132.Fn INSERT_OBJECT_OID "PTR" "LIST"
133.Fn INSERT_OBJECT_INT "PTR" "LIST"
134.Fn FIND_OBJECT_OID "LIST" "OID" "SUB"
135.Fn FIND_OBJECT_INT "LIST" "OID" "SUB"
136.Fn NEXT_OBJECT_OID "LIST" "OID" "SUB"
137.Fn NEXT_OBJECT_INT "LIST" "OID" "SUB"
138.Vt extern uint64_t this_tick ;
139.Vt extern uint64_t start_tick ;
140.Ft uint64_t
141.Fn get_ticks "void"
142.Vt extern struct systemg systemg ;
143.Ft u_int
144.Fn comm_define "u_int priv" "const char *descr" "struct lmodule *mod" "const char *str"
145.Ft const char *
146.Fn comm_string "u_int comm"
147.Vt extern u_int community ;
148.Vt extern const struct asn_oid oid_zeroDotZero ;
149.Ft u_int
150.Fn reqid_allocate "int size" "struct lmodule *mod"
151.Ft int32_t
152.Fn reqid_next "u_int type"
153.Ft int32_t
154.Fn reqid_base "u_int type"
155.Ft int
156.Fn reqid_istype "int32_t reqid" "u_int type"
157.Ft u_int
158.Fn reqid_type "int32_t reqid"
159.Ft void *
160.Fn timer_start "u_int ticks" "void (*func)(void *)" "void *uarg" "struct lmodule *mod"
161.Ft void *
162.Fn timer_start_repeat "u_int ticks" "u_int repeat_ticks" "void (*func)(void *)" "void *uarg" "struct lmodule *mod"
163.Ft void
164.Fn timer_stop "void *timer_id"
165.Ft void *
166.Fn fd_select "int fd" "void (*func)(int, void *)" "void *uarg" "struct lmodule *mod"
167.Ft void
168.Fn fd_deselect "void *fd_id"
169.Ft void
170.Fn fd_suspend "void *fd_id"
171.Ft int
172.Fn fd_resume "void *fd_id"
173.Ft u_int
174.Fn or_register "const struct asn_oid *oid" "const char *descr" "struct lmodule *mod"
175.Ft void
176.Fn or_unregister "u_int or_id"
177.Ft void *
178.Fn buf_alloc "int tx"
179.Ft size_t
180.Fn buf_size "int tx"
181.Ft enum snmpd_input_err
182.Fo snmp_input_start
183.Fa "const u_char *buf" "size_t len" "const char *source"
184.Fa "struct snmp_pdu *pdu" "int32_t *ip" "size_t *pdulen"
185.Fc
186.Ft enum snmpd_input_err
187.Fo snmp_input_finish
188.Fa "struct snmp_pdu *pdu" "const u_char *rcvbuf"
189.Fa "size_t rcvlen" "u_char *sndbuf" "size_t *sndlen" "const char *source"
190.Fa "enum snmpd_input_err ierr" "int32_t ip" "void *data"
191.Fc
192.Ft void
193.Fo snmp_output
194.Fa "struct snmp_pdu *pdu" "u_char *sndbuf" "size_t *sndlen"
195.Fa "const char *dest"
196.Fc
197.Ft void
198.Fo snmp_send_port
199.Fa "void *trans" "const struct asn_oid *port"
200.Fa "struct snmp_pdu *pdu" "const struct sockaddr *addr" "socklen_t addrlen"
201.Fc
202.Ft void
203.Fn snmp_send_trap "const struct asn_oid *oid" "..."
204.Ft int
205.Fn string_save "struct snmp_value *val" "struct snmp_context *ctx" "ssize_t req_size" "u_char **strp"
206.Ft void
207.Fn string_commit "struct snmp_context *ctx"
208.Ft void
209.Fn string_rollback "struct snmp_context *ctx" "u_char **strp"
210.Ft int
211.Fn string_get "struct snmp_value *val" "const u_char *str" "ssize_t len"
212.Ft int
213.Fn string_get_max "struct snmp_value *val" "const u_char *str" "ssize_t len" "size_t maxlen"
214.Ft void
215.Fn string_free "struct snmp_context *ctx"
216.Ft int
217.Fn ip_save "struct snmp_value *val" "struct snmp_context *ctx" "u_char *ipa"
218.Ft void
219.Fn ip_rollback "struct snmp_context *ctx" "u_char *ipa"
220.Ft void
221.Fn ip_commit "struct snmp_context *ctx"
222.Ft int
223.Fn ip_get "struct snmp_value *val" "u_char *ipa"
224.Ft int
225.Fn oid_save "struct snmp_value *val" "struct snmp_context *ctx" "struct asn_oid *oid"
226.Ft void
227.Fn oid_rollback "struct snmp_context *ctx" "struct asn_oid *oid"
228.Ft void
229.Fn oid_commit "struct snmp_context *ctx"
230.Ft int
231.Fn oid_get "struct snmp_value *val" "const struct asn_oid *oid"
232.Ft int
233.Fn index_decode "const struct asn_oid *oid" "u_int sub" "u_int code" "..."
234.Ft int
235.Fn index_compare "const struct asn_oid *oid1" "u_int sub" "const struct asn_oid *oid2"
236.Ft int
237.Fn index_compare_off "const struct asn_oid *oid1" "u_int sub" "const struct asn_oid *oid2" "u_int off"
238.Ft void
239.Fn index_append "struct asn_oid *dst" "u_int sub" "const struct asn_oid *src"
240.Ft void
241.Fn index_append_off "struct asn_oid *dst" "u_int sub" "const struct asn_oid *src" "u_int off"
|
| 242.Ft struct snmpd_usmstat *
243.Fn bsnmpd_get_usm_stats "void"
244.Ft void
245.Fn bsnmpd_reset_usm_stats "void"
246.Ft struct usm_user *
247.Fn usm_first_user "void"
248.Ft struct usm_user *
249.Fn usm_next_user "struct usm_user *uuser"
250.Ft struct usm_user *
251.Fn usm_find_user "uint8_t *engine" "uint32_t elen" "char *uname"
252.Ft struct usm_user *
253.Fn usm_new_user "uint8_t *engine" "uint32_t elen" "char *uname"
254.Ft void
255.Fn usm_delete_user "struct usm_user *"
256.Ft void
257.Fn usm_flush_users "void"
258.Vt extern struct usm_user *usm_user;
259.Vt extern const struct asn_oid oid_usmUnknownEngineIDs;
260.Vt extern const struct asn_oid oid_usmNotInTimeWindows;
|
231.Sh DESCRIPTION
232The
233.Xr bsnmpd 1
234SNMP daemon implements a minimal MIB which consists of the system group, part
235of the SNMP MIB, a private configuration MIB, a trap destination table, a
236UDP port table, a community table, a module table, a statistics group and
237a debugging group.
238All other MIBs are support through loadable modules.
239This allows
240.Xr bsnmpd 1
241to use for task, that are not the classical SNMP task.
242.Ss MODULE LOADING AND UNLOADING
243Modules are loaded by writing to the module table.
244This table is indexed by a string, that identifies the module to the daemon.
245This identifier is used
246to select the correct configuration section from the configuration files and
247to identify resources allocated to this module.
248A row in the module table is
249created by writing a string of non-zero length to the
250.Va begemotSnmpdModulePath
251column.
252This string must be the complete path to the file containing the module.
253A module can be unloaded by writing a zero length string to the path column
254of an existing row.
255.Pp
256Modules may depend on each other an hence must be loaded in the correct order.
257The dependencies are listed in the corresponding manual pages.
258.Pp
259Upon loading a module the SNMP daemon expects the module file to a export
260a global symbol
261.Va config .
262This symbol should be a variable of type
263.Vt struct snmp_module :
264.Bd -literal -offset indent
265typedef enum snmpd_proxy_err (*proxy_err_f)(struct snmp_pdu *, void *,
266 const struct asn_oid *, const struct sockaddr *, socklen_t,
267 enum snmpd_input_err, int32_t);
268
269
270struct snmp_module {
271 const char *comment;
272 int (*init)(struct lmodule *, int argc, char *argv[]);
273 int (*fini)(void);
274 void (*idle)(void);
275 void (*dump)(void);
276 void (*config)(void);
277 void (*start)(void);
278 proxy_err_f proxy;
279 const struct snmp_node *tree;
280 u_int tree_size;
281 void (*loading)(const struct lmodule *, int);
282};
283.Ed
284.Pp
285This structure must be statically initialized and its fields have the
286following functions:
287.Bl -tag -width ".It Va tree_size"
288.It Va comment
289This is a string that will be visible in the module table.
290It should give some hint about the function of this module.
291.It Va init
292This function is called upon loading the module.
293The module pointer should
294be stored by the module because it is needed in other calls and the
295argument vector will contain the arguments to this module from the daemons
296command line.
297This function should return 0 if everything is ok or an UNIX error code (see
298.Xr errno 3 ) .
299Once the function returns 0, the
300.Va fini
301function is called when the module is unloaded.
302.It Va fini
303The module is unloaded.
304This gives the module a chance to free resources that
305are not automatically freed.
306Be sure to free all memory, because daemons tend to run very long.
307This function pointer may be
308.Li NULL
309if it is not needed.
310.It Va idle
311If this function pointer is not
312.Li NULL ,
313the function pointed to by it is called whenever the daemon is going
314to wait for an event.
315Try to avoid using this feature.
316.It Va dump
317Whenever the daemon receives a
318.Li SIGUSR1
319it dumps it internal state via
320.Xr syslog 3 .
321If the
322.Va dump
323field is not
324.Li NULL
325it is called by the daemon to dump the state of the module.
326.It Va config
327Whenever the daemon receives a
328.Li SIGHUP
329signal it re-reads its configuration file.
330If the
331.Va config
332field is not
333.Li NULL
334it is called after reading the configuration file to give the module a chance
335to adapt to the new configuration.
336.It Va start
337If not
338.Li NULL
339this function is called after successful loading and initializing the module
340to start its actual operation.
341.It Va proxy
342If the daemon receives a PDU and that PDU has a community string whose
343community was registered by this module and
344.Va proxy
345is not
346.Li NULL
347than this function is called to handle the PDU.
348.It Va tree
349This is a pointer to the node array for the MIB tree implemented by this module.
350.It Va tree_size
351This is the number of nodes in
352.Va tree .
353.It Va loading
354If this pointer is not
355.Li NULL
356it is called whenever another module was loaded or unloaded.
357It gets a
358pointer to that module and a flag that is 0 for unloading and 1 for loading.
359.El
360.Pp
361When everything is ok, the daemon merges the module's MIB tree into its current
362global tree, calls the modules
363.Fn init
364function.
365If this function returns an error, the modules MIB tree is removed from
366the global one and the module is unloaded.
367If initialization is successful, the modules
368.Fn start
369function is called.
370After it returns the
371.Fn loaded
372functions of all modules (including the loaded one) are called.
373.Pp
374When the module is unloaded, its MIB tree is removed from the global one,
375the communities, request id ranges, running timers and selected file
376descriptors are released, the
377.Fn fini
378function is called, the module file is unloaded and the
379.Fn loaded
380functions of all other modules are called.
381.Ss IMPLEMENTING TABLES
382There are a number of macros designed to help implementing SNMP tables.
383A problem while implementing a table is the support for the GETNEXT operator.
384The GETNEXT operation has to find out whether, given an arbitrary OID, the
385lessest table row, that has an OID higher than the given OID.
386The easiest way
387to do this is to keep the table as an ordered list of structures each one
388of which contains an OID that is the index of the table row.
389This allows easy removal, insertion and search.
390.Pp
391The helper macros assume, that the table is organized as a TAILQ (see
392.Xr queue 3
393and each structure contains a
394.Vt struct asn_oid
395that is used as index.
396For simple tables with only a integer or unsigned index, an alternate form
397of the macros is available, that presume the existence of an integer or
398unsigned field as index field.
399.Pp
400The macros have name of the form
401.Bd -literal -offset indent
402{INSERT,FIND,NEXT}_OBJECT_{OID,INT}[_LINK[_INDEX]]
403.Ed
404.Pp
405The
406.Fn INSERT_*
407macros are used in the SET operation to insert a new table row into the table.
408The
409.Fn FIND_*
410macros are used in the GET operation to find a specific row in the table.
411The
412.Fn NEXT_*
413macros are used in the GETNEXT operation to find the next row in the table.
414The last two macros return a pointer to the row structure if a row is found,
415.Li NULL
416otherwise.
417The macros
418.Fn *_OBJECT_OID_*
419assume the existence of a
420.Vt struct asn_oid
421that is used as index, the macros
422.Fn *_OBJECT_INT_*
423assume the existence of an unsigned integer field that is used as index.
424.Pp
425The macros
426.Fn *_INDEX
427allow the explicit naming of the index field in the parameter
428.Fa INDEX ,
429whereas the other macros assume that this field is named
430.Va index .
431The macros
432.Fn *_LINK_*
433allow the explicit naming of the link field of the tail queues, the others
434assume that the link field is named
435.Va link .
436Explicitly naming the link field may be necessary if the same structures
437are held in two or more different tables.
438.Pp
439The arguments to the macros are as follows:
440.Bl -tag -width "INDEX"
441.It Fa PTR
442A pointer to the new structure to be inserted into the table.
443.It Fa LIST
444A pointer to the tail queue head.
445.It Fa LINK
446The name of the link field in the row structure.
447.It Fa INDEX
448The name of the index field in the row structure.
449.It Fa OID
450Must point to the
451.Va var
452field of the
453.Fa value
454argument to the node operation callback.
455This is the OID to search for.
456.It Fa SUB
457This is the index of the start of the table index in the OID pointed to
458by
459.Fa OID .
460This is usually the same as the
461.Fa sub
462argument to the node operation callback.
463.El
464.Ss DAEMON TIMESTAMPS
465The variable
466.Va this_tick
467contains the tick (there are 100 SNMP ticks in a second) when
468the current PDU processing was started.
469The variable
470.Va start_tick
471contains the tick when the daemon was started.
472The function
473.Fn get_ticks
474returns the current tick.
475The number of ticks since the daemon was started
476is
477.Bd -literal -offset indent
478get_ticks() - start_tick
479.Ed
480.Ss THE SYSTEM GROUP
481The scalar fields of the system group are held in the global variable
482.Va systemg :
483.Bd -literal -offset indent
484struct systemg {
485 u_char *descr;
486 struct asn_oid object_id;
487 u_char *contact;
488 u_char *name;
489 u_char *location;
490 uint32_t services;
491 uint32_t or_last_change;
492};
493.Ed
494.Ss COMMUNITIES
495The SNMP daemon implements a community table.
496On recipte of a request message
497the community string in that message is compared to each of the community
498strings in that table, if a match is found, the global variable
499.Va community
500is set to the community identifier for that community.
501Community identifiers are unsigned integers.
502For the three standard communities there are three constants defined:
503.Bd -literal -offset indent
504#define COMM_INITIALIZE 0
505#define COMM_READ 1
506#define COMM_WRITE 2
507.Ed
508.Pp
509.Va community
510is set to
511.Li COMM_INITIALIZE
512while the assignments in the configuration file are processed.
513To
514.Li COMM_READ
515or
516.Li COMM_WRITE
517when the community strings for the read-write or read-only community are found
518in the incoming PDU.
519.Pp
520Modules can define additional communities.
521This may be necessary to provide
522transport proxying (a PDU received on one communication link is proxied to
523another link) or to implement non-UDP access points to SNMP.
524A new community is defined with the function
525.Fn comm_define .
526It takes the following parameters:
527.Bl -tag -width ".It Fa descr"
528.It Fa priv
529This is an integer identifying the community to the module.
530Each module has its own namespace with regard to this parameter.
531The community table is indexed with the module name and this identifier.
532.It Fa descr
533This is a string providing a human readable description of the community.
534It is visible in the community table.
535.It Fa mod
536This is the module defining the community.
537.It Fa str
538This is the initial community string.
539.El
540.Pp
541The function returns a globally unique community identifier.
| 261.Sh DESCRIPTION
262The
263.Xr bsnmpd 1
264SNMP daemon implements a minimal MIB which consists of the system group, part
265of the SNMP MIB, a private configuration MIB, a trap destination table, a
266UDP port table, a community table, a module table, a statistics group and
267a debugging group.
268All other MIBs are support through loadable modules.
269This allows
270.Xr bsnmpd 1
271to use for task, that are not the classical SNMP task.
272.Ss MODULE LOADING AND UNLOADING
273Modules are loaded by writing to the module table.
274This table is indexed by a string, that identifies the module to the daemon.
275This identifier is used
276to select the correct configuration section from the configuration files and
277to identify resources allocated to this module.
278A row in the module table is
279created by writing a string of non-zero length to the
280.Va begemotSnmpdModulePath
281column.
282This string must be the complete path to the file containing the module.
283A module can be unloaded by writing a zero length string to the path column
284of an existing row.
285.Pp
286Modules may depend on each other an hence must be loaded in the correct order.
287The dependencies are listed in the corresponding manual pages.
288.Pp
289Upon loading a module the SNMP daemon expects the module file to a export
290a global symbol
291.Va config .
292This symbol should be a variable of type
293.Vt struct snmp_module :
294.Bd -literal -offset indent
295typedef enum snmpd_proxy_err (*proxy_err_f)(struct snmp_pdu *, void *,
296 const struct asn_oid *, const struct sockaddr *, socklen_t,
297 enum snmpd_input_err, int32_t);
298
299
300struct snmp_module {
301 const char *comment;
302 int (*init)(struct lmodule *, int argc, char *argv[]);
303 int (*fini)(void);
304 void (*idle)(void);
305 void (*dump)(void);
306 void (*config)(void);
307 void (*start)(void);
308 proxy_err_f proxy;
309 const struct snmp_node *tree;
310 u_int tree_size;
311 void (*loading)(const struct lmodule *, int);
312};
313.Ed
314.Pp
315This structure must be statically initialized and its fields have the
316following functions:
317.Bl -tag -width ".It Va tree_size"
318.It Va comment
319This is a string that will be visible in the module table.
320It should give some hint about the function of this module.
321.It Va init
322This function is called upon loading the module.
323The module pointer should
324be stored by the module because it is needed in other calls and the
325argument vector will contain the arguments to this module from the daemons
326command line.
327This function should return 0 if everything is ok or an UNIX error code (see
328.Xr errno 3 ) .
329Once the function returns 0, the
330.Va fini
331function is called when the module is unloaded.
332.It Va fini
333The module is unloaded.
334This gives the module a chance to free resources that
335are not automatically freed.
336Be sure to free all memory, because daemons tend to run very long.
337This function pointer may be
338.Li NULL
339if it is not needed.
340.It Va idle
341If this function pointer is not
342.Li NULL ,
343the function pointed to by it is called whenever the daemon is going
344to wait for an event.
345Try to avoid using this feature.
346.It Va dump
347Whenever the daemon receives a
348.Li SIGUSR1
349it dumps it internal state via
350.Xr syslog 3 .
351If the
352.Va dump
353field is not
354.Li NULL
355it is called by the daemon to dump the state of the module.
356.It Va config
357Whenever the daemon receives a
358.Li SIGHUP
359signal it re-reads its configuration file.
360If the
361.Va config
362field is not
363.Li NULL
364it is called after reading the configuration file to give the module a chance
365to adapt to the new configuration.
366.It Va start
367If not
368.Li NULL
369this function is called after successful loading and initializing the module
370to start its actual operation.
371.It Va proxy
372If the daemon receives a PDU and that PDU has a community string whose
373community was registered by this module and
374.Va proxy
375is not
376.Li NULL
377than this function is called to handle the PDU.
378.It Va tree
379This is a pointer to the node array for the MIB tree implemented by this module.
380.It Va tree_size
381This is the number of nodes in
382.Va tree .
383.It Va loading
384If this pointer is not
385.Li NULL
386it is called whenever another module was loaded or unloaded.
387It gets a
388pointer to that module and a flag that is 0 for unloading and 1 for loading.
389.El
390.Pp
391When everything is ok, the daemon merges the module's MIB tree into its current
392global tree, calls the modules
393.Fn init
394function.
395If this function returns an error, the modules MIB tree is removed from
396the global one and the module is unloaded.
397If initialization is successful, the modules
398.Fn start
399function is called.
400After it returns the
401.Fn loaded
402functions of all modules (including the loaded one) are called.
403.Pp
404When the module is unloaded, its MIB tree is removed from the global one,
405the communities, request id ranges, running timers and selected file
406descriptors are released, the
407.Fn fini
408function is called, the module file is unloaded and the
409.Fn loaded
410functions of all other modules are called.
411.Ss IMPLEMENTING TABLES
412There are a number of macros designed to help implementing SNMP tables.
413A problem while implementing a table is the support for the GETNEXT operator.
414The GETNEXT operation has to find out whether, given an arbitrary OID, the
415lessest table row, that has an OID higher than the given OID.
416The easiest way
417to do this is to keep the table as an ordered list of structures each one
418of which contains an OID that is the index of the table row.
419This allows easy removal, insertion and search.
420.Pp
421The helper macros assume, that the table is organized as a TAILQ (see
422.Xr queue 3
423and each structure contains a
424.Vt struct asn_oid
425that is used as index.
426For simple tables with only a integer or unsigned index, an alternate form
427of the macros is available, that presume the existence of an integer or
428unsigned field as index field.
429.Pp
430The macros have name of the form
431.Bd -literal -offset indent
432{INSERT,FIND,NEXT}_OBJECT_{OID,INT}[_LINK[_INDEX]]
433.Ed
434.Pp
435The
436.Fn INSERT_*
437macros are used in the SET operation to insert a new table row into the table.
438The
439.Fn FIND_*
440macros are used in the GET operation to find a specific row in the table.
441The
442.Fn NEXT_*
443macros are used in the GETNEXT operation to find the next row in the table.
444The last two macros return a pointer to the row structure if a row is found,
445.Li NULL
446otherwise.
447The macros
448.Fn *_OBJECT_OID_*
449assume the existence of a
450.Vt struct asn_oid
451that is used as index, the macros
452.Fn *_OBJECT_INT_*
453assume the existence of an unsigned integer field that is used as index.
454.Pp
455The macros
456.Fn *_INDEX
457allow the explicit naming of the index field in the parameter
458.Fa INDEX ,
459whereas the other macros assume that this field is named
460.Va index .
461The macros
462.Fn *_LINK_*
463allow the explicit naming of the link field of the tail queues, the others
464assume that the link field is named
465.Va link .
466Explicitly naming the link field may be necessary if the same structures
467are held in two or more different tables.
468.Pp
469The arguments to the macros are as follows:
470.Bl -tag -width "INDEX"
471.It Fa PTR
472A pointer to the new structure to be inserted into the table.
473.It Fa LIST
474A pointer to the tail queue head.
475.It Fa LINK
476The name of the link field in the row structure.
477.It Fa INDEX
478The name of the index field in the row structure.
479.It Fa OID
480Must point to the
481.Va var
482field of the
483.Fa value
484argument to the node operation callback.
485This is the OID to search for.
486.It Fa SUB
487This is the index of the start of the table index in the OID pointed to
488by
489.Fa OID .
490This is usually the same as the
491.Fa sub
492argument to the node operation callback.
493.El
494.Ss DAEMON TIMESTAMPS
495The variable
496.Va this_tick
497contains the tick (there are 100 SNMP ticks in a second) when
498the current PDU processing was started.
499The variable
500.Va start_tick
501contains the tick when the daemon was started.
502The function
503.Fn get_ticks
504returns the current tick.
505The number of ticks since the daemon was started
506is
507.Bd -literal -offset indent
508get_ticks() - start_tick
509.Ed
510.Ss THE SYSTEM GROUP
511The scalar fields of the system group are held in the global variable
512.Va systemg :
513.Bd -literal -offset indent
514struct systemg {
515 u_char *descr;
516 struct asn_oid object_id;
517 u_char *contact;
518 u_char *name;
519 u_char *location;
520 uint32_t services;
521 uint32_t or_last_change;
522};
523.Ed
524.Ss COMMUNITIES
525The SNMP daemon implements a community table.
526On recipte of a request message
527the community string in that message is compared to each of the community
528strings in that table, if a match is found, the global variable
529.Va community
530is set to the community identifier for that community.
531Community identifiers are unsigned integers.
532For the three standard communities there are three constants defined:
533.Bd -literal -offset indent
534#define COMM_INITIALIZE 0
535#define COMM_READ 1
536#define COMM_WRITE 2
537.Ed
538.Pp
539.Va community
540is set to
541.Li COMM_INITIALIZE
542while the assignments in the configuration file are processed.
543To
544.Li COMM_READ
545or
546.Li COMM_WRITE
547when the community strings for the read-write or read-only community are found
548in the incoming PDU.
549.Pp
550Modules can define additional communities.
551This may be necessary to provide
552transport proxying (a PDU received on one communication link is proxied to
553another link) or to implement non-UDP access points to SNMP.
554A new community is defined with the function
555.Fn comm_define .
556It takes the following parameters:
557.Bl -tag -width ".It Fa descr"
558.It Fa priv
559This is an integer identifying the community to the module.
560Each module has its own namespace with regard to this parameter.
561The community table is indexed with the module name and this identifier.
562.It Fa descr
563This is a string providing a human readable description of the community.
564It is visible in the community table.
565.It Fa mod
566This is the module defining the community.
567.It Fa str
568This is the initial community string.
569.El
570.Pp
571The function returns a globally unique community identifier.
|
542If a PDU is
| 572If a SNMPv1 or SNMPv2 PDU is
|
543received who's community string matches, this identifier is set into the global
544.Va community .
545.Pp
546The function
547.Fn comm_string
548returns the current community string for the given community.
549.Pp
550All communities defined by a module are automatically released when the module
551is unloaded.
| 573received who's community string matches, this identifier is set into the global
574.Va community .
575.Pp
576The function
577.Fn comm_string
578returns the current community string for the given community.
579.Pp
580All communities defined by a module are automatically released when the module
581is unloaded.
|
| 582.Ss THE USER-BASED SECURITY GROUP
583The scalar statistics of the USM group are held in the global variable
584.Va snmpd_usmstats :
585.Bd -literal -offset indent
586struct snmpd_usmstat {
587 uint32_t unsupported_seclevels;
588 uint32_t not_in_time_windows;
589 uint32_t unknown_users;
590 uint32_t unknown_engine_ids;
591 uint32_t wrong_digests;
592 uint32_t decrypt_errors;
593};
594.Ed
595.Fn bsnmpd_get_usm_stats
596returns a pointer to the global structure containing the statistics.
597.Fn bsnmpd_reset_usm_stats
598clears the statistics of the USM group.
599.Pp
600A global list of configured USM users is maintained by the daemon.
601.Bd -literal -offset indent
602struct usm_user {
603 struct snmp_user suser;
604 uint8_t user_engine_id[SNMP_ENGINE_ID_SIZ];
605 uint32_t user_engine_len;
606 char user_public[SNMP_USM_NAME_SIZ];
607 uint32_t user_public_len;
608 int32_t status;
609 int32_t type;
610 SLIST_ENTRY(usm_user) up;
611};
612.Ed
613This structure represents an USM user. The daemon only responds to SNMPv3 PDUs
614with user credentials matching an USM user entry in its global list.
615If a SNMPv3 PDU is received, whose security model is USM, the global
616.Va usm_user
617is set to point at the user entry that matches the credentials contained in
618the PDU.
619However, the daemon does not create or remove USM users, it gives an interface
620to external loadable module(s) to manage the list.
621.Fn usm_new_user
622adds an user entry in the list, and
623.Fn usm_delete_user
624deletes an existing entry from the list.
625.Fn usm_flush_users
626is used to remove all configured USM users.
627.Fn usm_first_user
628will return the first user in the list, or
629.Li NULL
630if the list is empty.
631.Fn usm_next_user
632will return the next user of a given entry if one exists, or
633.Li NULL .
634The list is sorted according to the USM user name and Engine ID.
635.Fn usm_find_user
636returns the USM user entry matching the given
637.Fa engine
638and
639.Fa uname
640or
641.Li NULL
642if an user with the specified name and engine id is not present in the list.
|
552.Ss WELL KNOWN OIDS
553The global variable
554.Va oid_zeroDotZero
555contains the OID 0.0.
| 643.Ss WELL KNOWN OIDS
644The global variable
645.Va oid_zeroDotZero
646contains the OID 0.0.
|
| 647The global variables
648.Va oid_usmUnknownEngineIDs
649.Va oid_usmNotInTimeWindows
650contains the OIDs 1.3.6.1.6.3.15.1.1.4.0 and 1.3.6.1.6.3.15.1.1.2.0 used
651in the SNMPv3 USM Engine Discovery.
|
556.Ss REQUEST ID RANGES
557For modules that implement SNMP client functions besides SNMP agent functions
558it may be necessary to identify SNMP requests by their identifier to allow
559easier routing of responses to the correct sub-system.
560Request id ranges
561provide a way to acquire globally non-overlapping sub-ranges of the entire
56231-bit id range.
563.Pp
564A request id range is allocated with
565.Fn reqid_allocate .
566The arguments are: the size of the range and the module allocating the range.
567For example, the call
568.Bd -literal -offset indent
569id = reqid_allocate(1000, module);
570.Ed
571.Pp
572allocates a range of 1000 request ids.
573The function returns the request
574id range identifier or 0 if there is not enough identifier space.
575The function
576.Fn reqid_base
577returns the lowest request id in the given range.
578.Pp
579Request id are allocated starting at the lowest one linear throughout the range.
580If the client application may have a lot of outstanding request the range
581must be large enough so that an id is not reused until it is really expired.
582.Fn reqid_next
583returns the sequentially next id in the range.
584.Pp
585The function
586.Fn reqid_istype
587checks whether the request id
588.Fa reqid
589is within the range identified by
590.Fa type .
591The function
592.Fn reqid_type
593returns the range identifier for the given
594.Fa reqid
595or 0 if the request id is in none of the ranges.
596.Ss TIMERS
597The SNMP daemon supports an arbitrary number of timers with SNMP tick granularity.
598The function
599.Fn timer_start
600arranges for the callback
601.Fa func
602to be called with the argument
603.Fa uarg
604after
605.Fa ticks
606SNMP ticks have expired.
607.Fa mod
608is the module that starts the timer.
609These timers are one-shot, they are not restarted.
610Repeatable timers are started with
611.Fn timer_start_repeat
612which takes an additional argument
613.Fa repeat_ticks .
614The argument
615.Fa ticks
616gives the number of ticks until the first execution of the callback, while
617.Fa repeat_ticks
618is the number of ticks between invocations of the callback.
619Note, that currently the number of initial ticks silently may be set identical
620to the number of ticks between callback invocations.
621The function returns a timer identifier that can be used to stop the timer via
622.Fn timer_stop .
623If a module is unloaded all timers started by the module that have not expired
624yet are stopped.
625.Ss FILE DESCRIPTOR SUPPORT
626A module may need to get input from socket file descriptors without blocking
627the daemon (for example to implement alternative SNMP transports).
628.Pp
629The function
630.Fn fd_select
631causes the callback function
632.Fa func
633to be called with the file descriptor
634.Fa fd
635and the user argument
636.Fa uarg
637whenever the file descriptor
638.Fa fd
639can be read or has a close condition.
640If the file descriptor is not in
641non-blocking mode, it is set to non-blocking mode.
642If the callback is not needed anymore,
643.Fn fd_deselect
644may be called with the value returned from
645.Fn fd_select .
646All file descriptors selected by a module are automatically deselected when
647the module is unloaded.
648.Pp
649To temporarily suspend the file descriptor registration
650.Fn fd_suspend
651can be called.
652This also causes the file descriptor to be switched back to
653blocking mode if it was blocking prior the call to
654.Fn fd_select .
655This is necessary to do synchronous input on a selected socket.
656The effect of
657.Fn fd_suspend
658can be undone with
659.Fn fd_resume .
660.Ss OBJECT RESOURCES
661The system group contains an object resource table.
662A module may create an entry in this table by calling
663.Fn or_register
664with the
665.Fa oid
666to be registered, a textual description in
667.Fa str
668and a pointer to the module
669.Fa mod .
670The registration can be removed with
671.Fn or_unregister .
672All registrations of a module are automatically removed if the module is
673unloaded.
674.Ss TRANSMIT AND RECEIVE BUFFERS
675A buffer is allocated via
676.Fn buf_alloc .
677The argument must be 1 for transmit and 0 for receive buffers.
678The function may return
679.Li NULL
680if there is no memory available.
681The current buffersize can be obtained with
682.Fn buf_size .
683.Sh PROCESSING PDUS
684For modules that need to do their own PDU processing (for example for proxying)
685the following functions are available:
686.Pp
687Function
688.Fn snmp_input_start
689decodes the PDU, searches the community, and sets the global
690.Va this_tick .
691It returns one of the following error codes:
692.Bl -tag -width ".It Er SNMPD_INPUT_VALBADLEN"
693.It Er SNMPD_INPUT_OK
694Everything ok, continue with processing.
695.It Er SNMPD_INPUT_FAILED
696The PDU could not be decoded, has a wrong version or an unknown
697community string.
698.It Er SNMPD_INPUT_VALBADLEN
699A SET PDU had a value field in a binding with a wrong length field in an
700ASN.1 header.
701.It Er SNMPD_INPUT_VALRANGE
702A SET PDU had a value field in a binding with a value that is out of range
703for the given ASN.1 type.
704.It Er SNMPD_INPUT_VALBADENC
705A SET PDU had a value field in a binding with wrong ASN.1 encoding.
706.It Er SNMPD_INPUT_TRUNC
707The buffer appears to contain a valid begin of a PDU, but is too short.
708For streaming transports this means that the caller must save what he
709already has and trying to obtain more input and reissue this input to
710the function.
711For datagram transports this means that part of the
712datagram was lost and the input should be ignored.
713.El
714.Pp
715The function
716.Fn snmp_input_finish
717does the other half of processing: if
718.Fn snmp_input_start
719did not return OK, tries to construct an error response.
720If the start was OK, it calls the correct function from
721.Xr bsnmpagent 3
722to execute the request and depending on the outcome constructs a response or
723error response PDU or ignores the request PDU.
724It returns either
725.Er SNMPD_INPUT_OK
726or
727.Er SNMPD_INPUT_FAILED .
728In the first case a response PDU was constructed and should be sent.
729.Pp
730The function
731.Fn snmp_output
732takes a PDU and encodes it.
733.Pp
734The function
735.Fn snmp_send_port
736takes a PDU, encodes it and sends it through the given port (identified by
737the transport and the index in the port table) to the given address.
738.Pp
739The function
740.Fn snmp_send_trap
741sends a trap to all trap destinations.
742The arguments are the
743.Fa oid
744identifying the trap and a NULL-terminated list of
745.Vt struct snmp_value
746pointers that are to be inserted into the trap binding list.
747.Ss SIMPLE ACTION SUPPORT
748For simple scalar variables that need no dependencies a number of support
749functions is available to handle the set, commit, rollback and get.
750.Pp
751The following functions are used for OCTET STRING scalars, either NUL terminated
752or not:
753.Bl -tag -width "XXXXXXXXX"
754.It Fn string_save
755should be called for SNMP_OP_SET.
756.Fa value
757and
758.Fa ctx
759are the resp\&.\& arguments to the node callback.
760.Fa valp
761is a pointer to the pointer that holds the current value and
762.Fa req_size
763should be -1 if any size of the string is acceptable or a number larger or
764equal zero if the string must have a specific size.
765The function saves
766the old value in the scratch area (note, that any initial value must have
767been allocated by
768.Xr malloc 3 ) ,
769allocates a new string, copies over the new value, NUL-terminates it and
770sets the new current value.
771.It Fn string_commit
772simply frees the saved old value in the scratch area.
773.It Fn string_rollback
774frees the new value, and puts back the old one.
775.It Fn string_get
776is used for GET or GETNEXT.
777The function
778.It Fn string_get_max
779can be used instead of
780.Fn string_get
781to ensure that the returned string has a certain maximum length.
782If
783.Fa len
784is -1, the length is computed via
785.Xr strlen 3
786from the current string value.
787If the current value is NULL,
788a OCTET STRING of zero length is returned.
789.It Fn string_free
790must be called if either rollback or commit fails to free the saved old value.
791.El
792.Pp
793The following functions are used to process scalars of type IP-address:
794.Bl -tag -width "XXXXXXXXX"
795.It Fn ip_save
796Saves the current value in the scratch area and sets the new value from
797.Fa valp .
798.It Fn ip_commit
799Does nothing.
800.It Fn ip_rollback
801Restores the old IP address from the scratch area.
802.It Fn ip_get
803Retrieves the IP current address.
804.El
805.Pp
806The following functions handle OID-typed variables:
807.Bl -tag -width "XXXXXXXXX"
808.It Fn oid_save
809Saves the current value in the scratch area by allocating a
810.Vt struct asn_oid
811with
812.Xr malloc 3
813and sets the new value from
814.Fa oid .
815.It Fn oid_commit
816Frees the old value in the scratch area.
817.It Fn oid_rollback
818Restores the old OID from the scratch area and frees the old OID.
819.It Fn oid_get
820Retrieves the OID
821.El
822.Ss TABLE INDEX HANDLING
823The following functions help in handling table indexes:
824.Bl -tag -width "XXXXXXXXX"
825.It Fn index_decode
826Decodes the index part of the OID.
827The parameter
828.Fa oid
829must be a pointer to the
830.Va var
831field of the
832.Fa value
833argument of the node callback.
834The
835.Fa sub
836argument must be the index of the start of the index in the OID (this is
837the
838.Fa sub
839argument to the node callback).
840.Fa code
841is the index expression (parameter
842.Fa idx
843to the node callback).
844These parameters are followed by parameters depending on the syntax of the index
845elements as follows:
846.Bl -tag -width ".It Li OCTET STRING"
847.It Li INTEGER
848.Vt int32_t *
849expected as argument.
850.It Li COUNTER64
851.Vt uint64_t *
852expected as argument.
853Note, that this syntax is illegal for indexes.
854.It Li OCTET STRING
855A
856.Vt u_char **
857and a
858.Vt size_t *
859expected as arguments.
860A buffer is allocated to hold the decoded string.
861.It Li OID
862A
863.Vt struct asn_oid *
864is expected as argument.
865.It Li IP ADDRESS
866A
867.Vt u_int8_t *
868expected as argument that points to a buffer of at least four byte.
869.It Li COUNTER, GAUGE, TIMETICKS
870A
871.Vt u_int32_t
872expected.
873.It Li NULL
874No argument expected.
875.El
876.It Fn index_compare
877compares the current variable with an OID.
878.Fa oid1
879and
880.Fa sub
881come from the node callback arguments
882.Fa value->var
883and
884.Fa sub
885resp.
886.Fa oid2
887is the OID to compare to.
888The function returns -1, 0, +1 when the
889variable is lesser, equal, higher to the given OID.
890.Fa oid2
891must contain only the index part of the table column.
892.It Fn index_compare_off
893is equivalent to
894.Fn index_compare
895except that it takes an additional parameter
896.Fa off
897that causes it to ignore the first
898.Fa off
899components of both indexes.
900.It Fn index_append
901appends OID
902.Fa src
903beginning at position
904.Fa sub
905to
906.Fa dst .
907.It Fn index_append_off
908appends OID
909.Fa src
910beginning at position
911.Fa off
912to
913.Fa dst
914beginning at position
915.Fa sub
916+
917.Fa off .
918.El
919.Sh SEE ALSO
920.Xr gensnmptree 1 ,
921.Xr bsnmpd 1 ,
922.Xr bsnmpagent 3 ,
923.Xr bsnmpclient 3 ,
924.Xr bsnmplib 3
925.Sh STANDARDS
926This implementation conforms to the applicable IETF RFCs and ITU-T
927recommendations.
928.Sh AUTHORS
929.An Hartmut Brandt Aq harti@FreeBSD.org
| 652.Ss REQUEST ID RANGES
653For modules that implement SNMP client functions besides SNMP agent functions
654it may be necessary to identify SNMP requests by their identifier to allow
655easier routing of responses to the correct sub-system.
656Request id ranges
657provide a way to acquire globally non-overlapping sub-ranges of the entire
65831-bit id range.
659.Pp
660A request id range is allocated with
661.Fn reqid_allocate .
662The arguments are: the size of the range and the module allocating the range.
663For example, the call
664.Bd -literal -offset indent
665id = reqid_allocate(1000, module);
666.Ed
667.Pp
668allocates a range of 1000 request ids.
669The function returns the request
670id range identifier or 0 if there is not enough identifier space.
671The function
672.Fn reqid_base
673returns the lowest request id in the given range.
674.Pp
675Request id are allocated starting at the lowest one linear throughout the range.
676If the client application may have a lot of outstanding request the range
677must be large enough so that an id is not reused until it is really expired.
678.Fn reqid_next
679returns the sequentially next id in the range.
680.Pp
681The function
682.Fn reqid_istype
683checks whether the request id
684.Fa reqid
685is within the range identified by
686.Fa type .
687The function
688.Fn reqid_type
689returns the range identifier for the given
690.Fa reqid
691or 0 if the request id is in none of the ranges.
692.Ss TIMERS
693The SNMP daemon supports an arbitrary number of timers with SNMP tick granularity.
694The function
695.Fn timer_start
696arranges for the callback
697.Fa func
698to be called with the argument
699.Fa uarg
700after
701.Fa ticks
702SNMP ticks have expired.
703.Fa mod
704is the module that starts the timer.
705These timers are one-shot, they are not restarted.
706Repeatable timers are started with
707.Fn timer_start_repeat
708which takes an additional argument
709.Fa repeat_ticks .
710The argument
711.Fa ticks
712gives the number of ticks until the first execution of the callback, while
713.Fa repeat_ticks
714is the number of ticks between invocations of the callback.
715Note, that currently the number of initial ticks silently may be set identical
716to the number of ticks between callback invocations.
717The function returns a timer identifier that can be used to stop the timer via
718.Fn timer_stop .
719If a module is unloaded all timers started by the module that have not expired
720yet are stopped.
721.Ss FILE DESCRIPTOR SUPPORT
722A module may need to get input from socket file descriptors without blocking
723the daemon (for example to implement alternative SNMP transports).
724.Pp
725The function
726.Fn fd_select
727causes the callback function
728.Fa func
729to be called with the file descriptor
730.Fa fd
731and the user argument
732.Fa uarg
733whenever the file descriptor
734.Fa fd
735can be read or has a close condition.
736If the file descriptor is not in
737non-blocking mode, it is set to non-blocking mode.
738If the callback is not needed anymore,
739.Fn fd_deselect
740may be called with the value returned from
741.Fn fd_select .
742All file descriptors selected by a module are automatically deselected when
743the module is unloaded.
744.Pp
745To temporarily suspend the file descriptor registration
746.Fn fd_suspend
747can be called.
748This also causes the file descriptor to be switched back to
749blocking mode if it was blocking prior the call to
750.Fn fd_select .
751This is necessary to do synchronous input on a selected socket.
752The effect of
753.Fn fd_suspend
754can be undone with
755.Fn fd_resume .
756.Ss OBJECT RESOURCES
757The system group contains an object resource table.
758A module may create an entry in this table by calling
759.Fn or_register
760with the
761.Fa oid
762to be registered, a textual description in
763.Fa str
764and a pointer to the module
765.Fa mod .
766The registration can be removed with
767.Fn or_unregister .
768All registrations of a module are automatically removed if the module is
769unloaded.
770.Ss TRANSMIT AND RECEIVE BUFFERS
771A buffer is allocated via
772.Fn buf_alloc .
773The argument must be 1 for transmit and 0 for receive buffers.
774The function may return
775.Li NULL
776if there is no memory available.
777The current buffersize can be obtained with
778.Fn buf_size .
779.Sh PROCESSING PDUS
780For modules that need to do their own PDU processing (for example for proxying)
781the following functions are available:
782.Pp
783Function
784.Fn snmp_input_start
785decodes the PDU, searches the community, and sets the global
786.Va this_tick .
787It returns one of the following error codes:
788.Bl -tag -width ".It Er SNMPD_INPUT_VALBADLEN"
789.It Er SNMPD_INPUT_OK
790Everything ok, continue with processing.
791.It Er SNMPD_INPUT_FAILED
792The PDU could not be decoded, has a wrong version or an unknown
793community string.
794.It Er SNMPD_INPUT_VALBADLEN
795A SET PDU had a value field in a binding with a wrong length field in an
796ASN.1 header.
797.It Er SNMPD_INPUT_VALRANGE
798A SET PDU had a value field in a binding with a value that is out of range
799for the given ASN.1 type.
800.It Er SNMPD_INPUT_VALBADENC
801A SET PDU had a value field in a binding with wrong ASN.1 encoding.
802.It Er SNMPD_INPUT_TRUNC
803The buffer appears to contain a valid begin of a PDU, but is too short.
804For streaming transports this means that the caller must save what he
805already has and trying to obtain more input and reissue this input to
806the function.
807For datagram transports this means that part of the
808datagram was lost and the input should be ignored.
809.El
810.Pp
811The function
812.Fn snmp_input_finish
813does the other half of processing: if
814.Fn snmp_input_start
815did not return OK, tries to construct an error response.
816If the start was OK, it calls the correct function from
817.Xr bsnmpagent 3
818to execute the request and depending on the outcome constructs a response or
819error response PDU or ignores the request PDU.
820It returns either
821.Er SNMPD_INPUT_OK
822or
823.Er SNMPD_INPUT_FAILED .
824In the first case a response PDU was constructed and should be sent.
825.Pp
826The function
827.Fn snmp_output
828takes a PDU and encodes it.
829.Pp
830The function
831.Fn snmp_send_port
832takes a PDU, encodes it and sends it through the given port (identified by
833the transport and the index in the port table) to the given address.
834.Pp
835The function
836.Fn snmp_send_trap
837sends a trap to all trap destinations.
838The arguments are the
839.Fa oid
840identifying the trap and a NULL-terminated list of
841.Vt struct snmp_value
842pointers that are to be inserted into the trap binding list.
843.Ss SIMPLE ACTION SUPPORT
844For simple scalar variables that need no dependencies a number of support
845functions is available to handle the set, commit, rollback and get.
846.Pp
847The following functions are used for OCTET STRING scalars, either NUL terminated
848or not:
849.Bl -tag -width "XXXXXXXXX"
850.It Fn string_save
851should be called for SNMP_OP_SET.
852.Fa value
853and
854.Fa ctx
855are the resp\&.\& arguments to the node callback.
856.Fa valp
857is a pointer to the pointer that holds the current value and
858.Fa req_size
859should be -1 if any size of the string is acceptable or a number larger or
860equal zero if the string must have a specific size.
861The function saves
862the old value in the scratch area (note, that any initial value must have
863been allocated by
864.Xr malloc 3 ) ,
865allocates a new string, copies over the new value, NUL-terminates it and
866sets the new current value.
867.It Fn string_commit
868simply frees the saved old value in the scratch area.
869.It Fn string_rollback
870frees the new value, and puts back the old one.
871.It Fn string_get
872is used for GET or GETNEXT.
873The function
874.It Fn string_get_max
875can be used instead of
876.Fn string_get
877to ensure that the returned string has a certain maximum length.
878If
879.Fa len
880is -1, the length is computed via
881.Xr strlen 3
882from the current string value.
883If the current value is NULL,
884a OCTET STRING of zero length is returned.
885.It Fn string_free
886must be called if either rollback or commit fails to free the saved old value.
887.El
888.Pp
889The following functions are used to process scalars of type IP-address:
890.Bl -tag -width "XXXXXXXXX"
891.It Fn ip_save
892Saves the current value in the scratch area and sets the new value from
893.Fa valp .
894.It Fn ip_commit
895Does nothing.
896.It Fn ip_rollback
897Restores the old IP address from the scratch area.
898.It Fn ip_get
899Retrieves the IP current address.
900.El
901.Pp
902The following functions handle OID-typed variables:
903.Bl -tag -width "XXXXXXXXX"
904.It Fn oid_save
905Saves the current value in the scratch area by allocating a
906.Vt struct asn_oid
907with
908.Xr malloc 3
909and sets the new value from
910.Fa oid .
911.It Fn oid_commit
912Frees the old value in the scratch area.
913.It Fn oid_rollback
914Restores the old OID from the scratch area and frees the old OID.
915.It Fn oid_get
916Retrieves the OID
917.El
918.Ss TABLE INDEX HANDLING
919The following functions help in handling table indexes:
920.Bl -tag -width "XXXXXXXXX"
921.It Fn index_decode
922Decodes the index part of the OID.
923The parameter
924.Fa oid
925must be a pointer to the
926.Va var
927field of the
928.Fa value
929argument of the node callback.
930The
931.Fa sub
932argument must be the index of the start of the index in the OID (this is
933the
934.Fa sub
935argument to the node callback).
936.Fa code
937is the index expression (parameter
938.Fa idx
939to the node callback).
940These parameters are followed by parameters depending on the syntax of the index
941elements as follows:
942.Bl -tag -width ".It Li OCTET STRING"
943.It Li INTEGER
944.Vt int32_t *
945expected as argument.
946.It Li COUNTER64
947.Vt uint64_t *
948expected as argument.
949Note, that this syntax is illegal for indexes.
950.It Li OCTET STRING
951A
952.Vt u_char **
953and a
954.Vt size_t *
955expected as arguments.
956A buffer is allocated to hold the decoded string.
957.It Li OID
958A
959.Vt struct asn_oid *
960is expected as argument.
961.It Li IP ADDRESS
962A
963.Vt u_int8_t *
964expected as argument that points to a buffer of at least four byte.
965.It Li COUNTER, GAUGE, TIMETICKS
966A
967.Vt u_int32_t
968expected.
969.It Li NULL
970No argument expected.
971.El
972.It Fn index_compare
973compares the current variable with an OID.
974.Fa oid1
975and
976.Fa sub
977come from the node callback arguments
978.Fa value->var
979and
980.Fa sub
981resp.
982.Fa oid2
983is the OID to compare to.
984The function returns -1, 0, +1 when the
985variable is lesser, equal, higher to the given OID.
986.Fa oid2
987must contain only the index part of the table column.
988.It Fn index_compare_off
989is equivalent to
990.Fn index_compare
991except that it takes an additional parameter
992.Fa off
993that causes it to ignore the first
994.Fa off
995components of both indexes.
996.It Fn index_append
997appends OID
998.Fa src
999beginning at position
1000.Fa sub
1001to
1002.Fa dst .
1003.It Fn index_append_off
1004appends OID
1005.Fa src
1006beginning at position
1007.Fa off
1008to
1009.Fa dst
1010beginning at position
1011.Fa sub
1012+
1013.Fa off .
1014.El
1015.Sh SEE ALSO
1016.Xr gensnmptree 1 ,
1017.Xr bsnmpd 1 ,
1018.Xr bsnmpagent 3 ,
1019.Xr bsnmpclient 3 ,
1020.Xr bsnmplib 3
1021.Sh STANDARDS
1022This implementation conforms to the applicable IETF RFCs and ITU-T
1023recommendations.
1024.Sh AUTHORS
1025.An Hartmut Brandt Aq harti@FreeBSD.org
|