OpenBSD: Managing an inverter/converter with NUT

Article published the18 July 2021 ; modified the9 February 2024
9 minutes to read

This article has 1782 words.
RAW source of the article:
Commit version: 395ac55

Description

Having an Eaton Ellipse ECO UPS, I use the NUT project to manage it under OpenBSD.

⇒ OS:

OpenBSD: 6.9 ⇒ 7.6

⇒ UPS Hardware: Eaton Ellipse ECO 650 VA USB FR, MGE ELLIPSE 1000

Installation

Like as : # pkg_add nut

Configuration

The nut-scanner tool allow to detect any UPS hardware connected, either by USB, or network.

With administrator rights:

Example for Eaton Ellipse ECO 650 VA USB FR :

$ doas nut-scanner
SNMP library not found. SNMP search disabled.
Neon library not found. XML search disabled.
AVAHI client library not found. AVAHI search disabled.
Scanning USB bus.
No start IP, skipping NUT bus (old connect method)
[nutdev1]
    driver = "usbhid-ups"
    port = "auto"
    vendorid = "0463"
    productid = "FFFF"
    product = "Ellipse ECO"
    serial = "000000000"
    vendor = "EATON"
    bus = "005"

Example for MGE ELLIPSE 1000 :

Cannot load SNMP library (libnetsnmp.so) : file not found. SNMP search disabled.
Cannot load XML library (libneon.so) : file not found. XML search disabled.
Scanning USB bus.
No start IP, skipping NUT bus (old connect method)
Scanning NUT bus (avahi method).
[nutdev1]
    driver = "usbhid-ups"
    port = "auto"
    vendorid = "0463"
    productid = "FFFF"
    product = "ELLIPSE"
    serial = "1H6G4401F"
    vendor = "MGE UPS SYSTEMS"
    bus = "001"
    device = "002"
    busport = "002"
    ###NOTMATCHED-YET###bcdDevice = "4241"

Now, few configuration files are to be modified. Any change on one of them needs to restart the ad hoc services.

ups.conf

Configuration file: /etc/nut/ups.conf

You have to fill this file with the returned informations by the software:

Example for Eaton Ellipse ECO 650 VA USB FR :

(…)

[eaton]
    desc = "Eaton Ellipse ECO 650 VA USB FR"
    driver = "usbhid-ups"
    port = "auto"
    vendorid = "0463"
    productid = "FFFF"
    product = "Ellipse ECO"
    serial = "000000000"
    vendor = "EATON"
    bus = "005"

upsd.conf

Configuration file: /etc/nut/upsd.conf

This file allow to set the access control to the managed datas by upds. By default, the server is only accessible on localhost, in IPv4, IPv6, on port 3493.

As instance, you need to set this file to use TLS.

Info

Since v2.4.0, the ACL and allowfrom directives have been replaced by the LISTEN directive and tcp-wrappers! (cf la note de changements…)

Do not use thoses oldiers ACL directives; many old tutorials refer to it :( Take it into account!

Warning

If the LISTEN directive is configured to allow access on IPv4, IPv6 adress, you have to manage PF to allow the connexion on the adequat port…

upsd.users

Configuration file: /etc/nut/upsd.users

This configuration file allow to set users who will have rights to interact with the upsd server.

Warning

It is IMPERATIVE that this file has the most minimalist system rights! By default, on OpenBSD, only the dedicate user had read and write access.

$ doas chmod 0400 /etc/nut/upsd.users

Now, set an user who will have the rights to comminucate between upsd and upmon servers:

[upsmon]
    password = ***
    upsmon master

More explains, here we are:

an upsmon username into the brackets
with master rights on upsmon service.
- (this defines the role which, according to its dominance, will stop the system first or last, in the case of management of several connected OS; in the context of a single managed OS, the value master is imposed by itself).
and, set the password value, by your choice.

Now, we modify the upsmon.conf file.

upsmon.conf

Configuration file: /etc/nut/upsmon.conf

This configuration file allow the monitor service.

Warning

Warning: this file contains sensitive information, it is therefore imperative to check the permissions and user rights.

Following the modification of the upsd.users file to configure a upsmon user, we need to add a MONITOR directive, such as:

MONITOR eaton@localhost 1 upsmon *** master

(Change ‘***’ by your upsmon password)

⇒ Now, at least, we need to modify NOTIFYMSG, NOTIFYFLAG directives; please, see the official documentation…

⇒ About the NOTIFYFLAG directives, it is important to add the EXEC flag for the execution of commands. Without it, they will not be executed.

⇒ About the NOTIFYCMD directive: this is not set up correctly:

first, uncomment it, and
change the path to the upssched binary, like: NOTIFYCMD /usr/local/sbin/upssched

Now, the upsmon service will relay to upsched binary; this tool will read the upssched.conf configuration file. See the Suppressing notify storms official documentation about why it’s needed!

upssched.conf

Configuration file: /etc/nut/upssched.conf

This configuration file allow actions to plan.

It’s necessary to uncomment PIPEFN, LOCKFN, and AT directives.

⇒ About LOCKFN and PIPEFN: the absolute pathname by default not exists; you need to create and give access for the _ups user:

# install -d -o _ups -g wheel -m 750 /var/db/nut/upssched

⇒ Now, we create the needed AT directives; as instance:

(…)
AT ONBATT * START-TIMER onbatt 15
AT ONBATT * START-TIMER onbattwarn 30
(…)
AT ONLINE * CANCEL-TIMER onbatt
AT ONLINE * CANCEL-TIMER onbattwarn
(…)
AT ONLINE * EXECUTE ups-back-on-line

FYI: it’s possible to modify the /usr/local/bin/upssched-cmd script to interact with the system according to the called event. See the official documentation…

upsset.conf

Configuration file: /etc/nut/upsset.conf

This file allow to use CGI scripts, builded on the nut-cgi package. One only role: to certify that the configuration to use the CGI scripts is indeed (supposedly?) secure.

It is only useful in this context.

Permissions

Info

At each OpenBSD release migration, it will be necessary to change the permissions again, as they are permissions again, as they are reset.

During the installation, here are configured:

an _ups user
and an _ups group

It is necessary to configure user permissions in order to have access to the appropriate device node.

⇒ For the USB devices, you need to identify the USB controller to which the UPS device is connected, or even the ugen device node(s).

We use the usbdevs command, like as:

$ doas usbdevs
(…)
Controller /dev/usb5:
addr 01: 1002:0000 ATI, OHCI root hub
addr 02: 0463:ffff EATON, Ellipse ECO
(…)

In this cas, the UPS device is connected on the usb5 controller, without specified device nodes.

Now, we change the rights user on the device; on this case:

$ doas chown :_ups /dev/usb5 # ou, chgrp _ups /dev/usb5
$ doas chmod g+w /dev/usb5

Now, the _ups group gained access to the controller!

Finally, let’s make sure we have user rights on the files into ‘/etc/nut’:

$ doas chown _ups:_ups /etc/nut/ups*

Normally, this enough to start the services.

Warning

Few USB APC-like inverters have problems; see the pkg-readme file!

⇒ if the inverter is connected by RS232, either you need to:

add the _ups user to the dialer group, or
modify the user rights on the /dev/tty adequat, that the _ups user can manage it.

Services

About services, you have to enable and start those follow daemons:

upsd: to manage network server
upsmon: to manage the monitor

upsd need to start in first, before upsmon.

$ doas rcctl enable upsd upsmon
$ doas rcctl set upsd flags -u _ups
$ doas rcctl start upsd upsmon

Normally, the daemon log notify thoses services:

(…)
Jul 17 13:25:34 sh1 usbhid-ups[47317]: Startup successful
Jul 17 13:25:34 sh1 upsd[83153]: listening on ::1 port 3493
Jul 17 13:25:34 sh1 upsd[83153]: listening on 127.0.0.1 port 3493
Jul 17 13:25:34 sh1 upsd[83153]: Connected to UPS [eaton]: usbhid-ups-eaton
Jul 17 13:25:34 sh1 upsd[90348]: Startup successful
Jul 17 13:25:34 sh1 upsmon[19005]: Startup successful
(…)

Check

Status

upsc is a tool to check the inverter status, like: $ upsc eaton est la même chose que faire $ upsc eaton@localhost

⇒ To known the battery status:

$ upsc eaton ups.status
OL

Few explains:

OL signify On Line; all is good!
OB: On Battery: the inverter now only works on the battery
LB: Low Battery: the battery is at its lowest charge level!

OB and LB must trigger actions; they are configured on upsmon.conf file, or even upssched.conf.

Process and files

You can check what are the process managed by the _ups user, and the opened files; as instance, with ps and fstat:

$ ps aux -U _ups
USER       PID %CPU %MEM   VSZ   RSS TT  STAT   STARTED       TIME COMMAND
_ups     31655  0.0  0.0   836  1668 ??  S       5:07PM    0:00.70 /usr/local/bin/usbhid-ups -a eaton
_ups      4840  0.0  0.0   764  1308 ??  S       5:07PM    0:00.12 /usr/local/sbin/upsd -u _ups
_ups     65469  0.0  0.0   780  3084 ??  S       5:07PM    0:00.09 /usr/local/sbin/upsmon

$ fstat -u _ups -n
USER     CMD          PID   FD  DEV      INUM        MODE   R/W    SZ|DV
_ups     upsmon     65469   wd  4,0    103712        40700    r      512
_ups     upsmon     65469    0  4,0     27162        20666   rw    2,2
_ups     upsmon     65469    1  4,0     27162        20666   rw    2,2
_ups     upsmon     65469    2  4,0     27162        20666   rw    2,2
_ups     upsmon     65469    3* internet stream tcp 0x0 127.0.0.1:26706 --> 127.0.0.1:3493
_ups     upsmon     65469    4 pipe 0x0 state:
_ups     upsd        4840   wd  4,4     26111        40700    r      512
_ups     upsd        4840    0  4,0     27162        20666   rw    2,2
_ups     upsd        4840    1  4,0     27162        20666   rw    2,2
_ups     upsd        4840    2  4,0     27162        20666   rw    2,2
_ups     upsd        4840    3* internet6 stream tcp 0x0 [::1]:3493
_ups     upsd        4840    4* internet stream tcp 0x0 127.0.0.1:3493
_ups     upsd        4840    5* unix stream 0x0
_ups     upsd        4840    6* internet stream tcp 0x0 127.0.0.1:3493 <-- 127.0.0.1:26706
_ups     usbhid-ups 31655   wd  4,4     26111        40700    r      512
_ups     usbhid-ups 31655    0  4,0     27162        20666   rw    2,2
_ups     usbhid-ups 31655    1  4,0     27162        20666   rw    2,2
_ups     usbhid-ups 31655    2  4,0     27162        20666   rw    2,2
_ups     usbhid-ups 31655    3 pipe 0x0 state:
_ups     usbhid-ups 31655    4 pipe 0x0 state:
_ups     usbhid-ups 31655    5* unix stream 0x0 /var/db/nut/usbhid-ups-eaton
_ups     usbhid-ups 31655    6* unix stream 0x0 /var/db/nut/usbhid-ups-eaton

We notice:

upsd and upsmon run correctly, well managed by _ups user
- streams TCP are correctly created, and used on localhost
the eaton profil is correctly managed by usbhid-ups!

Troubleshooting

Connection refused

Here, an example about errors messages:

(…)
upsd[55984]: Can't connect to UPS [eaton] (usbhid-ups-eaton): Connection refused
upsmon[20574]: Poll UPS [eaton@localhost] failed - Driver not connected
upsmon[20574]: Communications with UPS eaton@localhost lost
(…)
upsmon[44238]: UPS eaton@localhost is unavailable
upsmon[44238]: UPS [eaton@localhost]: connect failed: Connection failure: Connection refused
(…)

At least, two possibles reasons:

check the physical USB connection. May be, it’s usefull to change the USB cable, or disconnect to reconnect it. Even, the USB ports on the motherboard or your USB hub can be defective/faulty.
after a OpenBSD upgrade: it’s necessary to redo the needed permissions !

upsmon[39287]: Login on UPS [eaton@localhost] failed - got [ERR ACCESS-DENIED]

Check your managed user between upsd.users and upsmon.conf files.

Permission denied

upsd[87303]: Can't open /etc/nut/upsd.conf: Permission denied

Check the user rights on this file; it must belong to the _ups user.

nut-cgi

nut-cgi provides CGI scripts to monitor the inverter through the web service.

Actually, this officially works only with the Apache server, and requires writing a configuration file hosts.conf, not created by default.

Documentations

Projet NUT : https://networkupstools.org/
pkg-readme : /usr/local/share/doc/pkg-readmes/nut

Description

Installation

Configuration

ups.conf

upsd.conf

upsd.users

upsmon.conf

upssched.conf

upsset.conf

Permissions

Services

Check

Status

Process and files

Troubleshooting

Connection refused

Login failed

Permission denied

nut-cgi

Documentations