NUT Package (2.8.1 and above)

[dennypage]

[Reserved]

[dennypage]

Notes on USB quirks

If you are using a locally attached USB UPS, and the driver fails to start, it is likely that there is no USB quirk in FreeBSD for your UPS. You can test this by adding

user=root

to the Additional configuration lines for ups.conf. If this allows NUT to start, this means that there is no quirk for your UPS.

Please do not stop here. Help the world.

You can address this by developing quirk for your UPS, and then you can help others that by submitting the quirk for inclusion in FreeBSD.

The basic format of a quirk for a UPS looks like this:

0x051d 0x0002 0x0000 0xffff UQ_HID_IGNORE

Where

• 0x051d is the Vendor ID
• 0x0002 is the Product ID
• 0x0000 is the LowRevision
• 0xffff is the HighRevision
• UQ_HID_IGNORE is the USB quirk (ignore)

This quirk tells the operating system to ignore (not attach a driver) to that particular type of USB device when it is connected to the system. By default, if there is no quirk saying to ignore a device, the kernel will attach a default driver to the device. It requires root privileges to replace the default driver which prevents NUT from being able to access the device unless it is running as root. This is why we need to create a quirk to allow NUT to run without root privilege.

To create a new quirk, we need to determine what the appropriate Vendor and Product IDs will be. The following command will dump USB information for your system:

usbconfig -v

This command can generate quite a bit of output. We are looking for a section that looks like this:

ugen0.2: <American Power Conversion Smart-UPS1000 FW:UPS 16.1 / ID1047> at usbus0, cfg=0 md=HOST spd=FULL (12Mbps) pwr=ON (10mA)

  bLength = 0x0012
  bDescriptorType = 0x0001
  bcdUSB = 0x0200
  bDeviceClass = 0x0000  <Probed by interface class>
  bDeviceSubClass = 0x0000
  bDeviceProtocol = 0x0000
  bMaxPacketSize0 = 0x0040
  idVendor = 0x051d
  idProduct = 0x0003
  bcdDevice = 0x0001
  iManufacturer = 0x0001  <American Power Conversion >
  iProduct = 0x0002  <Smart-UPS_1000 FW:UPS 16.1 / ID=1047>
  iSerialNumber = 0x0003  <ASXXXXXXXXX    >
  bNumConfigurations = 0x0001

The fields we are interested in are 'idVendor' and 'idProduct'. These fields equate to Vendor ID and Product ID as shown in the quirk format above.

Notice that in the usbconfig output the idVendor field matches the ID in quirk above, but the idProduct field does not match. This is because the vendor introduced a new generation of UPS systems and updated the Product ID. To address this, we need to create a new quirk.

The quirk we want to create looks like this:

0x051d 0x0003 0x0000 0xffff UQ_HID_IGNORE

[Note: We are only interested in the Vendor ID and Product ID fields. The other fields will always be the same.]

Now that we have our quirk, we can test it by adding it to the system with the following command:

usbconfig add_dev_quirk_vplh 0x051d 0x0003 0x0000 0xffff UQ_HID_IGNORE

Following that, disconnect and reconnect the USB cable to the UPS and try to start NUT. If the NUT USB driver starts, you've got your quirk.

Adding the quirk via the usbconfig command is temporary, and does not survive a reboot. To permanently add the quirk, we need to add an entry to /boot/loader.conf.local that looks like this:

hw.usb.quirk.0="0x051d 0x0003 0x0000 0xffff UQ_HID_IGNORE"

Note that the number following 'hw.usb.quirk' must be unique, so in the unlikely event you need to add multiple quirks in /boot/loader.conf.local, it would look like this:

hw.usb.quirk.0="0x051d 0x0002 0x0000 0xffff UQ_HID_IGNORE"
hw.usb.quirk.1="0x051d 0x0003 0x0000 0xffff UQ_HID_IGNORE"

If you develop a new quirk, please let the world know. Either post about it here, or submit it directly to FreeBSD.

---

Additional information:

Detailed information regarding quirks can be found here.

Full documentation on usbconfig can be found here.

You can see the attached kernel driver with the following command:

usbconfig -d ugen0.2 show_ifdrv

which will product output like so:

ugen0.2: <American Power Conversion Smart-UPS1000 FW:UPS 16.0 / ID1047> at usbus0, cfg=0 md=HOST spd=FULL (12Mbps) pwr=ON (10mA)
ugen0.2.0: uhid0: <American Power Conversion Smart-UPS1000 FW:UPS 16.0 / ID1047, class 0/0, rev 2.00/0.01, addr 4>

The second line indicates that there is an attached kernel driver (uhid0).

You can detach the kernel driver with the following command:

usbconfig -d ugen0.2 detach_kernel_driver

After detaching the driver, or if you have an installed quirk, show_ifdrv will just have the first line:

ugen0.2: <American Power Conversion Smart-UPS1000 FW:UPS 16.0 / ID1047> at usbus0, cfg=0 md=HOST spd=FULL (12Mbps) pwr=ON (10mA)

You can see all the relevant quirks in your system with the following command:

usbconfig dump_device_quirks | grep HID_IGNORE

The quirks discussed above will show up like so:

VID=0x051d PID=0x0002 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x051d PID=0x0003 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE

[dennypage]

Call for testing!

We are in a testing/feedback phase for the 2.8.1 pfSense NUT package. Many of you have experienced issues with the 2.8.0 version and are running custom builds. I would like to ask you to test the new package prior to a general release.

The 2.8.1 packages are available from the Redmine issue here. In order to install the package, you must be running 23.09. Be sure to select the correct package for your architecture.

In order to install the package, please use the following steps:

1. Have previously installed the NUT package
2. Download the new package from Redmine and copy it to your firewall in /tmp
3. Disable or stop the NUT service
4. Using the command line, remove the old version of NUT:
   pkg remove -fy nut
5. Install the new version of NUT:
   pkg install -fy /tmp/nut-devel-2023.10.07_1.pkg
6. Re-enable or restart the NUT service

If you are able to test, please let me know results. PM is preferred. Please include the following information:

• UPS Type
• Driver (if used)
• Extra Arguments to driver (if used)

Thank you all for your help!

[DavidIr]

@dennypage Not sure if this is because I did something stupid but I have updated the package as instructed and as soon as I restarted the NUT service my router immediately shut down completely. Below is what my SSH session showed as it happened.

Spoiler

[23.09-RELEASE][admin@pfSense.irwazu.co.uk]/tmp: pkg remove -fy nut
Checking integrity... done (0 conflicting)
Deinstallation has been requested for the following 1 packages (of 0 packages in                                                       the universe):

Installed packages to be REMOVED:
        nut: 2.8.0_23

Number of packages to be removed: 1

The operation will free 7 MiB.
[1/1] Deinstalling nut-2.8.0_23...
[1/1] Deleting files for nut-2.8.0_23: 100%
==> You should manually remove the "nut" user.
==> You should manually remove the "nut" group
You may need to manually remove /usr/local/etc/nut/ups.conf if it is no longer n                                                      eeded.
You may need to manually remove /usr/local/etc/nut/upsd.conf if it is no longer                                                       needed.
You may need to manually remove /usr/local/etc/nut/upsd.users if it is no longer                                                       needed.
You may need to manually remove /usr/local/etc/nut/upsmon.conf if it is no longe                                                      r needed.
[23.09-RELEASE][admin@pfSense.irwazu.co.uk]/tmp: pkg install -fy /tmp/armv7_nut-                                                      devel-2023.10.07_1.pkg
Updating pfSense-core repository catalogue...
Fetching meta.conf:   0%
pfSense-core repository is up to date.
Updating pfSense repository catalogue...
Fetching meta.conf:   0%
pfSense repository is up to date.
All repositories are up to date.
Checking integrity... done (0 conflicting)
The following 1 package(s) will be affected (of 0 checked):

New packages to be INSTALLED:
        nut-devel: 2023.10.07_1 [unknown-repository]

Number of packages to be installed: 1

The process will require 9 MiB more space.
[1/1] Installing nut-devel-2023.10.07_1...
===> Creating groups.
Using existing group 'nut'.
Using existing group 'dialer'.
===> Creating users
Using existing user 'nut'.
Extracting nut-devel-2023.10.07_1: 100%    124 B   0.1kB/s    00:01

Broadcast Message from root@pfSense.irwazu.co.uk
        (no tty) at 17:21 GMT...

Communications with UPS EatonUPS lost


Broadcast Message from root@pfSense.irwazu.co.uk
        (no tty) at 17:21 GMT...

Communications with UPS EatonUPS established


Broadcast Message from root@pfSense.irwazu.co.uk
        (no tty) at 17:21 GMT...

UPS EatonUPS: administratively OFF or asleep


Broadcast Message from root@pfSense.irwazu.co.uk
        (no tty) at 17:21 GMT...

UPS EatonUPS on battery


Broadcast Message from root@pfSense.irwazu.co.uk
        (no tty) at 17:21 GMT...

Executing automatic power-fail shutdown



Broadcast Message from root@pfSense.irwazu.co.uk
        (no tty) at 17:21 GMT...

Auto logout and shutdown proceeding


*** FINAL System shutdown message from root@pfSense.irwazu.co.uk ***

System going down IMMEDIATELY



Broadcast Message from root@pfSense.irwazu.co.uk
        (/dev/console) at 17:22 GMT...

NUT killing power...

I had not removed the "interruptonly" from the configuration.

I unplugged the USB, power cycled the router, removed the "interruptonly" setting, and re-connected the USB from the UPS. After doing this everything appears to work as expected.

Hardware: Eaton Ellipse Eco 650
Driver: usbhid
I have the "LISTEN" configuration to make the daemon available to other kit connected to the UPS.

[dennypage]

@DavidIr That is strange to say the least. Are you sure the NUT service was down? Do you have a service watchdog that might have restarted it?

[DavidIr]

@dennypage for step 6 of the installation instructions I went in to the pfsense UI and pressed the restart button on the NUT service. Was that the step I got wrong?

[dennypage]

@DavidIr I don't see anything that you did wrong. Trying to understand how the shutdown could have been triggered.

[mcury]

Hello, I installed this version following the step-by-step provided above, and everything is working.
Send a PM to the OP as he said is preferred. Device: SG-4100 | UPS: Eaton E5 650USB

[wirehead]

@dennypage

So far so good, resolves my issues also with a CP1500AVRLCDa via USB

[vizi0n]

nothing for CE 2.7.0 yet ? :(

[dennypage]

@vizi0n said in NUT Package (2.8.1 and above):

nothing for CE 2.7.0 yet ?

I believe 2.7.1 will be the minimum version on the CE side, similar to how 23.09 is required on the Plus side.

[vizi0n]

@dennypage indeed, installing 2.7.1RC also installed nut-devel-2023.10.07_1 under the 2.8.1 name.

So far, USB connectivity is already better ! Yay. Thanks

[Unoptanio]

@dennypage said in NUT Package (2.8.1 and above):

rican Power Conversion Smart-UPS1000 FW:UPS 16.1 / ID1047>

Hello,

for my RIELLO model Vision VST1100
https://www.riello-ups.it/products/1-gruppi-di-continuita/54-vision

[2.7.0-RELEASE][admin@xxxxxxxxxxx-pfSense.home.arpa]/root: usbconfig -d ugen2.2 show_ifdrv
ugen2.2: <Cypress Semiconductor USB to Serial> at usbus2, cfg=0 md=HOST spd=LOW (1.5Mbps) pwr=ON (100mA)

in pfsense i have this data from command usbconfig -v

ugen2.2: <Cypress Semiconductor USB to Serial> at usbus2, cfg=0 md=HOST spd=LOW (1.5Mbps) pwr=ON (100mA)

  bLength = 0x0012
  bDescriptorType = 0x0001
  bcdUSB = 0x0200
  bDeviceClass = 0x0000  <Probed by interface class>
  bDeviceSubClass = 0x0000
  bDeviceProtocol = 0x0000
  bMaxPacketSize0 = 0x0008
  idVendor = 0x04b4
  idProduct = 0x5500
  bcdDevice = 0x0001
  iManufacturer = 0x0001  <Cypress Semiconductor>
  iProduct = 0x0002  <USB to Serial>
  iSerialNumber = 0x0000  <no string>
  bNumConfigurations = 0x0001


 Configuration index 0

    bLength = 0x0009
    bDescriptorType = 0x0002
    wTotalLength = 0x0029
    bNumInterfaces = 0x0001
    bConfigurationValue = 0x0001
    iConfiguration = 0x0003  <Sample HID>
    bmAttributes = 0x0080
    bMaxPower = 0x0032

    Interface 0
      bLength = 0x0009
      bDescriptorType = 0x0004
      bInterfaceNumber = 0x0000
      bAlternateSetting = 0x0000
      bNumEndpoints = 0x0002
      bInterfaceClass = 0x0003  <HID device>
      bInterfaceSubClass = 0x0000
      bInterfaceProtocol = 0x0000
      iInterface = 0x0004  <EndPoint1 Interrupt Pipe>

      Additional Descriptor

      bLength = 0x09
      bDescriptorType = 0x21
      bDescriptorSubType = 0x11
       RAW dump:
       0x00 | 0x09, 0x21, 0x11, 0x01, 0x00, 0x01, 0x22, 0x25,
       0x08 | 0x00

     Endpoint 0
        bLength = 0x0007
        bDescriptorType = 0x0005
        bEndpointAddress = 0x0081  <IN>
        bmAttributes = 0x0003  <INTERRUPT>
        wMaxPacketSize = 0x0008
        bInterval = 0x000a
        bRefresh = 0x0000
        bSynchAddress = 0x0000

     Endpoint 1
        bLength = 0x0007
        bDescriptorType = 0x0005
        bEndpointAddress = 0x0002  <OUT>
        bmAttributes = 0x0003  <INTERRUPT>
        wMaxPacketSize = 0x0008
        bInterval = 0x000a
        bRefresh = 0x0000
        bSynchAddress = 0x0000

[2.7.0-RELEASE][admin@xxxxxx-pfSense.home.arpa]/root:
[2.7.0-RELEASE][admin@xxxxxx-pfSense.home.arpa]/root: usbconfig -d ugen2.2 detach_kernel_driver
[2.7.0-RELEASE][admin@xxxxxx-pfSense.home.arpa]/root: usbconfig -d ugen2.2 show_ifdrv
ugen2.2: <Cypress Semiconductor USB to Serial> at usbus2, cfg=0 md=HOST spd=LOW (1.5Mbps) pwr=ON (100mA)
[2.7.0-RELEASE][admin@xxxxxx-pfSense.home.arpa]/root:
[2.7.0-RELEASE][admin@xxxxxx-pfSense.home.arpa]/root: usbconfig dump_device_quirks | grep HID_IGNORE
VID=0x0b05 PID=0x1726 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x051d PID=0x0002 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x051d PID=0x0003 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x050d PID=0x0375 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x050d PID=0x0551 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x050d PID=0x0750 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x050d PID=0x0751 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x050d PID=0x0900 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x050d PID=0x0910 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x050d PID=0x0912 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x050d PID=0x0980 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x050d PID=0x1100 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x0764 PID=0x0005 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x0764 PID=0x0501 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x0764 PID=0x0601 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x047c PID=0xffff REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x04b4 PID=0xfd13 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x1163 PID=0x0100 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x1d34 PID=0x0004 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x04d8 PID=0x0002 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x04d8 PID=0xc001 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x06da PID=0xffff REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x10af PID=0x0004 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x10af PID=0x0001 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x0463 PID=0x0001 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x0463 PID=0xffff REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x0d9f PID=0x00a2 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x0d9f PID=0x00a3 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x0d9f PID=0x00a4 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x0d9f PID=0x00a5 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x0d9f PID=0x00a6 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x09ae PID=0x1003 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x09ae PID=0x1007 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x09ae PID=0x1008 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x09ae PID=0x1f06 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x09ae PID=0x1f0a REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x09ae PID=0x2005 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x09ae PID=0x2007 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x09ae PID=0x3012 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x09ae PID=0x3014 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x09ae PID=0x4001 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x09ae PID=0x4002 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x09ae PID=0x4003 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x05ac PID=0x1290 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x05ac PID=0x1292 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x0665 PID=0x5161 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x04b4 PID=0x0bad REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x1781 PID=0x083e REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x1781 PID=0x083f REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
VID=0x1dd5 PID=0x5000 REVLO=0x0000 REVHI=0xffff QUIRK=UQ_HID_IGNORE
[2.7.0-RELEASE][admin@xxxxxx-pfSense.home.arpa]/root:

Is THIS my new quirk for Riello VST1100?

hw.usb.quirk.0="0x04b4 0x5500 0x0000 0xffff UQ_HID_IGNORE"

It seems like the new quirk isn't working

one moment....correction....I disconnected the USB cable and reconnected...I re-executed the command: "/usr/local/etc/rc.d/nut.sh start"

Result:

Have we reached the final solution?

Can I add my new quirk into the bootloader?

Can you write me the complete command?

.......
maybe I found it, can you confirm?
nano /boot/loader.conf

I shut down the system and restart

OK!!!

UPS Working after system reboot.
Without any settings Extra arguments to the driver (optional)

hw.usb.quirk.0="0x04b4 0x5500 0x0000 0xffff UQ_HID_IGNORE"

I also own UPS Riello Sentinel Pro 2200 and Riello Sentinel Dual SDU 6Kw.

As soon as I have time I'll check if the quirk also applies to this other UPS or if it has a different one

.Test in progress ........
Confirm: Quirk for Riello VST1100 also works on Riello Sentinel Pro 2200

[dennypage]

@Unoptanio Good job!

[dmitri]

I'm on 2.7CE, recently updated to NUT package 2.8.1 and started to have issues connecting to the remote NUT server. I have a UPS plugged into another machine (truenas) and pfSense connects to that machine over the network to get the UPS data. Has been working great since I've set this up a couple of years ago, but now the NUT service fails to start. Nothing in the System logs.

I've added "RUN_AS_USER root" to the upsmon.conf and "user=root" to ups.conf. But those didn't have any effect.

Any other suggestions?

[KarB1NE]

@dmitri I believe you need to be either on pfSense CE 2.7.1 or pfSense Plus 23.09 for NUT 2.8.1 to work.

[dmitri]

@KarB1NE hmm. I'll give that a try in the coming days. I'm surprised that being on 2.7 it allows you to update to a package not compatible with that version. But certainly, that could be the issue. Thanks!

[dennypage]

@dmitri said in NUT Package (2.8.1 and above):

I'm on 2.7CE, recently updated to NUT package 2.8.1

Can you clarify? Did you update the NUT package my hand?

Currently, for pfSense 23.09 or 2.7.0 I would expect NUT 2.8.0_2 as the package version. NUT 2.8.1 would be expected with either pfSense 23.09 or 2.7.1 only as a test version only.

[dmitri]

@dennypage I didn't update by hand, used the Package Manager. But, I think I know what may have happened: I was trying to update to CE 2.7.1-RC and changed the branch (even though I'm still on 2.7), and that may have caused the new NUT package to show up.

Now I'm unable to upgradeto 2.7.1, however. The Update page says I'm on the latest 2.7. Even if I change to 2.7.1-RC branch. May need to force-upgrade it.

[dennypage]

@dmitri said in NUT Package (2.8.1 and above):

I've added "RUN_AS_USER root" to the upsmon.conf and "user=root" to ups.conf. But those didn't have any effect.

FYI, if you are using a remote nut connection, you are not running upsd.