Install apcupsd within a LXC Container

Introduction

This quick guide shows you how to set up the apcupsd daemon inside a LXC container, for APC uninterruptible power supplies which communicate over the APC PowerChute USB cable.

The LXC host and container are both running native Ubuntu 22.04 (meaning no Proxmox instance is present here).

Step 1: Get the device location

After connecting your UPS to the LXC host via USB, you have to find out under what device the UPS is listed. I recommend searching through dmesg for useful information:

dmesg | grep 'UPS'

[    4.004092] usb 1-1.2: Product: Back-UPS XS 1400U  FW:926.T2 .I USB FW:T2 
[    7.539578] hid-generic 0003:051D:0002.0001: hiddev0,hidraw0: USB HID v1.10 Device [American Power Conversion Back-UPS XS 1400U  FW:926.T2 .I USB FW:T2 ] on usb-0000:00:12.0-1.2/input0

As stated in line two, we should look out for devices named hiddev0 or hidraw0. These are referring to the devices /dev/usb/hiddev0 and /dev/hidraw0 respectively.

In your case it may really well possible that your device is named something like ttyUSB0, ttyACM0 or ttyS0 – even though these are not as common.

Step 2: Pass the device to the container

If no container exists already, I recommend you reading my guide on how to create a LXC container with a designated IP address on the LAN. If you don’t want a bridged IP address, a normal lxc launch ubuntu:22.04 <YOUR-CONTAINER-NAME> is also fine.

Continue to pass-through the USB device of the UPS we’ve got in the last step:

lxc stop <YOUR-CONTAINER-NAME>
lxc config device add <YOUR-CONTAINER-NAME> powerchute unix-char uid=0 gid=0 path=/dev/usb/hiddev0

Here I named the device powerchute, but this name is completely up to you. As the UPS communicates over serial, the device type is of unix-char owned by root:root (user-id 0 and group-id 0).

Step 3: Install apcupsd

Now change into the container and install apcupsd.

lxc exec <YOUR-CONTAINER-NAME> bash

Now inside the container:

apt-get update
apt-get upgrade
apt-get install apcupsd

Continue by editing the configuration file found under /etc/apcupsd/apcupsd.conf.

Make sure to adjust the DEVICE setting with the passed through USB device from before. Other settings such as BATTERYLEVEL or MINUTES can also be adjusted if you want to. The configuration file provides all the necessary documentation.

DEVICE /dev/usb/hiddev0
BATTERYLEVEL 10
MINUTES 10

Finally, enable the apcupsd service by editing the /etc/default/apcupsd file. Set the ISCONFIGURED option to yes.

ISCONFIGURED=yes

Restart the accompanying service:

systemctl restart apcupsd

Step 4 (Optional): Install the webinterface

Here we’ll be installing the apcupsd CGI logic and serving them out via the nginx web server.

Please keep in mind that your container has to be reachable from the outside world for this to work. This could be done via an own IP address as already mentioned before or via an internal reverse proxy.

Start off by installing all the required packages…

apt-get install nginx fcgiwrap apcupsd-cgi

…and setting up nginx afterwards with the file /etc/nginx/sites-available/apcupsd

server {
    listen 80 default_server;
    listen [::]:80 default_server;

    fastcgi_index multimon.cgi;
    root /usr/lib/cgi-bin/apcupsd/;

    location / {
        gzip off;
        try_files $uri $uri/ =404;

        fastcgi_pass unix:/var/run/fcgiwrap.socket;

        include /etc/nginx/fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}

Activate this configuration and restart nginx:

cd /etc/nginx/sites-enabled
rm -rf default
ln -s /etc/nginx/sites-available/apcupsd .

nginx -t
systemctl restart nginx

That’s it! You can now reach the webinterface directly under your container’s IP address.