2 .\" Copyright (c) 2004-2005
4 .\" All rights reserved.
5 .\" Copyright (c) 2001-2003
6 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
7 .\" All rights reserved.
9 .\" Author: Harti Brandt <harti@FreeBSD.org>
11 .\" Redistribution and use in source and binary forms, with or without
12 .\" modification, are permitted provided that the following conditions
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.
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
32 .\" $Begemot: bsnmp/lib/bsnmpclient.3,v 1.12 2005/10/04 08:46:50 brandt_h Exp $
40 .Nm snmp_timeout_cb_f ,
41 .Nm snmp_timeout_start_f ,
42 .Nm snmp_timeout_stop_f ,
46 .Nm snmp_add_binding ,
50 .Nm snmp_parse_server ,
53 .Nm snmp_table_fetch ,
54 .Nm snmp_table_fetch_async ,
56 .Nm snmp_discover_engine
57 .Nd "SNMP client library"
66 .Fn (*snmp_send_cb_f) "struct snmp_pdu *req" "struct snmp_pdu *resp" "void *uarg"
68 .Fn (*snmp_timeout_cb_f) "void *uarg"
70 .Fn (*snmp_timeout_start_f) "struct timeval *timeout" "snmp_timeout_cb_f callback" "void *uarg"
72 .Fn (*snmp_timeout_stop_f) "void *timeout_id"
73 .Vt extern struct snmp_client snmp_client ;
75 .Fn snmp_client_init "struct snmp_client *client"
77 .Fn snmp_client_set_host "struct snmp_client *client" "const char *host"
79 .Fn snmp_client_set_port "struct snmp_client *client" "const char *port"
81 .Fn snmp_open "const char *host" "const char *port" "const char *read_community" "const char *write_community"
85 .Fn snmp_pdu_create "struct snmp_pdu *pdu" "u_int op"
87 .Fn snmp_add_binding "struct snmp_pdu *pdu" "..."
89 .Fn snmp_pdu_check "const struct snmp_pdu *req" "const struct snmp_pdu *resp"
91 .Fn snmp_pdu_send "struct snmp_pdu *pdu" "snmp_send_cb_f func" "void *uarg"
93 .Fn snmp_oid_append "struct asn_oid *oid" "const char *fmt" "..."
95 .Fn snmp_parse_server "struct snmp_client *sc" "const char *str"
97 .Fn snmp_receive "int blocking"
99 .Fn (*snmp_table_cb_f) "void *list" "void *arg" "int res"
101 .Fn snmp_table_fetch "const struct snmp_table *descr" "void *list"
103 .Fn snmp_table_fetch_async "const struct snmp_table *descr" "void *list" "snmp_table_cb_f callback" "void *uarg"
105 .Fn snmp_dialog "struct snmp_pdu *req" "struct snmp_pdu *resp"
107 .Fn snmp_discover_engine "void"
109 The SNMP library contains routines to easily build SNMP client applications
110 that use SNMP versions 1, 2 or 3.
111 Most of the routines use a
112 .Vt struct snmp_client :
113 .Bd -literal -offset indent
115 enum snmp_version version;
116 int trans; /* which transport to use */
118 /* these two are read-only for the application */
119 char *cport; /* port number as string */
120 char *chost; /* host name or IP address as string */
122 char read_community[SNMP_COMMUNITY_MAXLEN + 1];
123 char write_community[SNMP_COMMUNITY_MAXLEN + 1];
125 /* SNMPv3 specific fields */
127 int32_t security_model;
128 struct snmp_engine engine;
129 struct snmp_user user;
131 /* SNMPv3 Access control - VACM*/
133 uint8_t cengine[SNMP_ENGINE_ID_SIZ];
134 char cname[SNMP_CONTEXT_NAME_SIZ];
136 struct timeval timeout;
150 char error[SNMP_STRERROR_LEN];
152 snmp_timeout_start_f timeout_start;
153 snmp_timeout_stop_f timeout_stop;
155 char local_path[sizeof(SNMP_LOCAL_PATH)];
159 The fields of this structure are described below.
160 .Bl -tag -width "timeout_start"
162 This is the version of SNMP to use.
165 for applicable values.
166 The default version is
170 .Dv SNMP_TRANS_LOC_DGRAM
171 a local datagram socket is used.
173 .Dv SNMP_TRANS_LOC_STREAM
174 a local stream socket is used.
177 a UDP socket is created.
180 field as the path to the server's socket for local sockets.
182 The SNMP agent's UDP port number.
183 This may be a symbolic port number (from
185 or a numeric port number.
188 (the default) the standard SNMP port is used.
189 This field should not be changed directly but rather by calling
190 .Fn snmp_client_set_port .
192 The SNMP agent's host name, IP address or
194 domain socket path name.
200 This field should not be changed directly but rather through calling
201 .Fn snmp_client_set_host .
202 .It Va read_community
203 This is the community name to be used for all requests except SET requests.
206 .It Va write_community
207 The community name to be used for SET requests.
211 The message indentifier value to be used with SNMPv3 PDUs. Incremented with
212 each transmitted PDU.
213 .It Va security_model
214 The security model to be used with SNMPv3 PDUs. Currently only User-Based
215 Security model specified by RFC 3414 (value 3) is supported.
217 The authorative SNMP engine parameters to be used with SNMPv3 PDUs.
219 The USM SNMP user credentials to be used with SNMPv3 PDUs.
221 The length of the context engine id to be used with SNMPv3 PDUs.
223 The context engine id to be used with SNMPv3 PDUs. Default is empty.
225 The context name to be used with SNMPv3 PDUs. Default is
228 The maximum time to wait for responses to requests.
229 If the time elapses, the request is resent up to
232 The default is 3 seconds.
234 Number of times a request PDU is to be resent.
235 If set to 0, the request is sent only once.
236 The default is 3 retransmissions.
238 If set to a non-zero value all received and sent PDUs are dumped via
239 .Xr snmp_pdu_dump 3 .
240 The default is not to dump PDUs.
242 The encoding buffer size to be allocated for transmitted PDUs.
243 The default is 10000 octets.
245 The decoding buffer size to be allocated for received PDUs.
246 This is the size of the maximum PDU that can be received.
247 The default is 10000 octets.
251 this is the file socket file descriptor used for sending and receiving PDUs.
253 The request id of the next PDU to send.
254 Used internal by the library.
256 The maximum request id to use for outgoing PDUs.
260 The minimum request id to use for outgoing PDUs.
261 Request ids are allocated linearily starting at
266 If an error happens, this field is set to a printable string describing the
269 This field must point to a function setting up a one shot timeout.
270 After the timeout has elapsed, the given callback function must be called
271 with the user argument.
274 function must return a
276 identifying the timeout.
278 This field must be set to a function that stops a running timeout.
279 The function will be called with the return value of the corresponding
283 If in local socket mode, the name of the clients socket.
284 Not needed by the application.
287 In the current implementation there is a global variable
289 .D1 Vt extern struct snmp_client snmp_client ;
291 that is used by all the library functions.
292 The first call into the library must be a call to
294 to initialize this global variable to the default values.
295 After this call and before calling
297 the fields of the variable may be modified by the user.
298 The modification of the
302 fields should be done only via the functions
303 .Fn snmp_client_set_host
305 .Fn snmp_client_set_port .
311 domain socket and connects it to the agent's IP address and port.
312 If any of the arguments of the call is not
314 the corresponding field in the global
316 is set from the argument.
317 Otherwise the values that are already in that variable are used.
320 closes the socket, stops all timeouts and frees all dynamically allocated
323 The next three functions are used to create request PDUs.
326 initializes a PDU of type
328 It does not allocate space for the PDU itself.
329 This is the responsibility of the caller.
331 adds bindings to the PDU and returns the (zero based) index of the first new
333 The arguments are pairs of pointer to the OIDs and syntax constants,
334 terminated by a NULL.
336 .Bd -literal -offset indent
337 snmp_add_binding(&pdu,
338 &oid1, SNMP_SYNTAX_INTEGER,
339 &oid2, SNMP_SYNTAX_OCTETSTRING,
343 adds two new bindings to the PDU and returns the index of the first one.
344 It is the responsibility of the caller to set the value part of the binding
346 The functions returns -1 if the maximum number of bindings is exhausted.
349 can be used to construct variable OIDs for requests.
350 It takes a pointer to an
352 that is to be constructed, a format string, and a number of arguments
353 the type of which depends on the format string.
354 The format string is interpreted
355 character by character in the following way:
356 .Bl -tag -width ".It Li ( Va N Ns Li )"
358 This format expects an argument of type
360 and appends this as a single integer to the OID.
362 This format expects an argument of type
364 and appends to four parts of the IP address to the OID.
366 This format expects an argument of type
368 and appends the length of the string (as computed by
370 and each of the characters in the string to the OID.
372 This format expects no argument.
374 must be a decimal number and is stored into an internal variable
377 This format expects an argument of type
381 characters from the string to the OID.
382 The string may contain
386 This format expects two arguments: one of type
390 The first argument gives the number of bytes to append to the OID from the string
391 pointed to by the second argument.
396 may be used to check a response PDU.
397 A number of checks are performed
398 (error code, equal number of bindings, syntaxes and values for SET PDUs).
399 The function returns +1 if everything is ok, 0 if a NOSUCHNAME or similar
400 error was detected, -1 if the response PDU had fatal errors
405 (a timeout occurred).
409 encodes and sends the given PDU.
410 It records the PDU together with the callback
411 and user pointers in an internal list and arranges for retransmission if no
412 response is received.
413 When a response is received or the retransmission count
414 is exceeded the callback
416 is called with the orignal request PDU, the response PDU and the user argument
418 If the retransmit count is exceeded,
420 is called with the original request PDU, the response pointer set to
422 and the user argument
424 The caller should not free the request PDU until the callback function is
426 The callback function must free the request PDU and the response PDU (if not
431 tries to receive a PDU.
432 If the argument is zero, the function polls to see
433 whether a packet is available, if the argument is non-zero, the function blocks
434 until the next packet is received.
435 The packet is delivered via the usual callback
436 mechanism (non-response packets are silently dropped).
437 The function returns 0, if a packet was received and successfully dispatched,
438 -1 if an error occurred or no packet was available (in polling mode).
440 The next two functions are used to retrieve tables from SNMP agents.
442 the following input structure, that describes the table:
443 .Bd -literal -offset indent
445 struct asn_oid table;
446 struct asn_oid last_change;
452 struct snmp_table_entry {
454 enum snmp_syntax syntax;
460 The fields of this structure have the following meaning:
461 .Bl -tag -width "last_change"
463 This is the base OID of the table.
465 Some tables have a scalar variable of type TIMETICKS attached to them,
466 that holds the time when the table was last changed.
467 This OID should be the OID of this variable (without the \&.0 index).
468 When the table is retrieved
469 with multiple GET requests, and the variable changes between two request,
470 the table fetch is restarted.
472 Maximum number of tries to fetch the table.
474 The table fetching routines return a list of structures one for each table
476 This variable is the size of one structure and used to
480 This is the number of index columns in the table.
482 This is a bit mask with a 1 for each table column that is required.
483 Bit 0 corresponds to the first element (index 0) in the array
485 bit 1 to the second (index 1) and so on.
486 SNMP tables may be sparse.
487 For sparse columns the bit should not be set.
488 If the bit for a given column is set and
489 the column value cannot be retrieved for a given row, the table fetch is
490 restarted assuming that the table is currently being modified by the agent.
491 The bits for the index columns are ignored.
493 This is a variable sized array of column descriptors.
494 This array is terminated by an element with syntax
495 .Li SNMP_SYNTAX_NULL .
498 elements describe all the index columns of the table, the rest are normal
503 .Ql req_mask & (1 << N)
504 yields true, the column is considered a required column.
505 The fields of this the array elements have the following meaning:
506 .Bl -tag -width "syntax"
508 This is the OID subid of the column.
509 This is ignored for index entries.
510 Index entries are decoded according to the
514 This is the syntax of the column or index.
517 terminates the array.
519 This is the starting offset of the value of the column in the return structures.
520 This field can be set with the ISO-C
526 Both table fetching functions return TAILQ (see
528 of structures--one for each table row.
529 These structures must start with a
533 and are allocated via
537 argument of the table functions must point to a
541 fields, usually called
543 is used to indicate which of the columns have been found for the given
545 It is encoded like the
551 synchronously fetches the given table.
552 If everything is ok 0 is returned.
553 Otherwise the function returns -1 and sets an appropriate error string.
555 .Fn snmp_table_fetch_async
556 fetches the tables asynchronously.
557 If either the entire table is fetch, or
558 an error occurs the callback function
560 is called with the callers arguments
564 and a parameter that is either 0 if the table was fetched, or
565 -1 if there was an error.
566 The function itself returns -1 if it could not
567 initialize fetching of the table.
569 The following table description is used to fetch the ATM interface table:
570 .Bd -literal -offset indent
572 * ATM interface table
575 TAILQ_ENTRY(atmif) link;
591 TAILQ_HEAD(atmif_list, atmif);
593 /* list of all ATM interfaces */
594 struct atmif_list atmif_list;
596 static const struct snmp_table atmif_table = {
597 OIDX_begemotAtmIfTable,
598 OIDX_begemotAtmIfTableLastChange, 2,
599 sizeof(struct atmif),
602 { 0, SNMP_SYNTAX_INTEGER,
603 offsetof(struct atmif, index) },
604 { 1, SNMP_SYNTAX_OCTETSTRING,
605 offsetof(struct atmif, ifname) },
606 { 2, SNMP_SYNTAX_GAUGE,
607 offsetof(struct atmif, node_id) },
608 { 3, SNMP_SYNTAX_GAUGE,
609 offsetof(struct atmif, pcr) },
610 { 4, SNMP_SYNTAX_INTEGER,
611 offsetof(struct atmif, media) },
612 { 5, SNMP_SYNTAX_GAUGE,
613 offsetof(struct atmif, vpi_bits) },
614 { 6, SNMP_SYNTAX_GAUGE,
615 offsetof(struct atmif, vci_bits) },
616 { 7, SNMP_SYNTAX_GAUGE,
617 offsetof(struct atmif, max_vpcs) },
618 { 8, SNMP_SYNTAX_GAUGE,
619 offsetof(struct atmif, max_vccs) },
620 { 9, SNMP_SYNTAX_OCTETSTRING,
621 offsetof(struct atmif, esi) },
622 { 10, SNMP_SYNTAX_INTEGER,
623 offsetof(struct atmif, carrier) },
624 { 0, SNMP_SYNTAX_NULL, 0 }
629 if (snmp_table_fetch(&atmif_table, &atmif_list) != 0)
630 errx(1, "AtmIf table: %s", snmp_client.error);
636 is used to execute a synchonuous dialog with the agent.
639 is sent and the function blocks until the response PDU is received.
641 that asynchonuous receives are handled (i.e. callback functions of other send
642 calls or table fetches may be called while in the function).
643 The response PDU is returned in
645 If no response could be received after all timeouts and retries, the function
647 If a response was received 0 is returned.
650 .Fn snmp_discover_engine
651 is used to discover the authorative snmpEngineId of a remote SNMPv3 agent.
652 A request PDU with empty USM user name is sent and the client's engine
653 parameters are set according to the snmpEngine parameters received in the
655 If the client is configured to use authentication and/or privacy and the
656 snmpEngineBoots and/or snmpEngineTime in the response had zero values, an
657 additional request (possibly encrypted) with the appropriate user credentials
658 is sent to fetch the missing values.
659 Note, that the function blocks until the discovery proccess is completed.
660 If no response could be received after all timeouts and retries, or the
661 response contained errors the function returns -1.
662 If the discovery proccess was completed 0 is returned.
665 .Fn snmp_parse_server
666 is used to parse an SNMP server specification string and fill in the
668 .Vt struct snmp_client .
669 The syntax of a server specification is
671 .D1 [trans::][community@][server][:port]
675 is the transport name (one of udp, stream or dgram),
677 is the string to be used for both the read and the write community,
679 is the server's host name in case of UDP and the path name in case
680 of a local socket, and
682 is the port in case of UDP transport.
683 The function returns 0 in the case of success and return -1 and sets
684 the error string in case of an error.
686 If an error occurs in any of the function an error indication as described
688 Additionally the function sets a printable error string
699 This implementation conforms to the applicable IETF RFCs and ITU-T
702 .An Hartmut Brandt Aq harti@FreeBSD.org
703 .An Kendy Kutzner Aq kutzner@fokus.gmd.de