NUT on Mac OS X

Network UPS Tools (NUT) on Mac OS X (10.4.10)

Author:	poushag
Date:	2007-07-01
Revision:	01
Description:	This is a how-to about implementing NUT on OS X

Motivation

I have more than one computer powered by my old serial cable UPS. I wanted to try to have a safe shutdown of all systems with the Mac as master (polling the UPS) and others as slaves (polling the Mac). See "Advanced configuration" graphic on http://www.networkupstools.org/docs/user-manual.chunked/ar01s06.html#DataRoom for diagram.

It wasn't too difficult but the nuggets needed to figure it out were scattered around the net a bit and obfuscated somewhat by other info. So now that I have filtered out all the useless data and implemented NUT successfully, I wanted to share the methods in case others would like to do the same.

Prerequisites

Before dealing with NUT, I had to get the UPS connected to the Mac. The first thing needed was a DB-9 (male) serial port. For me this meant buying a USB to serial adapter cable and a USB PCI card as well since I didn't have any spare USB ports. (My Mac is a PowerMac G4 MDD.)

I obtained a USB 2.0 PCI card Encore ENLUSB2-5PCI-BR (4 ports ext, 1 port int). All I had to do was power down and install the card.

I also found a CP-Tech CP-US-03 adapter that sources said was compatible with Linux as it is based on the Prolific PL2303 chip. I found that it required a driver for OSX that was NOT on the manufacturers website or the CD that came with the part. I found it here: <http://www.llondel.org/md_pl2303_v109b6.zip> (Thanks to David Hough for posting this driver. His "Interfacing a Contact-Closure UPS to Mac OS X and Linux" write-up was a good source but was not exclusively focussed on OSX as my text here is.) The driver installation required a reboot and then the device showed up at /dev/tty.usbserial and was visible in the System Profiler app on the USB bus.

Installing NUT

NUT binaries were not available for Mac OS X as of June 2007. But thanks to Ranger Rick and his friends at Fink I was able to build NUT myself. This is not as hard as it might sound. I followed the one-page quick start <http://www.finkproject.org/download/index.php?phpLang=en> for the most part. It should have mentioned in step 6 that Fink Commander is at <http://sourceforge.net/project/showfiles.php?group_id=48896> and (for using fink packages from source on 10.4) XCode 2.4.1 is at <http://connect.apple.com> & under 'Downloads' click 'Developer Tools' (requires free user registration). After this I ran the Fink self-update from source and then installed the 'nut' package from source. (For a serial cable UPS, the 'nut-usb' package is not needed. And the 'nut-cgi' package is only needed for webpage monitoring of the UPS.)

Configuring NUT

NUT requires a fair amount of linux style configuration and a bit of Mac type tweaking too. First I backed up all the sample files and removed the '.sample' extension. Then I edited the configuration files as follows.

ups.conf contains settings specific to the UPS:

[bp1100]
        driver = genericups
        port = /dev/tty.usbserial
        upstype = 2
        mfr = APC
        model = BP1100

The NUT hardware compatibility list at <http://www.networkupstools.org/stable-hcl.html> has a table of supported hardware and each corresponding driver (and upstype if applicable) for entry in the ups.conf file. As for the rest, it was just the same port info from above plus manufacturer and model number. The user has complete freedom to name the UPS via the string between the brackets. This name will be used to poll the UPS in combination with the hostname or IP address of the server.

upsd.users for OS X master (with password deleted of course):

[nobody]
        password  =
        allowfrom = localhost
        upsmon master

upsmon.conf I left alone except one line (again without actual password):

MONITOR bp1100@localhost 1 nobody <password> master

upssched.conf I deleted after determining that no timers are needed for my application of NUT.

Verifying NUT Configuration

Initial verification can be done by starting all the processes manually. Make sure you have nothing else important in progress because if you get things wrong it may decide that the machine needs to be shut down immediately. Connect the all cable terminations.

Start the NUT processes as root in a terminal. (I prefer iTerm <http://iterm.sourceforge.net/download.shtml>):

sudo /sw/lib/nut/upsdrvctl start
sudo upsd
sudo upsmon
ps auxwww | grep ups
upsc bp1100@localhost

Of course you should substitute the name of your own UPS as you set it in the ups.conf file.

The 'ps aux' command should return something like this:

nobody     462   0.0  0.0    27416    148  ??  Ss   25Jun07   1:35.21 /sw/lib/nut/genericups -a bp1100
nobody     464   0.0  0.0    27420    160  ??  Ss   25Jun07   2:30.35 /sw/sbin/upsd
root       466   0.0  0.0    27412     92  ??  Ss   25Jun07   0:00.00 /sw/sbin/upsmon
nobody     467   0.0  0.0    27412    152  ??  S    25Jun07   1:37.81 /sw/sbin/upsmon

And the 'upsc' command output similar to this:

driver.name: genericups
driver.parameter.mfr: APC
driver.parameter.model: BP1100
driver.parameter.port: /dev/tty.usbserial
driver.parameter.upstype: 2
driver.version: 2.0.5
driver.version.internal: 1.32
ups.mfr: APC
ups.model: BP1100
ups.status: OL

Autostarting NUT

For OS X it is necessary to navigate to /System/Library/StartupItems. I started by copying another directory tree (I used 'NFS') as a template for 'UPS' directory. Then I changed to the 'UPS' directory and renamed the 'NFS' file to 'UPS' using the mv command. And last I edited the files in the 'UPS' directory.

These are the terminal commands:

cd /System/Library/StartupItems
sudo cp -R NFS UPS
cd UPS
ls
sudo mv NFS UPS
sudo vi UPS

Edit 'UPS' to match this content:

#!/bin/sh

##
# UPS Monitor script
# Using Network UPS Tools executables
# based on script by David Hough
# @ http://www.llondel.org/ups.shtml
# Note that fink executables cannot use Apple's rc.common routines
# and fink binaries don't keep their pid files in the standard OS X location
##

NUT_PREFIX=/sw/lib/nut
FINK_BIN=/sw/sbin

case $1 in
                start  )

                ${NUT_PREFIX}/upsdrvctl start
                ${FINK_BIN}/upsd
                ${FINK_BIN}/upsmon
;;

                stop  )

                ${FINK_BIN}/upsmon -c stop
                ${FINK_BIN}/upsd -c stop
                ${NUT_PREFIX}/upsdrvctl stop
;;

                restart  )

                $0 stop
                $0 start
;;

esac

Edit the StartupParameters.plist file to read:

{
        Description = "UPS Monitor (NUT)";
        Messages = {start = "Starting UPS Monitor (NUT)"; stop = "Stopping UPS Monitor (NUT)"; };
        OrderPreference = None;
        Provides = (UPS);
        Requires = (Resolver);
}

Securing NUT

NUT is built to run under the user 'nobody' on OS X. This user already existed so all I did was change the owner and permissions on the configuration files to make them secure:

sudo chown nobody:wheel /sw/etc/nut/*
sudo chmod 660 /sw/etc/nut/*

After the config files are secured, if further configuration tweaking is needed I find Pseudo a good tool for editing (as root) these files with BBEdit Lite on OS X. <http://personalpages.tds.net/~brian_hill/pseudo.html>

'Field' Testing NUT

Reboot and run the upsc command as before. If output appears normal then the final test is to trip the circuit breaker feeding power to the UPS. The system should flip over to battery power and return a warning in the terminal window that it is on battery. You should be able to configure clients on other machines, such as I did using WinNUT <http://csociety.ecn.purdue.edu/~delpha/winnut/>.