NUT

From Gentoo Wiki
Jump to:navigation Jump to:search

NUT provides control and monitoring features for uninterruptible power supplies, power distribution units, automatic transfer switches, and solar controllers.

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

To connect a UPS via USB, make sure to set the usb USE flag:

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

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.
man Build and install man pages
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.
split-usr Enable behavior to support maintaining /bin, /lib*, /sbin and /usr/sbin separately from /usr/bin and /usr/lib*
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)
ups_drivers_al175 Driver for Eltek UPS models with AL175 alarm module
ups_drivers_apcsmart Driver for American Power Conversion Smart Protocol UPS equipment
ups_drivers_apcsmart-old Driver for American Power Conversion Smart Protocol UPS equipment
ups_drivers_apcupsd-ups Driver for apcupsd client access
ups_drivers_bcmxcp Driver for UPSes supporting the serial BCM/XCP protocol
ups_drivers_bcmxcp_usb Experimental driver for UPSes supporting the BCM/XCP protocol over USB
ups_drivers_belkin Driver for Belkin serial UPS equipment
ups_drivers_belkinunv Driver for Belkin "Universal UPS" and compatible
ups_drivers_bestfcom Driver for Best Power Fortress/Ferrups
ups_drivers_bestfortress Driver for old Best Fortress UPS equipment
ups_drivers_bestuferrups Driver for Best Power Micro-Ferrups
ups_drivers_bestups Driver for Best Power / SOLA (Phoenixtec protocol) UPS equipment
ups_drivers_blazer_ser Driver for Megatec/Q1 protocol serial based UPS equipment
ups_drivers_blazer_usb Driver for Megatec/Q1 protocol USB based UPS equipment
ups_drivers_clone Fake driver to clone outlets for device grouping
ups_drivers_clone-outlet Fake driver to clone outlets for device grouping
ups_drivers_dummy-ups Driver for multi-purpose UPS emulation
ups_drivers_etapro Driver for ETA UPS equipment
ups_drivers_everups Driver for Ever UPS models
ups_drivers_gamatronic Driver for Gamatronic UPS equipment
ups_drivers_genericups Driver for contact-closure UPS equipment
ups_drivers_isbmex Driver for ISBMEX UPS equipment
ups_drivers_ivtscd driver for the IVT Solar Controller Device
ups_drivers_liebert Driver for Liebert contact-closure UPS equipment
ups_drivers_liebert-esp2 Driver for Liebert UPS, using the ESP-II serial protocol
ups_drivers_masterguard Driver for Masterguard UPS equipment
ups_drivers_metasys Driver for Meta System UPS equipment
ups_drivers_mge-shut Driver for SHUT Protocol UPS equipment
ups_drivers_mge-utalk Driver for MGE UPS SYSTEMS UTalk protocol equipment
ups_drivers_microdowell Driver for Microdowell Enterprise UPS series
ups_drivers_netxml-ups Driver for Eaton / MGE Network Management Card / Proxy (XML/HTTP Protocol) equipment
ups_drivers_nut-ipmipsu Driver for IPMI Power Supply Units (PSU)
ups_drivers_nutdrv_qx Driver for Q* protocol serial and USB based UPS equipment
ups_drivers_oldmge-shut Driver for SHUT Protocol UPS equipment (older implementation)
ups_drivers_oneac Driver for Oneac UPS equipment
ups_drivers_optiups Driver for Opti-UPS (Viewsonic) UPS and Zinto D (ONLINE-USV) equipment
ups_drivers_powercom UPS driver for serial Powercom/Trust/Advice UPS equipment
ups_drivers_powerpanel Driver for PowerPanel Plus compatible UPS equipment
ups_drivers_rhino Driver for Brazilian Microsol RHINO UPS equipment
ups_drivers_richcomm_usb Driver UPS equipment using Richcomm dry-contact to USB solution
ups_drivers_riello_ser Driver for Riello UPS Protocol UPS equipment
ups_drivers_riello_usb Driver for Riello UPS Protocol UPS equipment via USB
ups_drivers_safenet Driver for SafeNet compatible UPS equipment
ups_drivers_snmp-ups Multi-MIB Driver for SNMP UPS equipment
ups_drivers_solis Driver for Brazilian Microsol SOLIS UPS equipment
ups_drivers_tripplite Driver for Tripp-Lite SmartPro UPS equipment
ups_drivers_tripplite_usb Driver for older Tripp Lite USB UPSes (not PDC HID)
ups_drivers_tripplitesu Driver for Tripp-Lite SmartOnline (SU) UPS equipment
ups_drivers_upscode2 Driver for UPScode II compatible UPS equipment
ups_drivers_usbhid-ups Driver for USB/HID UPS equipment
ups_drivers_victronups Driver for IMV/Victron UPS unit Match, Match Lite, NetUps
usb Includes all UPS drivers that use USB.
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: 2024-02-06 06:53 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 the machine is connected to the UPS directly and 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

The main UPS configuration file. Make sure that the UPS name (the text in the brackets) doesn't have any spaces. For configuration specific to the 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

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 the UPS.

root #nano -w /etc/nut/upsd.users
FILE /etc/nut/upsd.usersExample upsd.users configuration
[monmaster]
    password = masterpassword
    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 masterpassword 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+EXEC
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

Configure operations on that upsmon will check on the status of the 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

To check the status of the UPS manually (adjust the UPS name as needed):

root #upsc APCSMC1500@127.0.0.1 ups.status
OL

OL means that the UPS is "online" and not drawing from the battery and is configured correctly.

In the event of a shutdown due to a power failure, nut can additionally turn off the UPS by adding nut.powerfail to the 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 = masterpassword
    upsmon master

[monslave]
    password = slavepassword
    upsmon slave

Client configuration

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.

/etc/nut/upsd.conf

This file is not needed for slave monitor.

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

Copy the standalone configuration, but create a different 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 slavepassword 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, only the upsmon service is needed. 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

To check the status of the UPS manually (adjust the UPS name as needed):

root #upsc APCSMC1500@192.168.1.1 ups.status
OL

External resources

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