https://github.com/fphammerle/systemctl-mqtt
MQTT client triggering & reporting shutdown on systemd-based systems :house_with_garden: 🐳
https://github.com/fphammerle/systemctl-mqtt
automation home-assistant internet-of-things mqtt poweroff shutdown systemd
Last synced: 22 days ago
JSON representation
MQTT client triggering & reporting shutdown on systemd-based systems :house_with_garden: 🐳
- Host: GitHub
- URL: https://github.com/fphammerle/systemctl-mqtt
- Owner: fphammerle
- License: gpl-3.0
- Created: 2020-06-15T10:11:47.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2025-04-11T08:23:48.000Z (24 days ago)
- Last Synced: 2025-04-12T00:49:32.332Z (23 days ago)
- Topics: automation, home-assistant, internet-of-things, mqtt, poweroff, shutdown, systemd
- Language: Python
- Homepage: https://pypi.org/project/systemctl-mqtt/
- Size: 653 KB
- Stars: 13
- Watchers: 4
- Forks: 6
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: COPYING
Awesome Lists containing this project
README
# systemctl-mqtt
[](https://github.com/psf/black)
[](https://github.com/fphammerle/systemctl-mqtt/actions)
[](https://pypi.org/project/systemctl-mqtt/#history)
[](https://pypi.org/project/systemctl-mqtt/)
[](https://zenodo.org/badge/latestdoi/272405671)
MQTT client triggering & reporting shutdown on [systemd](https://freedesktop.org/wiki/Software/systemd/)-based systems
## Setup
### Via Pip
```sh
$ pip3 install --user --upgrade systemctl-mqtt
```
On debian-based systems, a subset of dependencies can optionally be installed via:
```sh
$ sudo apt-get install --no-install-recommends python3-jeepney python3-paho-mqtt
```
Follow instructions in [systemd-user.service](systemd-user.service) to start
systemctl-mqtt automatically via systemd.
### Via Docker Compose 🐳
1. Clone this repository.
2. Load [AppArmor](https://en.wikipedia.org/wiki/AppArmor) profile:
`sudo apparmor_parser ./docker-apparmor-profile`
3. `sudo docker-compose up --build`
Pre-built docker image are available at https://hub.docker.com/r/fphammerle/systemctl-mqtt/tags
Annotation of signed tags `docker/*` contains docker image digests: https://github.com/fphammerle/systemctl-mqtt/tags
## Usage
```sh
$ systemctl-mqtt --mqtt-host HOSTNAME_OR_IP_ADDRESS
```
`systemctl-mqtt --help` explains all available command-line options / parameters.
### MQTT via TLS
TLS is enabled by default.
Run `systemctl-mqtt --mqtt-disable-tls …` to disable TLS.
### MQTT Authentication
```sh
systemctl-mqtt --mqtt-username me --mqtt-password-file /run/secrets/password …
# or for testing (unsafe):
systemctl-mqtt --mqtt-username me --mqtt-password secret …
```
### Schedule Poweroff
Schedule poweroff by sending a MQTT message to topic `systemctl/hostname/poweroff`.
```sh
$ mosquitto_pub -h MQTT_BROKER -t systemctl/hostname/poweroff -n
```
Adapt delay via: `systemctl-mqtt --poweroff-delay-seconds 60 …`
### Shutdown Report
`systemctl-mqtt` subscribes to [logind](https://freedesktop.org/wiki/Software/systemd/logind/)'s `PrepareForShutdown` signal.
`systemctl halt|poweroff|reboot` triggers a message with payload `true` on topic `systemctl/hostname/preparing-for-shutdown`.
### Lock Screen
Lock screen by sending a MQTT message to topic `systemctl/hostname/lock-all-sessions`.
```
$ mosquitto_pub -h MQTT_BROKER -t systemctl/hostname/lock-all-sessions -n
```
### Suspend
```
$ mosquitto_pub -h MQTT_BROKER -t systemctl/hostname/suspend -n
```
### Monitor `ActiveState` of System Units
```
$ systemctl-mqtt --monitor-system-unit foo.service
```
enables reports on topic
`systemctl/[hostname]/unit/system/[unit_name]/active-state`.
### Restarting of System Units
```
$ systemctl-mqtt --control-system-unit
```
enables that a system unit can be restarted by a message on topic
`systemctl/[hostname]/unit/system/[unit_name]/restart`.
## Home Assistant 🏡
When [MQTT Discovery](https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery)
is enabled (default in Home Assistant ≥0.117.0), the following entities will be
added automatically:
- `binary_sensor.[hostname]_logind_preparing_for_shutdown`
- `button.[hostname]_logind_lock_all_sessions`
- `button.[hostname]_logind_poweroff`
- `button.[hostname]_logind_suspend`
- `sensor.[hostname]_unit_system_[unit_name]_active_state`
for `--monitor-system-unit [unit_name]`
- `button.[hostname]_unit_system_[unit_name]_restart`
for `--control-system-unit [unit_name]`
Pass `--homeassistant-discovery-prefix custom-prefix` to `systemctl-mqtt` when
using a custom discovery topic prefix.