cplieger/docker-nut-upsd repository overview

⁠docker-nut-upsd

docker-nut-upsd is a container for Network UPS Tools (NUT), set up from compose settings, with TLS and USB reconnect. It shares the status of the UPS on this machine with your network. It has no web page.

⁠What it does

Your NAS, servers and other NUT clients follow one UPS and shut down cleanly when its battery runs low.

• 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. Clients without TLS still connect.
• 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 alert rules for UPS events. 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 and frequent NUT updates.
• 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 docs/configuration.md and docs/hardening.md 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. Together they let the driver reach a UPS that
    # drops off USB and comes back. A devices: mapping cannot do that.
    device_cgroup_rules:
      - "c 189:* rmw"
    volumes:
      - "/dev/bus/usb:/dev/bus/usb"

⁠Documentation

• Full documentation⁠ — configuration, behavior, security
• Configuration⁠
• Security⁠
• How docker-nut-upsd works⁠
• Monitoring and alerts⁠
• Contributing⁠
• Releases and changelog⁠

⁠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.