The OpenNET Project / Index page

[ новости /+++ | форум | теги | ]

Интерактивная система просмотра системных руководств (man-ов)

 ТемаНаборКатегория 
 
 [Cписок руководств | Печать]

bsnmpclient (3)
  • >> bsnmpclient (3) ( FreeBSD man: Библиотечные вызовы )

  • BSD mandoc
     

    NAME

    
    
    snmp_client
    
     
    snmp_send_cb_f
    
     
    snmp_timeout_cb_f
    
     
    snmp_timeout_start_f
    
     
    snmp_timeout_stop_f
    
     
    snmp_open
    
     
    snmp_close
    
     
    snmp_pdu_create
    
     
    snmp_add_binding
    
     
    snmp_pdu_check
    
     
    snmp_pdu_send
    
     
    snmp_oid_append
    
     
    snmp_parse_server
    
     
    snmp_receive
    
     
    snmp_table_cb_f
    
     
    snmp_table_fetch
    
     
    snmp_table_fetch_async
    
     
    snmp_dialog
    
     - SNMP client library
    
     
    

    LIBRARY

    Begemot SNMP library
    (libbsnmp, -lbsnmp)
    
     
    

    SYNOPSIS

       #include <asn1.h>
       #include <snmp.h>
       #include <snmpclient.h>
    typedef void Fn (*snmp_send_cb_f) struct snmp_pdu *req struct snmp_pdu *resp void *uarg typedef void Fn (*snmp_timeout_cb_f) void *uarg typedef void * Fn (*snmp_timeout_start_f) struct timeval *timeout snmp_timeout_cb_f callback void *uarg typedef void Fn (*snmp_timeout_stop_f) void *timeout_id Vt extern struct snmp_client snmp_client ; void snmp_client_init (struct snmp_client *client);
    int snmp_client_set_host (struct snmp_client *client const char *host);
    int snmp_client_set_port (struct snmp_client *client const char *port);
    int snmp_open (const char *host const char *port const char *read_community const char *write_community);
    void snmp_close (void);
    void snmp_pdu_create (struct snmp_pdu *pdu u_int op);
    int snmp_add_binding (struct snmp_pdu *pdu ...);
    int snmp_pdu_check (const struct snmp_pdu *req const struct snmp_pdu *resp);
    int32_t snmp_pdu_send (struct snmp_pdu *pdu snmp_send_cb_f func void *uarg);
    int snmp_oid_append (struct asn_oid *oid const char *fmt ...);
    int snmp_parse_server (struct snmp_client *sc const char *str);
    int snmp_receive (int blocking);
    typedef void Fn (*snmp_table_cb_f) void *list void *arg int res int snmp_table_fetch (const struct snmp_table *descr void *list);
    int snmp_table_fetch_async (const struct snmp_table *descr void *list snmp_table_cb_f callback void *uarg);
    int snmp_dialog (struct snmp_pdu *req struct snmp_pdu *resp);
     

    DESCRIPTION

    The SNMP library contains routines to easily build SNMP client applications that use SNMP versions 1 or 2. Most of the routines use a Vt struct snmp_client :
    struct snmp_client {
            enum snmp_version version;
            int     trans;  /* transport type to use */
    
            /* these two are read-only for the application */
            char    *cport; /* port number as string */
            char    *chost; /* host name or IP address as string */
    
            char    read_community[SNMP_COMMUNITY_MAXLEN + 1];
            char    write_community[SNMP_COMMUNITY_MAXLEN + 1];
    
            struct timeval  timeout;
            u_int   retries;
    
            int     dump_pdus;
    
            size_t  txbuflen;
            size_t  rxbuflen;
    
            int     fd;
    
            int32_t next_reqid;
            int32_t max_reqid;
            int32_t min_reqid;
    
            char    error[SNMP_STRERROR_LEN];
    
            snmp_timeout_start_f timeout_start;
            snmp_timeout_stop_f timeout_stop;
    
            /* private */
            char    local_path[sizeof(SNMP_LOCAL_PATH)];
    };
    

    The fields of this structure are described below.

    version
    This is the version of SNMP to use. See bsnmplib(3) for applicable values. The default version is SNMP_V2c
    trans
    If this is SNMP_TRANS_LOC_DGRAM a local datagram socket is used. If it is SNMP_TRANS_LOC_STREAM a local stream socket is used. For SNMP_TRANS_UDP a UDP socket is created. It uses the chost field as the path to the server's socket for local sockets.
    cport
    The SNMP agent's UDP port number. This may be a symbolic port number (from /etc/services or a numeric port number. If this field is NULL (the default) the standard SNMP port is used. This field should not be changed directly but rather by calling snmp_client_set_port (.);
    chost
    The SNMP agent's host name, IP address or UNIX domain socket path name. If this is NULL (the default) localhost is assumed. This field should not be changed directly but rather through calling snmp_client_set_host (.);
    read_community
    This is the community name to be used for all requests except SET requests. The default is `public'
    write_community
    The community name to be used for SET requests. The default is `private'
    timeout
    The maximum time to wait for responses to requests. If the time elapses, the request is resent up to retries times. The default is 3 seconds.
    retries
    Number of times a request PDU is to be resent. If set to 0, the request is sent only once. The default is 3 retransmissions.
    dump_pdus
    If set to a non-zero value all received and sent PDUs are dumped via snmp_pdu_dump3. The default is not to dump PDUs.
    txbuflen
    The encoding buffer size to be allocated for transmitted PDUs. The default is 10000 octets.
    rxbuflen
    The decoding buffer size to be allocated for received PDUs. This is the size of the maximum PDU that can be received. The default is 10000 octets.
    fd
    After calling snmp_open ();
    this is the file socket file descriptor used for sending and receiving PDUs.
    next_reqid
    The request id of the next PDU to send. Used internal by the library.
    max_reqid
    The maximum request id to use for outgoing PDUs. The default is INT32_MAX
    min_reqid
    The minimum request id to use for outgoing PDUs. Request ids are allocated linearily starting at min_reqid up to max_reqid
    error
    If an error happens, this field is set to a printable string describing the error.
    timeout_start
    This field must point to a function setting up a one shot timeout. After the timeout has elapsed, the given callback function must be called with the user argument. The timeout_start ();
    function must return a Vt void * identifying the timeout.
    timeout_stop
    This field must be set to a function that stops a running timeout. The function will be called with the return value of the corresponding timeout_start ();
    function.
    local_path
    If in local socket mode, the name of the clients socket. Not needed by the application.

    In the current implementation there is a global variable

    that is used by all the library functions. The first call into the library must be a call to snmp_client_init ();
    to initialize this global variable to the default values. After this call and before calling snmp_open ();
    the fields of the variable may be modified by the user. The modification of the chost and cport fields should be done only via the functions snmp_client_set_host ();
    and snmp_client_set_port (.);

    The function snmp_open ();
    creates a UDP or UNIX domain socket and connects it to the agent's IP address and port. If any of the arguments of the call is not NULL the corresponding field in the global snmp_client is set from the argument. Otherwise the values that are already in that variable are used. The function snmp_close ();
    closes the socket, stops all timeouts and frees all dynamically allocated resources.

    The next three functions are used to create request PDUs. The function snmp_pdu_create ();
    initializes a PDU of type op It does not allocate space for the PDU itself. This is the responsibility of the caller. snmp_add_binding ();
    adds bindings to the PDU and returns the (zero based) index of the first new binding. The arguments are pairs of pointer to the OIDs and syntax constants, terminated by a NULL. The call

    snmp_add_binding(&pdu,
        &oid1, SNMP_SYNTAX_INTEGER,
        &oid2, SNMP_SYNTAX_OCTETSTRING,
        NULL);
    

    adds two new bindings to the PDU and returns the index of the first one. It is the responsibility of the caller to set the value part of the binding if necessary. The functions returns -1 if the maximum number of bindings is exhausted. The function snmp_oid_append ();
    can be used to construct variable OIDs for requests. It takes a pointer to an Vt struct asn_oid that is to be constructed, a format string, and a number of arguments the type of which depends on the format string. The format string is interpreted character by character in the following way:

    i
    This format expects an argument of type Vt asn_subid_t and appends this as a single integer to the OID.
    a
    This format expects an argument of type Vt struct in_addr and appends to four parts of the IP address to the OID.
    s
    This format expects an argument of type Vt const char * and appends the length of the string (as computed by strlen(3)) and each of the characters in the string to the OID.
    ( N )
    This format expects no argument. N must be a decimal number and is stored into an internal variable size
    b
    This format expects an argument of type Vt const char * and appends size characters from the string to the OID. The string may contain NUL characters.
    c
    This format expects two arguments: one of type Vt size_t and one of type Vt const u_char * . The first argument gives the number of bytes to append to the OID from the string pointed to by the second argument.

    The function snmp_pdu_check ();
    may be used to check a response PDU. A number of checks are performed (error code, equal number of bindings, syntaxes and values for SET PDUs). The function returns +1 if everything is ok, 0 if a NOSUCHNAME or similar error was detected, -1 if the response PDU had fatal errors and -2 if Fa resp is NULL (a timeout occurred).

    The function snmp_pdu_send ();
    encodes and sends the given PDU. It records the PDU together with the callback and user pointers in an internal list and arranges for retransmission if no response is received. When a response is received or the retransmission count is exceeded the callback Fa func is called with the orignal request PDU, the response PDU and the user argument Fa uarg . If the retransmit count is exceeded, Fa func is called with the original request PDU, the response pointer set to NULL and the user argument Fa uarg . The caller should not free the request PDU until the callback function is called. The callback function must free the request PDU and the response PDU (if not NULL ).

    The function snmp_receive ();
    tries to receive a PDU. If the argument is zero, the function polls to see whether a packet is available, if the argument is non-zero, the function blocks until the next packet is received. The packet is delivered via the usual callback mechanism (non-response packets are silently dropped). The function returns 0, if a packet was received and successfully dispatched, -1 if an error occurred or no packet was available (in polling mode).

    The next two functions are used to retrieve tables from SNMP agents. They use the following input structure, that describes the table:

    struct snmp_table {
            struct asn_oid          table;
            struct asn_oid          last_change;
            u_int                   max_iter;
            size_t                  entry_size;
            u_int                   index_size;
            uint64_t                req_mask;
    
            struct snmp_table_entry {
                asn_subid_t         subid;
                enum snmp_syntax    syntax;
                off_t               offset;
            }                       entries[];
    };
    

    The fields of this structure have the following meaning:

    table
    This is the base OID of the table.
    last_change
    Some tables have a scalar variable of type TIMETICKS attached to them, that holds the time when the table was last changed. This OID should be the OID of this variable (without the .0 index). When the table is retrieved with multiple GET requests, and the variable changes between two request, the table fetch is restarted.
    max_iter
    Maximum number of tries to fetch the table.
    entry_size
    The table fetching routines return a list of structures one for each table row. This variable is the size of one structure and used to malloc(3) the structure.
    index_size
    This is the number of index columns in the table.
    req_mask
    This is a bit mask with a 1 for each table column that is required. Bit 0 corresponds to the first element (index 0) in the array entries bit 1 to the second (index 1) and so on. SNMP tables may be sparse. For sparse columns the bit should not be set. If the bit for a given column is set and the column value cannot be retrieved for a given row, the table fetch is restarted assuming that the table is currently being modified by the agent. The bits for the index columns are ignored.
    entries
    This is a variable sized array of column descriptors. This array is terminated by an element with syntax SNMP_SYNTAX_NULL The first index_size elements describe all the index columns of the table, the rest are normal columns. If for the column at `entries[N]' the expression `req_mask' & (1 << N) yields true, the column is considered a required column. The fields of this the array elements have the following meaning:

    subid
    This is the OID subid of the column. This is ignored for index entries. Index entries are decoded according to the syntax field.
    syntax
    This is the syntax of the column or index. A syntax of SNMP_SYNTAX_NULL terminates the array.
    offset
    This is the starting offset of the value of the column in the return structures. This field can be set with the ISO-C offsetof ();
    macro.

    Both table fetching functions return TAILQ (see queue(3)) of structures--one for each table row. These structures must start with a TAILQ_ENTRY ();
    and a Vt uint64_t and are allocated via malloc(3). The Fa list argument of the table functions must point to a TAILQ_HEAD (.);
    The Vt uint64_t fields, usually called found is used to indicate which of the columns have been found for the given row. It is encoded like the Fa req_mask field.

    The function snmp_table_fetch ();
    synchronously fetches the given table. If everything is ok 0 is returned. Otherwise the function returns -1 and sets an appropriate error string. The function snmp_table_fetch_async ();
    fetches the tables asynchronously. If either the entire table is fetch, or an error occurs the callback function Fa callback is called with the callers arguments Fa list and Fa uarg and a parameter that is either 0 if the table was fetched, or -1 if there was an error. The function itself returns -1 if it could not initialize fetching of the table.

    The following table description is used to fetch the ATM interface table:

    /*
     * ATM interface table
     */
    struct atmif {
            TAILQ_ENTRY(atmif) link;
            uint64_t        found;
            int32_t         index;
            u_char          *ifname;
            size_t          ifnamelen;
            uint32_t        node_id;
            uint32_t        pcr;
            int32_t         media;
            uint32_t        vpi_bits;
            uint32_t        vci_bits;
            uint32_t        max_vpcs;
            uint32_t        max_vccs;
            u_char          *esi;
            size_t          esilen;
            int32_t         carrier;
    };
    TAILQ_HEAD(atmif_list, atmif);
    
    /* list of all ATM interfaces */
    struct atmif_list atmif_list;
    
    static const struct snmp_table atmif_table = {
            OIDX_begemotAtmIfTable,
            OIDX_begemotAtmIfTableLastChange, 2,
            sizeof(struct atmif),
            1, 0x7ffULL,
            {
              { 0, SNMP_SYNTAX_INTEGER,
                    offsetof(struct atmif, index) },
              { 1, SNMP_SYNTAX_OCTETSTRING,
                    offsetof(struct atmif, ifname) },
              { 2, SNMP_SYNTAX_GAUGE,
                    offsetof(struct atmif, node_id) },
              { 3, SNMP_SYNTAX_GAUGE,
                    offsetof(struct atmif, pcr) },
              { 4, SNMP_SYNTAX_INTEGER,
                    offsetof(struct atmif, media) },
              { 5, SNMP_SYNTAX_GAUGE,
                    offsetof(struct atmif, vpi_bits) },
              { 6, SNMP_SYNTAX_GAUGE,
                    offsetof(struct atmif, vci_bits) },
              { 7, SNMP_SYNTAX_GAUGE,
                    offsetof(struct atmif, max_vpcs) },
              { 8, SNMP_SYNTAX_GAUGE,
                    offsetof(struct atmif, max_vccs) },
              { 9, SNMP_SYNTAX_OCTETSTRING,
                    offsetof(struct atmif, esi) },
              { 10, SNMP_SYNTAX_INTEGER,
                    offsetof(struct atmif, carrier) },
              { 0, SNMP_SYNTAX_NULL, 0 }
            }
    };
    
    ...
            if (snmp_table_fetch(&atmif_table, &atmif_list) != 0)
                    errx(1, "AtmIf table: %s", snmp_client.error);
    ...
    

    The function snmp_dialog ();
    is used to execute a synchonuous dialog with the agent. The request PDU Fa req is sent and the function blocks until the response PDU is received. Note, that asynchonuous receives are handled (i.e. callback functions of other send calls or table fetches may be called while in the function). The response PDU is returned in Fa resp . If no response could be received after all timeouts and retries, the function returns -1. If a response was received 0 is returned.

    The function snmp_parse_server ();
    is used to parse an SNMP server specification string and fill in the fields of a Vt struct snmp_client . The syntax of a server specification is

    where trans is the transport name (one of udp, stream or dgram), community is the string to be used for both the read and the write community, server is the server's host name in case of UDP and the path name in case of a local socket, and port is the port in case of UDP transport. The function returns 0 in the case of success and return -1 and sets the error string in case of an error.  

    DIAGNOSTICS

    If an error occurs in any of the function an error indication as described above is returned. Additionally the function sets a printable error string in the error filed of snmp_client  

    SEE ALSO

    gensnmptree(1), bsnmpd(1), bsnmpagent(3), bsnmplib(3)  

    STANDARDS

    This implementation conforms to the applicable IETF RFCs and ITU-T recommendations.  

    AUTHORS

    An Hartmut Brandt Aq harti@freebsd.org An Kendy Kutzner Aq kutzner@fokus.gmd.de


     

    Index

    NAME
    LIBRARY
    SYNOPSIS
    DESCRIPTION
    DIAGNOSTICS
    SEE ALSO
    STANDARDS
    AUTHORS


    Поиск по тексту MAN-ов: 




    Партнёры:
    PostgresPro
    Inferno Solutions
    Hosting by Hoster.ru
    Хостинг:

    Закладки на сайте
    Проследить за страницей
    Created 1996-2024 by Maxim Chirkov
    Добавить, Поддержать, Вебмастеру