Skip to content
This repository has been archived by the owner on Jun 21, 2024. It is now read-only.

Latest commit

 

History

History
145 lines (110 loc) · 6.33 KB

README.md

File metadata and controls

145 lines (110 loc) · 6.33 KB
Raw

SNMPMAN

Java CI with Maven javadoc Maven Central Docker Image Size (latest by date) License

This repo has been set to read-only because there are no maintainers in our organization to maintain the project. Feel free to fork.

The SNMPMAN is a command-line application that simulates SNMP-capable devices and was developed to be usable during unit testing. It may be used to test traffic monitoring applications that execute SNMP queries. Due to the lack of flexibility in already existing alternatives, it was developed by the IONOS SE to improve flexibility. Therefore the SNMPMAN is highly extendable and will be enhanced over time.

Multiple SNMP agents may be started at once and will run in parallel. The agents running in parallel will return the data queried and save it to a textual walk result file. This file will be created by querying a real device. It is also possible to query several device types at once. The query configuration may contain policies on how to dynamically change the query responses. E.g. the response of an ifInOctets may be incremented with each query to simulate traffic. Several variable modifiers are already in existence for different data types.

Usage

SNMPMAN can either be used as

  • Java library
  • Standalone command line program
  • Docker image

Java library usage

You can include the SNMPMAN as a Maven dependency from Maven Central.

<dependency>
    <groupId>com.oneandone</groupId>
    <artifactId>snmpman</artifactId>
    <version>2.2.0</version>
</dependency>

In order to start and stop the simulation use this code snippet as an example:

/* 
 * creates a new instance of the SNMPMAN with the specified configuration file 
 * and executes all agents 
 */
Snmpman snmpman = Snmpman.start(new File("configuration.yaml"));
/* ... do something with the agents */

/* stop the SNMPMAN and all started agents */
snmpman.stop();

Standalone commandline usage

For standalone commandline usage, you need to pass a YAML file as a configuration.

The commandline options are:

 -c (--configuration) FILE  : the path to the configuration YAML
 -h (--help)                : print the help message (Vorgabe: false)

A YAML configuration specifying one SNMP agent, binding to IP 127.0.0.1, UDP port 10000 and SNMP community 'public' is given here:

- name: "example1"
  device: "/opt/snmpman/etc/devices/ios.yaml"
  walk: "/opt/snmpman/etc/walk/example1.walk"
  ip: "127.0.0.1"
  port: 10000
  community: public

The walk can be a SNMP walk extracted with the 'snmpwalk' command line program with the options -On.

Docker usage

There's an experimental docker image available that can be used to simulate SNMP agents.

Available configuration options:

  • SNMPMAN_CONFIG: The location of the default configuration can be changed using the env var SNMPMAN_CONFIG, it defaults to a sample config at /snmpman/etc/configuration.yaml if you're not specifying thie config file. Instead of providing a full-blown config, you can also let the docker entrypoint create a config for you with the following env vars.
  • SNMPMAN_PORT: The UDP port to bind to, from the perspective of the docker container. Only gets written if SNMPMAN_CONFIG is not set.
  • SNMPMAN_COMMUNITY: The SNMP community to use for authentication. Only gets written if SNMPMAN_CONFIG is not set.
  • SNMPMAN_WALK: The location of the SNMP walk to provide via SNMP in the docker container filesystem (can be bind-mounted as a volume into the container). Only gets written if SNMPMAN_CONFIG is not set.

Sample call mounting a walk inside the container and binding the container towards the standard SNMP port 161:

docker run -v ABSOLUTE/PATH/TO/walk.txt:/snmpman/etc/walk/example1.walk -p 161:10000/udp stephanfuhrmannionos/snmpman

Installation and building

Prerequisites

  • Java JDK 9+
  • Apache Maven 3.5.2

Building a fat Jar

In order to build the SNMPMAN you can use Apache Maven to build a far JAR:

mvn clean package

After that you find your JAR in snmpman-cli/target/snmpman-cli-$VERSION-SNAPSHOT-jar-with-dependencies.jar.

Execution

To execute an instance of the SNMPMAN you have to start the execution script and specify a value for the -c or --configuration option that lists the path to the configuration YAML file that will be loaded during execution.

Configuration

The SNMPMAN configuration can be found in two main YAML files ...

  • The agent configuration lists all agents which will be started
  • The device type configuration defines the modifiers that will be applied to a range of OIDs

You can find some YAML example configuration files within the test resources of this project in this directory.

The third component of the configuration are the walk files for the agents as specified in the agent configuration.

This is a basic overview and more information will be provided on the project's Wiki pages.

Contribution

This section gives some pointers about contributions to the snmpman project. The project is being developed by the community. Maintainers merge pull-requests, fix critical bugs, etc.

If you fixed or added something useful to the project, you can send a pull-request. It will be reviewed and accepted, or commented on for rework by maintainers. Pull-requests are declined if a maintainer closes the request.