Uninterruptible power supply (UPS)

Updated 13 November 2026

Introduction

If a UPS is connected to the computer, then when the power goes off the computer must shut down before the battery runs out, and start up on its own once power is restored. For this, the system must see the UPS, and a UPS monitor must be running on the computer: a program that watches the power supply and starts the shutdown in time.

In Calculate Linux this is done by two packages: sys-power/apcupsd for American Power Conversion (APC) devices, whose name is carried over into the package name, and sys-power/nut (Network UPS Tools) for UPSes of different manufacturers, including devices with network management cards.

The UPS model you plan to service through NUT is checked in advance against the list of supported hardware: an entry for the model means a suitable driver and set of parameters exist.

Installation

Install sys-power/apcupsd:

For UPSes of other manufacturers, install NUT:

USE flags enable support for the required connection method. The Calculate Linux profile enables usb, serial and snmp for sys-power/nut, so emerge -a sys-power/nut builds the USB, serial and SNMP drivers right away.

The remaining connection methods - modbus, ipmi, i2c, gpio - are added with an entry in /etc/portage/package.use/nut:

sys-power/nut ipmi modbus

The cgi flag installs web monitoring pages to /usr/share/nut/cgi, monitor installs the graphical NUT-Monitor program, which also requires python.

For apcupsd, flags set support for SNMP (snmp), MODBUS (modbus, enabled by default) and web monitoring pages (cgi).

UPS monitoring with apcupsd

Connect the UPS device to your computer with a USB cable.

For configuration, please run the following:

# If during a power failure, the remaining battery percentage
# (as reported by the UPS) is below or equal to BATTERYLEVEL, 
# apcupsd will initiate a system shutdown.
BATTERYLEVEL 10 

# If KILLDELAY is non-zero, apcupsd will continue running after a
# shutdown has been requested, and after the specified time in
# seconds attempt to kill the power. This is for use on systems
# where apcupsd cannot regain control after a shutdown.
# KILLDELAY <seconds>  0 disables
KILLDELAY 60

Parameter values:

• BATTERYLEVEL is the percentage of battery charge that triggers the computer shutdown.
• KILLDELAY is to be set in seconds. A specified time ( 60 sec. in the configuration above) after sending a shutdown signal, the UPS will turn off. You should set this parameter in order, first, to save some battery, and second, to make the computer start when the power supply is reestablished.

With this configuration, the UPS will initiate shutting down the computer connected via USB when the battery level is 10% .

The BATTERYLEVEL and MINUTES parameters operate together. It means that a shutdown signal will be sent by the computer when the battery charge reaches a level defined in these parameters.

Start the apcupsd service and add it to autostart.

To have the UPS cut the load after shutdown, add the power-off service to the shutdown runlevel:

When the system shuts down, it checks the /etc/apcupsd/powerfail flag and calls apcupsd --killpower: the UPS cuts the load, and restores it once external power is back. The KILLDELAY parameter gives the same result when apcupsd cannot regain control after a shutdown.

The current UPS status is shown by the command:

APC      : 001,043,1003
DATE     : 2018-04-28 17:07:30 +0300  
HOSTNAME : pc284
VERSION  : 3.14.14 (31 May 2016) gentoo
UPSNAME  : pc284
CABLE    : USB Cable
DRIVER   : USB UPS Driver
UPSMODE  : Stand Alone
STARTTIME: 2018-04-28 16:48:42 +0300  
MODEL    : Smart-UPS 750 
STATUS   : ONLINE 
LINEV    : 223.2 Volts
LOADPCT  : 9.1 Percent
BCHARGE  : 100.0 Percent
TIMELEFT : 106.0 Minutes
MBATTCHG : 0 Percent
MINTIMEL : 0 Minutes
MAXTIME  : 40 Seconds
OUTPUTV  : 223.2 Volts
SENSE    : High
DWAKE    : -1 Seconds
DSHUTD   : 90 Seconds
LOTRANS  : 208.0 Volts
HITRANS  : 253.0 Volts
RETPCT   : 0.0 Percent
ITEMP    : 34.6 C
ALARMDEL : 30 Seconds
BATTV    : 27.3 Volts
LINEFREQ : 50.0 Hz
LASTXFER : No transfers since turnon
NUMXFERS : 0
TONBATT  : 0 Seconds
CUMONBATT: 0 Seconds
XOFFBATT : N/A
SELFTEST : NO
STESTI   : 14 days
STATFLAG : 0x05000008
MANDATE  : 2007-07-20
SERIALNO : AS0729143376
BATTDATE : 2007-07-20
NOMOUTV  : 230 Volts
NOMBATTV : 24.0 Volts
FIRMWARE : 651.13.I USB FW:7.3
END APC  : 2018-04-28 17:07:34 +0300

Get the value of a single parameter with -p, dropping the units with -u:

Multiple machines through apcupsd

Several machines monitor a single UPS over the network. The computer connected to the UPS with a USB cable becomes the server: upon receiving a shutdown signal, it passes it on to the clients, and they shut down.

Apply the following parameters on the server:

# NISIP <dotted notation ip address>
#  IP address on which NIS server will listen for incoming connections.
#  This is useful if your server is multi-homed (has more than one
#  network interface and IP address). Default value is 0.0.0.0 which
#  means any incoming request will be serviced. Alternatively, you can
#  configure this setting to any specific IP address of your server and 
#  NIS will listen for connections only on that interface. Use the
#  loopback address (127.0.0.1) to accept connections only from the
#  local machine.
NISIP 192.168.0.1 

Specify the server IP in the NISIP option, In the example above, this would be 192.168.0.1.

Restart the apcupsd service for the changes to take effect:

Edit the configuration file on the client, as follows:

# UPSCABLE <cable>
#   Defines the type of cable connecting the UPS to your computer.
#
#   Possible generic choices for <cable> are:
#     simple, smart, ether, usb
#
#   Or a specific cable model number may be used:
#     940-0119A, 940-0127A, 940-0128A, 940-0020B,
#     940-0020C, 940-0023A, 940-0024B, 940-0024C,
#     940-1524C, 940-0024G, 940-0095A, 940-0095B,
#     940-0095C, M-04-02-2000
#
UPSCABLE ether

# To get apcupsd to work, in addition to defining the cable
# above, you must also define a UPSTYPE, which corresponds to
# the type of UPS you have (see the Description for more details).
# You must also specify a DEVICE, sometimes referred to as a port.
# For USB UPSes, please leave the DEVICE directive blank. For
# other UPS types, you must specify an appropriate port or address.
UPSTYPE net
DEVICE 192.168.0.1:3551

• To connect via Ethernet, specify ether in the UPSCABLE parameter.
• To connect to a network, specify net in the UPSTYPE parameter.
• In the DEVICE parameter, specify the IP address of the server with port 3551 : in the example above, 192.168.0.1: 3551 .

Start the apcupsd service and add it to autostart.

UPS connection methods in apcupsd

The way apcupsd communicates with the UPS is set by the UPSTYPE and DEVICE parameter pair in /etc/apcupsd/apcupsd.conf; for USB, leave DEVICE empty. Supported:

• apcsmart - the serial port of SmartUPS models with the smart protocol;
• usb - APC UPS over USB; an empty DEVICE enables autodetection;
• net - address and port (default 3551) of another apcupsd connected to the UPS;
• snmp - address, port 161, manufacturer (APC or APC_NOTRAP) and community (usually private) of a UPS with a network management card; the package is built with the snmp flag;
• dumb - serial port of a UPS with a simple signaling protocol;
• pcnet - management card address, credentials and port (default 3052) - the PowerChute Network Shutdown protocol for AP9617 family cards;
• modbus - serial port or USB of newer SmartUPS models; an empty DEVICE means MODBUS over USB, while specifying a serial number binds the driver to a particular device if there are several UPSes.

UPS monitoring with NUT

Connecting the UPS

The UPS is described in /etc/nut/ups.conf: section name, driver and port. The section name is part of the device address of the form name@host and is used in commands, so choose a short, meaningful name. For a USB device this is enough:

[office]
        driver = "usbhid-ups"
        port = "auto"
        desc = "Workstation"

If several UPSes are connected to the machine, tell the sections apart with the vendorid, productid, serial, bus or device parameters. To check that the system sees the device, use the NUT scanner:

Scanning USB bus.

The mode is set in /etc/nut/nut.conf: standalone - the machine watches the connected UPS itself, netserver - it serves data to other machines. The installed package has MODE=none, so change the value before the first launch.

Add all three services to autostart and start them: upsd does not bring up the drivers itself, and without a running driver it does not see the UPS.

You can check how the configuration is parsed without starting the drivers: in test mode, upsdrvctl prints the startup commands and stops:

Accounts and shutdown

The password that upsmon uses to access upsd is set in /etc/nut/upsd.users. The role of the machine is defined by the upsmon line: set primary on the machine connected to the UPS, which is the one that shuts down when the battery runs out; set secondary on machines that only receive data over the network. The lines actions = SET, actions = FSD and instcmds grant the right to change device settings and run its commands.

[monuser]
        password = "<password>"
        upsmon primary
        actions = SET
        actions = FSD
        instcmds = ALL

In /etc/nut/upsmon.conf you specify which UPS to watch and what to shut down: the MONITOR line is required; without it the service does not start. The second field is the number of power supplies fed by this UPS (1 for a desktop machine), and it must match MINSUPPLIES.

MONITOR office@localhost 1 monuser <password> primary
MINSUPPLIES 1
SHUTDOWNCMD "/sbin/shutdown -h +0"
POWERDOWNFLAG "/etc/killpower"

When the battery charge runs low, upsmon creates the POWERDOWNFLAG file and shuts the system down. To have the UPS cut the load afterwards, add the nut.powerfail service to the shutdown runlevel: on shutdown it finds /etc/killpower (or /etc/nut/killpower) and runs upsdrvctl shutdown.

As with apcupsd, the machine must be configured to power on automatically when power is restored, otherwise it will not come back up on its own after an outage.

The files under /etc/nut are installed world-readable, while passwords are stored in /etc/nut/upsd.users and /etc/nut/upsmon.conf, so restrict their permissions while keeping access for the nut user, under which the services run:

One UPS for several machines

On the machine with the UPS connected, set MODE=netserver and specify in /etc/nut/upsd.conf the addresses on which to listen on port 3493. The LISTEN lines replace the default address, so keep local access with an explicit line for 127.0.0.1:

LISTEN 127.0.0.1 3493
LISTEN 192.168.0.1 3493

In our example, the server address is 192.168.0.1.

On the client, configure only upsmon: on the server, create a user with upsmon secondary in /etc/nut/upsd.users, and in the client's /etc/nut/upsmon.conf, describe the UPS with the server address. Do not start the drivers or upsd on the client.

MONITOR office@192.168.0.1 1 clientuser <password> secondary

Status, parameters and control commands

upsc -l gives the list of monitored devices, upsc with a section name shows all the UPS parameters, and you get the value of a single parameter by passing it as the second argument:

battery.charge: 89
battery.runtime: 4316
battery.voltage: 14.1
input.voltage: 120.0
output.voltage: 120.0
ups.load: 8
ups.status: OL CHRG

The output is shortened: it shows the parameters that indicate the power supply and battery state. The ups.status value consists of space-separated tokens: OL - power from the mains, OB - running on batteries, LB - low battery, FSD - forced shutdown command; a working device normally shows a combination such as OL CHRG.

upsrw without parameters shows the parameters available for modification; write a value with -s, and add -w to wait for the driver response:

upscmd -l lists the commands that the device performs immediately on request; their execution requires the user to have instcmds rights:

The set of commands depends on the UPS model, so check the capabilities of your device in the upscmd -l output.

Checking the configuration without hardware

You can check how the machine reacts to a power failure even before the UPS is connected: the dummy-ups driver reproduces a device from a text description. Take a ready description from the NUT dump library - it contains snapshots of real UPS parameters:

[test]
        driver = "dummy-ups"
        port = "/var/lib/nut/test.dev"

The driver runs as the nut user, so put the description file somewhere that user can read, for example in /var/lib/nut, and restart the services:

The upsc output is the sign that the description has been read: UPS parameters are taken from the file, and among the driver variables you can see driver.name: dummy-ups; for devices where the description file does not set the model, ups.model stays equal to Dummy UPS.

battery.charge: 89
battery.runtime: 4316
driver.name: dummy-ups
ups.load: 8
ups.model: Dummy UPS
ups.status: OL CHRG

Check the shutdown scenario with the forced shutdown command: upsmon -c fsd sets the FSD flag, and the machines that monitor this UPS shut down in the usual way. To keep the check from shutting the machine down, temporarily replace the standard shutdown command with a logger:

SHUTDOWNCMD "/usr/bin/logger NUT: shutdown scenario executed"

After such a check the FSD flag stays in upsd until the service is restarted, and the service itself does not remove the POWERDOWNFLAG flag file: when you are finished, restart upsd and make sure the flag file is gone.

Battery status and scheduled tests

The remaining charge is shown by the BCHARGE field in the apcaccess output and by the battery.charge parameter in NUT, while TIMELEFT and battery.runtime show the available runtime. The BATTDATE field stores the date the batteries were installed: the service life is counted from it to schedule their replacement.

apcupsd tests the battery on its own: the self-test interval is set by the SELFTEST parameter in hours (336 - two weeks, 168 - one week, ON - on startup, OFF - disabled), and the latest result is shown in the SELFTEST field of the apcaccess status output.

For a controlled load test, use apctest: run it without parameters, and it performs low-level tests of a UPS with a simple signaling protocol, reads and programs EEPROM values, and calibrates the battery runtime under the APC smart protocol. It cannot run at the same time as apcupsd, so stop the service before running it:

In NUT the discharge thresholds are set by the battery.charge.low and battery.runtime.low parameters; upsrw shows their current values and descriptions, and upscmd -l lists the available battery tests.

Responding to events

apcupsd handles a UPS state change through /etc/apcupsd/apccontrol: it receives the event name and the UPS name as arguments and performs the standard action - for example, it prints a message to all logged-in users with wall. The full list of events is visible in the case statement of this script: killpower, commfailure, commok, powerout, onbattery, offbattery, mainsback, failing, timeout, loadlimit, runlimit, doreboot, doshutdown, annoyme, emergency, changeme, remotedown, startselftest, endselftest, battdetach, battattach.

Add your own action as a file in the same /etc/apcupsd: apccontrol runs an executable file named after the event before the standard handling. If the standard handling is not needed, the script exits with code 99:

#!/bin/sh
logger "UPS $2 switched to battery"
exit 99

apccontrol takes the common event-handling variables (for example WALL and SYSADMIN) from the /etc/apcupsd/config file, if it exists.

In NUT, upsmon reports a state change: for the events ONLINE, ONBATT, LOWBATT, FSD, COMMOK, COMMBAD, SHUTDOWN, REPLBATT and NOCOMM, the behavior is defined by NOTIFYFLAG lines, where a combination of the SYSLOG, WALL and EXEC flags means writing to the log, messaging all logged-in users, and running NOTIFYCMD:

NOTIFYFLAG ONBATT SYSLOG+WALL+EXEC
NOTIFYCMD /usr/sbin/upssched

For delayed reactions - for example, shutting down a secondary machine only after a prolonged power outage - use upssched: specify it in NOTIFYCMD and describe the timers in /etc/nut/upssched.conf, where CMDSCRIPT sets the program that receives the events.

Additional materials

• NUT supported hardware list - which UPS models are supported and by which driver.
• NUT device dump library - snapshots of real UPS parameters, suitable as a description for dummy-ups.
• apcupsd manual - the purpose of every apcupsd.conf parameter and the shutdown sequence.