HUB
Sign inSign up

cplieger/docker-nut-upsd

By cplieger

•Updated 3 days ago

Container for Network UPS Tools (NUT), set up from compose settings, with TLS and USB reconnect

Image
Networking
Monitoring & observability
1

10K+

cplieger/docker-nut-upsd repository overview

⁠docker-nut-upsd

docker-nut-upsd runs Network UPS Tools (NUT) on the machine your UPS plugs into and shares the UPS with every machine on the same power. It has no web page.

⁠What it does

Your NAS, servers and other NUT clients shut down cleanly on low battery, and Home Assistant shows the UPS status.

  • Sets up NUT from a few compose settings, with no NUT config files to write.
  • Works with USB, serial, Modbus and network (SNMP) UPSes, on amd64 and arm64.
  • Reconnects to a UPS that drops off USB and comes back, without a container restart.
  • Encrypts the connection for clients that support TLS, and still serves the others.
  • Can also power off this machine on low battery. This is off by default.

⁠Who it is for

docker-nut-upsd is built for a UPS on an always-on Linux machine that runs Docker, shared with every machine on the same power. It checks every setting before it starts and ships UPS metrics and alert rules. You need a UPS listed on the NUT hardware list⁠, connected to that machine by USB, serial or the network.

Two other projects suit a different setup:

  • Consider NUT for Unraid⁠ if your UPS plugs into an Unraid server. The plugin adds NUT to Unraid itself, with a settings frontend. Its maintainer ends support on 30 November 2026.
  • Consider gpdm/nut-upsd⁠ if you want one container to monitor several UPSes from NUT config files you write.

docker-nut-upsd is free software under the Apache-2.0 license.

⁠Pull

docker pull cplieger/docker-nut-upsd:latest

Also published to ghcr.io/cplieger/docker-nut-upsd with identical images and tags. Release versions are tagged vX.Y.Z alongside latest.

⁠Quick start

# Example compose for docker-nut-upsd. See the README for all configuration options and hardening.
services:
  nut-upsd:
    image: ghcr.io/cplieger/docker-nut-upsd:latest
    container_name: nut-upsd
    restart: unless-stopped

    environment:
      UPS_NAME: "ups"
      UPS_DESC: "My UPS"
      UPS_DRIVER: "usbhid-ups"  # the driver the NUT hardware list names for your UPS model
      UPS_PORT: "auto"  # auto finds a USB UPS. For serial and network UPSes, see docs/configuration.md
      API_USER: "monuser"
      API_PASSWORD: "secret"  # your NUT clients log in with it. If no Synology NAS uses this server, change it

    ports:
      - "3493:3493"

    # Keep both USB lines below. They let the driver reach the UPS again after it
    # drops off USB and comes back, which a devices: mapping cannot do.
    device_cgroup_rules:
      - "c 189:* rmw"
    volumes:
      - "/dev/bus/usb:/dev/bus/usb"

⁠Documentation

⁠License

Apache-2.0. See LICENSE⁠.

The image carries the license text of every bundled component under /usr/share/licenses/. The Alpine packages in the image ship no license file upstream, so their license texts are kept under licenses/ in this repository and copied in.

The image packages Network UPS Tools⁠ (GPL-2.0-or-later), compiled from the release tarball the Dockerfile fetches at the version its NUT_VERSION argument pins (https://github.com/networkupstools/nut/releases/download/<version>/nut-<version>.tar.gz), and links libmodbus⁠ and Net-SNMP⁠, each compiled the same way from the tarball its own version argument pins. Each component's own license text is in that tree.

The build applies checked-in backports of upstream NUT source, so those files stay GPL-2.0-or-later:

  • patches/cve-2026-54161-notifycmd-execvp.patch backports upstream commit ecf98e7542e4ae2b62b211622ee26989274b2220.
  • patches/libusb-exit-reconnect-deadlock.patch backports upstream commit bfbba15928aa6a91b3e4b8943e0cad16199d9d48.
  • patches/libusb-rdlens-oob-read.patch backports upstream commit edc06fb39435b892d5daeec53cb4845cb12d1d50.
  • patches/richcomm-libusb-context-reopen.patch backports upstream commit ce2364e2b1e79406248be50b01a031db67c1c9fd.

This repository's Dockerfile and those patch files are the complete recipe for the NUT, libmodbus and Net-SNMP binaries the image ships: the corresponding source is the upstream tarball each pin names, with the patches above applied.

Tag summary

Content type

Image

Digest

sha256:ab60e95c5…

Size

28.1 MB

Last updated

3 days ago

docker pull cplieger/docker-nut-upsd