Introducing MQTTrooper

Introduction

MQTTrooper, is a lightweight, flexible, and easy-to-use daemon written in go that listens for commands via MQTT or HTTP and executes them on the host machine. You can configure the messages you expect from a mqtt topic, and the associated command you want to execute on the host machine.

With its simple configuration file and intuitive interface, you can easily manage multiple services and execute complex tasks with minimal effort.

Key Features

• Multiple Interfaces: Execute commands via MQTT messages or HTTP requests.
• Flexible Configuration: Configure services and settings using a simple YAML file.
• Service Management: Run as a systemd service on Linux or a launchd service on macOS.
• Dry Run Mode: Test your configuration without executing any commands.
• Easy to Deploy: Single binary with minimal dependencies.

Example use cases

MQTTrooper is a versatile tool that can be used in various scenarios, from simple home automation tasks to more complex IoT integrations. Here are some examples of what you can achieve with MQTTrooper:

• Suspend your computer when you leave your home: Create an automation in home assistant to send an MQTT message when you leave your home. Configure MQTTrooper to execute the systemctl suspend when that message is received.

• Button to restart a systemd service: Create a button in your dashboard to restart that systemd service that stops working from time to time.

• Automated notifications: Integrate MQTTrooper with your home automation system to receive a desktop notification on your mac when a door is opened or closed.

• Slider to adjust a computer volume: Create a slider in Home Assistant that changes the volume of a linux computer that is running MQTTrooper.

  To do this, you can add the following services to the config.yaml of your MQTTrooper instance:

  services:
    volume0: pactl set-sink-volume @DEFAULT_SINK@ 0%
    volume1: pactl set-sink-volume @DEFAULT_SINK@ 10%
    ...
    volume10: pactl set-sink-volume @DEFAULT_SINK@ 100%
  

  Then, create a helper of type input_number in home assistant, and create an automation like this:

  alias: My computer volume
  description: ""
  triggers:
    - entity_id:
        - input_number.my_computer_volume
      trigger: state
  conditions: []
  actions:
    - data:
        topic: /mqttrooper/my_computer
        payload: volume{{states('input_number.my_computer_volume') |round}}
      action: mqtt.publish
  mode: restart
  

Getting Started

To get started with MQTTrooper head over to the Github repository README and follow the instructions there. In a nutshell you’ll need to:

1. Clone the repository.
2. Build the project using make.
3. Copy the example configuration file (config.yaml.example) to your desired location.
4. Edit the config.yaml file with your MQTT broker details, and the services you want to execute.
5. Generate systemd (linux) or launchd (macosx) configuration.
6. Start the daemon.

Configuration

MQTTrooper is configured using a simple YAML file, which allows you to easily manage multiple services and settings. The services section maps service names to command strings.

services:
  date: "date"
  volume_up: "amixer -D pulse sset Master 5%+"
  volume_down: "amixer -D pulse sset Master 5%-"

Check the README.md for more info about the possible configuration values: MQTTrooper

Running MQTTrooper

MQTTrooper can be run as a systemd service on Linux or a launchd service on macOS. To start the service, use the following commands:

mqttrooper dump-systemd-service > mqttrooper.service
systemctl --user link ./mqttrooper.service
systemctl --user enable mqttrooper.service
systemctl --user start mqttrooper.service

Or for macOS:

mqttrooper dump-plist > ~/Library/LaunchAgents/com.YOUR_USER.mqttrooper.plist
launchctl load -w ~/Library/LaunchAgents/com.YOUR_USER.mqttrooper.plist

MQTT API

When enabled, MQTTrooper subscribes to the specified topic and executes received messages as service names. To use the MQTT interface, configure the mqtt section in your config.yaml file:

mqtt:
  enabled: true
  address: "tcp://127.0.0.1:1883"
  client_id: "your_client_id"
  user: "your_user"
  pass: "your_password"
  topic: "/mqttrooper/your_computer_name"

HTTP API

When enabled, MQTTrooper provides a simple HTTP interface that allows you to execute commands using GET requests. To access the home page and list available services, use http://<bind_address>:<port>/. To execute a service, make a GET request with the following parameters:

• URL: http://<bind_address>:<port>/r
• Method: GET
• Query Parameters:
  • s: The name of the service to execute.

Security considerations

Reverse proxy: MQTTrooper does not provide any built-in security measures for the HTTP interface. To secure your MQTTrooper setup, you should consider using a reverse proxy with authentication and SSL/TLS encryption.

Dedicated user: To run MQTTrooper securely, create a dedicated user with minimal privileges and restrict file permissions for the config.yaml file. Configure the shell used to execute commands using a restricted shell like rbash.

Wrapping up

You now have a solid understanding of how to use MQTTrooper as a bridge between your IoT devices, home automation systems, and the scripts or commands you want to run on your server. With its simple configuration file and intuitive interface, you can manage multiple services and execute complex tasks with minimal effort.

💗 Send some love

Want to show your support? Head over to the GitHub repository and give it a star ⭐! Your love will fuel its future updates. Stay tuned for new content by subscribing to this blog or following me on social media.