The SET request is used to modify information on the target agent - updating the configuration of that agent, or controlling the behaviour of the remote system. This protocol operation can be sent via the snmpset command line tool.
The syntax of the
snmpset command is similar to that of the
command, and most of the snmpget tutorial applies here too.
The main difference is in specifying the information to work with.
Instead of a single OID, the
snmpset command requires the
OID to update, the data type of this object, and the new value to apply:
snmpset -v 1 -c demopublic test.net-snmp.org ucdDemoPublicString.0 s "hi there!"
The effect of this command can usually be seen by retrieving the value of an object, both before and after the SET request:
$ snmpget -v 1 -c demopublic test.net-snmp.org ucdDemoPublicString.0 UCD-DEMO-MIB::ucdDemoPublicString.0 = "hi there!" $ snmpset -v 1 -c demopublic test.net-snmp.org ucdDemoPublicString.0 s "Hello, world!" UCD-DEMO-MIB::ucdDemoPublicString.0 = "Hello, world!" $ snmpget -v 1 -c demopublic test.net-snmp.org ucdDemoPublicString.0 UCD-DEMO-MIB::ucdDemoPublicString.0 = "Hello, world!"
Note that the values returned following the SET request will always be the same as those provided. This is normally the same as that returned by a subsequent GET request (as shown above), but not necessarily:
$ snmpget test.net-snmp.org snmpSetSerialNo.0 SNMPv2-MIB::snmpSetSerialNo.0 = INTEGER: 123456 $ snmpset test.net-snmp.org snmpSetSerialNo.0 i 123456 SNMPv2-MIB::snmpSetSerialNo.0 = INTEGER: 123456 $ snmpget test.net-snmp.org snmpSetSerialNo.0 SNMPv2-MIB::snmpSetSerialNo.0 = INTEGER: 123457
The list of valid datatypes can be found at the end of the snmpset help output:
$ snmpset -h |& tail -4 type - one of i, u, t, a, o, s, x, d, n i: INTEGER, u: unsigned INTEGER, t: TIMETICKS, a: IPADDRESS o: OBJID, s: STRING, x: HEX STRING, d: DECIMAL STRING U: unsigned int64, I: signed int64, F: float, D: double
Note that the last four types are only valid when talking to the Net-SNMP agent. They are not part of the official SNMP specification.
Assuming that the MIB file is loaded, then it's also possible to
specify the type as "=", and the
snmpset command will
supply the appropriate type from the MIB file:
$ snmpset test.net-snmp.org ucdDemoPublicString.0 = "Hello clouds" UCD-DEMO-MIB::ucdDemoPublicString.0 = "Hello clouds"
This doesn't work if the MIB file isn't loaded, of course - but then referring to the MIB object by name wouldn't either!
As with the
snmpget command, it also is possible to SET several
new values in the one request. Simply specify the list of (OID,type,value)
triples on the command line:
$ snmpset test.net-snmp.org ucdDemoPublicString.0 s "Hello sky" snmpSetSerialNo.0 i 123457 UCD-DEMO-MIB::ucdDemoPublicString.0 = "Hello sky" SNMPv2-MIB::snmpSetSerialNo.0 = INTEGER: 123457
If one of these assigments is invalid, then the request will be rejected without applying any of the new values - regardless of the order they appear in the list. This is quite useful for the administrator wanting to manage their systems, but can be something of a headache for the poor schmuck landed with the task of implementing the SET handling within the agent.
If the MIB file has been loaded, and the supplied value is invalid according to the MIB definitions (e.g. the wrong type, or outside the valid range for that object), then <command>snmpset</command> will display a failure message without ever sending the request to the target agent:
$ snmpset test.net-snmp.org snmpSetSerialNo.0 s "as any fule kno" snmpSetSerialNo.0: Bad variable type (Type of attribute is INTEGER, not OCTET STRING)
If the MIB file is not available, or the value matches the syntax from the MIB definition, then the request will be sent to the target agent which may then reject the request:
$ snmpset test.net-snmp.org snmpSetSerialNo.0 i 9999 Error in packet. Reason: (badValue) The value given has the wrong type or length Failed object: SNMPv2-MIB::snmpSetSerialNo.0
The same effect can be seen by suppressing the local validation:
$ snmpset test.net-snmp.org -Ir snmpSetSerialNo.0 s "How To Be Topp" Error in packet. Reason: (badValue) The value given has the wrong type or length Failed object: SNMPv2-MIB::snmpSetSerialNo.0
SNMPv1 reports such problems using a single error report (
as shown above. SNMPv2c is a little more informative:
$ snmpset -v 2c test.net-snmp.org -Ir snmpSetSerialNo.0 s "uterly wet" Error in packet. Reason: (wrongType) The set datatype does not match the data type the agent expects Failed object: SNMPv2-MIB::snmpSetSerialNo.0 <tasks>[ ] Actually returns
wrongValue</tasks> $ snmpset -v 2c test.net-snmp.org snmpSetSerialNo.0 i 9999 Error in packet. Reason: (wrongValue) The set value is illegal or unsupported in some way Failed object: SNMPv2-MIB::snmpSetSerialNo.0
Similarly, if you don't have permission to write to an object, the error reported will be different depending on the version of SNMP used:
$ snmpset -v 1 -c rocommunity test.net-snmp.org snmpSetSerialNo.0 i 123457 Error in packet. Reason: (noSuchName) There is no such variable name in this MIB. Failed object: SNMPv2-MIB::snmpSetSerialNo.0 $ snmpset -v 2c -c rocommunity test.net-snmp.org snmpSetSerialNo.0 i 123457 Error in packet. Reason: noAccess Failed object: SNMPv2-MIB::snmpSetSerialNo.0 <tasks>[ ] Should this return
SNMPv3 uses the same (improved) error codes as SNMPv2c, as well as providing much better security - which is potentially quite important when it comes to SET requests!
About the SNMP Protocol
These tutorial links talk about SNMP generically and how the protocol itself works. They are good introductory reading material and the concepts are important to understand before diving into the later tutorials about Net-SNMP itself.
- How SNMP Works: About the protocol itself (GETs, GETNEXTs, etc)
- What data is in SNMP: All about SNMP Management Information Bases (MIBs)
- Securing SNMP: How to use the SNMP protocol securely
Net-SNMP Command Line Applications
These tutorial pages discuss the command line tools provided in the Net-SNMP suite of tools. Nearly all the example commands in these tutorials works if you try it yourself, as they're all examples that talk to our online Net-SNMP test agent. Given them a shot!
- snmptranslate: learning about the MIB tree.
- snmpget: retrieving data from a host.
- snmpgetnext: retrieving unknown indexed data.
- snmpwalk: retrieving lots of data at once!
- snmptable: displaying a table.
- snmpset: peforming write operations.
- snmpbulkget: communicates with a network entity using SNMP GETBULK request
- snmpbulkwalk: retrieve a sub-tree of management values using SNMP GETBULK requests.
- snmptrap: Sending and receiving traps, and acting upon them.
- Common command line options:
- Writing mib2c config files
All of our applications support configuration to allow you to customize how they behave.
- SNMP Agent (snmpd) Configuration
- SNMP Notification Receiver (snmptrapd)
- Agent Monitoring
Net-SNMP comes with a highly flexible and extensible API. The API allows you to create your own commands, add extensions to the agent to support your own MIBs and perform specialized processing of notifications.
- Client / Manager Coding Tutorials
- Agent Coding Tutorials
- The Agent Architecture page might be worth reading before or after the agent coding tutorials, and describes how the Agent Helpers work under the hood.
- Writing a mib module to serve information described by an SNMP MIB, and how to compile it into the net-snmp snmpd agent.
- Writing a Dynamically Loadable Object that can be loaded into the SNMP agent.
- Writing a Subagent that can be run to attach to the snmpd master agent.
- Writing a perl plugin to extend the agent using the NetSNMP::agent module.
- Writing shell scripts to extend the agent
- Using mib2c to help write an agent code template for you
- Header files and autoconf
Debugging SNMP Applications and Agents
All our tools and applications have extensive debugging output. These tutorials talk about how the debugging system works and how you can add your own debugging statements to you code:
- Debugging output printed using the -D command line option
- Using -Ddump to display packet breakdowns
- Debugging using GDB