systemctl-mqtt

MQTT client triggering & reporting shutdown on systemd-based systems

Setup

Via Pip

$ pip3 install --user --upgrade systemctl-mqtt

On debian-based systems, a subset of dependencies can optionally be installed via:

$ sudo apt-get install --no-install-recommends python3-jeepney python3-paho-mqtt

Follow instructions in systemd-user.service to start systemctl-mqtt automatically via systemd.

Via Docker Compose 🐳

1. Clone this repository.
2. Load 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

$ 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

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.

$ 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'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.

Control System Units

$ systemctl-mqtt  --control-system-unit <unit_name>

enables that a system unit can be started, stopped, restarted and isolated by a message on topic systemctl/[hostname]/unit/system/[unit_name]/start, …/stop, …/restart, …/isolate.

Home Assistant 🏡

Note: Home Assistant 2025.10+ is required for MQTT Discovery of systemctl-mqtt entities.

When 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]_start for --control-system-unit [unit_name]
• button.[hostname]_unit_system_[unit_name]_stop for --control-system-unit [unit_name]
• button.[hostname]_unit_system_[unit_name]_restart for --control-system-unit [unit_name]
• button.[hostname]_unit_system_[unit_name]_isolate for --control-system-unit [unit_name], when the unit allows isolation (e.g., targets)

Pass --homeassistant-discovery-prefix custom-prefix to systemctl-mqtt when using a custom discovery topic prefix.