snmpsim Documentation

Variation modules allow you to extend the behavior of the SNMP Simulator for specific OIDs. Instead of returning static values, these modules can produce dynamic data, simulate network conditions, or interface with external storage.

Available standard modules include:

• numeric: Produces non-decreasing sequences of integers.
• notification: Sends SNMP TRAP/INFORM messages to a target.
• writecache: Stores and returns values modified via SNMP SET.
• sql: Reads/writes var-binds to a SQL database.
• redis: Reads/writes var-binds to a Redis key-value store.
• delay: Introduces latency in SNMP responses.
• error: Flags errors (e.g., noAccess, wrongType) in the response PDU.
• multiplex: Cycles through a series of .snmprec files to simulate changing state.
• subprocess: Executes an external process and uses its stdout as the response.

The suite provides two command responder programs:

1. snmpsim-command-responder: The full version supporting all SNMP versions.
2. snmpsim-command-responder-lite: A lightweight version limited to SNMP v1 and v2c.

Both tools share common options for daemonization, privilege management, and data directory configuration.

Simulation data for each agent is stored in plain-text .snmprec files. Each line represents a single SNMP object using the following pipe-separated format:

OID|TYPE|VALUE

Example content of a .snmprec file:

1.3.6.1.2.1.1.1.0|4|Linux 2.6.25.5-smp SMP Tue Jun 19 14:58:11 CDT 2007 i686
1.3.6.1.2.1.1.2.0|6|1.3.6.1.4.1.8072.3.2.10
1.3.6.1.2.1.1.3.0|67|233425120
1.3.6.1.2.1.2.2.1.6.2|4x|00127962f940
1.3.6.1.2.1.4.22.1.3.2.192.21.54.7|64x|c3dafe61

The simulator selects the appropriate .snmprec file based on the parameters of the incoming SNMP query, such as the SNMP community name, SNMPv3 context, or IP address.

In snmpsim, when the simulator is NOT running in --v2c-arch mode, it uses .snmprec files for specific request matching.

A .snmprec file is used if the following three conditions match the request:

1. The ContextName in the SNMP request.
2. The transport domain.
3. The source address being used.

These files allow you to provide specific responses based on the identity and origin of the SNMP request.

The SNMP Simulator uses .snmprec files to build SNMP responses. These files are selected based on the following criteria depending on the SNMP version used:

• SNMPv1/v2c: The simulator uses the community name as the selector.
• SNMPv3: The simulator uses the context name as the selector.

Upon startup, the Simulator will report all .snmprec files it discovers, along with the specific community or context names required to address them.

The multiplex variation module allows the SNMP simulator to build responses by choosing from multiple .snmprec files in a time-dependent fashion. This is useful for simulating devices that change their state or data over time.

To use this functionality, you need a collection of .snmprec files (which can be generated automatically using the snmprec.py tool) that represent different states or time intervals.

By default, simulated SNMP Agents are static and read-only. Variation modules allow you to:

• Make returned data change over time (dynamic data).
• Gather data from external sources like SQL databases, executed processes, or web services.
• Enable SNMP SET operations to modify values and persist them in a database.
• Trigger events in other systems (e.g., the notification module sending TRAPs/INFORM messages upon receiving an SNMP SET request).
• Develop custom logic using the Python variation module API.

When a subtree is routed to a variation module, the TAG-ID part of the tag is omitted to allow the module to handle multiple types within that subtree.

When running the SNMP Simulator in --v2c-arch mode, the directory data/1.3.6.1.6.1.1.0/ acts as a special case for matching requests based on transport domains and source addresses.

If a request is received where the community name is empty, the Simulator will attempt to use .snmprec files from this directory if the transport domain and source address of the request match the filename of the .snmprec file.

When the SNMP Simulator is NOT running in --v2c-arch mode, you can use .snmprec files to provide specific responses based on the ContextName, the transport domain, and the source address of the incoming request.

For the IPv6 transport domain, the filename for a .snmprec file must follow a specific pattern: use the IPv6 address, but replace all colons (:) with underscores (_).

The Simulator will match a request to a .snmprec file if and only if:

1. The ContextName in the request matches.
2. The transport domain matches.
3. The source address of the request matches the address encoded in the filename.