Overview
What is NUT? NUT, or Network UPS Tools, is a collection of applications that lets your system monitor and react to the status of a battery backup, whether you’re directly connected to the UPS or not. It uses the client server model, which allows several systems to react to the same information. For example, at its most basic, you can use NUT to safely power down all the systems connected to a single UPS when the power goes out. NUT can also provide statistics on the UPS, like its current wattage, estimated battery runtime, and whether or not the battery should be replaced. This guide will walk you through the installation and configuration of NUT for a shared shutdown on power outage, using unraid as the server, with client instructions for Ubuntu, Windows, and pfSense. I picked unraid as the server because it already has a robust notification system built in, and the NUT plugin for unraid utilizes this notification system, so you can be notified of power outages even when you aren’t logged into the unraid dashboard.
Prerequisites
Hardware
First and foremost, before you start installing anything, you need to make sure you have a supported UPS. The good news is NUT supports hundreds of different models from dozens of manufacturers. The UPS just needs to have some form of remote monitoring port, whether it’s USB, serial, or Ethernet. If you already have a UPS, you can check if it’s supported using the Hardware Compatibility List, and if you don’t have one, the CyberPower models we recommend are all supported, and they include the necessary USB monitoring cable in the box.
Additionally, you need to make sure that the systems you want to control are all connected to the battery backup outlets, as well as the networking equipment that connects these systems. One quick word of warning, don’t use a surge supressor to split one outlet into many without checking the manual for your specific UPS first. Most UPSes have surge supression built-in, and adding another supressor downstream can cause problems. Instead, you can use something like an Outlet Splitter for a couple devices with lower power requirements.
Software
NUT can be installed on most modern Operating Systems. There are pre-compiled binaries available for Windows and MacOS, as well as several distributions of Linux and BSD. There is even a client VIB available for VMware ESXi 5, 6, and 7. Lastly, if you aren’t running one of those, NUT is an open source project, so you could download the source and compile it yourself if you wanted. This guide will focus on software installation in Linux, Windows, and pfSense, but the configuration files are the same regardless of your OS, so as long as you can get it installed, you should be able to loosely follow the configuration steps in this guide and apply them to your situation.
NUT Server Installation
Unraid has a NUT plugin available in the Community Apps. Search for NUT and NUT Network UPS Tools should be the first result. Click the Install icon and you’ll get the NUT client and server all in one. Note that there is also a nut influxdb exporter plugin that uses the same icon. Installing the exporter is outside the scope of this guide, but if you have a TIG stack, you can install it once you get NUT configured.
NUT Server Configuration
Before you configure NUT, if you had been using the APC UPS Daemon previously, you will need to disable it, since NUT and APCUPSD cannot coexist. Go into Settings > UPS Settings and click the Default button in the lower left. You may then proceed with the rest of the steps.
Once you have the plugin installed, go to Settings > NUT Settings. In NUT Settings, first click the Autodetect button in the lower left. A NUT Scanner dialog will pop up and it should list your UPS after a second or two. Click the Done button to go back to the NUT Settings page.
Now, you need to configure the rest of the settings. Changing some values will make others appear, so make sure you change them in the order listed below. Also, if a setting isn’t listed, don’t change it from the default value.
- UPS Mode - Netserver. As the name implies, netserver mode broadcasts the UPS status on your local network so other systems running NUT can connect.
- UPS Monitor Password - Something unique. This password will be used by client systems that monitor the status of the UPS.
- UPS Slave Password - Something else unique. This password should be different than the monitor password, and will be used by client systems that shut down when the UPS is on battery power.
- Shutdown Mode - Time on Battery. I recommend this option, which will cause the least wear and tear on your UPS batteries, and should give you plenty of time for a safe shutdown of all systems connected to the UPS. The other options,
Battery LevelandRuntime Leftcould potentially lead to the battery running out of juice before your systems have completely powered down. - Time on battery before shutdown (minutes) - Probably 5, but do the math first. Generally, if the power is out for more than 5 minutes, it’s going to be out for a while. Also, 5 minutes is short enough that most UPSes should still have plenty of power left for everything to shutdown safely. However, if you are powering a lot of devices, you may need to adjust this time shorter, or potentially upgrade to a more powerful UPS. To calculate the appropriate time for your system, you just need a couple numbers.
- First, you need the estimated runtime for the unit, based on your load. You can check the estimated runtimes for both CyberPower and APC based on your wattage. The runtimes listed there will give you a rough idea, but don’t take those runtimes as gospel, they are tested under ideal circumstances with brand new units and fixed loads.
- Second, you need to know how long it takes your systems to shut down once the command is initiated. You can use the stop watch on your phone, or just use the Google Stopwatch,running on a system not connected to the UPS, obviously. You don’t need to be precise to the millisecond, you just need to know if your systems shut down in 10 seconds or 5 minutes or somewhere in between. You should run this test for every system connected to the UPS, and use the longest time in the formulas below.
- With these two numbers, you just take the
Estimated Runtime of your UPS-Longest shutdown time, round the result down to the nearest minute, divide by 2, and you’ll get the longest time on battery that I would recommend. You may ask why you can’t just use the numbers provided by the unraid plugin.
- Turn off UPS after shutdown - Yes (but it might not work). Turning off the UPS after all the systems have safely shut down can save some wear and tear on the unit, as well as leaving a little charge left in the batteries that you could use in an extended outage to charge your phone. Additionally, if your UPS supports it, it can turn itself on again once external power is restored. Unfortunately, neither of the UPSes I’ve used in my testing support this feature, so I’m unable to vouch for how well it works.
With all of those settings configured, click Apply. Now, scroll up to the top again and change Start Network UPS Tools service to Yes, and click Apply one more time. At this point, your NUT server should be configured, and you should see your UPS status at the top, and details about your UPS under NUT Details below the configuration. One last setting that you can optionally change, under Display Settings, is Display Page Footer. If you enable this, you will see two icons on the bottom status bar with the battery percentage and used wattage. You can also see this information on the dashboard page.
Congratulations, you have now configured the NUT server. Before you move on to configuring the clients, grab the UPS Name, UPS Slave Username and UPS Slave Password, as well as your unraid server’s IP. You’ll need them for the clients.
NUT Client Installation
Ubuntu
NUT is available in the stock PPAs for Ubuntu server and desktop. Ubuntu splits the software into several smaller pacakges, some of which are optional. To get the client, open a terminal and run
sudo apt install nut-client
Windows
Official NUT Package
There is currently a beta port of NUT for Windows, which works as a client, but requires some additional libraries to be manually copied into the folder after installation. You can download the beta on the NUT downloads page under the Binary Packages section. During the installation, it will ask if you want to install libUSB. You don’t need to install this component for the client to function.
Once you have NUT installed, go here: https://github.com/IndySockets/OpenSSL-Binaries and download the most recent i386 copy of the OpenSSL package, currently openssl-1.0.2u-i386-win32.zip as of the date this guiide was written. Now, open the zip file and grab the files libeay32.dll and ssleay32.dll from it. You’ll need to copy these files into your C:\Program Files (x86)\NUT\bin folder, as well as into the C:\Program Files (x86)\NUT\sbin folder. Finally, grab the file libgcc_s_dw2-1.dll from the C:\Program Files (x86)\NUT\bin folder, and copy it into the C:\Program Files (x86)\NUT\sbin folder. So, just to recap, when you’re finished, you should have the files ssleay32.dll, libeay32.dll and libgcc_s_dw2-1.dll in both the C:\Program Files (x86)\NUT\bin folder and the C:\Program Files (x86)\NUT\sbin folder. To verify your work, browse to the C:\Program Files (x86)\NUT\bin folder and double-click on the file upsc.exe. If you see a window briefly flash on the screen and then nothing else, you got the libraries installed properly. If you get an error The code execution cannot proceed because SSLEAY32.dll was not found. then double-check you put the files in the correct folders.
3rd Party NUT Client
If you prefer a graphical NUT client, you can try WinNUT, available on github here. Grab the latest release installer (v2.0.4.0 as of the date this guide was written), and run it on your Windows systems. This installer includes all the necessary libraries.
pfSense
NUT is available as an add-on package for pfSense. Go to System > Available Packages and click the +Install button next to NUT, then Confirm. The package will take a few moments to install, and when it finishes you should see a Success message.
NUT Client Configuration
Ubuntu or Windows Official Client
Both Windows and Ubuntu clients use the same files for configuration, so I’ll only include these instructions once. On Ubuntu, you will find these files under /etc/nut, and in Windows, they will be in C:\Program Files (x86)\NUT\etc. The installation should put some sample config files in these folders, which include details about different options you can include. On Windows, you’ll need to rename the files to remove the .sample extension, then edit the files one at a time to make your changes.
In Ubuntu, the config files are only editable by root, so you’ll need to use sudo to open them. For quick edits in the terminal, I prefer nano, but you can also use gedit in the GUI.
nut.conf
The file nut.conf specifies the mode that NUT runs in, client, server, or standalone. You only need to make one change in this file. At the bottom, change the last line to:
MODE=netclient
It needs to be capitalized and entered exactly as I entered it. Once you’ve made this change, save the file and close it.
upsmon.conf
The file upsmon.conf specifies how to connect to your NUT server and how to react to UPS events to shut down when necessary. The sample file has descriptions for all the options, so you’ll need to page down through the file to find and edit the necessary lines. There are only two lines that you need to configure for a NUT client.
-
The first line you need to add tells the service how to connect to your NUT server. Page down until you see these lines:
and then on the blank line below the last example, enter the following:MONITOR <ups_name>@<NUT_server_IP> 1 <slave_username> <slave_password> slaveYou’ll need to substitute the information you obtained when you configured the server. For example, for my UPS on 192.168.10.10, I entered the following:
MONITOR ups@192.168.10.10 1 slaveuser slavepassword slave -
Next, page down until you see
SHUTDOWNCMD. On Ubuntu, this should already be set to the proper shutdown command, but on Windows, you’ll need to update it to the following:SHUTDOWNCMD "C:\\WINDOWS\\system32\\shutdown.exe -p"
With those two parts edited, you can save and close the file.
Starting the client service
Ubuntu Service
In the terminal, run
sudo systemctl restart nut-client
Windows Service
In the Start menu, go to Nut > Start Service.
WinNUT Configuration
If you chose to use WinNUT for your Windows clients, the configuration is all done in the GUI. Open the program and click the Settings menu. From there, first you need to configure the connection. Use the IP, UPS name, username and password from above. You also need the NUT port, which defaults to 3493, and the delay, in milliseconds. I would recommend a minimum of 5000 ms, and the max is 60,000 ms. Here’s a screenshot of my settings with a 15,000 ms delay. Lastly, check the Re-establish connection box to enable the program to connect with the NUT server automatically.
You will also want to go to the Miscellaneous tab and enable a few options in here. I would recommend checking Minimize to tray, Start Minimized, Close to Tray, and Start with Windows. The logging is optional, but I would leave it disabled for now. If you need to troubleshoot things, you can come in and enable the log later. Here are my settings for reference.
Finally, you need to configure the Shutdown Options. Change Type of Stop to Shutdown and Delay to Shutdown (sec) to 360.
Once you have everything configured, click OK to save the settings, and on the main window you should see your UPS statistics populate, similar to this:
pfSense Configuration
To configure NUT in pfSense, go to Services > UPS. Next, go to UPS Settings. In the dropdown, choose Remote NUT server. Next, configure the following:
- UPS Name - The name of the UPS you set in unraid
- Remote IP address or hostname - Your unraid server’s IP
- Remote username - The UPS Slave username
- Remote password - The UPS Slave password
Click Save and you’re set. The service should enable automatically, and when the page refreshes you should see some of your UPS stats.
You can also optionally add a UPS Status widget to the pfSense dashboard, which displays the runtime, load and battery charge percentage.
Testing
Controlled Test Scenario
Now that you have your server and clients configured, it’s time to test things in a controlled environment. Save any unsaved documents you were working on, just in case something doesn’t work properly. Then, on Unraid, open a terminal and enter upsmon -c fsd. This command will immediately initiate a shutdown on the server and all connected clients without actually draining the battery. All of the systems should perform a normal shutdown routine before completely powering off. If it worked, you’re basically done. If any of the systems didn’t power down properly, double-check the configuration.
Live Test Scenario
Don’t run this test until after you’ve successfully run the controlled test. For this test, turn on all your systems and let them boot completely. Then, unplug your UPS from the outlet. You should get a notification almost immediately in Unraid that your system is running on battery power. Now, just sit back and watch. After the UPS has been on battery for as long as you specified, your clients should shut down automatically, followed by unraid. Right when unraid gets to the end of its shutdown procedure, if your UPS supports it, it should shut itself off. Give it 30 seconds or so for your drives to spin down, then plug the UPS in again. Then, if your UPS supports it, it should power on automatically when you plug it in and start recharging the batteries.
Final Thoughts and Suggestions
In my opinion, a properly functioning UPS is essential for any home server equipment, and configuring your server to react to the UPS status and shut down when necessary is just as important. While NUT isn’t the only option to accomplish this, it is the most customizable option. The synchronized shutdown you can do with the instructions in this guide is just the tip of the iceberg. With the appropriate hardware, you could interface NUT with things like PDUs, solar controllers, automatic transfer switches, and more. That’s a bit beyond the scope of this guide, but not beyond the capabilities of NUT. Check out the full documentation for more details.
You may be thinking “Now that I can turn off my machines automatically during a power outage, how can I turn them on again when the power is restored?”, and then you might remember that the BIOS in a lot of systems has an option to automatically turn the system on when power is restored. It sounds great, but it’s probably not the best idea. When I’ve had power outages at home, the power isn’t always stable immediately after it’s restored. I’ve had the power go on for a few seconds, then off again, then on for a few seconds, then off for a few minutes, before finally being completely restored. It’s annoying enough to see your kitchen lights flicker on and off like that, but it can potentially be destructive if your computer cycles on and off that quickly. The battery in your UPS might be able to keep you up through a couple of those 30 second outages if you didn’t drain too much power during the initial shutdown, but if it’s already mostly depleted from the initial shutdown, it’s not going to be very useful again until it’s had time to recharge. I would recommend keeping your systems powered down until the utility power is stable again and your UPS has had a chance to recover.
