1NETSNMP_AGENT_API(3)               Net-SNMP               NETSNMP_AGENT_API(3)
2
3
4

NAME

6       netsnmp_agent_api - embedding an agent into a external application
7

SYNOPSIS

9       #include <net-snmp/net-snmp-config.h>
10       #include <net-snmp/net-snmp-includes.h>
11       #include <net-snmp/agent/net-snmp-agent-includes.h>
12
13       int
14       main (int argc, char *argv[])
15       {
16         int agentx_subagent = 1;  /* Change this if you're a master agent.  */
17
18         snmp_enable_stderrlog();
19
20         /*  If we're an AgentX subagent...  */
21         if (agentx_subagent) {
22             /* ...make us an AgentX client.  */
23             netsnmp_ds_set_boolean(NETSNMP_DS_APPLICATION_ID,
24                                    NETSNMP_DS_AGENT_ROLE, 1);
25         }
26
27         init_agent("yourappname");
28
29         /*  Initialize your MIB code here.  */
30         init_my_mib_code();
31
32         /*  `yourappname' will be used to read yourappname.conf files.  */
33         init_snmp("yourappname");
34
35         /*  If we're going to be a SNMP master agent...  */
36         if (!agentx_subagent)
37             init_master_agent();  /*  Listen on default port (161).  */
38
39         /*  Your main loop here...  */
40         while (whatever) {
41             /* if you use select(), see snmp_api(3) */
42             /*     --- OR ---  */
43             agent_check_and_process(0); /* 0 == don't block */
44         }
45
46         /*  At shutdown time:  */
47         snmp_shutdown("yourappname");
48       }
49
50       Then:
51       $(CC) ... `net-snmp-config --agent-libs`
52
53

DESCRIPTION

55       Our  goal  is to create a easy to use interface to the Net-SNMP package
56       such that you can take  code  that  you  have  written  that  has  been
57       designed  to  be  a  Net-SNMP  MIB module and embed it into an external
58       application where you can either chose to be a SNMP master agent or  an
59       AgentX  sub-agent  using  the  same MIB module code.  Our suggestion is
60       that you use our (or another) SNMP agent as the AgentX master agent and
61       chose to become an AgentX subagent which then attaches to the master.
62
63       The  Net-SNMP  package  provides  a pair of libraries that enables easy
64       embedding of an SNMP or AgentX agent into an external software package.
65       AgentX  is  an extensible protocol designed to allow multiple SNMP sub-
66       agents all run on one machine under a single SNMP master agent.  It  is
67       defined in RFC 2741.
68
69       You will need to perform a few tasks in order to accomplish this. First
70       off, you will need to initialize both the SNMP  library  and  the  SNMP
71       agent  library.  As  indicated above, this is done slightly differently
72       depending on whether or not you are going to perform as a master  agent
73       or an AgentX sub-agent.
74

CONFIGURATION

76       If  you intend to operate as an AgentX sub-agent, you will have to con‐
77       figured the Net-SNMP package with agentx support (which is turned on by
78       default, so just don't turn it off)
79
80       Additionally, you will need to link against the Net-SNMP libraries (use
81       the output of "net-snmp-config --agent-libs" to get a library list) and
82       call subagent_pre_init() as indicated above.
83

COMPILING

85       In  order  to  make  use of any of the above API, you will need to link
86       against at least the four libraries listed above.
87

FUNCTIONS

89       where to find out more information on them.  It is certainly not a com‐
90       plete list of what is available within all the Net-SNMP libraries.
91
92       snmp_enable_stderrlog()
93              Logs  error  output  from  the  SNMP agent to the standard error
94              stream.
95
96       netsnmp_ds_set_boolean()
97              Please see the default_store(3) manual page for more information
98              about this API.
99
100       init_agent(char *name)
101              Initializes  the  embedded  agent.  This should be called before
102              the init_snmp() call.  name is used to dictate what  .conf  file
103              to read when init_snmp() is called later.
104
105       init_snmp(char *name)
106              Initializes  the SNMP library.  Note that one of the things this
107              will do will be to read configuration files in an effort to con‐
108              figure  your application. It will attempt to read the configura‐
109              tion files named by the name string that you passed in.  It  can
110              be  used to configure access control, for instance.   Please see
111              the  netsnmp_config_api(3),  snmp_config(5),  and  snmpd.conf(5)
112              manual pages for further details on this subject.
113
114       init_master_agent(void)
115              Initializes  the  master  agent and causes it to listen for SNMP
116              requests on its default UDP port of 161.
117
118       agent_check_and_process(int block)
119              This checks for packets arriving on the SNMP port and  processes
120              them if some are found.  If block is non-zero, the function call
121              will block until a packet arrives or an alarm must be  run  (see
122              snmp_alarm(3)).   The return value from this function is a posi‐
123              tive integer  if  packets  were  processed,  zero  if  an  alarm
124              occurred and -1 if an error occured.
125
126       snmp_shutdown(char *name);
127              This shuts down the agent, saving any needed persistent storage,
128              etc.
129

SEE ALSO

131       http://www.net-snmp.org/tutorial-5/toolkit/   select(2),   snmp_api(3),
132       default_store(3), snmp_alarm(3), netsnmp_config_api(3), snmp_config(5),
133       snmpd.conf(5)
134
135
136
137V5.7.2                            13 Aug 2010             NETSNMP_AGENT_API(3)
Impressum