# systemctl2mqtt - Deliver systemctl status information over MQTT
[](https://github.com/miaucl/systemctl2mqtt/actions/workflows/mypy.yaml)
[](https://github.com/miaucl/systemctl2mqtt/actions/workflows/ruff.yml)
[](https://github.com/miaucl/systemctl2mqtt/actions/workflows/markdownlint.yml)
[](https://github.com/miaucl/systemctl2mqtt/actions/workflows/publish.yml)
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](https://github.com/miaucl/linux2mqtt)
* [miaucl/docker2mqtt](https://github.com/miaucl/docker2mqtt)
* [miaucl/systemctl2mqtt](https://github.com/miaucl/systemctl2mqtt)
## Installation and Deployment
It is available as python package on [pypi/systemctl2mqtt](https://pypi.org/p/systemctl2mqtt).
### Pypi package
[](https://pypi.org/p/systemctl2mqtt)
```bash
pip install systemctl2mqtt
systemctl2mqtt --name MySystemName --events -vvvvv
```
Usage
```python
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.
| Config | Default | Description |
|--------|---------|-------------|
| `log_level` | `INFO` | Set to `DEBUG,INFO,WARN,ERROR,CRITICAL` to enable different levels of verbosity. |
| `systemctl2mqtt_hostname` | systemctl2mqtt Hostname | The hostname of your host, if you want to overwrite it. |
| `homeassistant_prefix` | `homeassistant` | The prefix for Home Assistant discovery. Must be the same as `discovery_prefix` in your Home Assistant configuration. |
| `mqtt_client_id` | `mqtt2discord` | The client id to send to the MQTT broker. |
| `mqtt_host` | `localhost` | The MQTT broker to connect to. |
| `mqtt_port` | `1883` | The port on the broker to connect to. |
| `mqtt_user` | | The user to send to the MQTT broker. Leave unset to disable authentication. |
| `mqtt_password` | | The password to send to the MQTT broker. Leave unset to disable authentication. |
| `mqtt_timeout` | `30` | The timeout for the MQTT connection. |
| `mqtt_topic_prefix` | `systemctl` | The MQTT topic prefix. With the default data will be published to `systemctl/<hostname>`. |
| `mqtt_qos` | `1` | The MQTT QOS level |
| `service_whitelist` | | Define a whitelist for services to consider, if empty, everything is monitored. The entries are either match as literal strings or as regex. |
| `service_blacklist` | | Define a blacklist for services to consider, takes priority over whitelist. The entries are either match as literal strings or as regex. |
| `destroyed_service_ttl` | `86400` | How long, in seconds, before destroyed services are removed from Home Assistant. Services won't be removed if the service is restarted before the TTL expires. |
| `stats_record_seconds` | `30` | The number of seconds to record state and make an average |
| `enable_events` | `0` | 1 Or 0 for processing events |
| `enable_stats` | `0` | 1 Or 0 for processing statistics |
## 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](https://github.com/miaucl/systemctl2mqtt/blob/master/systemctl2mqtt/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](https://github.com/miaucl/systemctl2mqtt/blob/master/systemctl2mqtt/type_definitions.py) or the documentation.
## Home Assistant
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](https://mosquitto.org/) 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.
## Documentation
Using `mkdocs`, the documentation and reference is generated and available on [github pages](https://miaucl.github.io/systemctl2mqtt/).
## Dev
Setup the dev environment using VSCode, it is highly recommended.
```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements_dev.txt
```
Install [pre-commit](https://pre-commit.com)
```bash
pre-commit install
# Run the commit hooks manually
pre-commit run --all-files
```
Following VSCode integrations may be helpful:
* [ruff](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff)
* [mypy](https://marketplace.visualstudio.com/items?itemName=matangover.mypy)
* [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)
### Releasing
It is only possible to release a _final version_ on the `master` branch. For it to pass the gates of the `publish` workflow, it must have the same version in the `tag`, the `setup.cfg`, the `bring_api/__init__.py` and an entry in the `CHANGELOG.md` file.
To release a prerelease version, no changelog entry is required, but it can only happen on a feature branch (**not** `master` branch). Also, prerelease versions are marked as such in the github release page.
## Credits
This is inspired from my other repo [docker2mqtt](https://github.com/miaucl/docker2mqtt).
# CHANGELOG
## 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/miaucl/systemctl2mqtt",
"name": "systemctl2mqtt",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "mqtt, paho, systemctl, metrics",
"author": "Cyrill Raccaud",
"author_email": "cyrill.raccaud+pypi@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e8/6f/a6239b0a1ee1d2802d43c785a49754d9f0da0b9a4076eb1106e7de4db02c/systemctl2mqtt-1.2.0.tar.gz",
"platform": null,
"description": "# systemctl2mqtt - Deliver systemctl status information over MQTT\n\n[](https://github.com/miaucl/systemctl2mqtt/actions/workflows/mypy.yaml)\n[](https://github.com/miaucl/systemctl2mqtt/actions/workflows/ruff.yml)\n[](https://github.com/miaucl/systemctl2mqtt/actions/workflows/markdownlint.yml)\n[](https://github.com/miaucl/systemctl2mqtt/actions/workflows/publish.yml)\n\nThis 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.\n\nThe 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.\n\n_This is part of a family of similar tools:_\n\n* [miaucl/linux2mqtt](https://github.com/miaucl/linux2mqtt)\n* [miaucl/docker2mqtt](https://github.com/miaucl/docker2mqtt)\n* [miaucl/systemctl2mqtt](https://github.com/miaucl/systemctl2mqtt)\n\n## Installation and Deployment\n\nIt is available as python package on [pypi/systemctl2mqtt](https://pypi.org/p/systemctl2mqtt).\n\n### Pypi package\n\n[](https://pypi.org/p/systemctl2mqtt)\n\n```bash\npip install systemctl2mqtt\nsystemctl2mqtt --name MySystemName --events -vvvvv\n```\n\nUsage\n\n```python\nfrom systemctl2mqtt import systemctl2Mqtt, DEFAULT_CONFIG\n\ncfg = Systemctl2MqttConfig({ \n **DEFAULT_CONFIG,\n \"host\": \"mosquitto\",\n \"enable_events\": True\n})\n\ntry:\n systemctl2mqtt = Systemctl2Mqtt(cfg)\n systemctl2mqtt.loop_busy()\n\nexcept Exception as ex:\n # Do something\n```\n\n## Default Configuration\n\nYou can use environment variables to control the behavior.\n\n| Config | Default | Description |\n|--------|---------|-------------|\n| `log_level` | `INFO` | Set to `DEBUG,INFO,WARN,ERROR,CRITICAL` to enable different levels of verbosity. |\n| `systemctl2mqtt_hostname` | systemctl2mqtt Hostname | The hostname of your host, if you want to overwrite it. |\n| `homeassistant_prefix` | `homeassistant` | The prefix for Home Assistant discovery. Must be the same as `discovery_prefix` in your Home Assistant configuration. |\n| `mqtt_client_id` | `mqtt2discord` | The client id to send to the MQTT broker. |\n| `mqtt_host` | `localhost` | The MQTT broker to connect to. |\n| `mqtt_port` | `1883` | The port on the broker to connect to. |\n| `mqtt_user` | | The user to send to the MQTT broker. Leave unset to disable authentication. |\n| `mqtt_password` | | The password to send to the MQTT broker. Leave unset to disable authentication. |\n| `mqtt_timeout` | `30` | The timeout for the MQTT connection. |\n| `mqtt_topic_prefix` | `systemctl` | The MQTT topic prefix. With the default data will be published to `systemctl/<hostname>`. |\n| `mqtt_qos` | `1` | The MQTT QOS level |\n| `service_whitelist` | | Define a whitelist for services to consider, if empty, everything is monitored. The entries are either match as literal strings or as regex. |\n| `service_blacklist` | | Define a blacklist for services to consider, takes priority over whitelist. The entries are either match as literal strings or as regex. |\n| `destroyed_service_ttl` | `86400` | How long, in seconds, before destroyed services are removed from Home Assistant. Services won't be removed if the service is restarted before the TTL expires. |\n| `stats_record_seconds` | `30` | The number of seconds to record state and make an average |\n| `enable_events` | `0` | 1 Or 0 for processing events |\n| `enable_stats` | `0` | 1 Or 0 for processing statistics |\n\n## Consuming The Data\n\nData 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](https://github.com/miaucl/systemctl2mqtt/blob/master/systemctl2mqtt/type_definitions.py) or the documentation.\n\nData 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](https://github.com/miaucl/systemctl2mqtt/blob/master/systemctl2mqtt/type_definitions.py) or the documentation.\n\n## Home Assistant\n\nOnce `systemctl2mqtt` is collecting data and publishing it to MQTT, it's rather trivial to use the data in Home Assistant.\n\nA few assumptions:\n\n* **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](https://mosquitto.org/) will need to be installed and the HA MQTT integration configured.\n* **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.\n* **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.\n\nAfter 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.\n\n\n\n## Documentation\n\nUsing `mkdocs`, the documentation and reference is generated and available on [github pages](https://miaucl.github.io/systemctl2mqtt/).\n\n## Dev\n\nSetup the dev environment using VSCode, it is highly recommended.\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate\npip install -r requirements_dev.txt\n```\n\nInstall [pre-commit](https://pre-commit.com)\n\n```bash\npre-commit install\n\n# Run the commit hooks manually\npre-commit run --all-files\n```\n\nFollowing VSCode integrations may be helpful:\n\n* [ruff](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff)\n* [mypy](https://marketplace.visualstudio.com/items?itemName=matangover.mypy)\n* [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)\n\n### Releasing\n\nIt is only possible to release a _final version_ on the `master` branch. For it to pass the gates of the `publish` workflow, it must have the same version in the `tag`, the `setup.cfg`, the `bring_api/__init__.py` and an entry in the `CHANGELOG.md` file.\n\nTo release a prerelease version, no changelog entry is required, but it can only happen on a feature branch (**not** `master` branch). Also, prerelease versions are marked as such in the github release page.\n\n## Credits\n\nThis is inspired from my other repo [docker2mqtt](https://github.com/miaucl/docker2mqtt).\n\n# CHANGELOG\n\n## 1.2.0\n\n* Update version package identifier and bump setuptools\n* Fix mypy setup\n\n## 1.1.2\n\n* Update the discovery jsons for home assistant\n\n## 1.1.1\n\n* Refresh child PIDs every interval data is reported (see README.md for limitations of this behaviour)\n\n## 1.1.0\n\n* Add child pids to metrics\n\n## 1.0.0\n\n* Initial version.\n",
"bugtrack_url": null,
"license": null,
"summary": "Send your systemctl stats and and events to mqtt and discovery them in home assistant.",
"version": "1.2.0",
"project_urls": {
"Homepage": "https://github.com/miaucl/systemctl2mqtt"
},
"split_keywords": [
"mqtt",
" paho",
" systemctl",
" metrics"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "df40cf8675a53fbce19356c7edece4e6709e2010766cf1cc8ce0ad1e8b35b87c",
"md5": "286bd9cfb6c0b702cc8819a14750b328",
"sha256": "be4c214e55164de104852636647772441240c86fb2d3e350025d7f8e4ca6dc5e"
},
"downloads": -1,
"filename": "systemctl2mqtt-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "286bd9cfb6c0b702cc8819a14750b328",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 19880,
"upload_time": "2024-09-19T18:00:50",
"upload_time_iso_8601": "2024-09-19T18:00:50.660308Z",
"url": "https://files.pythonhosted.org/packages/df/40/cf8675a53fbce19356c7edece4e6709e2010766cf1cc8ce0ad1e8b35b87c/systemctl2mqtt-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e86fa6239b0a1ee1d2802d43c785a49754d9f0da0b9a4076eb1106e7de4db02c",
"md5": "e4d73dc5d6988d6b664ff9742afdfe6f",
"sha256": "351506db36241507cd1ec35900203ea4ee05552c1506298cb145624799a58aa0"
},
"downloads": -1,
"filename": "systemctl2mqtt-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "e4d73dc5d6988d6b664ff9742afdfe6f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 22632,
"upload_time": "2024-09-19T18:00:52",
"upload_time_iso_8601": "2024-09-19T18:00:52.002725Z",
"url": "https://files.pythonhosted.org/packages/e8/6f/a6239b0a1ee1d2802d43c785a49754d9f0da0b9a4076eb1106e7de4db02c/systemctl2mqtt-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-19 18:00:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "miaucl",
"github_project": "systemctl2mqtt",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "paho-mqtt",
"specs": []
}
],
"lcname": "systemctl2mqtt"
}
JSON
