tmunzer/mist_snmp_gateway repository overview

⁠Mist SNMP Gateway

This application is a gateway to provide Mist Cloud information through SNMP. The application is periodicly synchronising the statistics from the Mist Cloud to expose them through SNMP.

This is just a proof of concept/example, and only a few information are exposed. It can be extended to provide more information.

⁠Menu

• License⁠
• Features⁠
• Examples⁠
• Installation⁠

⁠MIT LICENSE

Copyright (c) 2022 Thomas Munzer

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

⁠Features

• Supports SNMP v2c and v3
• Synchronises statistics data from a Mist Organisation:
  • Mist Org Stats
  • Mist Sites Stats
  • APs Stats
  • Switches Stats
• Runs SNMP server to expose statistics through SNMP

⁠Note

A custom SNMP MIB has been written for this purpose. It can be found here⁠

⁠Note 2

Since this is just a proof of concept, the written MIB does not use a registered Private Enterprise Number (PEN). The enterprise OID has been randomly selected (OID .1.3.6.1.4.1.65535) and may interfer with other SNMP solutions. If it's the case, please update the SNMP_OID env variable, and the enterprises OID in the MIB file.

⁠Examples

⁠Org Stats

⁠Site Stats

Note: The SNMP Index is the site ID (e.g. snmpget -v2c -cpublic <host> .1.3.6.1.4.1.65535.2.1.1.2.\"<site_id>\")

⁠AP Stats

Note: The SNMP Index is the site ID and the AP MAC address (e.g. snmpget -v2c -cpublic <host> .1.3.6.1.4.1.65535.2.1.1.2.\"<site_id>\".\"<mac>\")

⁠Switches Stats

Note: The SNMP Index is the site ID and the AP MAC address (e.g. snmpget -v2c -cpublic <host> MISTLAB-MIB::switchName.\"<site_id>\".\"<mac>\".<fpcId>)

⁠Installation

This Reference Application can be used as a standalone Application, or it can be deployed as a Docker Image (recommanded).

⁠Deploy the Docker version (recommanded)

This application is available as a Docker Image⁠. The Dockerfile is also available if you want top build it on your own.

The Docker Image exposes the following ports:

• UDP161

⁠Run with Docker Compose

A docker-compose file is available to deploy the App.

Before starting, please configure the environment variables with your values! It is recommanded to customize the Mongo User/Password. To do so, make sure to use the same values for MONGO_INITDB_ROOT_USERNAME and MONGO_USER, and for MONGO_INITDB_ROOT_PASSWORD and MONGO_PASSWORD.

To start it, you must have docker installed, and run the command docker-compose up from the folder where docker-compose.yaml is located.

Hint: You can use the command docker-compose up -d to start it in background, and docker-compose down to stop it.

⁠Manually Run the Docker version

docker create -v <path_to_config.js>/env_file:/app/.env:ro --link <mongoDB_container_name>:mongo --name="<container_name>" -p 161:161 tmunzer/mist_snmp_gateway

⁠Configure the Docker version

Configuration can be done through the config file. An example of the config.js file can be found in src/config_example.js. Then, you just need to link the config.js file to /app/config.js in you container.

You can also use environment variables to configure the app:

⁠Deploy the Standalone Application

This Reference APP is built over NodeJS. You must have a MongoDB⁠ server accessible from the AP to get it working.

⁠Deploy the Application

• Install NodeJS LTS: https://nodejs.org/en/download/⁠.
• Clone this repo.
• Configure the APP settings, in the src/.env file. You will find an example in src/env_example. With Docker deployment, all the settings can be configured by using Environment Variables (see above)
• Install npm packages (npm install from the project folder).
• Start the APP with npm start from the src folder