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 makeTo use containerization platform, we recommend that you instasll:
For testing purposes, we recommend that you install:
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.
cargo build --releaseBuild the application and its container-image by using make (or gmake):
makeThe 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=releasecargo make builddocker build -t snmp-sim .docker run -p 127.0.0.1:8161:8161/udp --name snmp-sim -t snmp-sim &docker stop snmp-simdocker-compose builddocker-compose up -ddocker-compose downThe following command will invoke doc, unit-tests and integration-tests execution:
cargo testor by using cargo-make
cargo make testImplementation 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.
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 bunyanAnd then, when you need to prettify the output logs, you can pipe the stdout of snmp-sim-rust into bunyan like:
cargo run | bunyanThe 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"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.
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.
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 runEvery script is executed in the database only once, even if the migration is invoked multiple times.
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-entityThe 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.
The rust client implementation is auto-generated from the openapi specification by running a build script.
cd clients/rust
cargo buildFirst 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.
The HTTP RestAPI openapi spectification is exposed by Swagger UI by browsing the service /swagger path, e.g. http://localhost:8180/swagger
See README for more details.
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.2This SNMP Simulator CLI tool is licensed under the APACHE-2.0 license.
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.