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 (9.10 and 11.0), but the concepts should be applicable to Corral 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 networkupstools.org'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':
Code:
[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:
Code:
[root@boomer] ~# upsc ups
battery.charge: 100
battery.charge.low: 10
battery.charge.warning: 50
battery.date: 2001/09/25
battery.mfr.date: 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
driver.name: 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
driver.version.data: 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
ups.mfr.date: 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.

Testing

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 networkupstools.org 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 enable the SSH service on the ESXi server and set up private key authentication. 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:
Code:
Mar 17 13:17:40 boomer upsmon[2071]: parent: Unable to call shutdown command: /mnt/tank/systems/scripts/esxi-poweroff-host.sh
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:
ups-master.jpg


Slave UPS Settings:
ups-slave.jpg
Author
Spearfoot
First release
Last update
Rating
5.00 star(s) 3 ratings

More resources from Spearfoot

Latest reviews

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