AgentX: SNMP Master Agent vs Subagent Explained

By the SNMP Monitoring team · Reviewed July 2026

One host, three teams, four apps that all want to publish SNMP objects. You could fork snmpd into a monster that knows about databases, custom hardware, and that one Perl script from 2011. Or you split the problem: a master agent owns UDP 161, and subagents register OID subtrees and answer for their slice.

That split is AgentX—the Agent Extensibility Protocol, RFC 2741 (related MIB transport material in RFC 2742). Parent architecture: SNMP architecture. Plain agent role: SNMP agent.

If you've never heard of AgentX, you can still run a fine estate. The day a vendor says "our metrics show up under AgentX" or net-snmp docs mention master agentx, this page is the map.

Why AgentX exists

Monolithic agents don't scale as software projects. Every new metric domain wants its own release cycle, privileges, and crash domain. Cramming everything into one process means:

• One bug takes down all SNMP on the box
• Packaging becomes a dependency hairball
• Security reviews turn into "why does snmpd talk to the DB?"

AgentX lets specialty code register a subtree and serve it, while the master keeps the on-wire SNMP face stable for managers. Extensibility without rewriting the universe.

It's not magic multi-host clustering. It's in-host (or tightly coupled) delegation of MIB ownership. Managers still talk normal SNMP to port 161. They don't speak AgentX on the open internet as a replacement for SNMP.

Master agent vs subagent

Master = the SNMP agent managers know. Subagent = backend worker for a branch of the tree. If the subagent dies, that branch goes dark; the rest of the MIB may still answer. That's both a feature (isolation) and a paging source ("half our enterprise OIDs vanished after deploy").

How AgentX communication works

Numbered flow for a Get that lands in a subagent tree:

1. Manager sends SNMP Get/GetNext/GetBulk to the master on UDP 161.
2. Master checks auth/view like any agent.
3. Master looks up which registered subtree owns the OID.
4. Master asks the responsible subagent over the AgentX channel (often a Unix socket, sometimes TCP).
5. Subagent returns the value(s).
6. Master packages a normal SNMP Response back to the manager.

Registration matters as much as data path. Subagent starts → connects to master → registers "I own 1.3.6.1.4.1.example…" → master updates the table. Duplicate registrations and priority rules are why two modules fighting over the same prefix make ops sad. Read the agent logs when walks look "randomly empty."

Example manager-side check (still plain SNMP—no AgentX client on the NMS):

snmpget -v2c -c <RO_string> <host> 1.3.6.1.2.1.1.3.0

DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (60000) 0:10:00.00

That proves the master answers. To prove a custom subtree, walk the OID your subagent registered—not just system.

AgentX vs older mechanisms (SMUX, proxy)

Before AgentX, SMUX (RFC 1227) tried a similar extensibility story. It's the older, deprecated path AgentX replaced in polite company. If a fossil doc tells you to enable SMUX in 2026, treat it as museum text unless a vendor is truly stuck.

Proxying is a different idea: one SNMP entity forwards requests toward another SNMP agent (often another host). Proxy is multipoint SNMP. AgentX is master/subagent extensibility—usually local. Don't use the words interchangeably in runbooks or you'll debug the wrong socket.

Sibling context: manager still only sees SNMP on 161.

Using AgentX with net-snmp

On net-snmp, the master side is commonly enabled in snmpd.conf with a directive along the lines of:

master agentx

(Exact socket paths and permissions vary by distro package—read the local snmpd.conf man bits and unit files.) Subagents then connect to the AgentX endpoint the master exposes (Unix socket or TCP, depending on config).

Ops checklist:

1. Enable master AgentX in snmpd and restart cleanly.
2. Start the subagent; confirm it logs successful registration.
3. From a poller, walk the registered subtree.
4. Kill the subagent in staging—confirm only that branch dies.
5. Lock down who can open the AgentX socket (local root-only is common sense).

Config home: snmpd.conf. Custom metrics patterns: custom OID.

AgentX does not replace VACM. Managers still need allowed views on the master. A registered subtree hidden by the view is still invisible.

When AgentX is the wrong hammer

• You only need stock HOST-RESOURCES / IF-MIB — stock snmpd is enough.
• You wanted multi-host federation — that's managers and proxies, not AgentX.
• You can extend a simple script and don't need a long-lived subagent — net-snmp extend/pass may be simpler (agent).
• Nobody will own the subagent lifecycle — zombie registrations and silent OID gaps follow.

Reach for AgentX when a real application must publish a stable MIB module with its own process boundary. Otherwise keep the agent boring.

Failure modes worth a paragraph

• Master up, subagent down — partial MIB; NMS templates look flaky.
• Socket permissions — subagent can't connect; registration never happens.
• Order of start — subagent before master races; use unit dependencies.
• Duplicate OIDs — two registrants, undefined pain.
• Firewall theater — someone opens AgentX TCP to the world; don't.

Debug with master logs + subagent logs + a walk of the specific prefix. Not with more NMS templates.

One more practical note: permissions on the AgentX socket are a security boundary. If any local user can connect as a subagent and register a subtree, you've built an interesting way to inject management data. Keep the socket root-owned, mode tight, and document which unit starts which subagent after reboot.

Glossary: glossary.

Frequently asked questions

What is AgentX in SNMP?

AgentX is the Agent Extensibility Protocol (RFC 2741) that lets a master agent delegate MIB subtrees to subagents while still presenting one SNMP agent on UDP 161.

Difference between master agent and subagent?

The master owns the SNMP port and registration table and talks to managers. Subagents register OID ranges and serve those objects over AgentX to the master.

Is SMUX still used?

SMUX (RFC 1227) is the older extensibility mechanism and is deprecated in favor of AgentX. Don't start new designs on SMUX.

How do I enable AgentX in net-snmp?

Configure the master with master agentx (and related socket settings) in snmpd.conf, restart snmpd, then run subagents that connect and register. Details: snmpd.conf.

Key takeaways

• AgentX (RFC 2741) = master on 161 + subagents for subtrees.
• Managers still speak normal SNMP; they don't replace AgentX for polls.
• SMUX is the deprecated predecessor.
• net-snmp: master agentx + careful socket/lifecycle ops.
• Use it for real module boundaries; not for simple one-off scripts if extend will do.
• Next: agent, architecture, custom OID.