systemctl2mqtt - Deliver systemctl status information over MQTT

This program uses journalctl and systemctl to watch for changes in your services, and top for metrics about those services, and delivers current status to MQTT. It will also publish Home Assistant MQTT Discovery messages so that (binary) sensors automatically show up in Home Assistant.

The focus lies on long-running services with continuous uptime, instead of single or one-shot services, as the stats being reported as well as the child PIDs being refreshed every stats_record_seconds. For services with a lifespan comparable to this interval, the reported stats will not be accurate. Further, as the library uses top and matches the services with their respective PIDs, including child PIDs from subprocesses, it is also not suited for monitoring services which spawn regularly new threads.

This is part of a family of similar tools:

• miaucl/linux2mqtt
• miaucl/docker2mqtt
• miaucl/systemctl2mqtt

Installation and Deployment

It is available as python package on pypi/systemctl2mqtt.

Pypi package

pip install systemctl2mqtt
systemctl2mqtt --name MySystemName --events -vvvvv

Usage

from systemctl2mqtt import systemctl2Mqtt, DEFAULT_CONFIG

cfg = Systemctl2MqttConfig({ 
  **DEFAULT_CONFIG,
  "host": "mosquitto",
  "enable_events": True
})

try:
  systemctl2mqtt = Systemctl2Mqtt(cfg)
  systemctl2mqtt.loop_busy()

except Exception as ex:
  # Do something

Default Configuration

You can use environment variables to control the behavior.

Consuming The Data

Data is published to the topic systemctl/<hostname>/events using JSON serialization. It will arrive whenever a change happens and its type can be inspected in type_definitions.py or the documentation.

Data is also published to the topic systemctl/<hostname>/stats using JSON serialization. It will arrive every STATS_RECORD_SECONDS seconds or so can be inspected in type_definitions.py or the documentation.

Discovery

It is possible to enable/disable discovery of the metrics.

systemctl2mqtt --name Server1 -vvvvv --discovery "<your_discovery>"

Setting it to an empty list will deactivate discovery, per default homeassistant is active.

systemctl2mqtt --name Server1 -vvvvv --discovery ""

Home Assistant

systemctl2mqtt --name Server1 -vvvvv --discovery "homeassistant"

Once systemctl2mqtt is collecting data and publishing it to MQTT, it's rather trivial to use the data in Home Assistant.

A few assumptions:

• Home Assistant is already configured to use a MQTT broker. Setting up MQTT and HA is beyond the scope of this documentation. However, there are a lot of great tutorials on YouTube. An external broker (or as add-on) like Mosquitto will need to be installed and the HA MQTT integration configured.
• The HA MQTT integration is configured to use homeassistant as the MQTT autodiscovery prefix. This is the default for the integration and also the default for systemctl2mqtt. If you have changed this from the default, use the --prefix parameter to specify the correct one.
• You're not using TLS to connect to the MQTT broker. Currently systemctl2mqtt only works with unencrypted connections. Username / password authentication can be specified with the --username and --password parameters, but TLS encryption is not yet supported.

After you start the service (binary) sensors should show up in Home Assistant immediately. Look for sensors that start with (binary_)sensor.systemctl. Metadata about the container will be available as attributes for events, which you can then expose using template sensors if you wish.

Logging

systemctl2mqtt can log to a directory in addition to the console using the --logdir parameter. The specified directory can be absolute or relative and is created if it doesn't exist. The verbosity parameter applies to file logging and the log file size is limited to 1M bytes and 5 previous files are kept.

systemctl2mqtt --name Server1 -vvvvv --logdir /var/log/systemctl2mqtt/

Documentation

Using mkdocs, the documentation and reference is generated and available on github pages.

Dev

Setup the dev environment using VSCode, it is highly recommended.

python -m venv .venv
source .venv/bin/activate
pip install -r requirements_dev.txt

Install pre-commit

pre-commit install

# Run the commit hooks manually
pre-commit run --all-files

Following VSCode integrations may be helpful:

• ruff
• mypy
• markdownlint

Releasing

A final version can only be released from the master branch. To pass the gates of the publish workflow, the version must match in both the tag and systemctl2mqtt/__init__.py.

To release a prerelease version, it must be done from a feature branch (not master). Prerelease versions are explicitly marked as such on the GitHub release page.

Credits

This is inspired from my other repo docker2mqtt.

CHANGELOG

DEPRECATED

This changelog is no longer maintained and will not be updated in future releases. Please refer to the release notes on GitHub for the latest changes.

1.3.1

• Fix parsing of memory values with suffixes from top

1.3.0

• Add option to group all entities into a single device in home assistant

1.2.0

• Update version package identifier and bump setuptools
• Fix mypy setup

1.1.2

• Update the discovery jsons for home assistant

1.1.1

• Refresh child PIDs every interval data is reported (see README.md for limitations of this behaviour)

1.1.0

• Add child pids to metrics

1.0.0

• Initial version.