Bandwidth-Monitor

Bandwidth-Monitor is a tool to measure and monitor your latency and bandwidth. This tool stores the measured data in JSON (TinyDB) or in a MongoDB database. You can use Bandwidth-Monitor e.g. to determine the average internet-speed or measure the bandwidth from your Notebook at a certain place. Bandwidth-Monitor uses the speedtest-cli python library for the measurements.

Tested Platforms

OS	Python Version	Docker Version
mac OS Mojave (10.14.6)	3.7.3	19.03.5
Ubuntu 18.04.3	3.6.8	18.09.7
rancherOS on ARM (rpi3) 4.14.114	3.5.3	Not working yet
Raspbian 10 (kernel: 4.19.75-v7+)	Python 3.7.3	Not yet tested

Prerequisites

When you want to run this service directly from your CLI, first clone this repository and switch into its directory:

git clone https://github.com/racoon63/bandwidth-monitor.git
cd bandwidth-monitor/

Install the dependencies with:

sudo pip3 install -r requirements.txt

Create a config.ini according to the configuration section. This is optional. If you don't want to provide a config, the service will create a default config.

When you didn't define a datapath, the data will be stored relatively to the bandwidth-monitor directory in: data/bwm.json

Configuration

The service can be configured either by providing a config.ini configuration file or setting the required environment variables. The following table shows you which options are available, if they are required and what the default values are:

Parameter	Required	Values	Comments
speedtest-server	no	<1-50000> default: auto	If you want to use a specific speedtest-server you can enter its ID here. If no ID is provided, the service will determine the nearest server. To get an overview of speedtest-server see here
interval	no	default: 60	No value under 30 is allowed and recommended for now, because the data gathering takes some time to proceed.
type	yes	tinydb mongodb default: tinydb	TinyDB is a lightweight database which uses plain JSON files to store data. MongoDB is a document-oriented database in which you can store your data.
datapath	yes, if type is tinydb	default: data/bwm.json	The default path is relative to the main.py file.
host	yes, if type is mongodb		Everything in the form of an IP address or FQDN/DNS name like 1.2.3.4 or database.example.com
user	yes, if type is mongodb		For example: root
password	yes, if type is mongodb		For example: 123456

You'll find a config example below:

[General]
speedtest-server = 15431
interval = 75

[Database]
type = mongodb
host = 1.2.3.4
user = my-mongodb-username
password = 123456

[Logging]
logpath = /var/log/bwm
loglevel = info

Or you just use the config skeleton here.

Environment Variables

Name	Description
SPEEDTEST-SERVER	auto or the ID of your preferred speedtest-server.
INTERVAL	An integer which shouldn't be less than 60 and every value under 30 isn't allowed.
DBTYPE	tinydb or mongodb.
DATAPATH	This can be an absolute or a relative path.
DBHOST	An IP address or a DNS name in the form: 1.2.3.4 or mongo.example.com.
DBUSER	Your MongoDB user if you choosed mongodb at DBTYPE.
DBPASSWORD	Your MongoDB password for your provided db user.
LOGPATH	This can be an absolute or a relative path.
LOGLEVEL	Your desired logelevel. The common loglevels are available: debug, info, warning, error, critical.

Run

After all the requirements have been met, you can run the service either directly from the CLI or create a docker container for it.

CLI

To run this tool directly from your command-line, switch into the bandwidth-monitor directory (where the bwm file is placed) and run the following command on your machine to start the bandwidth-monitor:

python3 bwm

Docker

To run this service in a docker container you can

• build the image by yourself and run it afterwards
• create a config.ini and map it into the docker container or
• just create a volume and run a new docker instance.

To build the Dockerfile by yourself, just run:

docker build -t <YOUR-TAG> .
docker run -d <YOUR-TAG>

If you want to provide your config.ini and map it into the container, run:

docker run -d \
           -v ${pwd}/config.ini:/bwm/config.ini \
           <YOUR-TAG>

You can also just run the image and configure the service with the available environment variables described here:

docker volume create bwm
docker run -d \
           --name bwm \
           -v bwm:/bwm/data \
           -e SPEEDTEST-SERVER="auto" \
           -e INTERVAL=60 \
           -e DBTYPE="tinydb" \
           -e DATAPATH="/bwm/data/bwm.json" \
           -e LOGPATH="/bwm/log/bwm.log" \
           -e LOGLEVEL="info" \
           racoon/bandwidth-monitor:latest

Docker-Compose

If you want to store your data in a MongoDB database and run everything in a container environment you can use the docker-compose.yml file to start the services. Start all service by running:

docker-compose up -d

Missing

• config fle changes on the fly
• Monitoring over web interface (e.g. Grafana)

Known bugs

• Logging can not be changed by the given config.ini
• Switch to another docker container image builder cause of long container image times

Maintainer

racoon63 racoon63@gmx.net