Resource icon

Configuring UPS support for single or multiple FreeNAS servers

If you are running a FreeNAS server you definitely need to connect it to a UPS.

Standalone Configuration

You should read the FreeNAS UPS service documentation for your version of FreeNAS before proceeding. The instructions below are specific to FreeNAS versions 9.10-11.2U8 using the 'Legacy' user interface, but the concepts are equally applicable to the newer interface as well.

Configuring a standalone FreeNAS server is fairly simple, provided your UPS is supported by the Network UPS Tools driver used by FreeNAS. You may consult's hardware compatibility list to see if you find your UPS there. Bear in mind that, even if it isn't listed, your particular model may work fine with one of the generic drivers.

In most cases, your UPS will connect to your FreeNAS server with a USB cable. After connecting your UPS, you can determine the USB port it's using by running dmesg | grep ugen at a shell prompt. I get this result on my system named 'boomer':
[root@boomer] ~# dmesg | grep ugen
ugen0.1: <0x15ad> at usbus0
ugen1.1: <0x15ad> at usbus1
ugen0.2: <VMware> at usbus0
ugen0.3: <vendor 0x0e0f> at usbus0
ugen0.4: <American Power Conversion> at usbus0
[root@boomer] ~#
The output shows that my American Power Conversion (APC) UPS is plugged into /dev/ugen0.4, which is the device I specify as the Port on the UPS Settings form shown below.

Once you've configured the UPS service, you should check it to confirm everything is working properly. The NUT tools include the upsc command, which you can run in a shell session to check your configuration, passing it the Identifier you assigned in the UPS Settings:
[root@boomer] ~# upsc ups
battery.charge: 100
battery.charge.low: 10
battery.charge.warning: 50 2001/09/25 2014/05/22
battery.runtime: 555
battery.runtime.low: 120
battery.type: PbAc
battery.voltage: 26.9
battery.voltage.nominal: 24.0
device.mfr: American Power Conversion
device.model: Back-UPS RS 1500
device.serial: BB0743004482
device.type: ups usbhid-ups
driver.parameter.pollfreq: 30
driver.parameter.pollinterval: 2
driver.parameter.port: /dev/ugen0.4
driver.parameter.synchronous: no
driver.version: 2.7.3 APC HID 0.95
driver.version.internal: 0.39
input.sensitivity: high
input.transfer.high: 132
input.transfer.low: 97
input.transfer.reason: input voltage out of range
input.voltage: 123.0
input.voltage.nominal: 120
ups.beeper.status: disabled
ups.delay.shutdown: 20
ups.firmware: 8.g9a.D
ups.firmware.aux: g9a
ups.load: 36
ups.mfr: American Power Conversion 2007/10/23
ups.model: Back-UPS RS 1500
ups.productid: 0002
ups.realpower.nominal: 865
ups.serial: BB0743004482
ups.status: OL
ups.test.result: No test initiated
ups.timer.reboot: 0
ups.timer.shutdown: -1
ups.vendorid: 051d

In my case, tests show the battery.runtime value of 555 seconds is quite accurate. I therefore configure my systems with a Shutdown timer value of 150 seconds to provide a safe margin for a clean shutdown before the battery runs out of juice.


Now that your UPS is configured, it's time to test it -- but don't unplug the UPS yet! We'll get to that later. The NUT tools include another command for this purpose: upsmon -c fsd initiates a 'Forced Shut Down', just as though the UPS had lost power, but without actually using the UPS to provide power. This saves wear and tear on your battery. See the "Testing shutdowns" section at the website for details. For now, simply run upsmon -c fsd at a shell prompt. Your system will enter the shutdown sequence and, if all goes well, shut itself down after the period of time you specified in the Shutdown timer parameter in UPS Settings.

Hint: if you're impatient like me, use a short time period -- 120 seconds or so -- for the Shutdown timer setting during testing. You won't have to wait and twiddle your thumbs for 3 or 4 minutes while the shutdown sequence pokes along. Once you have everything working to your liking, change this setting back to whatever value you want to use in production.

Once the Forced Shutdown test works correctly, you should unplug your UPS as the final Acid Test. This will ensure that you've configured the timeout period correctly for the actual runtime capability of your UPS with the load you are putting on it.

Multiple servers on one UPS

Setting up the UPS NUT service to shut down a standalone FreeNAS system is straightforward. But things become more interesting when you connect multiple systems to a single UPS, and especially so when those systems are All-In-One (AIO) servers with FreeNAS running as a virtual machine on VMware's ESXi.

If you power multiple servers with a single UPS, you must connect one of them to the UPS with an appropriate USB or serial cable (as described above) and configure this server as the Master. Be sure to specify the server's IP address in the upsd Auxillary parameters section for the UPS daemon to listen on. This provides a communications link between the Master and the other servers on your network powered by the UPS. Configure these other servers in Slave mode, specifying the Master's IP address as the Remote Host and 3493 as the Port.

In the case of AIO systems you don't want to shut down FreeNAS directly. Instead, you want to shut down ESXi and let it shut down all of its virtual machines, including FreeNAS.

If you're running ESXi v4.x/5.x/6.x, you're fortunate in that you can gracefully power it down with a simple poweroff command, provided you have the VMware tools installed on all of its virtual machines. And yes, FreeNAS installs these tools automatically when you install it as a virtual machine.

First configure your ESXi server as described below. Then configure the FreeNAS UPS service with this Shutdown Command: ssh root@esxihost poweroff. I name my ESXi systems after well-known cats - Felix and Fritz - so my specific commands are ssh root@felix poweroff and ssh root@fritz poweroff, as you'll see in the screenshots below.

WARNING: I tried using a shell script for the UPS Shutdown Command and couldn't get it to work consistently; upsmon wasn't always able to execute it despite the script working fine when run manually and having the correct ownership and execute permissions. I got this error in my message log:
Mar 17 13:17:40 boomer upsmon[2071]: parent: Unable to call shutdown command: /mnt/tank/systems/scripts/
It's a riddle wrapped in a mystery inside an enigma, so stick with the explicit ssh commands shown.

Once you've configured all of the systems connected to the UPS, you should perform the shutdown tests described earlier, from the Master server.

Master UPS Settings:

Slave UPS Settings:

Configuring ESXi
In order to shutdown your ESXi server from FreeNAS, you need to configure it.

Enable the SSH and ESXi Shell services -- the TSM and TSM-SSH services shown below:

Add your FreeNAS root user SSH key to the authorized keys file located here: /etc/ssh/keys-root/authorized_keys.

Now connect to your ESXi server from your FreeNAS server using an SSH session. You should see the notice below:

Finally, configure your ESXi server for graceful shutdowns. You will need to install the VMware Tools on your virtual machines. Then edit the Autostart settings, insuring the 'Stop action' is 'Shut down':

Shutting down Windows machines: WinNUT
What about shutting down your Windows workstation? WinNUT is a tool that allows you to monitor your NUT-based UPS system and shutdown your PC when required. It's old, but it has the virtue of working. I have tested it with Windows 7, but there are reports that it works with Windows 10 as well. See the article "Shutdown Windows Computer and Synology NAS using WinNUT" for details.

It is available on the Google Code Archive here: winnut

Download the latest version (WinNUT- and install it on your Windows PC. Modify it's configuration file to monitor your UPS-equipped FreeNAS server:
MONITOR ups@ 1 upsmon 'your_upsmon_password' slave
First release
Last update
5.00 star(s) 8 ratings

More resources from Spearfoot

Latest updates

  1. Shutting down Windows PCs

    Added information on shutting down Windows PCs with WinNUT
  2. Added ESXi configuration details

    I've added more detailed instructions on configuring ESXi servers for graceful shutdown.

Latest reviews

Top notch! One thing I ran into on my system, 2 Truenas-12.0-U1 servers in master/slave, is that I needed to ensure the "Power Off UPS" setting was not turned on for my config. Otherwise part way through the boot process after the shutdown it would kill the UPS power and the kill the power to my Server mid boot.
This was the single best guide for setting up my two Truenas 12.0 U1.1 servers on a single UPS. Thank You !!! Minor detail: the UPS name set on the slave system needs to be the UPS name on the master system.
Thanks for the review, @leka! I don't see anything wrong with my description of the master/slave setup: the master system is configured to listen on an IP address and the slave system is configured to access the master via that same IP address. I suppose you could use hostnames instead, but I use IP addresses to save a DNS lookup.
Thanks for this summary. It has helped me to get connection to UPS up and running.
Great job.
Excellent resource. My systems are now all in sync, thanks to the "LISTEN" parameter. Love the ability to test without actually going on battery. Great job!
Straight path from A to B to C and UPS is up and running, shutdown sequence tested. Thank you for a compact guide.
Thank you! This helped me set up my UPS. My specific UPS wasn't listed in the dropdown (Cyber Power PR1500LCDRT2U), but selecting a different model with the "usbhid-ups" driver did the trick. Next step - configuring the 2nd UPS I have. My server has redundant power supplies, which I have plugged into separate UPSs. (Which are plugged into separate power circuits.) Looks like I may need to manually edit some config files to get that working.
End to end explained UPS configuration, also covers the subject of testing the setup (which isn't discussed anywhere else on the internet, AFAIK).