This is Gentoo's testing wiki. It is a non-operational environment and its textual content is outdated.

Please visit our production wiki at https://wiki.gentoo.org

NUT

From Gentoo Wiki (test)
Jump to:navigation Jump to:search

Do you have a UPS? Do you want to have you system gracefully shutdown in case of a power outage? This guide will show how you can make the most out of your UPS by using NUT from the Network UPS Tools project

Installation

USE flag

If you are connecting your UPS via USB, make sure to set the usb USE flag:

USE flags for sys-power/nut Network-UPS Tools

+man Build and install man pages
+usb Includes all UPS drivers that use USB.
cgi Add CGI script support
doc Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally
gpio Includes all UPS drivers that use GPIO.
i2c Includes all UPS drivers that use I2C.
ipmi Includes all UPS drivers that use ipmi.
modbus Includes all UPS drivers that use MODBUS.
monitor Add a QT5 gui monitor.
python Add optional support/bindings for the Python language
selinux  !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
serial Includes all UPS drivers that use SERIAL.
snmp Includes all UPS drivers that use SNMP.
ssl Add support for SSL/TLS connections (Secure Socket Layer / Transport Layer Security)
systemd Enable use of systemd-specific libraries and features like socket activation or session tracking
tcpd Add support for TCP wrappers
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
xml Includes all UPS drivers that use XML.
zeroconf Support for DNS Service Discovery (DNS-SD)
Data provided by the Gentoo Package Database · Last update: 2025-05-17 14:12 More information about USE flags

Emerge

root #emerge --ask sys-power/nut

Configuration standalone

Search a UPS with nut-scanner:

root #/usr/bin/nut-scanner
Scanning USB bus.
Scanning XML/HTTP bus.
No start IP, skipping NUT bus (old connect method)
[nutdev1]
        driver = "usbhid-ups"
        port = "auto"
        vendorid = "051D"
        productid = "0002"
        product = "Back-UPS SMC 1500 FW:879.L4 .I USB FW:L4"
        serial = "***"
        vendor = "American Power Conversion"
        bus = "003"

Take note of driver name and port type for configuration file.

If UPS is connected via USB port, add user nut to group usb.

root #usermod -a -G usb nut

Files

/etc/nut/nut.conf

Set mode to standalone if your machine is connected to the UPS directly and you want to run NUT on this machine.

root #nano -w /etc/nut/nut.conf
FILE /etc/nut/nut.confDesired settings
MODE=standalone

/etc/nut/ups.conf

This is where you set up your UPS configuration. Make sure that your UPS name (the text in the brackets) doesn't have any spaces. For configuration specific to your UPS you need to look it up here: NUT Hardware Compatibility Lookup

root #nano -w /etc/nut/ups.conf
FILE /etc/nut/ups.confExample ups.conf configuration
[APCSMC1500]
    driver = usbhid-ups
    port = auto
    desc = "APC SMC1500 UPS"
# Change some variables in UPS hardware. Not all devices or drivers
# implement this, so this may not have effect on your system.
    override.battery.charge.low = 30
    override.battery.runtime.low = 180

/etc/nut/upsd.users

You need to configure at least one user so that upsmon can be launched later. upsd will create a TCP connection that upsmon will use to check on the status of your UPS.

root #nano -w /etc/nut/upsd.users
FILE /etc/nut/upsd.usersExample upsd.users configuration
[monmaster]
    password = mypassword
    upsmon master

/etc/nut/upsmon.conf

Create a MONITOR configuration in /etc/nut/upsmon.conf:

root #nano -w /etc/nut/upsmon.conf
FILE /etc/nut/upsmon.confExample upsmon configuration
MONITOR APCSMC1500@127.0.0.1 1 monmaster mypassword master

# If you want that NUT can shutdown the computer, you need root privileges:
RUN_AS_USER root

MINSUPPLIES 1
SHUTDOWNCMD "/sbin/shutdown -h +0"
NOTIFYCMD /usr/sbin/upssched
POLLFREQ 5
POLLFREQALERT 1
HOSTSYNC 15
DEADTIME 15
POWERDOWNFLAG /etc/killpower

NOTIFYMSG ONLINE	"UPS %s on line power"
NOTIFYMSG ONBATT	"UPS %s on battery"
NOTIFYMSG LOWBATT	"UPS %s battery is low"
NOTIFYMSG FSD		"UPS %s: forced shutdown in progress"
NOTIFYMSG COMMOK	"Communications with UPS %s established"
NOTIFYMSG COMMBAD	"Communications with UPS %s lost"
NOTIFYMSG SHUTDOWN	"Auto logout and shutdown proceeding"
NOTIFYMSG REPLBATT	"UPS %s battery needs to be replaced"
NOTIFYMSG NOCOMM	"UPS %s is unavailable"
NOTIFYMSG NOPARENT	"upsmon parent process died - shutdown impossible"

NOTIFYFLAG ONLINE	SYSLOG+WALL+EXEC
NOTIFYFLAG ONBATT	SYSLOG+WALL+EXEC
NOTIFYFLAG LOWBATT	SYSLOG+WALL
NOTIFYFLAG FSD		SYSLOG+WALL+EXEC
NOTIFYFLAG COMMOK	SYSLOG+WALL+EXEC
NOTIFYFLAG COMMBAD	SYSLOG+WALL+EXEC
NOTIFYFLAG SHUTDOWN	SYSLOG+WALL+EXEC
NOTIFYFLAG REPLBATT	SYSLOG+WALL+EXEC
NOTIFYFLAG NOCOMM	SYSLOG+WALL+EXEC
NOTIFYFLAG NOPARENT	SYSLOG+WALL

RBWARNTIME 43200

NOCOMMWARNTIME 600

FINALDELAY 5

/etc/nut/upssched.conf

You need to configure operations on that upsmon will check on the status of your UPS.

root #nano -w /etc/nut/upssched.conf
FILE /etc/nut/upssched.confExample upssched.conf configuration
CMDSCRIPT /usr/bin/upssched-cmd
PIPEFN /var/lib/nut/upssched/upssched.pipe
LOCKFN /var/lib/nut/upssched/upssched.lock

AT ONBATT * START-TIMER onbatt 300
AT ONLINE * CANCEL-TIMER onbatt online
AT LOWBATT * EXECUTE onbatt
AT COMMBAD * START-TIMER commbad 30
AT COMMOK * CANCEL-TIMER commbad commok
AT NOCOMM * EXECUTE commbad
AT SHUTDOWN * EXECUTE powerdown
AT REPLBATT * EXECUTE replacebatt
root #mkdir -p /var/lib/nut/upssched
root #chown nut:nut /var/lib/nut/upssched

/usr/bin/upssched-cmd

root #nano -w /usr/bin/upssched-cmd
FILE /usr/bin/upssched-cmdExample upssched.conf configuration
#! /bin/sh
#
# This script should be called by upssched via the CMDSCRIPT directive.
#
# Here is a quick example to show how to handle a bunch of possible
# timer names with the help of the case structure.
#
# This script may be replaced with another program without harm.
#
# The first argument passed to your CMDSCRIPT is the name of the timer
# from your AT lines.

case $1 in
        onbatt)
                logger -t upssched-cmd "The UPS is on battery"
                mail -s "The UPS is on battery" admin@example.com
                # For example, uncommenting, you can stop some power-hog services
                #rc-service boinc stop
                #rc-service xmr-stak stop
                ;;
        online)
                logger -t upssched-cmd "The UPS is back on power"
                mail -s "The UPS is back on power" admin@example.com
                # For example, uncommenting, you can restart useful power-hog services
                #rc-service boinc start
                #rc-service xmr-stak start
                ;;
        commbad)
                logger -t upssched-cmd "The server lost communication with UPS"
                mail -s "The server lost communication with UPS" admin@example.com
                ;;
        commok)
                logger -t upssched-cmd "The server re-establish communication with UPS"
                mail -s "The server re-establish communication with UPS" admin@example.com
                ;;
        powerdown)
                logger -t upssched-cmd "The UPS is shutting down the system"
                mail -s "The UPS is shutting down the system" admin@example.com
                ;;
        replacebatt)
                logger -t upssched-cmd "The UPS needs new battery"
                mail -s "The UPS needs new battery" admin@example.com
                ;;
        *)
                logger -t upssched-cmd "Unrecognized command: $1"
                ;;
esac

Services

OpenRC

To add the services to start on system boot:

root #rc-update add upsdrv default
root #rc-update add upsd default
root #rc-update add upsmon default

To start upsd now run:

root #rc-service upsdrv start
root #rc-service upsd start
root #rc-service upsmon start

Check the status of your ups manually. Note that you might have to adjust your UPS name for this work.

root #upsc APCSMC1500@127.0.0.1 ups.status
OL

OL means that your UPS is "online" and not drawing from the battery. It also means that you configured the above files correctly.

If you want nut to power off your UPS when it shuts down your system in a power failure, you must add nut.powerfail to your shutdown runlevel:

root #rc-update add nut.powerfail shutdown

LAN client/server configuration

Server configuration

Starting from standalone configuration, change:

Server files

/etc/nut/nut.conf
root #nano -w /etc/nut/nut.conf
FILE /etc/nut/nut.confDesired settings
MODE=netserver
/etc/nut/upsd.conf
root #nano -w /etc/nut/upsd.conf
FILE /etc/nut/upsd.confDesired settings
LISTEN 127.0.0.1 3493
LISTEN 192.168.1.1 3493
/etc/nut/upsd.users
root #nano -w /etc/nut/upsd.users
FILE /etc/nut/upsd.usersExample upsd.users configuration
[monmaster]
    password = mypassword
    upsmon master

[monslave]
    password = mypassword
    upsmon slave

Client files

/etc/nut/nut.conf
root #nano -w /etc/nut/nut.conf
FILE /etc/nut/nut.confDesired settings
MODE=netclient
/etc/nut/ups.conf

This file is not needed for slave monitor, so you can leave blank or full of comments.

/etc/nut/upsd.conf

This file is not needed for slave monitor, so you can leave blank or full of comments.

/etc/nut/upsd.users
root #nano -w /etc/nut/upsd.users
FILE /etc/nut/upsd.usersExample upsd.users configuration
[monslave]
    password = mypassword
    upsmon slave
/etc/nut/upsmon.conf

Create a MONITOR configuration in /etc/nut/upsmon.conf:

root #nano -w /etc/nut/upsmon.conf
FILE /etc/nut/upsmon.confExample upsmon configuration
MONITOR APCSMC1500@192.168.1.1 1 monslave mypassword slave
/etc/nut/upssched.conf

This file can be the same of standalone configuration.

/usr/bin/upssched-cmd

This file can be the same of standalone configuration.

Client services

On client machine, you need only upsmon service. To add the services to start on system boot:

root #rc-update add upsmon default

To start upsd now run:

root #rc-service upsmon start

Check the status of your ups manually. Note that you might have to adjust your UPS name for this work.

root #upsc APCSMC1500@192.168.1.1 ups.status
OL

External resources

Retrieved from "https://wikitest.gentoo.org/index.php?title=NUT&oldid=745126"