net-snmp API分为两种,一种叫传统API(Traditional API),一种叫单个API(Single API)。早期的neet-snmp没有考虑到多线程的问题,所有的会话共享同一个资源,这些就是传统API,后来支持多线程的就叫做单个API。Single API是线程安全的。
先熟悉术语,尤其要注意对Session的官方理解:
APDU Application Protocol Data Unit
Session Concept embodying the management of transacting SNMP APDUs.
下面先列出Traditional API和Single API之间主要的区别:
The functions in the following table are functionally equivalent,
with the exception of these behaviors:
- The Traditional API manages many sessions
- The Traditional API passes a struct snmp_session pointer,
and touches the Sessions list
- The Single API manages only one session
- The Single API passes an opaque pointer, and does not use Sessions list
再看看API之间的区别:
Traditional Single Comment
=========== ============== =======
snmp_sess_init snmp_sess_init Call before either open
snmp_open snmp_sess_open Single not on Sessions lists
snmp_sess_session Exposes snmp_session pointer
snmp_send snmp_sess_send Send one APDU
snmp_async_send snmp_sess_async_send Send one APDU with callback
snmp_select_info snmp_sess_select_info Which session(s) have input
snmp_read snmp_sess_read Read APDUs
snmp_timeout snmp_sess_timeout Check for timeout
snmp_close snmp_sess_close Single not on Sessions list
snmp_synch_response snmp_sess_synch_response Send/receive one APDU
snmp_error snmp_sess_error Get library,system errno
从上面可知snmp_session是贯穿始终的,有必要了解一下snmp_session,先看一下定义:
/** @struct snmp_session * The snmp session structure. */
struct snmp_session {
/* * Protocol-version independent fields */
/** snmp version */
long version;
/** Number of retries before timeout. */
int retries;
/** Number of uS until first timeout, then exponential backoff */
long timeout;
u_long flags;
struct snmp_session *subsession;
struct snmp_session *next;
/** name or address of default peer (may include transport specifier and/or port number) */
char *peername;
/** UDP port number of peer. (NO LONGER USED - USE peername INSTEAD) */
u_short remote_port;
/** My Domain name or dotted IP address, 0 for default */
char *localname;
/** My UDP port number, 0 for default, picked randomly */
u_short local_port;
/** * Authentication function or NULL if null authentication is used s */
u_char *(*authenticator) (u_char *, size_t *, u_char *, size_t);
/** Function to interpret incoming data */
netsnmp_callback callback;
/** * Pointer to data that the callback function may consider important */
void *callback_magic;
/** copy of system errno */
int s_errno;
/** copy of library errno */
int s_snmp_errno;
/** Session id - AgentX only */
long sessid;
/* * SNMPv1 & SNMPv2c fields */
/** community for outgoing requests. */
u_char *community;
/** Length of community name. */
size_t community_len;
/** Largest message to try to receive. */
size_t rcvMsgMaxSize;
/** Largest message to try to send. */
size_t sndMsgMaxSize;
/* * SNMPv3 fields */
/** are we the authoritative engine? */
u_char isAuthoritative;
/** authoritative snmpEngineID */
u_char *contextEngineID;
/** Length of contextEngineID */
size_t contextEngineIDLen;
/** initial engineBoots for remote engine */
u_int engineBoots;
/** initial engineTime for remote engine */
u_int engineTime;
/** authoritative contextName */
char *contextName;
/** Length of contextName */
size_t contextNameLen;
/** authoritative snmpEngineID */
u_char *securityEngineID;
/** Length of contextEngineID */
size_t securityEngineIDLen;
/** on behalf of this principal */
char *securityName;
/** Length of securityName. */
size_t securityNameLen;
/** auth protocol oid */
oid *securityAuthProto;
/** Length of auth protocol oid */
size_t securityAuthProtoLen;
/** Ku for auth protocol XXX */
u_char securityAuthKey[USM_AUTH_KU_LEN];
/** Length of Ku for auth protocol */
size_t securityAuthKeyLen;
/** Kul for auth protocol */
u_char *securityAuthLocalKey;
/** Length of Kul for auth protocol XXX */
size_t securityAuthLocalKeyLen;
/** priv protocol oid */
oid *securityPrivProto;
/** Length of priv protocol oid */
size_t securityPrivProtoLen;
/** Ku for privacy protocol XXX */
u_char securityPrivKey[USM_PRIV_KU_LEN];
/** Length of Ku for priv protocol */
size_t securityPrivKeyLen;
/** Kul for priv protocol */
u_char *securityPrivLocalKey;
/** Length of Kul for priv protocol XXX */
size_t securityPrivLocalKeyLen;
/** snmp security model, v1, v2c, usm */
int securityModel;
/** noAuthNoPriv, authNoPriv, authPriv */
int securityLevel;
/** target param name */
char *paramName;
/** * security module specific */
void *securityInfo;
/** * transport specific configuration */
struct netsnmp_container_s *transport_configuration;
/** * use as you want data * used by 'SNMP_FLAGS_RESP_CALLBACK' handling in the agent
* XXX: or should we add a new field into this structure? */
void *myvoid;
};
这里面记录了我们发一个snmp APDUs所需要的重要信息,比如本地机和远程机的端口,名字,community string, timeout值,errorno,retries等等,参考一下Readme.thread,可以动态的修改session里面的参数。
After the struct snmp_session is setup, the thread must call snmp_sess_open() to create an SNMP session. If at any time the thread must change the Session configuration, snmp_sess_session() returns the pointer to the internal configuration structure (a struct snmp_session, copied from snmp_sess_open).
The thread can adjust parameters such as the session timeout or the community string with this returned struct snmp_session pointer. Changes to the remote or local port values have no effect on an opened Session.
1)分析采用的示例代码源自net-snmp官方教程中一片异步APP代码,详细可以点击这里
2)只列出了若干个API,更多的可以查看源码
3)这里分析的net-snmp源码版本为5.6.1
正文
if (!(hs->sess = snmp_open(&sess))) {
snmp_perror("snmp_open");
continue;
}
上面是snmp_open使用的演示代码,下面看看snmp_open里具体做了什么事情
netsnmp_session *
snmp_open(netsnmp_session *session)
{
struct session_list *slp;
slp = (struct session_list *) snmp_sess_open(session); //调用singleAPI创建
if (!slp) {
return NULL;
}
snmp_res_lock(MT_LIBRARY_ID, MT_LIB_SESSION); //这个函数是唬人的,根本没锁
slp->next = Sessions;//在snmp_api.c开头定义全局变量struct session_list *Sessions = NULL; /* MT_LIB_SESSION */
Sessions = slp; //添加到共享的Sessions链上
snmp_res_unlock(MT_LIBRARY_ID, MT_LIB_SESSION);//同样是唬人的s
return (slp->session);
}
snmp_open是传统API,这里可以看出所有的会话共享全局的Sessions链表。
snmp_res_lock为什么说是唬人的呢?我们明明在mt_suppotr.h和m_support.c里有看到支持跨平台的代码啊?注意看这两个文件里的宏编译之类NETSNMP_REENTRANT,可以在net-snmp-config.h里看到如下的注释:
/* add in recent resource lock functions (not complete) */
/* #undef NETSNMP_REENTRANT */
原来是还没有完全写完,OK,期待后续版本不用我们来自己写资源锁吧。
snmp_send
介绍:下面这些函数使用活动的会话发送PDUs
* snmp_send - traditional API, no callback
* snmp_async_send - traditional API, with callback(异步方式)
* snmp_sess_send - single session API, no callback
* snmp_sess_async_send - single session API, with callback(异步方式)
调用snmp_build来创建连续的包(即pdu),必要时采用会话的默认项设置某些pdu数据。
如果这个PDU有额外的响应,那就需要排列这个会话的外出请求并且存储这些回调向量。
通过会话向指定目标发送pdu。
如果成功,返回这个pdu请求的id,并且这个pdu被释放。如果失败,返回0,调用者必须调用snmmp_free_pdu释放资源。
snmp_send调用snmp_asyn_send,后者又调用snmp_sess_asyn_send,callback和cb_data参数都为NULL。
int snmp_async_send(netsnmp_session * session,
netsnmp_pdu *pdu, snmp_callback callback, void *cb_data)
{
void *sessp = snmp_sess_pointer(session);
return snmp_sess_async_send(sessp, pdu, callback, cb_data);
}
snmp_sess_pointer函数在全局变量Sessions里查找当前这个session,如果存在返回这个会话指针,否则返回NULL,snmp_error同时设置为SNMPERR_BAD_SESSION。
snmp_select_info
介绍:
输入:如果输入的timeout没有被定义,block设为1;如果输入的timeout被定义了,block设为0。
输出:如果输出的timeout没有被定义,block被视为1;如果输出的timeout被定义了,block被设为0。
上面的输入输出指定是参数timeout和block。
该函数的返回值为可以操作的socket数量,并且这些socket已经被选到了fdset里,供后续的select操作。
示例代码如下
int fds = 0, block = 1;
fd_set fdset;
struct timeval timeout;
FD_ZERO(&fdset);
snmp_select_info(&fds, &fdset, &timeout, &block);
fds = select(fds, &fdset, NULL, NULL, block ? NULL : &timeout);
if (fds < 0) {
perror("select failed");
exit(1);
}
if (fds) snmp_read(&fdset);
else snmp_timeout();
因为输入timeout没有定义,block为1,那么输出后timeout值为0,block值被设为0 s
这里需要注意的是是里面调用了netsnmp_large_fd_set这个结构,它的介绍如源码注释所说
/*
* Structure for holding a set of file descriptors, similar to fd_set.
*
* This structure however can hold so-called large file descriptors
* (>= FD_SETSIZE or 1024) on Unix systems or more than FD_SETSIZE (64)
* sockets on Windows systems.
*
* It is safe to allocate this structure on the stack.
*
* This structure must be initialized by calling netsnmp_large_fd_set_init()
* and must be cleaned up via netsnmp_large_fd_set_cleanup(). If this last
* function is not called this may result in a memory leak.
* The members of this structure are:
* lfs_setsize: maximum set size.
* lsf_setptr: points to lfs_set if lfs_setsize <= FD_SETSIZE, and otherwise
* to dynamically allocated memory.
* lfs_set: file descriptor / socket set data if lfs_setsize <= FD_SETSIZE.
*/
typedef struct netsnmp_large_fd_set_s {
unsigned lfs_setsize;
fd_set *lfs_setptr;
fd_set lfs_set;
} netsnmp_large_fd_set;
snmp_read
介绍:校验看看fd里面的集合是否属于snmp。每个socket的fd集合都有一个从它读取的包,同时snmp_parse被调用来接收包。pud的结果被传递给那个会话的回调例程。如果回调例程返回成功,这个pdu和它的请求就被删除掉。
snmp_timeout
介绍:当snmp_select_info里设定的超时期满的时候,这个函数应当被调用,但是它是幂等(idempotent)的,所以snmp_timeout能够被检验(大概一个cpu时间)。snmp_timeout检验查看每一个拥有对外请求的会话是否已经超时。如果它发现一个(或多个),并且那个pdu拥有多余可用的尝试次数,这个pud就构造一个新报文并且重新发送。如果没有多余的可用次数,这个会话的回调函数就会被用来通知用户超时了。