systemctl-mqtt


Namesystemctl-mqtt JSON
Version 1.1.0 PyPI version JSON
download
home_pagehttps://github.com/fphammerle/systemctl-mqtt
SummaryMQTT client triggering & reporting shutdown on systemd-based systems
upload_time2025-01-19 08:30:29
maintainerNone
docs_urlNone
authorFabian Peter Hammerle
requires_python>=3.9
licenseGPLv3+
keywords iot automation home-assistant home-automation lock mqtt shutdown systemd
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls. 
            # systemctl-mqtt

[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![CI Pipeline Status](https://github.com/fphammerle/systemctl-mqtt/workflows/tests/badge.svg)](https://github.com/fphammerle/systemctl-mqtt/actions)
![Coverage Status](https://ipfs.io/ipfs/QmP8k5H4MkfspFxQxdL2kEZ4QQWQjF8xwPYD35KvNH4CA6/20230429T090002+0200/s3.amazonaws.com/assets.coveralls.io/badges/coveralls_100.svg)
[![Last Release](https://img.shields.io/pypi/v/systemctl-mqtt.svg)](https://pypi.org/project/systemctl-mqtt/#history)
[![Compatible Python Versions](https://img.shields.io/pypi/pyversions/systemctl-mqtt.svg)](https://pypi.org/project/systemctl-mqtt/)
[![DOI](https://zenodo.org/badge/272405671.svg)](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 <unit_name>
```
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]`

![homeassistant entities_over_auto_discovery](docs/homeassistant/entities-after-auto-discovery.png)

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

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/fphammerle/systemctl-mqtt",
    "name": "systemctl-mqtt",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": null,
    "keywords": "IoT, automation, home-assistant, home-automation, lock, mqtt, shutdown, systemd",
    "author": "Fabian Peter Hammerle",
    "author_email": "fabian@hammerle.me",
    "download_url": "https://files.pythonhosted.org/packages/19/ab/0f50e8ddb3c734776130b6839d7e5d5a719fe4647ac70b8c0bd5c7b420ab/systemctl-mqtt-1.1.0.tar.gz",
    "platform": null,
    "description": "# systemctl-mqtt\n\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![CI Pipeline Status](https://github.com/fphammerle/systemctl-mqtt/workflows/tests/badge.svg)](https://github.com/fphammerle/systemctl-mqtt/actions)\n![Coverage Status](https://ipfs.io/ipfs/QmP8k5H4MkfspFxQxdL2kEZ4QQWQjF8xwPYD35KvNH4CA6/20230429T090002+0200/s3.amazonaws.com/assets.coveralls.io/badges/coveralls_100.svg)\n[![Last Release](https://img.shields.io/pypi/v/systemctl-mqtt.svg)](https://pypi.org/project/systemctl-mqtt/#history)\n[![Compatible Python Versions](https://img.shields.io/pypi/pyversions/systemctl-mqtt.svg)](https://pypi.org/project/systemctl-mqtt/)\n[![DOI](https://zenodo.org/badge/272405671.svg)](https://zenodo.org/badge/latestdoi/272405671)\n\nMQTT client triggering & reporting shutdown on [systemd](https://freedesktop.org/wiki/Software/systemd/)-based systems\n\n## Setup\n\n### Via Pip\n\n```sh\n$ pip3 install --user --upgrade systemctl-mqtt\n```\n\nOn debian-based systems, a subset of dependencies can optionally be installed via:\n```sh\n$ sudo apt-get install --no-install-recommends python3-jeepney python3-paho-mqtt\n```\n\nFollow instructions in [systemd-user.service](systemd-user.service) to start\nsystemctl-mqtt automatically via systemd.\n\n### Via Docker Compose \ud83d\udc33\n\n1. Clone this repository.\n2. Load [AppArmor](https://en.wikipedia.org/wiki/AppArmor) profile:\n   `sudo apparmor_parser ./docker-apparmor-profile`\n3. `sudo docker-compose up --build`\n\nPre-built docker image are available at https://hub.docker.com/r/fphammerle/systemctl-mqtt/tags\n\nAnnotation of signed tags `docker/*` contains docker image digests: https://github.com/fphammerle/systemctl-mqtt/tags\n\n## Usage\n\n```sh\n$ systemctl-mqtt --mqtt-host HOSTNAME_OR_IP_ADDRESS\n```\n\n`systemctl-mqtt --help` explains all available command-line options / parameters.\n\n### MQTT via TLS\n\nTLS is enabled by default.\nRun `systemctl-mqtt --mqtt-disable-tls \u2026` to disable TLS.\n\n### MQTT Authentication\n\n```sh\nsystemctl-mqtt --mqtt-username me --mqtt-password-file /run/secrets/password \u2026\n# or for testing (unsafe):\nsystemctl-mqtt --mqtt-username me --mqtt-password secret \u2026\n```\n\n### Schedule Poweroff\n\nSchedule poweroff by sending a MQTT message to topic `systemctl/hostname/poweroff`.\n\n```sh\n$ mosquitto_pub -h MQTT_BROKER -t systemctl/hostname/poweroff -n\n```\n\nAdapt delay via: `systemctl-mqtt --poweroff-delay-seconds 60 \u2026`\n\n### Shutdown Report\n\n`systemctl-mqtt` subscribes to [logind](https://freedesktop.org/wiki/Software/systemd/logind/)'s `PrepareForShutdown` signal.\n\n`systemctl halt|poweroff|reboot` triggers a message with payload `true` on topic `systemctl/hostname/preparing-for-shutdown`.\n\n### Lock Screen\n\nLock screen by sending a MQTT message to topic `systemctl/hostname/lock-all-sessions`.\n\n```\n$ mosquitto_pub -h MQTT_BROKER -t systemctl/hostname/lock-all-sessions -n\n```\n\n### Suspend\n\n```\n$ mosquitto_pub -h MQTT_BROKER -t systemctl/hostname/suspend -n\n```\n\n### Monitor `ActiveState` of System Units\n\n```\n$ systemctl-mqtt --monitor-system-unit foo.service\n```\nenables reports on topic\n`systemctl/[hostname]/unit/system/[unit_name]/active-state`.\n\n### Restarting of System Units\n\n```\n$ systemctl-mqtt  --control-system-unit <unit_name>\n```\nenables that a system unit can be restarted by a message on topic\n`systemctl/[hostname]/unit/system/[unit_name]/restart`.\n\n## Home Assistant \ud83c\udfe1\n\nWhen [MQTT Discovery](https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery)\nis enabled (default in Home Assistant \u22650.117.0), the following entities will be\nadded automatically:\n- `binary_sensor.[hostname]_logind_preparing_for_shutdown`\n- `button.[hostname]_logind_lock_all_sessions`\n- `button.[hostname]_logind_poweroff`\n- `button.[hostname]_logind_suspend`\n- `sensor.[hostname]_unit_system_[unit_name]_active_state`\n  for `--monitor-system-unit [unit_name]`\n- `button.[hostname]_unit_system_[unit_name]_restart`\n  for `--control-system-unit [unit_name]`\n\n![homeassistant entities_over_auto_discovery](docs/homeassistant/entities-after-auto-discovery.png)\n\nPass `--homeassistant-discovery-prefix custom-prefix` to `systemctl-mqtt` when\nusing a custom discovery topic prefix.\n",
    "bugtrack_url": null,
    "license": "GPLv3+",
    "summary": "MQTT client triggering & reporting shutdown on systemd-based systems",
    "version": "1.1.0",
    "project_urls": {
        "Changelog": "https://github.com/fphammerle/systemctl-mqtt/blob/master/CHANGELOG.md",
        "Homepage": "https://github.com/fphammerle/systemctl-mqtt"
    },
    "split_keywords": [
        "iot",
        " automation",
        " home-assistant",
        " home-automation",
        " lock",
        " mqtt",
        " shutdown",
        " systemd"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "a1c197173c35660e202d3ee33b5109a01f136d09ddc8cb55524628871c409564",
                "md5": "0aee9a3289069462e98b7d2627239daf",
                "sha256": "30e0635c1870d0d3dddf19f83b97c8fd016e92b1684fad9b55d78fc929c7ceeb"
            },
            "downloads": -1,
            "filename": "systemctl_mqtt-1.1.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "0aee9a3289069462e98b7d2627239daf",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9",
            "size": 31494,
            "upload_time": "2025-01-19T08:30:27",
            "upload_time_iso_8601": "2025-01-19T08:30:27.143677Z",
            "url": "https://files.pythonhosted.org/packages/a1/c1/97173c35660e202d3ee33b5109a01f136d09ddc8cb55524628871c409564/systemctl_mqtt-1.1.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "19ab0f50e8ddb3c734776130b6839d7e5d5a719fe4647ac70b8c0bd5c7b420ab",
                "md5": "49b86704a8ed2d208bd7135655ddfd38",
                "sha256": "245c74e4b408aab0365b6afbc333fb77058363b72eb4c19c4b8d83a4cd201acc"
            },
            "downloads": -1,
            "filename": "systemctl-mqtt-1.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "49b86704a8ed2d208bd7135655ddfd38",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9",
            "size": 84485,
            "upload_time": "2025-01-19T08:30:29",
            "upload_time_iso_8601": "2025-01-19T08:30:29.511520Z",
            "url": "https://files.pythonhosted.org/packages/19/ab/0f50e8ddb3c734776130b6839d7e5d5a719fe4647ac70b8c0bd5c7b420ab/systemctl-mqtt-1.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-01-19 08:30:29",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "fphammerle",
    "github_project": "systemctl-mqtt",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "systemctl-mqtt"
}
Fabian Peter Hammerle
Elapsed time: 0.48258s