Register for the iXsystems Community to get an ad-free experience and exclusive discounts in our eBay Store.
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':
First release
Last update
5.00 star(s) 5 ratings

More resources from Spearfoot

Latest updates

  1. Added ESXi configuration details

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

Latest reviews

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