frdbonif / sys2mqtt

Publish system statistics to an MQTT broker.

sys2mqtt v0.3.0

License

(C) Fred Boniface 2020 [email protected]

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

About

sys2mqtt was born out of my want to view statistics of several systems within OpenHAB. Using MQTT the data can be displayed or stored in many ways.

sys2mqtt v0.3.0 can publish the folliwing system statistics to an MQTT broker:

• Number of logical CPU Cores
• CPU Utilisation as a percentage
• Total RAM
• RAM utilisation as a percentage
• Total Swap
• Swap utilistation as a percentage

Compatibility

The program has been tested for compatibility on the following operating systems, for further compatibility information you can check the documentation for psutil on GitHub.

v0.3.0 Tested on:

It is likely that sys2mqtt will run on a number other of systems but cannot be tested on every distro. All non-Windows systems listed below have been tested using default repos unless otherwise noted. See footnotes for notes.

Linux

• CentOS 8
• Debian 10
• Sangoma Linux 7.6
• Ubuntu, 18.04, 20.04

Windows

• Please use version 0.2.3 on Windows for the time being.

Other

• Please use version 0.2.3 on FreeBSD for the time being.

Installation (Debian & Ubuntu)

See the bottom of the page for installation on other systems, we don't have a wiki at the moment.

Firstly, the program requires Python 3 and has been developed using Python 3.8.2. It also relies on the psutil, socket and paho-mqtt Python packages. If you follow the method below, these will all be installed for you.

You can install sys2mqtt as follows on Debian based systems, for other systems consult the wiki. (Commands starting $ to be run as user, commands starting # to be run as root or using sudo)

Ensure dependencies are available. #``apt install git

Move to the correct directory for installing. $``cd /usr/local/bin

Clone the source of sys2mqtt. #``git clone https://github.com/frdbonif/sys2mqtt.git

Move in to the newly created directory. $``cd sys2mqtt

Make sure the required files are executable. #``chmod +x install.sh

Run the installer script. Be aware: You should always check scripts before you run them to be sure you know what they are modifying on your system. If you'd rather not run the installer script, check the bottom of this README for alternative options. #``./install.sh

MQTT Topics

This information will be available on the sys2mqtt wiki.

Task List

• 0.3.0 Create installer script.
• 0.3.0 Insert loop into program to remove reliance on cron or systemd timers.
• 0.3.1 Inclusion of drive information.
• 0.3.1 Implement ON/OFF state setting suitable parameters to zero on shutdown.
• 0.3.2 Inclusion of temerature and fan information.
• 0.4.0 Extend conf.py file to allow users to choose which metrics they would like enabled.
• 0.5.0 Improved error handling.
• 0.5.1 Move to self hosted git solution.
• 0.5.2 Create wiki for documentation.
• 0.9.9(rc) Logging.

Footnotes

Only tested on Intel CPU's although believed to work on other x86 CPU's.

Install on Sangoma Linux 7.6 (login as root)

• yum install python36u-pip python36u-devel git
• pip install psutil paho-mqtt
• cd /usr/local/bin
• git clone https://github.com/frdbonif/sys2mqtt.git
• cd sys2mqtt

Now, open the python/conf.py file and enter the details for your MQTT server.

• cd /usr/local/bin/sys2mqtt
• chmod -R 0755 python
• cp systemd/sys2mqtt-sangoma76.service /etc/systemd/system/sys2mqtt.service
• systemctl daemon-reload
• systemctl enable sys2mqtt.service
• systemctl start sys2mqtt.service

Install on CentOS 8 (login as root)

• yum install python3 python3-pip git
• pip3 install psutil paho-mqtt --user
• cd /usr/local/bin
• git clone https://github.com/frdbonif/sys2mqtt.git
• cd sys2mqtt

Now, open the python/conf.py file and enter the details for your MQTT server.

• cd /usr/local/bin/sys2mqtt
• chmod -R 0755 python
• cp systemd/sys2mqtt.service /etc/systemd/system/sys2mqtt.service
• systemctl daemon-reload
• systemctl enable sys2mqtt.service
• systemctl start sys2mqtt.service

Install on FreeBSD

FreeBSD users should use the v0.2.3 branch until running sys2mqtt as a service on FreeBSD has been implemented. This branch can be downloaded with the command: `git clone -b v0.2.3 https://github.com/frdbonif/sys2mqtt.git

sys2mqtt's Issues

No instructions to install on Windows 10 as of v0.3.0

Installation instructions to be included with v0.4.0 at the latest.

main.py to be renamed sys2mqtt.py

To clarify what the file does to anyone who sees it outside of its directory such as in search results, system resource monitors etc.

Implement MQTT Discovery

Implement MQTT discovery for easy integration with Homeassistant.

Does not run as FreeBSD service.

systemd files are included for Ubuntu, Debian, CentOS and Sangoma Enterprise Linux.

A method of running as a service in FreeBSD should be included.

Integrate getting statistics and publising statistics into functions.

The getting of statistics and the publishing of statistics should be moved together into the already existing functions.

For example

def function
    get cpu-util
    publish cpu-util

def function2
    get mem-util
    publish mem-util

This will require checking MQTT connection status at the start of each loop as part of an if statement eg.

if mqtt is disconnected
then
    connect to mqtt
elif mqtt is connected
then
    pass

All files need updating.

As title.

Complete - requires testing - Enable distro and version check

Using distro module.

v0.3.0 Needs testing on all platforms before merging to master

Requires testing on Debian 10, Ubuntu 18.04, Ubuntu 20.04, CentOS 8, Sangoma Linux 7 and OpenSUSE using the install.sh script with systemd unit file.

Requires testing on Windows 10 and FreeBSD - separate install instructions need producing for these platforms.

Add drive, fan and temp info

Already included in psutil module, just need to expand code to push this to MQTT.

Add additional options to `conf.py`

Extend options in conf.py to allow users to choose which metrics that they would like to find and publish.

Installation Instructions

With the systemd unit file being put to use, detailed installation instructions will be needed for Windows and FreeBSD users.

Create new installer script

Create new installer script which creates a virtual environment for sys2mqtt to run in.

No exception handling.

main.py has no exception handling past defining the system hostname.

Before v0.3 release, exception handling should be added.

Use YAML file for configuration

Using a Python script to manage configuration is not optimal, the formatting is not easy to manage.

Using a config.yaml file and parsing this with pyyaml would make it easy to read and manage for users.

Logging

Add logging, this will be easy enough using systemd service but not on other platforms, try to create universal logging option.

systemd unit file needs testing on debian.

Systemd unit file to be tested on Debian before version testing commences for other platforms.

Static metrics do not always reach MQTT Server

Static metrics only reach the MQTT server sometimes. QOS is set to 1 as per the rest. No other publish lines seem to have this issue.

Implement connection status.

Use atexit module to publish 'Not Connected' and set utilisations to '0' when sys2mqtt exits.