NETSNMP_AGENT_API(3)

📦
version 5.9.5.2 · 5 versions
, in alpine 3.23, alpine 3.24, arch rolling, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu stonking

✨ NETSNMP_AGENT_API ✨

a.k.a. the Net-SNMP manual page, bestie — welcome to the group chat 💅

🎀 NAME

netsnmp_agent_api — embedding an agent into an external application

yes literally just that, "embedding an agent into an external application", that's the whole vibe 🦋

🌸 SYNOPSIS

#include <net-snmp/net-snmp-config.h>
#include <net-snmp/net-snmp-includes.h>
#include <net-snmp/agent/net-snmp-agent-includes.h>

int
main (int argc, char *argv[])
{
  int agentx_subagent = 1;  /* Change this if you're a master agent.  */

  snmp_enable_stderrlog();

  /*  If we're an AgentX subagent...  */
  if (agentx_subagent) {
      /* ...make us an AgentX client.  */
      netsnmp_ds_set_boolean(NETSNMP_DS_APPLICATION_ID,
                             NETSNMP_DS_AGENT_ROLE, 1);
  }

  init_agent("yourappname");

  /*  Initialize your MIB code here.  */
  init_my_mib_code();

  /*  `yourappname' will be used to read yourappname.conf files.  */
  init_snmp("yourappname");

  /*  If we're going to be an SNMP master agent...  */
  if (!agentx_subagent)
      init_master_agent();  /*  Listen on default port (161).  */

  /*  Your main loop here...  */
  while (whatever) {
      /* if you use select(), see snmp_api(3) */
      /*     --- OR ---  */
      agent_check_and_process(0); /* 0 == don't block */
  }

  /*  At shutdown time:  */
  snmp_shutdown("yourappname");
}

and then, to actually build the thing:

$(CC) ... `net-snmp-config --agent-libs`

💖 DESCRIPTION

okay so the whole goal here is to give you an easy-to-use interface to the Net-SNMP package. like, the dream is that you take code you already wrote that was designed to be a Net-SNMP MIB module, and you just… embed it into an external application. and from there you get to choose: are you an SNMP master agent or an AgentX sub-agent? same MIB module code either way, no cap. 🔥

our suggestion (and honestly it's giving main character energy) is that you use our SNMP agent — or somebody else's — as the AgentX master agent, and then choose to become an AgentX subagent that attaches to the master. periodt.

The Net-SNMP package hands you a pair of libraries that make it genuinely easy to embed an SNMP or AgentX agent into an external software package. AgentX is an extensible protocol designed to let multiple SNMP sub-agents all run on one machine under a single SNMP master agent. it's defined in RFC 2741. 📜

so to pull this off you've got a few tasks, bestie. first off, you need to initialize BOTH the SNMP library AND the SNMP agent library. and as shown up there in the synopsis, that's done slightly differently depending on whether you're performing as a master agent or as an AgentX sub-agent. 🫶

🧚 CONFIGURATION

if you intend to operate as an AgentX sub-agent, you will have to configure the Net-SNMP package with agentx support. good news: it's turned on by default, so just… don't turn it off. that's the whole instruction. iconic. 💅

additionally, you'll need to link against the Net-SNMP libraries — use the output of net-snmp-config --agent-libs to get yourself a library list — and call subagent_pre_init() as indicated above. ✨

🌈 COMPILING

in order to make use of any of the above API, you will need to link against at least the four libraries listed above. that's the bar. meet it. 👑

👑 FUNCTIONS

okay so this section is where to find out more information on them. it is certainly not a complete list of what is available within all the Net-SNMP libraries — think of it as a starter pack, not the whole closet. 🙈

⭐ snmp_enable_stderrlog()

Logs error output from the SNMP agent to the standard error stream. so like, when things go wrong, you actually get to see it. huge. 😭

⭐ netsnmp_ds_set_boolean()

bestie please see the default_store(3) manual page for more information about this API. iykyk. 🦋

⭐ init_agent(char *name)

Initializes the embedded agent. this should be called before the init_snmp() call. name is used to dictate what .conf file to read when init_snmp() is called later. so like… name it thoughtfully, it's load-bearing. 🎀

⭐ init_snmp(char *name)

Initializes the SNMP library. heads up: one of the things this will do is read configuration files in an effort to configure your application. it will attempt to read the configuration files named by the name string that you passed in. it can be used to configure access control, for instance. please see the netsnmp_config_api(3), snmp_config(5), and snmpd.conf(5) manual pages for further details on this subject. 📚

⭐ init_master_agent(void)

Initializes the master agent and causes it to listen for SNMP requests on its default UDP port of 161. yeah. port 161. it said what it said. 👑

⭐ agent_check_and_process(int block)

This checks for packets arriving on the SNMP port and processes them if some are found. if block is non-zero, the function call will block until a packet arrives or an alarm must be run (see snmp_alarm(3)).

and the return value? so real:

  • a positive integer if packets were processed ✅
  • zero if an alarm occurred ⏰
  • -1 if an error occurred 💀

⭐ snmp_shutdown(char *name);

This shuts down the agent, saving any needed persistent storage, etc. the goodbye arc. sad but necessary. 🥺

🍓 SEE ALSO

reminder bestie: everything up there is the actual documented behavior — no guessing, no vibes-based API claims. if it says block, it blocks. 🫶

okay that's the whole page, mwah 💖

this has been NETSNMP_AGENT_API(3) from the Net-SNMP manual, version V5.9.5.2, dated 13 Aug 2010. slay, drink some water, and go link those libraries. ✨🌸💅

📦 where this page comes from