APCUPSD

This is a simple Ubuntu base with apcupsd installed. It manages and monitors a USB Connected UPS Device, and has the ability to gracefully shut down the host computer in the event of a prolonged power outage and notify via Telegram. This is done with no customisation to the host whatsoever, there's no need for cron jobs on the host, or trigger files and scripts. Everything is done within the container.

Use Cases :
Use this image if your UPS is connected to your docker host by USB Cable and you don't want to run apcupsd in the physical host OS.

Equally, this container can be run on any other host to monitor another instance of this container running on a host connected to the UPS for power status messages from the UPS, and take action to gracefully shut down the non-UPS connected host.

The purpose of this image is to containerise the APC UPS monitoring daemon so that it is separated from the OS, yet still has access to the UPS via USB Cable.

Configuration :

Create the container with the following command.

docker run -d --privileged \
  --name=apcupsd  \
  -e TZ=Europe/London \
  -e TELEGRAM_TOKEN=put token here, e.g. 1000000000:AAAAAAAAAAAAAAAAAA \
  -e TELEGRAM_CHATID=put chat_id here>, e.g. -1000000000000 \
  --device=/dev/usb/hiddev1 \
  --restart unless-stopped \
  -p=3551:3551 \
  -v /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket \
  freender/apcupsd:main

And, for those using tools with docker-compose, here's an example:

version: '3.7'
services:
  apcupsd:
    #image: ghcr.io/freender/apcupsd:main
    build: https://github.com/freender/apcupsd.git
    pull_policy: build
    hostname: Network
    container_name: apcupsd
    devices:
      - /dev/usb/hiddev0
    ports:
      - 13551:3551
    environment: 
      TZ: "America/New_York" # Default value is Europe/London
      TELEGRAM_TOKEN: ${TELEGRAM_TOKEN} # Telegram BOT token
      TELEGRAM_CHATID: ${TELEGRAM_CHATID} # Telegram CHATID
    volumes:
      - /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket
    restart: always

As I mentioned above, you will likely want to customise /etc/apcupsd/apcupsd.conf for each of the hosts that you run this container on, so it will need to be bind mounded for persistence purpoes. I recommend setting the threshold for shutting down hosts not directly connected to the UPS a little higher than the host connected to the UPS, so that the remote hosts are able to shut down before the UPS Connected host is no longer available to provide signalling.

Notes

• In case you're interested, I discovered that (at least my Smart UPS 3000) reports itself over USB as a usbhid device. I discovered this by running usb-devices at the linux command line on the physical host that is connected to the UPS by USB, which told me the device type. Looking in /dev/usb/ I only had two to choose from, so I was able to hit on the correct one pretty quickly. This does not seem to change dunamically at boot, though I've not checked yet to see if it changes if I plug the USB Cable into a different port.
• Testing was done by running the apcaccess on the physical host, and in the container, though you likely only need to run it in the container, after all, we don't want the APC UPS software installed in the host, that's the point of this image after all. If the test is successful, then the output from apcaccess is quite a bit different compared with a fail scenario. The difference should be self explanatory. This lets us know that the apcupsd daemon successfully connected to the UPS over the USB cable. If all is well, port 3551 should also be exposed to the network allowing other systems to take a heartbeat signal from the UPS via this container.
• You may wish to customise the apcupsd.conf file in /etc/apcupsd/ but i'm pretty sure that the default settings are fine for most implementations. The one exception may be the UPSNAME directive which you may wish to customise, but it doesnt appear to have a bearing on anything in my environment.
• This container has the capability to gracefully shut down the physical host if there is a prolonged power failure. This is done using a DBus system call to the underlying host, though it’s necessary to run the container in privileged mode, and explicitly expose /var/run/dbus/system_bus_socket from the host into the guest. You can test this by running /etc/apcupsd/apccontrol doshutdown within this container, which should power off the host gracefully. This has been tested with the limited hosts I have in my lab environment and works successfully on Ubuntu 16.04 and 18.04 hosts. Your mileage may vary. If you run into difficulties, the action that triggers the host to shut down is in the /etc/apcupsd/doshutdown file inside the container. This file contains commented out lines for restarting instead of shutting down, for use when testing. it also has lines for managing Consolekit environments, which I'm lead to believe from my research behave differently in some way, but I've no way of testing this, so I just included them for completeness. For persistence, you may want to put this file on the host and bind mount it to the container as you've probably also already done with /etc/apcupsd/apcupsd.conf.
• The apcupsd software operates a Network information Server model (NIS) for sharing information between hosts. The remote hosts (those not directly connected to the UPS) poll the apcupsd instance that is directly connected to the UPS regular intervals. All of this is customisable. For more information please see the apcupsd manual online here : APC UPS Daemon User Manual