[Guide] Using NUT to power down multiple systems

image

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.

image

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.

image

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.

  1. UPS Mode - Netserver. As the name implies, netserver mode broadcasts the UPS status on your local network so other systems running NUT can connect.
  2. UPS Monitor Password - Something unique. This password will be used by client systems that monitor the status of the UPS.
  3. 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.
  4. 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 Level and Runtime Left could potentially lead to the battery running out of juice before your systems have completely powered down.
  5. 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.
  6. 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

image

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: Index of /SSL 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> slave
    

    You’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.

image

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.

image

Finally, you need to configure the Shutdown Options. Change Type of Stop to Shutdown and Delay to Shutdown (sec) to 360.

image

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:

image

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.

15 Likes

I am having problems with unaid and NUT. Under settings / UPS settings, I have start APC UPS daemon set to “no.” Under settings / NUT settings I have it set as you discussed above. My log file is full of Feb 21 05:01:24 unraid apcupsd[12790]: Communications with UPS lost.
When I go to settings / NUT settings and set “Stat network UPS tools service” to NO, I get a message from unraid that it re-connected with the UPS. What do I have set wrong?

(Edited to change to a more concise screenshot of the syslog)

NUT and APCUPSD can’t coexist, so if you were using APC previously, disable both APC and NUT, and then reboot. When you reboot, enable only NUT.

1 Like

I seem to be having trouble with my NUT client settings, when I run the “Controlled Test” my server shuts down fine, but my client does not. Client is my new Ubuntu QS box. Here is what I have entered:

MONITOR ups@192.168.1.48 1 slaveuser [slavepassword] slave

The IP address is the address for my Unraid NAS. Is that correct or should that be the IP for my UPS, which is 127.0.0.1?

Is there a way to send a shutdown command to JUST the client, to see if that part works?

The IP needs to be the system running the NUT server, so your unraid IP in this case. I would double check your client configuration, make sure the password is an exact match (it’s case sensitive), and also verify that you did NOT change the SHUTDOWNCMD directive from the default of:

SHUTDOWNCMD "/sbin/shutdown -h +0"

If all that is correct, try running the shutdown manually on the client. From the terminal, run

sudo /sbin/shutdown -h +0

and verify that your system shuts down immediately. Assuming it does, when you turn it on again, open the syslog monitor on your unraid server and look for messages similar to the following:

Feb 22 18:50:12 Tower upsd[100]: Client monuser@192.168.1.45
logged into UPS [ups]

The IP in this log entry should match your ubuntu box and shows that it connected to the NUT server properly. If you don’t see that, it’s possible the client isn’t starting properly, in which case you’ll need to check the log files on ubuntu for a clue.

Running the shutdown command and it shut down immediately. When I started it up I saw the log entry you described. However, when I run the upsmon -c fsd in Unraid the client does not shut down with the server.

EDIT: Early this morning there was the following error in my server log-

Tower usbhid-ups[8416]: nut_libusb_get_string: Pipe error.

Any connection to my issue? I’m guessing not…

Fixed it by going to UPS settings and hitting “restore default,” which apparently got rid of whatever vestige of APCUPSD was still running. Thanks for this guide. I haven’t been able to get winnut to work (connect) for me yet, but since I’ve moved my windows PC isn’t protected by the UPS currently, so I’ll work on that when my server moves back down to where the windows PC is…

Any other ideas to try? Could it be a permissions issue on the client, like I somehow don’t have upsmon running under the root user on my client?

To clarify, my client is running Ubuntu 20.04. Running sudo /sbin/shutdown -h +0 on the client does initiate shutdown. When the client was restarted I did see
Feb 22 18:50:12 Tower upsd[100]: Client slaveuser@192.168.1.71
logged into UPS [ups]

However, running upsmon -c fsd from Unraid does not result in the client shutting down.

I was having a hell of a time getting WinNUT to work. Had all the settings entered correctly, but it just refused to connect!. Finally changed the value of “Delay” from the default ‘0’ to ‘5000’ and it connected!

Glad to hear you got it working, and thanks for the info. I updated the guide noting the value needs to be changed from 0.

1 Like

EDIT

I missed a step.

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.

When I ran the upsc.exe file I didn’t see the error window and assumed it was working.

The slave is now showing up in the syslog when it reboots.

image

Thanks again for guide. With the upcoming PG&E power shutdowns looming this will make sure my computers shut down cleanly.

—OP BELOW—

Thanks for your excellent guide. I am using this for my Win10 Blue Iris bare metal box that is using the same UPS as my unRaid server. When doing a controlled test though the unRaid box rebooted but the Win10 box did not. The Win10 box is running the Official NUT Package.

A quick clarification on the NUT server IP in settings. I left it at default per your steps since it wasn’t detailed in the steps but does this IP need to match the unRaid server IP it is running on or do I leave it at the default 127.0.0.1?

image

Looking at my syslog it show this after the unRaid box rebooted during the controlled test.

Glad to see you got it figured out. And to answer your question about the IP, leave it at 127.0.0.1 on the server. You only need to use the unraid IP on the client systems.

1 Like