Introduction
UPS's work well with pfSense thanks to the Open Source 'Network UPS Tools' (NUT) providing the actual functionality. After installing the official pfSense package, the UPS is easily configured via web UI and also monitored via Nagios + NRPE. Hardware support is continuously improving as NUT is under active development and runs on a a variety of platforms besides pfSense (FreeBSD)
This guide assumes you are installing and configuring a UPS connected directly via USB to your pfSense firewall.
Hardware Selection
The official list of hardware supported by NUT is available at https://networkupstools.org/stable-hcl.html
A high-level Australia-centric recommendation would be:
- Get a UPS with USB, its 2019 after all. Ensure you have a USB port spare on your firewall device
- APC devices 'just work' over USB with the usbhid driver selected
- The limited range of Upsonic devices we have used 'just work' over USB with the blazer driver selected
- PowerShield Defender devices we have used 'just work' over USB with the blazer or newer nutdrv_qx driver selected
- After much persistence we where able to get the Eco-Alto from PSS to work with the blazer driver, but not the nutdrv_qx. Apparently its USB protocol is very quirky and broken. We had to force vendorid=0001, productid=0000, protocol=megatec. Don't waste your time or money on this product, any of the above will serve you better.
- Jaycar UPS are hopeless and will probably never work as they don't have a proper USB vendor and device ID.
If in doubt, just buy an APC. if you're cost conscious, they are also readily available refurbished with new batteries on Ebay - and you'll get a 1000VA for around the price of a new ~600VA.
In all cases YMMV! Please let us know of your successes and we will add them here.
Note: the nutdrv_qx driver is a rewrite of the blazer_usb driver. It's goal is to provide a clean and strict implementation of the Q* protocols, with quirks and subprotocols handled in discrete options. A well behaved UPS will probably work with both, so nutrv_qx is probably the best choice. Quirky UPS's may work with one but not the other. In case that your UPS works with blazer_usb but not nutdrv_qx, you may wish to report a but to the NUT developers.
Install the NUT Package
Log in to the web UI of your pfSense firewall, then from the top bar menu click System, then Package Manager. The Package Manager page will load.
Click the Available Packages tab then wait a second or two for the page to update.
Scroll down until you find the nut package, or use the Search feature at the top of the page.
Click "+ Install", then "Confirm" and wait a few moments for the package to install.
You may also like to install the Service_Watchdog and nrpe packages using the same steps.
Plug the UPS in via USB
Where possible, plug the UPS directly in to your Firewall's USB ports, rather than via a USB hub.
Our experience has been that sharing the USB root hub can cause flakey connectivity to the UPS. Especially as the UPS's USB circutry is often quite cheap and doesn't implement the USB spec properly.
So for best outcomes, avoid having any other devices connected on the same USB root hub. Generally this is at least the pair of ports soldered to the Firewall's mainboard.
You can confirm this by connecting to the console of your pfSense firewall (either the terminal or ssh), hit 8 to get the command prompt, then listing the connected USB devices by running the usbconfig command.
[root@firewall.local]/root: usbconfig
ugen4.1: <AMD EHCI root HUB> at usbus4, cfg=0 md=HOST spd=HIGH (480Mbps) pwr=SAVE (0mA)
ugen0.1: <0x1022 XHCI root HUB> at usbus0, cfg=0 md=HOST spd=SUPER (5.0Gbps) pwr=SAVE (0mA)
ugen3.1: <AMD OHCI root HUB> at usbus3, cfg=0 md=HOST spd=FULL (12Mbps) pwr=SAVE (0mA)
ugen2.1: <AMD EHCI root HUB> at usbus2, cfg=0 md=HOST spd=HIGH (480Mbps) pwr=SAVE (0mA)
ugen1.1: <AMD OHCI root HUB> at usbus1, cfg=0 md=HOST spd=FULL (12Mbps) pwr=SAVE (0mA)
ugen1.2: <ALCOR USB Hub 2.0> at usbus1, cfg=0 md=HOST spd=FULL (12Mbps) pwr=SAVE (100mA)
ugen1.3: <American Power Conversion Back-UPS CS 650 FW817.v9.I USB FWv9> at usbus1, cfg=0 md=HOST spd=LOW (1.5Mbps) pwr=ON (0mA)
ugen1.4: <HUAWEI Technology HUAWEI Mobile> at usbus1, cfg=0 md=HOST spd=FULL (12Mbps) pwr=ON (500mA)
In the above example, observe that each 'root hub' is named 'ugenX.1' where X is a number. Each device connected to that root hub is named 'ugenX.2' 'ugenX.3' etc.
For your reference, this example has not followed our advice to plug the UPS directly in to the FIrewall. Bold has been added to highlight where an APC UPS (ugen1.3) and a Huawei USB modem (ugen1.4) have been attached to a generic USB hub (ugen1.2) which is connected to the Firewall's USB port which is the root hub (ugen1.1).
The above example rectified would have only the APC device connected to the root hub.
We consider this to be best practice.
Configure UPS Settings
From the top bar menu select Services then UPS.
Click UPS Settings and configuration options will appear.
Select UPS Type of Local USB.
Type in a UPS Name, spaces are not allowed. Note this value for use with NRPE later.
Select Driver to match your device, the usbhid will suit many devices including those from APC. The blazer driver is also very common. Consult the NUT Hardware Compatibility List for more information about your specific device.
Click Save.
You should now see the UPS Status page with all sorts of details.
Configure Service Watchdog
(no graphics are provided for this section)
It's a good idea to install and configure the Service Watchdog. It will keep essential services running if they stop, and is trivial to configure.
Assuming you installed the package earlier, follow these steps.
From the top bar menu select Services then Service Watchdog.
On the page that appears, scroll to the bottom of the page and click "+ Add New Service". A new page will appear.
From the Service to Add drop down, select "nut: UPS monitoring daemon".
Click Add
You will be returned to the Service Watchdog page, and the nut service will now be listed under Monitored Services.
We recommend you repeat this simple process for all the services you use that are listed.
Configure NRPE for Nagios Monitoring
An exhaustive configuration guide for NRPE is outside the scope of this document.
You will however, need to check Enable NRPE, provide a Nagios Server(s) address or addresses. It is not recommended that you check Allow Arguments.
Now add the UPS configuration as follows.
Click "+ Add" near the bottom of the screen. A new row of input fields will appear under the Commands heading.
Provide the following values:
| Input Field | Value |
|---|---|
| Name | check_ups |
| Sudo | (leave unchecked) |
| Command | check_ups |
| Warning Level | 1 |
| Critical Level | 5 |
| Extra Options | -u Your_UPS_Name |
In the Extra Options field replace "Your_UPS_Name" with the value of UPS Name you provided earlier in the UPS Settings. This is what tells the check_ups nagios plugin which UPS to query NUT about.
The Warning Level and Critical Level you should adjust to suit your tastes.
Finally, in your Nagios system's (or similar) configuration files you should configure a service like this that will check the status via NRPE:
define service {
use generic-service
service_description UPS State
check_command check_nrpe_1arg!check_ups
(other configuration to suit your needs)
UPS Status on Dashboard
The UPS Status can be added to the Dashboard by first clicking the pfSense logo on the top bar, which will take you to the Dashboard.
To the far right of the title "Status / Dashboard" there is a save, plus (+) and question mark icon. Click the plus (+) icon. The Available Widgets selection will appear.
From the Available Widgets click UPS Status. The page will reload and the UPS Status widget will now be at the bottom.
Drag this widget to your preference position on the Dashboard.
Click the Save icon to retain your Dashboard layout.
The Service Status widget may also be useful to you. It displays the status of all services including the nut service. Follow the same steps again to add it.
Additional Notes
We have observed that usb modeswitching on Huawei 3G modems often disrupts connectivity to the UPS.
It recommended that you configure your USB modem to "modem only" mode. The modem will immediately present as a modem when plugged in, rather than as a media device. Therefore preventing the need to mode switch (either using the usb_modeswitch software, or automatically by the u3g kernel driver).
For older Huawei modems, use this AT command to set modem only mode:
AT^U2DIAG=0
On new modems try:
AT^SETPORT="FF;1,7,3,2,A1"
Or consulate your device's documentation for something equivalent.
Stuck?
We offer commercial support, why not contact us
This article is GREAT, however it is missing a key step.
After installing the NUT package, you must reboot the router for all the NUT rules to become engaged.
I spent many hours sorting out which driver to use with my CyperPower UPS when I came across another poor soul that had the same fate. He finally rebooted the router to try anything, and Voila.
The same happened to me. I received ‘Failure to connect’ messages, but upon rebooting I have full communication with the UPS.
Hope this helps make a great article even better.