Pi-NUT is an Ansible playbook and tools for deploying Network UPS Tools, NUT clients/monitors and servers onto Raspberry Pis. It supports configuration of many UPSes with automated discovery of UPS devices connected to each Raspberry Pi based NUT server.
It uses a fork of WebNUT to show a list of all UPS devices with their status and battery charge. This fork includes support for multiple UPS servers and other minor improvements.
Each UPS has a details page showing all the exposed NUT fields:
The NUT monitor responds to server UPS events by running arbitrary commands in response to each event. Events available are:
| Event | Description |
|---|---|
online |
UPS on line power. |
onbatt |
UPS on battery. |
lowbatt |
UPS battery is low. |
fsd |
UPS forced shutdown in process. |
commok |
UPS communication is OK. |
commbad |
UPS communication is lost. |
shutdown |
Logout and shutdown ongoing. |
replbatt |
UPS battery need replacing. |
nocomm |
UPS is not available. |
noparent |
The upsmon process has died, shutdown not possible |
See the nut_monitor section for further details of how this is configured.
The Ansible project is laid out according to the Ansible Sample directory layout and contains the following playbooks.
NUT servers collect data from connected UPS devices. A NUT server can support several UPS devices, limited by the number of available USB connections available on the Raspberry Pi.
The host_vars file for each server can be configured to override the default
driver and description for the UPS. The device IDs are extracted from the results
returned by lsusb.
ups_configs:
"<device id>":
desc: "<description>"
driver: "<driver>"
Each server can also be configured with a heartbeat UPS device which generates status for a dummy UPS.
The NUT monitor connects to all NUT servers and monitors the UPS devices
connected to them. The monitor server's host_vars file is configured to enable
events by setting them in the nut_events var:
nut_events: ["online", "onbatt", "lowbatt"]
Events values are always lowercase.
The host_vars file also contains configuration for actions which can be wired up to events on each UPS.
nut_actions:
"ups-1@nut-a.mydomain.com":
online: "echo ONLINE"
"ups-1@nut-b.mydomain.com":
online: "echo ONLINE"
onbatt: "echo ONBATT"
"ups-1@nut-c.mydomain.com":
online: "echo ONLINE"
lowbatt: "echo LOWBATT"
The NUT web server connects to all NUT servers and displays the state of all UPS devices. The WebNUT is a Python3 application running on the Pyramid Web Framework. The install footprint is quite large so the Raspberry Pi requires at least a 4Gb SD card for a full install.
Copy hosts.example to hosts and edit it. Each UPS should be connected to a
NUT server, servers can support more than one UPS. Set heartbeat_enabled=true
to configure a heartbeat UPS on each server.
Additional settings for each host can be set in individual
host_vars/<hostname>.yaml. See host_vars.example.yaml for more details.
The group_vars/all.yaml file contains other global settings.
The NUT monitor and NUT web can be installed on the same host, which can also be a NUT server.
Other useful pages related to this project: