/contrib/bsnmp/lib/bsnmpclient.3

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 703 lines · 687 code · 16 blank · 0 comment · 0 complexity · 2e0c31166da22cb7035f1ea7baff2cc4 MD5 · raw file

  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/lib/bsnmpclient.3,v 1.12 2005/10/04 08:46:50 brandt_h Exp $
  33. .\"
  34. .Dd September 9, 2010
  35. .Dt BSNMPCLIENT 3
  36. .Os
  37. .Sh NAME
  38. .Nm snmp_client ,
  39. .Nm snmp_send_cb_f ,
  40. .Nm snmp_timeout_cb_f ,
  41. .Nm snmp_timeout_start_f ,
  42. .Nm snmp_timeout_stop_f ,
  43. .Nm snmp_open ,
  44. .Nm snmp_close ,
  45. .Nm snmp_pdu_create ,
  46. .Nm snmp_add_binding ,
  47. .Nm snmp_pdu_check ,
  48. .Nm snmp_pdu_send ,
  49. .Nm snmp_oid_append ,
  50. .Nm snmp_parse_server ,
  51. .Nm snmp_receive ,
  52. .Nm snmp_table_cb_f ,
  53. .Nm snmp_table_fetch ,
  54. .Nm snmp_table_fetch_async ,
  55. .Nm snmp_dialog ,
  56. .Nm snmp_discover_engine
  57. .Nd "SNMP client library"
  58. .Sh LIBRARY
  59. Begemot SNMP library
  60. .Pq libbsnmp, -lbsnmp
  61. .Sh SYNOPSIS
  62. .In asn1.h
  63. .In snmp.h
  64. .In snmpclient.h
  65. .Ft typedef void
  66. .Fn (*snmp_send_cb_f) "struct snmp_pdu *req" "struct snmp_pdu *resp" "void *uarg"
  67. .Ft typedef void
  68. .Fn (*snmp_timeout_cb_f) "void *uarg"
  69. .Ft typedef void *
  70. .Fn (*snmp_timeout_start_f) "struct timeval *timeout" "snmp_timeout_cb_f callback" "void *uarg"
  71. .Ft typedef void
  72. .Fn (*snmp_timeout_stop_f) "void *timeout_id"
  73. .Vt extern struct snmp_client snmp_client ;
  74. .Ft void
  75. .Fn snmp_client_init "struct snmp_client *client"
  76. .Ft int
  77. .Fn snmp_client_set_host "struct snmp_client *client" "const char *host"
  78. .Ft int
  79. .Fn snmp_client_set_port "struct snmp_client *client" "const char *port"
  80. .Ft int
  81. .Fn snmp_open "const char *host" "const char *port" "const char *read_community" "const char *write_community"
  82. .Ft void
  83. .Fn snmp_close "void"
  84. .Ft void
  85. .Fn snmp_pdu_create "struct snmp_pdu *pdu" "u_int op"
  86. .Ft int
  87. .Fn snmp_add_binding "struct snmp_pdu *pdu" "..."
  88. .Ft int
  89. .Fn snmp_pdu_check "const struct snmp_pdu *req" "const struct snmp_pdu *resp"
  90. .Ft int32_t
  91. .Fn snmp_pdu_send "struct snmp_pdu *pdu" "snmp_send_cb_f func" "void *uarg"
  92. .Ft int
  93. .Fn snmp_oid_append "struct asn_oid *oid" "const char *fmt" "..."
  94. .Ft int
  95. .Fn snmp_parse_server "struct snmp_client *sc" "const char *str"
  96. .Ft int
  97. .Fn snmp_receive "int blocking"
  98. .Ft typedef void
  99. .Fn (*snmp_table_cb_f) "void *list" "void *arg" "int res"
  100. .Ft int
  101. .Fn snmp_table_fetch "const struct snmp_table *descr" "void *list"
  102. .Ft int
  103. .Fn snmp_table_fetch_async "const struct snmp_table *descr" "void *list" "snmp_table_cb_f callback" "void *uarg"
  104. .Ft int
  105. .Fn snmp_dialog "struct snmp_pdu *req" "struct snmp_pdu *resp"
  106. .Ft int
  107. .Fn snmp_discover_engine "void"
  108. .Sh DESCRIPTION
  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
  114. struct snmp_client {
  115. enum snmp_version version;
  116. int trans; /* which transport to use */
  117. /* these two are read-only for the application */
  118. char *cport; /* port number as string */
  119. char *chost; /* host name or IP address as string */
  120. char read_community[SNMP_COMMUNITY_MAXLEN + 1];
  121. char write_community[SNMP_COMMUNITY_MAXLEN + 1];
  122. /* SNMPv3 specific fields */
  123. int32_t identifier;
  124. int32_t security_model;
  125. struct snmp_engine engine;
  126. struct snmp_user user;
  127. /* SNMPv3 Access control - VACM*/
  128. uint32_t clen;
  129. uint8_t cengine[SNMP_ENGINE_ID_SIZ];
  130. char cname[SNMP_CONTEXT_NAME_SIZ];
  131. struct timeval timeout;
  132. u_int retries;
  133. int dump_pdus;
  134. size_t txbuflen;
  135. size_t rxbuflen;
  136. int fd;
  137. int32_t next_reqid;
  138. int32_t max_reqid;
  139. int32_t min_reqid;
  140. char error[SNMP_STRERROR_LEN];
  141. snmp_timeout_start_f timeout_start;
  142. snmp_timeout_stop_f timeout_stop;
  143. char local_path[sizeof(SNMP_LOCAL_PATH)];
  144. };
  145. .Ed
  146. .Pp
  147. The fields of this structure are described below.
  148. .Bl -tag -width "timeout_start"
  149. .It Va version
  150. This is the version of SNMP to use.
  151. See
  152. .Xr bsnmplib 3
  153. for applicable values.
  154. The default version is
  155. .Li SNMP_V2c .
  156. .It Va trans
  157. If this is
  158. .Dv SNMP_TRANS_LOC_DGRAM
  159. a local datagram socket is used.
  160. If it is
  161. .Dv SNMP_TRANS_LOC_STREAM
  162. a local stream socket is used.
  163. For
  164. .Dv SNMP_TRANS_UDP
  165. a UDP socket is created.
  166. It uses the
  167. .Va chost
  168. field as the path to the server's socket for local sockets.
  169. .It Va cport
  170. The SNMP agent's UDP port number.
  171. This may be a symbolic port number (from
  172. .Pa /etc/services )
  173. or a numeric port number.
  174. If this field is
  175. .Li NULL
  176. (the default) the standard SNMP port is used.
  177. This field should not be changed directly but rather by calling
  178. .Fn snmp_client_set_port .
  179. .It Va chost
  180. The SNMP agent's host name, IP address or
  181. .Ux
  182. domain socket path name.
  183. If this is
  184. .Li NULL
  185. (the default)
  186. .Li localhost
  187. is assumed.
  188. This field should not be changed directly but rather through calling
  189. .Fn snmp_client_set_host .
  190. .It Va read_community
  191. This is the community name to be used for all requests except SET requests.
  192. The default is
  193. .Sq public .
  194. .It Va write_community
  195. The community name to be used for SET requests.
  196. The default is
  197. .Sq private .
  198. .It Va identifier
  199. The message indentifier value to be used with SNMPv3 PDUs. Incremented with
  200. each transmitted PDU.
  201. .It Va security_model
  202. The security model to be used with SNMPv3 PDUs. Currently only User-Based
  203. Security model specified by RFC 3414 (value 3) is supported.
  204. .It Va engine
  205. The authorative SNMP engine parameters to be used with SNMPv3 PDUs.
  206. .It Va user
  207. The USM SNMP user credentials to be used with SNMPv3 PDUs.
  208. .It Va clen
  209. The length of the context engine id to be used with SNMPv3 PDUs.
  210. .It Va cengine
  211. The context engine id to be used with SNMPv3 PDUs. Default is empty.
  212. .It Va cname
  213. The context name to be used with SNMPv3 PDUs. Default is
  214. .Sq "" .
  215. .It Va timeout
  216. The maximum time to wait for responses to requests.
  217. If the time elapses, the request is resent up to
  218. .Va retries
  219. times.
  220. The default is 3 seconds.
  221. .It Va retries
  222. Number of times a request PDU is to be resent.
  223. If set to 0, the request is sent only once.
  224. The default is 3 retransmissions.
  225. .It Va dump_pdus
  226. If set to a non-zero value all received and sent PDUs are dumped via
  227. .Xr snmp_pdu_dump 3 .
  228. The default is not to dump PDUs.
  229. .It Va txbuflen
  230. The encoding buffer size to be allocated for transmitted PDUs.
  231. The default is 10000 octets.
  232. .It Va rxbuflen
  233. The decoding buffer size to be allocated for received PDUs.
  234. This is the size of the maximum PDU that can be received.
  235. The default is 10000 octets.
  236. .It Va fd
  237. After calling
  238. .Fn snmp_open
  239. this is the file socket file descriptor used for sending and receiving PDUs.
  240. .It Va next_reqid
  241. The request id of the next PDU to send.
  242. Used internal by the library.
  243. .It Va max_reqid
  244. The maximum request id to use for outgoing PDUs.
  245. The default is
  246. .Li INT32_MAX .
  247. .It Va min_reqid
  248. The minimum request id to use for outgoing PDUs.
  249. Request ids are allocated linearily starting at
  250. .Va min_reqid
  251. up to
  252. .Va max_reqid .
  253. .It Va error
  254. If an error happens, this field is set to a printable string describing the
  255. error.
  256. .It Va timeout_start
  257. This field must point to a function setting up a one shot timeout.
  258. After the timeout has elapsed, the given callback function must be called
  259. with the user argument.
  260. The
  261. .Fn timeout_start
  262. function must return a
  263. .Vt void *
  264. identifying the timeout.
  265. .It Va timeout_stop
  266. This field must be set to a function that stops a running timeout.
  267. The function will be called with the return value of the corresponding
  268. .Fn timeout_start
  269. function.
  270. .It Va local_path
  271. If in local socket mode, the name of the clients socket.
  272. Not needed by the application.
  273. .El
  274. .Pp
  275. In the current implementation there is a global variable
  276. .Pp
  277. .D1 Vt extern struct snmp_client snmp_client ;
  278. .Pp
  279. that is used by all the library functions.
  280. The first call into the library must be a call to
  281. .Fn snmp_client_init
  282. to initialize this global variable to the default values.
  283. After this call and before calling
  284. .Fn snmp_open
  285. the fields of the variable may be modified by the user.
  286. The modification of the
  287. .Va chost
  288. and
  289. .Va cport
  290. fields should be done only via the functions
  291. .Fn snmp_client_set_host
  292. and
  293. .Fn snmp_client_set_port .
  294. .Pp
  295. The function
  296. .Fn snmp_open
  297. creates a UDP or
  298. .Ux
  299. domain socket and connects it to the agent's IP address and port.
  300. If any of the arguments of the call is not
  301. .Li NULL
  302. the corresponding field in the global
  303. .Va snmp_client
  304. is set from the argument.
  305. Otherwise the values that are already in that variable are used.
  306. The function
  307. .Fn snmp_close
  308. closes the socket, stops all timeouts and frees all dynamically allocated
  309. resources.
  310. .Pp
  311. The next three functions are used to create request PDUs.
  312. The function
  313. .Fn snmp_pdu_create
  314. initializes a PDU of type
  315. .Va op .
  316. It does not allocate space for the PDU itself.
  317. This is the responsibility of the caller.
  318. .Fn snmp_add_binding
  319. adds bindings to the PDU and returns the (zero based) index of the first new
  320. binding.
  321. The arguments are pairs of pointer to the OIDs and syntax constants,
  322. terminated by a NULL.
  323. The call
  324. .Bd -literal -offset indent
  325. snmp_add_binding(&pdu,
  326. &oid1, SNMP_SYNTAX_INTEGER,
  327. &oid2, SNMP_SYNTAX_OCTETSTRING,
  328. NULL);
  329. .Ed
  330. .Pp
  331. adds two new bindings to the PDU and returns the index of the first one.
  332. It is the responsibility of the caller to set the value part of the binding
  333. if necessary.
  334. The functions returns -1 if the maximum number of bindings is exhausted.
  335. The function
  336. .Fn snmp_oid_append
  337. can be used to construct variable OIDs for requests.
  338. It takes a pointer to an
  339. .Vt struct asn_oid
  340. that is to be constructed, a format string, and a number of arguments
  341. the type of which depends on the format string.
  342. The format string is interpreted
  343. character by character in the following way:
  344. .Bl -tag -width ".It Li ( Va N Ns Li )"
  345. .It Li i
  346. This format expects an argument of type
  347. .Vt asn_subid_t
  348. and appends this as a single integer to the OID.
  349. .It Li a
  350. This format expects an argument of type
  351. .Vt struct in_addr
  352. and appends to four parts of the IP address to the OID.
  353. .It Li s
  354. This format expects an argument of type
  355. .Vt const char *
  356. and appends the length of the string (as computed by
  357. .Xr strlen 3 )
  358. and each of the characters in the string to the OID.
  359. .It ( Va N Ns )
  360. This format expects no argument.
  361. .Va N
  362. must be a decimal number and is stored into an internal variable
  363. .Va size .
  364. .It Li b
  365. This format expects an argument of type
  366. .Vt const char *
  367. and appends
  368. .Va size
  369. characters from the string to the OID.
  370. The string may contain
  371. .Li NUL
  372. characters.
  373. .It Li c
  374. This format expects two arguments: one of type
  375. .Vt size_t
  376. and one of type
  377. .Vt const u_char * .
  378. The first argument gives the number of bytes to append to the OID from the string
  379. pointed to by the second argument.
  380. .El
  381. .Pp
  382. The function
  383. .Fn snmp_pdu_check
  384. may be used to check a response PDU.
  385. A number of checks are performed
  386. (error code, equal number of bindings, syntaxes and values for SET PDUs).
  387. The function returns +1 if everything is ok, 0 if a NOSUCHNAME or similar
  388. error was detected, -1 if the response PDU had fatal errors
  389. and -2 if
  390. .Fa resp
  391. is
  392. .Li NULL
  393. (a timeout occurred).
  394. .Pp
  395. The function
  396. .Fn snmp_pdu_send
  397. encodes and sends the given PDU.
  398. It records the PDU together with the callback
  399. and user pointers in an internal list and arranges for retransmission if no
  400. response is received.
  401. When a response is received or the retransmission count
  402. is exceeded the callback
  403. .Fa func
  404. is called with the orignal request PDU, the response PDU and the user argument
  405. .Fa uarg .
  406. If the retransmit count is exceeded,
  407. .Fa func
  408. is called with the original request PDU, the response pointer set to
  409. .Li NULL
  410. and the user argument
  411. .Fa uarg .
  412. The caller should not free the request PDU until the callback function is
  413. called.
  414. The callback function must free the request PDU and the response PDU (if not
  415. .Li NULL ).
  416. .Pp
  417. The function
  418. .Fn snmp_receive
  419. tries to receive a PDU.
  420. If the argument is zero, the function polls to see
  421. whether a packet is available, if the argument is non-zero, the function blocks
  422. until the next packet is received.
  423. The packet is delivered via the usual callback
  424. mechanism (non-response packets are silently dropped).
  425. The function returns 0, if a packet was received and successfully dispatched,
  426. -1 if an error occurred or no packet was available (in polling mode).
  427. .Pp
  428. The next two functions are used to retrieve tables from SNMP agents.
  429. They use
  430. the following input structure, that describes the table:
  431. .Bd -literal -offset indent
  432. struct snmp_table {
  433. struct asn_oid table;
  434. struct asn_oid last_change;
  435. u_int max_iter;
  436. size_t entry_size;
  437. u_int index_size;
  438. uint64_t req_mask;
  439. struct snmp_table_entry {
  440. asn_subid_t subid;
  441. enum snmp_syntax syntax;
  442. off_t offset;
  443. } entries[];
  444. };
  445. .Ed
  446. .Pp
  447. The fields of this structure have the following meaning:
  448. .Bl -tag -width "last_change"
  449. .It Va table
  450. This is the base OID of the table.
  451. .It Va last_change
  452. Some tables have a scalar variable of type TIMETICKS attached to them,
  453. that holds the time when the table was last changed.
  454. This OID should be the OID of this variable (without the \&.0 index).
  455. When the table is retrieved
  456. with multiple GET requests, and the variable changes between two request,
  457. the table fetch is restarted.
  458. .It Va max_iter
  459. Maximum number of tries to fetch the table.
  460. .It Va entry_size
  461. The table fetching routines return a list of structures one for each table
  462. row.
  463. This variable is the size of one structure and used to
  464. .Xr malloc 3
  465. the structure.
  466. .It Va index_size
  467. This is the number of index columns in the table.
  468. .It Va req_mask
  469. This is a bit mask with a 1 for each table column that is required.
  470. Bit 0 corresponds to the first element (index 0) in the array
  471. .Va entries ,
  472. bit 1 to the second (index 1) and so on.
  473. SNMP tables may be sparse.
  474. For sparse columns the bit should not be set.
  475. If the bit for a given column is set and
  476. the column value cannot be retrieved for a given row, the table fetch is
  477. restarted assuming that the table is currently being modified by the agent.
  478. The bits for the index columns are ignored.
  479. .It Va entries
  480. This is a variable sized array of column descriptors.
  481. This array is terminated by an element with syntax
  482. .Li SNMP_SYNTAX_NULL .
  483. The first
  484. .Va index_size
  485. elements describe all the index columns of the table, the rest are normal
  486. columns.
  487. If for the column at
  488. .Ql entries[N]
  489. the expression
  490. .Ql req_mask & (1 << N)
  491. yields true, the column is considered a required column.
  492. The fields of this the array elements have the following meaning:
  493. .Bl -tag -width "syntax"
  494. .It Va subid
  495. This is the OID subid of the column.
  496. This is ignored for index entries.
  497. Index entries are decoded according to the
  498. .Va syntax
  499. field.
  500. .It Va syntax
  501. This is the syntax of the column or index.
  502. A syntax of
  503. .Li SNMP_SYNTAX_NULL
  504. terminates the array.
  505. .It Va offset
  506. This is the starting offset of the value of the column in the return structures.
  507. This field can be set with the ISO-C
  508. .Fn offsetof
  509. macro.
  510. .El
  511. .El
  512. .Pp
  513. Both table fetching functions return TAILQ (see
  514. .Xr queue 3 )
  515. of structures--one for each table row.
  516. These structures must start with a
  517. .Fn TAILQ_ENTRY
  518. and a
  519. .Vt uint64_t
  520. and are allocated via
  521. .Xr malloc 3 .
  522. The
  523. .Fa list
  524. argument of the table functions must point to a
  525. .Fn TAILQ_HEAD .
  526. The
  527. .Vt uint64_t
  528. fields, usually called
  529. .Va found
  530. is used to indicate which of the columns have been found for the given
  531. row.
  532. It is encoded like the
  533. .Fa req_mask
  534. field.
  535. .Pp
  536. The function
  537. .Fn snmp_table_fetch
  538. synchronously fetches the given table.
  539. If everything is ok 0 is returned.
  540. Otherwise the function returns -1 and sets an appropriate error string.
  541. The function
  542. .Fn snmp_table_fetch_async
  543. fetches the tables asynchronously.
  544. If either the entire table is fetch, or
  545. an error occurs the callback function
  546. .Fa callback
  547. is called with the callers arguments
  548. .Fa list
  549. and
  550. .Fa uarg
  551. and a parameter that is either 0 if the table was fetched, or
  552. -1 if there was an error.
  553. The function itself returns -1 if it could not
  554. initialize fetching of the table.
  555. .Pp
  556. The following table description is used to fetch the ATM interface table:
  557. .Bd -literal -offset indent
  558. /*
  559. * ATM interface table
  560. */
  561. struct atmif {
  562. TAILQ_ENTRY(atmif) link;
  563. uint64_t found;
  564. int32_t index;
  565. u_char *ifname;
  566. size_t ifnamelen;
  567. uint32_t node_id;
  568. uint32_t pcr;
  569. int32_t media;
  570. uint32_t vpi_bits;
  571. uint32_t vci_bits;
  572. uint32_t max_vpcs;
  573. uint32_t max_vccs;
  574. u_char *esi;
  575. size_t esilen;
  576. int32_t carrier;
  577. };
  578. TAILQ_HEAD(atmif_list, atmif);
  579. /* list of all ATM interfaces */
  580. struct atmif_list atmif_list;
  581. static const struct snmp_table atmif_table = {
  582. OIDX_begemotAtmIfTable,
  583. OIDX_begemotAtmIfTableLastChange, 2,
  584. sizeof(struct atmif),
  585. 1, 0x7ffULL,
  586. {
  587. { 0, SNMP_SYNTAX_INTEGER,
  588. offsetof(struct atmif, index) },
  589. { 1, SNMP_SYNTAX_OCTETSTRING,
  590. offsetof(struct atmif, ifname) },
  591. { 2, SNMP_SYNTAX_GAUGE,
  592. offsetof(struct atmif, node_id) },
  593. { 3, SNMP_SYNTAX_GAUGE,
  594. offsetof(struct atmif, pcr) },
  595. { 4, SNMP_SYNTAX_INTEGER,
  596. offsetof(struct atmif, media) },
  597. { 5, SNMP_SYNTAX_GAUGE,
  598. offsetof(struct atmif, vpi_bits) },
  599. { 6, SNMP_SYNTAX_GAUGE,
  600. offsetof(struct atmif, vci_bits) },
  601. { 7, SNMP_SYNTAX_GAUGE,
  602. offsetof(struct atmif, max_vpcs) },
  603. { 8, SNMP_SYNTAX_GAUGE,
  604. offsetof(struct atmif, max_vccs) },
  605. { 9, SNMP_SYNTAX_OCTETSTRING,
  606. offsetof(struct atmif, esi) },
  607. { 10, SNMP_SYNTAX_INTEGER,
  608. offsetof(struct atmif, carrier) },
  609. { 0, SNMP_SYNTAX_NULL, 0 }
  610. }
  611. };
  612. \&...
  613. if (snmp_table_fetch(&atmif_table, &atmif_list) != 0)
  614. errx(1, "AtmIf table: %s", snmp_client.error);
  615. \&...
  616. .Ed
  617. .Pp
  618. The function
  619. .Fn snmp_dialog
  620. is used to execute a synchonuous dialog with the agent.
  621. The request PDU
  622. .Fa req
  623. is sent and the function blocks until the response PDU is received.
  624. Note,
  625. that asynchonuous receives are handled (i.e. callback functions of other send
  626. calls or table fetches may be called while in the function).
  627. The response PDU is returned in
  628. .Fa resp .
  629. If no response could be received after all timeouts and retries, the function
  630. returns -1.
  631. If a response was received 0 is returned.
  632. .Pp
  633. The function
  634. .Fn snmp_discover_engine
  635. is used to discover the authorative snmpEngineId of a remote SNMPv3 agent.
  636. A request PDU with empty USM user name is sent and the client's engine
  637. parameters are set according to the snmpEngine parameters received in the
  638. response PDU.
  639. If the client is configured to use authentication and/or privacy and the
  640. snmpEngineBoots and/or snmpEngineTime in the response had zero values, an
  641. additional request (possibly encrypted) with the appropriate user credentials
  642. is sent to fetch the missing values.
  643. Note, that the function blocks until the discovery proccess is completed.
  644. If no response could be received after all timeouts and retries, or the
  645. response contained errors the function returns -1.
  646. If the discovery proccess was completed 0 is returned.
  647. .Pp
  648. The function
  649. .Fn snmp_parse_server
  650. is used to parse an SNMP server specification string and fill in the
  651. fields of a
  652. .Vt struct snmp_client .
  653. The syntax of a server specification is
  654. .Pp
  655. .D1 [trans::][community@][server][:port]
  656. .Pp
  657. where
  658. .Va trans
  659. is the transport name (one of udp, stream or dgram),
  660. .Va community
  661. is the string to be used for both the read and the write community,
  662. .Va server
  663. is the server's host name in case of UDP and the path name in case
  664. of a local socket, and
  665. .Va port
  666. is the port in case of UDP transport.
  667. The function returns 0 in the case of success and return -1 and sets
  668. the error string in case of an error.
  669. .Sh DIAGNOSTICS
  670. If an error occurs in any of the function an error indication as described
  671. above is returned.
  672. Additionally the function sets a printable error string
  673. in the
  674. .Va error
  675. filed of
  676. .Va snmp_client .
  677. .Sh SEE ALSO
  678. .Xr gensnmptree 1 ,
  679. .Xr bsnmpd 1 ,
  680. .Xr bsnmpagent 3 ,
  681. .Xr bsnmplib 3
  682. .Sh STANDARDS
  683. This implementation conforms to the applicable IETF RFCs and ITU-T
  684. recommendations.
  685. .Sh AUTHORS
  686. .An Hartmut Brandt Aq harti@FreeBSD.org
  687. .An Kendy Kutzner Aq kutzner@fokus.gmd.de