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 $
39 .Nm snmp_client_init ,
40 .Nm snmp_client_set_host ,
41 .Nm snmp_client_set_port ,
43 .Nm snmp_timeout_cb_f ,
44 .Nm snmp_timeout_start_f ,
45 .Nm snmp_timeout_stop_f ,
49 .Nm snmp_add_binding ,
53 .Nm snmp_parse_server ,
56 .Nm snmp_table_fetch ,
57 .Nm snmp_table_fetch_async ,
59 .Nm snmp_discover_engine
60 .Nd "SNMP client library"
69 .Fn (*snmp_send_cb_f) "struct snmp_pdu *req" "struct snmp_pdu *resp" "void *uarg"
71 .Fn (*snmp_timeout_cb_f) "void *uarg"
73 .Fn (*snmp_timeout_start_f) "struct timeval *timeout" "snmp_timeout_cb_f callback" "void *uarg"
75 .Fn (*snmp_timeout_stop_f) "void *timeout_id"
76 .Vt extern struct snmp_client snmp_client ;
78 .Fn snmp_client_init "struct snmp_client *client"
80 .Fn snmp_client_set_host "struct snmp_client *client" "const char *host"
82 .Fn snmp_client_set_port "struct snmp_client *client" "const char *port"
84 .Fn snmp_open "const char *host" "const char *port" "const char *read_community" "const char *write_community"
88 .Fn snmp_pdu_create "struct snmp_pdu *pdu" "u_int op"
90 .Fn snmp_add_binding "struct snmp_pdu *pdu" "..."
92 .Fn snmp_pdu_check "const struct snmp_pdu *req" "const struct snmp_pdu *resp"
94 .Fn snmp_pdu_send "struct snmp_pdu *pdu" "snmp_send_cb_f func" "void *uarg"
96 .Fn snmp_oid_append "struct asn_oid *oid" "const char *fmt" "..."
98 .Fn snmp_parse_server "struct snmp_client *sc" "const char *str"
100 .Fn snmp_receive "int blocking"
102 .Fn (*snmp_table_cb_f) "void *list" "void *arg" "int res"
104 .Fn snmp_table_fetch "const struct snmp_table *descr" "void *list"
106 .Fn snmp_table_fetch_async "const struct snmp_table *descr" "void *list" "snmp_table_cb_f callback" "void *uarg"
108 .Fn snmp_dialog "struct snmp_pdu *req" "struct snmp_pdu *resp"
110 .Fn snmp_discover_engine "void"
112 The SNMP library contains routines to easily build SNMP client applications
113 that use SNMP versions 1, 2 or 3.
114 Most of the routines use a
115 .Vt struct snmp_client :
116 .Bd -literal -offset indent
118 enum snmp_version version;
119 int trans; /* which transport to use */
121 /* these two are read-only for the application */
122 char *cport; /* port number as string */
123 char *chost; /* host name or IP address as string */
125 char read_community[SNMP_COMMUNITY_MAXLEN + 1];
126 char write_community[SNMP_COMMUNITY_MAXLEN + 1];
128 /* SNMPv3 specific fields */
130 int32_t security_model;
131 struct snmp_engine engine;
132 struct snmp_user user;
134 /* SNMPv3 Access control - VACM*/
136 uint8_t cengine[SNMP_ENGINE_ID_SIZ];
137 char cname[SNMP_CONTEXT_NAME_SIZ];
139 struct timeval timeout;
153 char error[SNMP_STRERROR_LEN];
155 snmp_timeout_start_f timeout_start;
156 snmp_timeout_stop_f timeout_stop;
158 char local_path[sizeof(SNMP_LOCAL_PATH)];
162 The fields of this structure are described below.
163 .Bl -tag -width "timeout_start"
165 This is the version of SNMP to use.
168 for applicable values.
169 The default version is
173 .Dv SNMP_TRANS_LOC_DGRAM
174 a local datagram socket is used.
176 .Dv SNMP_TRANS_LOC_STREAM
177 a local stream socket is used.
180 a UDPv4 socket and for
182 a UDPv6 socket is created.
185 field as the path to the server's socket for local sockets.
187 The SNMP agent's UDP port number.
188 This may be a symbolic port number (from
190 or a numeric port number.
193 (the default) the standard SNMP port is used.
194 This field should not be changed directly but rather by calling
195 .Fn snmp_client_set_port .
197 The SNMP agent's host name, IP address or
199 domain socket path name.
205 This field should not be changed directly but rather through calling
206 .Fn snmp_client_set_host .
207 .It Va read_community
208 This is the community name to be used for all requests except SET requests.
211 .It Va write_community
212 The community name to be used for SET requests.
216 The message identifier value to be used with SNMPv3 PDUs. Incremented with
217 each transmitted PDU.
218 .It Va security_model
219 The security model to be used with SNMPv3 PDUs. Currently only User-Based
220 Security model specified by RFC 3414 (value 3) is supported.
222 The authoritive SNMP engine parameters to be used with SNMPv3 PDUs.
224 The USM SNMP user credentials to be used with SNMPv3 PDUs.
226 The length of the context engine id to be used with SNMPv3 PDUs.
228 The context engine id to be used with SNMPv3 PDUs. Default is empty.
230 The context name to be used with SNMPv3 PDUs. Default is
233 The maximum time to wait for responses to requests.
234 If the time elapses, the request is resent up to
237 The default is 3 seconds.
239 Number of times a request PDU is to be resent.
240 If set to 0, the request is sent only once.
241 The default is 3 retransmissions.
243 If set to a non-zero value all received and sent PDUs are dumped via
244 .Xr snmp_pdu_dump 3 .
245 The default is not to dump PDUs.
247 The encoding buffer size to be allocated for transmitted PDUs.
248 The default is 10000 octets.
250 The decoding buffer size to be allocated for received PDUs.
251 This is the size of the maximum PDU that can be received.
252 The default is 10000 octets.
256 this is the file socket file descriptor used for sending and receiving PDUs.
258 The request id of the next PDU to send.
259 Used internal by the library.
261 The maximum request id to use for outgoing PDUs.
265 The minimum request id to use for outgoing PDUs.
266 Request ids are allocated linearily starting at
271 If an error happens, this field is set to a printable string describing the
274 This field must point to a function setting up a one shot timeout.
275 After the timeout has elapsed, the given callback function must be called
276 with the user argument.
279 function must return a
281 identifying the timeout.
283 This field must be set to a function that stops a running timeout.
284 The function will be called with the return value of the corresponding
288 If in local socket mode, the name of the clients socket.
289 Not needed by the application.
292 In the current implementation there is a global variable
294 .D1 Vt extern struct snmp_client snmp_client ;
296 that is used by all the library functions.
297 The first call into the library must be a call to
299 to initialize this global variable to the default values.
300 After this call and before calling
302 the fields of the variable may be modified by the user.
303 The modification of the
307 fields should be done only via the functions
308 .Fn snmp_client_set_host
310 .Fn snmp_client_set_port .
316 domain socket and connects it to the agent's IP address and port.
317 If any of the arguments of the call is not
319 the corresponding field in the global
321 is set from the argument.
322 Otherwise the values that are already in that variable are used.
325 closes the socket, stops all timeouts and frees all dynamically allocated
328 The next three functions are used to create request PDUs.
331 initializes a PDU of type
333 It does not allocate space for the PDU itself.
334 This is the responsibility of the caller.
336 adds bindings to the PDU and returns the (zero based) index of the first new
338 The arguments are pairs of pointer to the OIDs and syntax constants,
339 terminated by a NULL.
341 .Bd -literal -offset indent
342 snmp_add_binding(&pdu,
343 &oid1, SNMP_SYNTAX_INTEGER,
344 &oid2, SNMP_SYNTAX_OCTETSTRING,
348 adds two new bindings to the PDU and returns the index of the first one.
349 It is the responsibility of the caller to set the value part of the binding
351 The functions returns -1 if the maximum number of bindings is exhausted.
354 can be used to construct variable OIDs for requests.
355 It takes a pointer to an
357 that is to be constructed, a format string, and a number of arguments
358 the type of which depends on the format string.
359 The format string is interpreted
360 character by character in the following way:
361 .Bl -tag -width ".It Li ( Va N Ns Li )"
363 This format expects an argument of type
365 and appends this as a single integer to the OID.
367 This format expects an argument of type
369 and appends to four parts of the IP address to the OID.
371 This format expects an argument of type
373 and appends the length of the string (as computed by
375 and each of the characters in the string to the OID.
377 This format expects no argument.
379 must be a decimal number and is stored into an internal variable
382 This format expects an argument of type
386 characters from the string to the OID.
387 The string may contain
391 This format expects two arguments: one of type
395 The first argument gives the number of bytes to append to the OID from the string
396 pointed to by the second argument.
401 may be used to check a response PDU.
402 A number of checks are performed
403 (error code, equal number of bindings, syntaxes and values for SET PDUs).
404 The function returns +1 if everything is ok, 0 if a NOSUCHNAME or similar
405 error was detected, -1 if the response PDU had fatal errors
410 (a timeout occurred).
414 encodes and sends the given PDU.
415 It records the PDU together with the callback
416 and user pointers in an internal list and arranges for retransmission if no
417 response is received.
418 When a response is received or the retransmission count
419 is exceeded the callback
421 is called with the original request PDU, the response PDU and the user argument
423 If the retransmit count is exceeded,
425 is called with the original request PDU, the response pointer set to
427 and the user argument
429 The caller should not free the request PDU until the callback function is
431 The callback function must free the request PDU and the response PDU (if not
436 tries to receive a PDU.
437 If the argument is zero, the function polls to see
438 whether a packet is available, if the argument is non-zero, the function blocks
439 until the next packet is received.
440 The packet is delivered via the usual callback
441 mechanism (non-response packets are silently dropped).
442 The function returns 0, if a packet was received and successfully dispatched,
443 -1 if an error occurred or no packet was available (in polling mode).
445 The next two functions are used to retrieve tables from SNMP agents.
447 the following input structure, that describes the table:
448 .Bd -literal -offset indent
450 struct asn_oid table;
451 struct asn_oid last_change;
457 struct snmp_table_entry {
459 enum snmp_syntax syntax;
465 The fields of this structure have the following meaning:
466 .Bl -tag -width "last_change"
468 This is the base OID of the table.
470 Some tables have a scalar variable of type TIMETICKS attached to them,
471 that holds the time when the table was last changed.
472 This OID should be the OID of this variable (without the \&.0 index).
473 When the table is retrieved
474 with multiple GET requests, and the variable changes between two request,
475 the table fetch is restarted.
477 Maximum number of tries to fetch the table.
479 The table fetching routines return a list of structures one for each table
481 This variable is the size of one structure and used to
485 This is the number of index columns in the table.
487 This is a bit mask with a 1 for each table column that is required.
488 Bit 0 corresponds to the first element (index 0) in the array
490 bit 1 to the second (index 1) and so on.
491 SNMP tables may be sparse.
492 For sparse columns the bit should not be set.
493 If the bit for a given column is set and
494 the column value cannot be retrieved for a given row, the table fetch is
495 restarted assuming that the table is currently being modified by the agent.
496 The bits for the index columns are ignored.
498 This is a variable sized array of column descriptors.
499 This array is terminated by an element with syntax
500 .Li SNMP_SYNTAX_NULL .
503 elements describe all the index columns of the table, the rest are normal
508 .Ql req_mask & (1 << N)
509 yields true, the column is considered a required column.
510 The fields of this the array elements have the following meaning:
511 .Bl -tag -width "syntax"
513 This is the OID subid of the column.
514 This is ignored for index entries.
515 Index entries are decoded according to the
519 This is the syntax of the column or index.
522 terminates the array.
524 This is the starting offset of the value of the column in the return structures.
525 This field can be set with the ISO-C
531 Both table fetching functions return TAILQ (see
533 of structures--one for each table row.
534 These structures must start with a
538 and are allocated via
542 argument of the table functions must point to a
546 fields, usually called
548 is used to indicate which of the columns have been found for the given
550 It is encoded like the
556 synchronously fetches the given table.
557 If everything is ok 0 is returned.
558 Otherwise the function returns -1 and sets an appropriate error string.
560 .Fn snmp_table_fetch_async
561 fetches the tables asynchronously.
562 If either the entire table is fetch, or
563 an error occurs the callback function
565 is called with the callers arguments
569 and a parameter that is either 0 if the table was fetched, or
570 -1 if there was an error.
571 The function itself returns -1 if it could not
572 initialize fetching of the table.
574 The following table description is used to fetch the ATM interface table:
575 .Bd -literal -offset indent
577 * ATM interface table
580 TAILQ_ENTRY(atmif) link;
596 TAILQ_HEAD(atmif_list, atmif);
598 /* list of all ATM interfaces */
599 struct atmif_list atmif_list;
601 static const struct snmp_table atmif_table = {
602 OIDX_begemotAtmIfTable,
603 OIDX_begemotAtmIfTableLastChange, 2,
604 sizeof(struct atmif),
607 { 0, SNMP_SYNTAX_INTEGER,
608 offsetof(struct atmif, index) },
609 { 1, SNMP_SYNTAX_OCTETSTRING,
610 offsetof(struct atmif, ifname) },
611 { 2, SNMP_SYNTAX_GAUGE,
612 offsetof(struct atmif, node_id) },
613 { 3, SNMP_SYNTAX_GAUGE,
614 offsetof(struct atmif, pcr) },
615 { 4, SNMP_SYNTAX_INTEGER,
616 offsetof(struct atmif, media) },
617 { 5, SNMP_SYNTAX_GAUGE,
618 offsetof(struct atmif, vpi_bits) },
619 { 6, SNMP_SYNTAX_GAUGE,
620 offsetof(struct atmif, vci_bits) },
621 { 7, SNMP_SYNTAX_GAUGE,
622 offsetof(struct atmif, max_vpcs) },
623 { 8, SNMP_SYNTAX_GAUGE,
624 offsetof(struct atmif, max_vccs) },
625 { 9, SNMP_SYNTAX_OCTETSTRING,
626 offsetof(struct atmif, esi) },
627 { 10, SNMP_SYNTAX_INTEGER,
628 offsetof(struct atmif, carrier) },
629 { 0, SNMP_SYNTAX_NULL, 0 }
634 if (snmp_table_fetch(&atmif_table, &atmif_list) != 0)
635 errx(1, "AtmIf table: %s", snmp_client.error);
641 is used to execute a synchonuous dialog with the agent.
644 is sent and the function blocks until the response PDU is received.
646 that asynchonuous receives are handled (i.e. callback functions of other send
647 calls or table fetches may be called while in the function).
648 The response PDU is returned in
650 If no response could be received after all timeouts and retries, the function
652 If a response was received 0 is returned.
655 .Fn snmp_discover_engine
656 is used to discover the authoritative snmpEngineId of a remote SNMPv3 agent.
657 A request PDU with empty USM user name is sent and the client's engine
658 parameters are set according to the snmpEngine parameters received in the
660 If the client is configured to use authentication and/or privacy and the
661 snmpEngineBoots and/or snmpEngineTime in the response had zero values, an
662 additional request (possibly encrypted) with the appropriate user credentials
663 is sent to fetch the missing values.
664 Note, that the function blocks until the discovery process is completed.
665 If no response could be received after all timeouts and retries, or the
666 response contained errors the function returns -1.
667 If the discovery process was completed 0 is returned.
670 .Fn snmp_parse_server
671 is used to parse an SNMP server specification string and fill in the
673 .Vt struct snmp_client .
674 The syntax of a server specification is
676 .D1 [trans::][community@][server][:port]
680 is the transport name (one of
687 is the string to be used for both the read and the write community,
689 is the server's host name in case of UDP and the path name in case
690 of a local socket, and
692 is the port in case of UDP transport.
693 The function returns 0 in the case of success and return -1 and sets
694 the error string in case of an error.
697 .Fn snmp_parse_serverr
698 fills the transport, the port number and the community strings with
699 reasonable default values when they are not specified.
700 The default transport
703 If the host name contains a slash the default is modified to
704 .Dv SNMP_TRANS_LOC_DGRAM .
705 If the host name looks like a numeric IPv6 address the default is
706 .Dv SNMP_TRANS_UDP6 .
707 For numeric IPv6 addresses the transport name udp is automatically
709 .Dv SNMP_TRANS_UDP6 .
710 The default port number (for
716 The default read community is
718 and the default write community
721 .Fn snmp_parse_server
722 recognizes path names, host names and numerical IPv4 and IPv6 addresses.
723 A string consisting of digits and periods is assumed to be an IPv4 address
724 and must be parseable by
726 An IPv6 address is any string enclosed in square brackets.
727 It must be parseable with
731 .Fn snmp_parse_server
732 can be specified numerically or symbolically.
733 It is ignored for local sockets.
735 If an error occurs in any of the functions an error indication as described
737 Additionally the function sets a printable error string in the
747 This implementation conforms to the applicable IETF RFCs and ITU-T
750 .An Hartmut Brandt Aq harti@FreeBSD.org
751 .An Kendy Kutzner Aq kutzner@fokus.gmd.de