dunnart

dunnart

Lightweight remote system monitoring over MQTT for Home Assistant.

Lightweight in that the binary is standalone and has no dependencies - just copy the binary to your target with a suitable config file and go.

Lightweight in that it has a small footprint, in terms of both the binary size and CPU load.

Lightweight in that it only monitors what you want it to - it doesn't bloat your MQTT and Home Assistant with an abundance of sensors that you don't care about.

Lightweight in that the sensors that you want to monitor are automatically detected by the Home Assistant MQTT integration. Just specify what you want to monitor in the dunnart config file and they appear in Home Assistant.

Currently tested on Raspberry Pis and OpenWrt routers, but should work on any Linux based device.

Example Setup

A device with this configuration:

modules: [cpu, mem, fs]

fs:
  mountpoints: [root, home]
  root.path: "/"
  home.path: "/home"

mqtt:
  broker: tcp://<mqtt server>:1883
  username: <username>
  password: <password>

produces these sensors in Home Assistant:

The cpu usage gives some indication of the system load with dunnart running.

This particular device doesn't actually have a /home mountpoint (i.e. the config is intentionally broken) so it shows as disconnected, and the usage as unavailable.

If the daemon is stopped, or the device stops for whatever reason, then all the sensors become unavailable:

with the exception of the device status itself which shows as disconnected/offline.

Installation

The basic steps:

• get a copy of the repo
• build for your target using make <target> for the appropriate target type, or alternatively call go build with the compile options suitable for your target.
• customise dunnart.yaml
• copy the dunnart binary and config to your target
• run the daemon to check everything works
• configure the init system to start the daemon - an example dunnart.service for systemd is provided.

Configuration

The top level of the configuration contains the modules being loaded, the global defaults for common configuration, the mqtt and home assistant configuration sections, and optionally the configuration for each of the modules.

Sections only need to be present to override default values, or where no default value is provided.

MQTT

The mqtt section specifies the connection to the MQTT broker.

This section is required as there is no default provided for the broker URL.

Home Assistant

The Home Assistant section specifies how to detect HA MQTT reconnection and how to publish entity config messages so HA can automatically discover the entities and assign them to a device corresponding to the dunnart host.

Discovery relies on HA having discovery enabled and publishing to the birth_message_topic when it first connects to the MQTT broker, so both Enable discovery and Enable birth message must be set in the MQTT integration options on HA, and the Discovery prefix and Birth message topic must match in the HA and dunnart configurations.

The dunnart defaults correspond to the default HA configuration, in which case the homeassistant section can be omitted. For non-default setups the bold settings must be set to match the HA configuration.

Modules

As per the Home Assistant section, the module sections are only requried to override the default settings.

CPU

Supported entities:

• used_percent
• temperature
• uptime

Memory (mem)

Supported entities:

• ram_used_percent
• swap_used_percent

Filesystem (fs)

For a particular host, the mount points available are listed by mount.

Supported entities:

• mounted
• used_percent

Network Interface (net)

For a particular host, the interfaces available are listed in /sys/class/net.

Supported entities:

• operstate (interface up or down)
• carrier (carrier medium connected)
• rx_bytes
• rx_packets
• rx_packet_rate
• rx_throughput
• tx_bytes
• tx_packets
• tx_packet_rate
• tx_throughput

System Info

The info is drawn from uname and /etc/os-release.

Supported entities:

• machine (uname -m)
• kernel_name (uname -s)
• kernel_release (uname -r)
• kerrnel_version (uname -v)
• machine (uname -m)
• os_name (/etc/os-release NAME)
• os_release (/etc/os-release PRETTY_NAME)
• os_version (/etc/os-release/VERSION)

WAN

Supported entities:

• link
• ip

Background

This is a spin-off from a couple of daemons I wrote some time ago to control some devices over MQTT. Over time I modified those to integrate into Home Assistant and used glances to monitor the Raspberry Pis the daemons were running on.

I came to realise that glances was overkill for what I needed, and so extended those daemons to provide the system monitoring that I required instead.

I then realised that it would be useful to be able to monitor the other devices in my setup, so moved the common system monitoring into dunnart and the old daemons became special case extensions of that.

Features

Home Assistant Integration

Entities are discoverable by Home Assistant via the MQTT integration. Discovery must be enabled in the MQTT integration, and dunnart must be configured with the corresponding discovery topic prefix.

All entities are assigned to a device, corresponding to the dunnart host, on Home Assistant.

Sensor availability is automatically dependent on the availability of the dunnart daemon.

dunnart subscribes to the Home Assistant birth message topic and will re-advertise the sensor config and republish the sensor states whenever Home Assistant reconnects to MQTT.

Modular Design

Entities are grouped into modules, so groups of entities can be easily enabled or disabled. Modules must be explicitly enabled, and disabled modules use no resources.

The existing set of provided modules includes cpu, memory, file system, net and wan. The modules and entities provided are currently minimal, being those I found sufficient to monitor the health of my setup.

The current entities include:

• device availability
• cpu used percentage
• cpu temperature
• ram used percentage
• swap used percentage
• file system mountpoint used percentage
• network interface connectivity and statistics
• os and kernel version
• uptime
• wan link availability
• wan IP address

Refer to the module configuration sections for a complete list of supported entities.

Polling Rate

The polling rate for polled sensors is individually controllable, both via configuration and via MQTT. e.g. cpu load may be checked every minute while file system usage may checked every 10 minutes. To update the polling period, publish a message with the new polling period to <sensor topic>/rqd/poll_period.

Sensors may also be requested to update on demand via MQTT - publish a message to <sensor topic>/rqd and the sensor will refresh and publish its current state.

Roadmap

Additional modules under consideration:

• GPIO (input pins as sensors, output pins as switches)
• RPi Power
• Exec (execute an arbitrary command on the remote host)