---
categories: ['OpenBSD','System','sysutils']
date: 2021-07-18T15:34:24+02:00
description: "Managing an inverter with the NUT project on OpenBSD"
draft: false
tags: ["OpenBSD","NUT","UPS"]
title: "OpenBSD: Managing an inverter/converter with NUT"
translationKey: 'openbsd-nut'
---

## Description

Having an Eaton Ellipse ECO UPS, I use the <abbr title="Network UPS Tools">NUT</abbr> 
project to manage it under OpenBSD.

⇒ OS: 

* OpenBSD: <del>6.9</del> ⇒ 7.4

⇒ UPS Hardware: **Eaton Ellipse ECO 650 VA USB FR**

## 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:
```sh
$ 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"
```

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:
```cfg
(…)

[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.

{{< note info >}}
Since v2.4.0, the **ACL** and **allowfrom** directives have been replaced
by the **LISTEN** directive and tcp-wrappers!<br>
*(cf la [note de changements](https://networkupstools.org/docs/user-manual.chunked/apis12.html)…)*

Do not use thoses oldiers ACL directives; many old tutorials refer to it :( <br>
Take it into account!
{{</note>}}

{{< note 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…
{{</note>}}

### 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. 

{{< note warning >}}
It is IMPERATIVE that this file has the most minimalist system rights!<br>
*By default, on OpenBSD, only the dedicate user had read and write access.*

```sh
$ doas chmod 0400 /etc/nut/upsd.users
```
{{</note>}} 

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

```cfg
[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.

{{< note warning >}}
Warning: this file contains sensitive information, it is therefore 
imperative to check the permissions and user rights.
{{</note>}}

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

```cfg
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: <br>
`NOTIFYCMD /usr/local/sbin/upssched`

Now, the **upsmon** service will relay to **upsched** binary; this tool 
will read the **upssched.conf** configuration file. <br>
*See the **[Suppressing notify storms](https://networkupstools.org/docs/user-manual.chunked/ar01s07.html)** 
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:
```sh
# mkdir -p /var/db/nut/upssched
# chown _ups /var/db/nut/upssched
```

⇒ Now, we create the needed **AT** directives; as instance:
```cfg
(…)
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

{{< note info >}}
At each OpenBSD release migration, it will be necessary to change the 
permissions again, as they are permissions again, as they are reset. 
{{</note>}}

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:
```sh
$ 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:

```sh
$ 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': 
```sh
$ doas chown _ups:_ups /etc/nut/ups*
```

Normally, this enough to start the services.

---

{{< note warning >}}
Few USB APC-like inverters have problems; see the pkg-readme file!
{{</note>}}

---

⇒ 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**. 
```sh
$ doas rcctl enable upsd upsmon
$ doas rcctl set upsd flags -u _ups
$ doas rcctl start upsd upsmon
```

Normally, the **daemon** log notify thoses services:
```sh
(…)
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: <br>
`$ upsc eaton` est la même chose que faire `$ upsc eaton@localhost`

⇒ To known the battery status:
```sh
$ 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`: 
```sh
$ 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:
```sh
(…)
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 {{< anchor permissions permissions >}}!

### Login failed

```sh
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

```sh
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`

---