PYSNMPCMD(1)

✨ NAME ✨

pysnmpcmd — the options and behaviour that basically every PySNMP command-line tool shares. We're talking the whole fam: this is page PYSNMPCMD(1) from the PySNMP manual, bestie 💅

---

🦋 SYNOPSIS 🦋

pysnmpcmd [OPTIONS] AGENT [PARAMETERS]

---

🌸 DESCRIPTION 🌸

Okay so listen. This page is the ✨shared lore✨ for all the PySNMP commands — and that means pysnmpbulkwalk, pysnmpget, pysnmpset, pysnmptranslate, and pysnmpwalk. All five. Every single one of them.

These command line apps use the SNMP protocol to talk to an SNMP capable network entity — aka an agent. That's the vibe 🫶

Now, each individual application typically (but not necessarily!) takes extra parameters, and those get dropped in after the agent specification. Those parameters live in their own manual pages, one per application. So if you're looking for app-specific stuff, wrong page, bestie, go read the right one 🌈

---

💖 OPTIONS 💖

• -a authProtocol — sets the authentication protocol for authenticated SNMPv3 messages. Your choices: MD5 or SHA.
• -A authPassword — sets the authentication pass phrase used for authenticated SNMPv3 messages. 🔐
• -c community — sets the community string for SNMPv1/v2c transactions.
• -d — dumps the raw SNMP packets sent and received, in hexadecimal. Every last byte, no filter 💀
• -D TOKEN[,...] — turns on debugging output for the given TOKEN(s). Wanna go feral? Try all for extremely verbose output. It's giving firehose 🔥
• -e engineID — sets the authoritative (security) engineID used for SNMPv3 REQUEST messages. Lowkey you usually don't need this — it normally gets discovered automatically ✨
• -E engineID — sets the context engineID used for SNMPv3 REQUEST messages scopedPdu. If you don't specify it, it defaults to the authoritative engineID.
• -h, --help — shows a brief usage message, then dips out. 👋
• -H — prints a list of the configuration file directives understood by the command, then exits. Like a little menu of what it speaks 📜
• -I [hu] — specifies input parsing options. Full tea is in INPUT OPTIONS below ⬇️
• -l secLevel — sets the securityLevel used for SNMPv3 messages. Options are noAuthNoPriv, authNoPriv, or authPriv. Heads up: you must provide the appropriate pass phrase(s) if you go any higher than noAuthNoPriv. No pass phrase, no entry 🚫
• -m MIBLIST — specifies a colon separated list of MIB modules to load for this application. Note: modules, not files 👀

The special keyword ALL loads every MIB module in the MIB directory search list. And like — every file whose name does not begin with "." will get parsed as if it were a MIB file. Yes, all of them. Good luck bestie 😭

• -M DIRLIST — specifies a colon separated list of directories to search for MIBs. Important: MIBs you named with -m get loaded from one of the directories listed by -M (or its equivalents). They don't just appear out of thin air 🧚
• -n contextName — sets the contextName used for SNMPv3 messages. The default contextName is the empty string "".
• -O [abeEfnqQsStTuUvxX] — specifies output printing options. The whole saga is in OUTPUT OPTIONS below ⬇️
• -r retries — specifies the number of retries used in the requests. Default is 5.
• -t timeout — specifies the timeout in seconds between retries. Default is 1.
• -u secName — sets the securityName used for authenticated SNMPv3 messages.
• -v 1 | 2c | 3 — specifies the protocol version to use:
  • 1 → RFCs 1155-1157
  • 2c → RFCs 1901-1908
  • 3 → RFCs 2571-2574

The default is typically version 3.

• -V, --version — displays version information for the application, then exits. ✨
• -x privProtocol — sets the privacy protocol for encrypted SNMPv3 messages. Your choices: DES or AES.
• -X privPassword — sets the privacy pass phrase used for encrypted SNMPv3 messages. 🔒
• -Z boots,time — sets the engineBoots and engineTime used for authenticated SNMPv3 messages. This initializes the local notion of the agent's boots/time with an authenticated value stored in the LCD. And yeah — it's typically not necessary to specify this option, because these values will usually be discovered automatically 💫

---

👑 AGENT SPECIFICATION 👑

The string AGENT up in the SYNOPSIS is doing the heavy lifting here — it specifies the remote SNMP entity you want to communicate with. The spec takes this form:

[<transport-specifier>:]<transport-address>

At its simplest, the AGENT specification can just be a hostname, or an IPv4 address in the standard "dotted quad" notation. In that case, communication will be attempted using UDP/IPv4 to port 161 of the given host.

Otherwise, the <transport-address> part of the spec gets parsed according to this:

• <transport-specifier>: udp — <transport-address> format: hostname[:port] or IPv4-address[:port]

Also important: <transport-specifier> strings are case-insensitive, so like… "tcp" and "TCP" are equivalent. Same energy, periodt 💅

Here are some examples, with their interpretations:

• hostname:161 — performs a query using UDP/IPv4 datagrams to hostname on port 161. The ":161" is redundant here, since that's the default SNMP port anyway.
• udp:hostname — identical to the previous specification. The "udp:" is redundant here since UDP/IPv4 is the default transport.

---

🌈 OUTPUT OPTIONS 🌈

The format of the output from SNMP commands can be controlled using various parameters of the -O flag. Wanna see the difference? Compare any of these against the default output, which — unless otherwise specified — looks like this:

$ snmpget -c public -v 1 localhost sysUpTime.0
SNMPv2-MIB::sysUpTime.0 = Timeticks: (14096763) 1 day, 15:09:27.63

Now, the sub-options 👇

• -Oa — displays string values as ASCII strings (unless there's a DISPLAY-HINT defined for the corresponding MIB object). By default, the library tries to figure out whether the value is a printable or binary string, and displays it accordingly.

Heads up: this option does not affect objects that do have a Display Hint. 🚫

• -Ob — displays table indexes numerically, instead of trying to interpret the instance subidentifiers as string or OID values:

$ snmpgetnext -c public -v 1 localhost vacmSecurityModel
SNMP-VIEW-BASED-ACM-MIB::vacmSecurityModel.0."wes" = xxx
$ snmpgetnext -c public -v 1 -Ob localhost vacmSecurityModel
SNMP-VIEW-BASED-ACM-MIB::vacmSecurityModel.0.3.119.101.115 = xxx

• -Oe — removes the symbolic labels from enumeration values:

$ snmpget -c public -v 1 localhost ipForwarding.0
IP-MIB::ipForwarding.0 = INTEGER: forwarding(1)
$ snmpget -c public -v 1 -Oe localhost ipForwarding.0
IP-MIB::ipForwarding.0 = INTEGER: 1

• -OE — modifies index strings to escape the quote characters:

$ snmpgetnext -c public -v 1 localhost vacmSecurityModel
SNMP-VIEW-BASED-ACM-MIB::vacmSecurityModel.0."wes" = xxx
$ snmpgetnext -c public -v 1 -OE localhost vacmSecurityModel
SNMP-VIEW-BASED-ACM-MIB::vacmSecurityModel.0.\"wes\" = xxx

This one lets you reuse the output in shell commands. Iconic, honestly 🐚

• -Of — includes the full list of MIB objects when displaying an OID:

.iso.org.dod.internet.mgmt.mib-2.system.sysUpTime.0 = Timeticks: (14096763) 1 day, 15:09:27.63

• -On — displays the OID numerically:

.1.3.6.1.2.1.1.3.0 = Timeticks: (14096763) 1 day, 15:09:27.63

• -Oq — removes the equal sign and the type information when displaying varbind values:

SNMPv2-MIB::sysUpTime.0 1:15:09:27.63

• -OQ — removes the type information when displaying varbind values:

SNMPv2-MIB::sysUpTime.0 = 1:15:09:27.63

• -Os — displays the MIB object name (plus any instance or other subidentifiers):

sysUpTime.0 = Timeticks: (14096763) 1 day, 15:09:27.63

• -OS — displays the name of the MIB, as well as the object name:

SNMPv2-MIB::sysUpTime.0 = Timeticks: (14096763) 1 day, 15:09:27.63

This is the default OID output format. ✨

• -Ot — displays TimeTicks values as raw numbers:

SNMPv2-MIB::sysUpTime.0 = 14096763

• -OT — if values are printed as Hex strings, also displays a printable version.
• -Ou — displays the OID in the traditional UCD-style (inherited from the original CMU code). What that means: it removes a series of "standard" prefixes from the OID, and displays the remaining list of MIB object names (plus any other subidentifiers):

system.sysUpTime.0 = Timeticks: (14096763) 1 day, 15:09:27.63

• -OU — does not print the UNITS suffix at the end of the value.
• -Ov — displays the varbind value only, not the OID:

$ snmpget -c public -v 1 -Oe localhost ipForwarding.0
INTEGER: forwarding(1)

• -Ox — displays string values as Hex strings (unless there's a DISPLAY-HINT defined for the corresponding MIB object). By default, the library tries to figure out whether the value is a printable or binary string, and displays it accordingly.

Same caveat as -Oa: this option does not affect objects that do have a Display Hint. 🚫

• -OX — displays table indexes in a more "program like" output, imitating a traditional array-style index format:

$ snmpgetnext -c public -v 1 localhost ipv6RouteTable
IPv6-MIB::ipv6RouteIfIndex.63.254.1.0.255.0.0.0.0.0.0.0.0.0.0.0.64.1 = INTEGER: 2
$ snmpgetnext -c public -v 1 -OE localhost ipv6RouteTable
IPv6-MIB::ipv6RouteIfIndex[3ffe:100:ff00:0:0:0:0:0][64][1] = INTEGER: 2

Most of these options can also be configured via configuration tokens. See the snmp.conf(5) manual page for the details 📖

✨ INPUT OPTIONS ✨

okay bestie so here's the thing — how pysnmp reads your input object names and the values you're assigning is fully controllable through the -I flag, and it has a bunch of lil sub-flavours. the default behaviour is explained at the very end of this section, so don't skip ahead, i see you 👀

• -Ib — says "bestie, treat this name as a regular expression" and match it against object names in the MIB tree, case-insensitively. the "best" match gets used — and "best" means the one that matches closest to the beginning of the node name and sits highest in the tree. for example, the MIB object vacmSecurityModel could be matched by the expression vacmsecuritymodel (same full name, different case) or vacm.*model (a regexp pattern). ✨

⚠️ heads up: . is a special character in regular expression patterns, so your expression cannot specify instance subidentifiers, and it can't cover more than one object name. a "best match" expression only gets applied against single MIB object names. like, the expression sys*ontact.0 would not match the instance sysContact.0 (even though sys*ontact would match sysContact). same energy with module names — specifying a MIB module name will not succeed, so SNMPv2-MIB::sys.*ontact wouldn't match either. 💀

• -Ih — turns off the use of DISPLAY-HINT info when assigning values. so now you gotta hand over the raw value, no filter:

snmpset ... HOST-RESOURCES-MIB::hrSystemData.0
                x "07 D2 0C 0A 02 04 06 08"

instead of the cute formatted version:

snmpset ... HOST-RESOURCES-MIB::hrSystemDate.0
                = 2002-12-10,2:4:6.8

• -Ir — disables checking table indexes and the value you're assigning against the relevant MIB definitions. so instead of catching it locally, this will (hopefully 🙈) make the remote agent report an invalid request, rather than checking (and rejecting) it before it even gets sent over there.

local checks are more efficient (and the diagnostics they give you tend to be more precise too, no cap), but turning this off is particularly useful when you're testing the remote agent. 🧪

• -IR — enables "random access" lookup of MIB names. instead of giving a full OID path to the object you want (or qualifying it with an explicit MIB module name), the MIB tree just gets searched for the matching object name. so .iso.org.dod.internet.mib-2.system.sysDescr.0 (or SNMPv2-MIB::sysDescr.0) can be written as simply as sysDescr.0. iconic, honestly. 💅

🚨 Warning: since MIB object names are not globally unique, this approach may return a different MIB object depending on which MIB files have been loaded. it's giving chaos. proceed with awareness.

the MIB-MODULE::objectName syntax has the advantage of uniquely identifying a particular MIB object, plus it's slightly more efficient (and it'll automatically load the necessary MIB file if it needs to). so like, pick your fighter. 👑

• -Is SUFFIX — adds the specified suffix to each textual OID given on the command line. great for retrieving multiple objects from the same row of a table, by specifying a common index value. 🎀
• -IS PREFIX — adds the specified prefix to each textual OID given on the command line. use it to specify an explicit MIB module name for all the objects being retrieved (or for incurably lazy typists, no judgement). 😌
• -Iu — enables the traditional UCD-style approach to interpreting input OIDs. this assumes OIDs are rooted at the 'mib-2' point in the tree (unless they start with an explicit . or include a MIB module name). so that sysDescr instance from before would be referenced as system.sysDescr.0. retro vibes. 🌈

---

object names specified with a leading . are always interpreted as "fully qualified" OIDs — they list the sequence of MIB objects from the root of the MIB tree. such objects, and those qualified by an explicit MIB module name, are unaffected by the -Ib, -IR and -Iu flags. they simply don't care. 💅

otherwise, if none of the above input options are specified, the default behaviour for a "relative" OID is to try and interpret it as an (implicitly) fully qualified OID, then apply "random access" lookup (-IR), followed by "best match" pattern matching (-Ib). that's the whole pipeline bestie 🫶

🌸 ENVIRONMENT VARIABLES 🌸

• PREFIX — the standard prefix for object identifiers (when using UCD-style output). defaults to .iso.org.dod.internet.mgmt.mib-2
• MIBS — the list of MIBs to load. defaults to SNMPv2-TC:SNMPv2-MIB:IF-MIB:IP-MIB:TCP-MIB:UDP-MIB:SNMP-VACM-MIB. overridden by the -m option.
• MIBDIRS — the list of directories to search for MIBs. defaults to DATADIR/snmp/mibs. overridden by the -M option.

🦋 FILES 🦋

• SYSCONFDIR/snmp/snmpd.conf — the agent configuration file. see snmpd.conf(5). 🐝
• SYSCONFDIR/snmp/snmp.conf
• ~/.snmp/snmp.conf — application configuration files. see snmp.conf(5). 🎀

💖 SEE ALSO 💖

pysnmpbulkwalk(1), pysnmpget(1), pysnmpset(1), pysnmpbulktranslate(1), pysnmpwalk(1).

---

and that's the whole page bestie, we ate and left no crumbs 💅✨ this was Version 4, dated 1 May 2007, and the page itself is PYSNMPCMD(1) — go forth and poll responsibly, ily 🫶💜