Skip to content

Latest commit

 

History

History
250 lines (164 loc) · 8.23 KB

README.md

File metadata and controls

250 lines (164 loc) · 8.23 KB
Raw

SNMP Simulator

Build codecov License

Pre-requisite

To only compile the application manually you'll need to install:

To use the automated build/test tools, we recommend that you install:

Once Brew is installed, you can install both docker and GNU make:

brew install docker make

To use containerization platform, we recommend that you instasll:

For testing purposes, we recommend that you install:

MacOS pre-requisutes

Since macOS provides an older version of GNU make (v3.81 dated April 1, 2006), we recommend installing and using gmake, which provides numerous features and performance enhancements.

How to build

Build with cargo

cargo build --release

Build the application and its container-image by using make (or gmake):

make

The deafult is to compile the application in debug-mode. If you want to build a release-mode binary, then set the RELEASE_OR_DEBUG flag to release:

make RELEASE_OR_DEBUG=release

Build with cargo-make

cargo make build

Build with docker

docker build -t snmp-sim .
docker run -p 127.0.0.1:8161:8161/udp --name snmp-sim -t snmp-sim &
docker stop snmp-sim

Build with docker-compose

docker-compose build
docker-compose up -d
docker-compose down

How to run the tests using cargo

The following command will invoke doc, unit-tests and integration-tests execution:

cargo test

or by using cargo-make

cargo make test

Development

Implementation of the SNMP Simulator service is relying on the Actix web frammework.

The service implements an HTTP REST API and exposes it to access the simulator functional operations.

YAML files are used to store the static service configuration. The configuration files can be extended via merging configuration parameters from environment variables.

The SNMP Simulator uses SQLite database as a persistent storage of runtime configuration.

Structured Logging

SNMP Simulator outputs the tracing log records in bunyan-compatible JSON format. The JSON format is extremely friendly when it comes to searching: an engine like ElasticSearch can easily ingest all these records, infer a schema and index the request_id, name and email fields. It unlocks the full power of a querying engine to sift through our logs. While the JSON format if useful for machine processing, it's almost unreadable for humans. The bunyan CLI comes to the rescue.

You can simply install the bunyan tool by running the following command:

cargo install bunyan

And then, when you need to prettify the output logs, you can pipe the stdout of snmp-sim-rust into bunyan like:

cargo run | bunyan

Configuration

The static service configuration is expected at ./configuration/base.yaml mandatory file. The base configuration can be extended or overriden by optional configuration file expected at ./configuration/local.yaml.

An example of base.yaml configuration:

application:
  host: 0.0.0.0
  port: 8080
  uri_prefix: "mngmt/v1"
  level: "error"

database:
  connection_uri: "sqlite://~/.snmp-sim/snmp-sim.db"

An example of local.yaml configuration:

application:
  host: localhost
  port: 8180
  uri_prefix: ""
  level: "trace"

Configuration from Environment Variable

In addition to static configuration files, environment variables can be used to define the service configuration. This is useful with automated CI or cloud environments.

Setting the APP__APPLICATION__PORT=5001 environment variable overrides the application.port static configuration file content.

Database

SNMP Simulator is relying on SeaORM relational, async and dynamic ORM crate which provides abstraction over common operations against an SQLite database. SQLx crate is used as SeaORM's underlying driver.

Create and Run Migrations

sqlx migrate add <name>

Creates a new file in migrations/<timestamp>-<name>.sql. Add your database schema changes to this new file. The SNMP simulator executes the migrations scripts as part of startup procedure. The SQLite database is created, if not exists. The database path and filename can be configured by the configuration file.

You can run the database migrations scripts manually by:

sqlx migrate run

Every script is executed in the database only once, even if the migration is invoked multiple times.

Update Database Entity Files

SeaORM can discover all tables in a database and generate a corresponding SeaORM entity files for each table.

Running the following command, the database entities implementations stored in ./src/data_access/entity folder are auto-generated, so never modify the content of that folder, since it will be overwritten.

cargo make db-entity

OpenAPI Specification

The HTTP RestAPI specification is generated from the server implementation by running a build script. The generate_spec binary is built together with the snmp-sim crate and binary. The generate_spec binary exports the current openapi specification to the output file. It needs to be invoked manually to generate the actual HTTP RestAPI openapi specification.

HTTP RestAPI Rust Client

The rust client implementation is auto-generated from the openapi specification by running a build script.

cd clients/rust
cargo build

First the cargo builds and runs the build script that invokes the generate_spec binary to create the current openapi specification stored at openapi.json

Then the rust client code is generated by invoking the openapi-generator using the openapi.json directly from the build script at compile time.

The version of the generated rust client crate is based on the version specified in ./clients/rust/Cargo.toml. Follow the SemVer compatibility quidelines, whenever the HTTP RestAPI specification is changed.

Swagger UI

The HTTP RestAPI openapi spectification is exposed by Swagger UI by browsing the service /swagger path, e.g. http://localhost:8180/swagger

SNMP Simulator CLI

See README for more details.

Testing using snmpget

The snmp-sim can be also tested by an external tool snmpget:

snmpget -v1 -c public localhost:8161 .1.3.6.1.4.1.11.2.14.11.5.1.1.2
snmpget -v2c -c public localhost:8161 .1.3.6.1.4.1.11.2.14.11.5.1.1.2
snmpget -v3 -c public localhost:8161 .1.3.6.1.4.1.11.2.14.11.5.1.1.2

License

This SNMP Simulator CLI tool is licensed under the APACHE-2.0 license.

Contributing

Want to contribute? Great 🎉

There are many ways to give back to the project, whether it be writing new code, fixing bugs, or just reporting errors. All forms of contributions are encouraged!

For instructions on how to contribute, see our Guide to contributing.