Network UPS Tools: INSTALL These are the essential steps for compiling and installing this software, including configuring safe shutdowns when the UPS battery runs out of power. There are many programs and other features in this package. You should check out the README file and other accompanying documentation to see how it all works. The paths shown below are the default values you get by just calling configure by itself. If you have used --prefix or similar, things will be different. Also, if you didn't install this program from source yourself, the paths will probably have a number of differences. Note: by default, your system probably won't find the man pages, since they install to /usr/local/ups/man. You can fix this by editing your MANPATH, or just do this: man -M /usr/local/ups/man man -M /usr/local/ups/man upsd.conf Also, if your favorite system offers up to date binary packages, always prefer these over a source installation. Along with the known advantages of such systems for installation, upgrade and removal, there are many integration issues that have been addressed. ============================================================================ ============================================================================ ============================================================================ Prepare your system =================== 1. Create at least one user and a group for running this software. You might call them "ups" and "nut". The exact names aren't important as long as you are consistent. The process for doing this varies from one system to the next, and explaining how to add users is beyond the scope of this document. For the purposes of this document, the user name and group name will be "ups" and "nut" respectively. Be sure the new user is a member of the new group! If you forget to do this, you will have problems later on when you try to start upsd. ============================================================================ ============================================================================ ============================================================================ Build and install ================= 1. Configure the source tree for your system. Add the --with-user and --with-group switch to set the user name and group that you created above. ./configure --with-user=ups --with-group=nut If you need any other switches for configure, add them here. For example: * to build and install USB drivers, add --with-usb (note that you need to install libusb development package or files). * to build and install SNMP drivers, add --with-snmp (note that you need to install libsnmp development package or files). * to build and install CGI scripts, add --with-cgi. * to build and install NUT development files (needed to compile WMNut and MGE PSP), add --with-lib. * to build and install HAL support, add --with-hal. See docs/configure.txt or "./configure --help" for the available options. If you alter paths with additional switches, be sure to use those new paths while reading the rest of the steps. *** Reference: docs/configure.txt --------------------------------------------------------------------------- 2. Build the programs. make This will build the NUT client and server programs and the selected drivers. It will also build any other features that were selected during configuration in step 1. above. --------------------------------------------------------------------------- 3. Gain privileges for installing software if necessary. su --------------------------------------------------------------------------- 4. Install the files to a system level directory. make install This will install the compiled programs and man pages, as well as some data files required by NUT. Any optional features selected during configuration will also be installed. This will also install sample versions of the NUT configuration files. Sample files are installed with names like ups.conf.sample so they will not overwrite any existing real config files you may have created. If you are packaging this software, then you will probably want to use the DESTDIR variable to redirect the build into another place, i.e.: make DESTDIR=/tmp/package install make DESTDIR=/tmp/package install-conf --------------------------------------------------------------------------- 5. Create the state path directory for the driver(s) and server to use for storing UPS status data and other auxiliary files, and make it owned by the user you created. mkdir -p /var/state/ups chmod 0770 /var/state/ups chown root:nut /var/state/ups --------------------------------------------------------------------------- 6. Set ownership data and permissions on your serial or USB ports that go to your UPS hardware. Be sure to limit access to just the user you created earlier. These examples assume the second serial port (ttyS1) on a typical Slackware system. On FreeBSD, that would be cuaa1. Serial ports vary greatly, so yours may be called something else. chmod 0660 /dev/ttyS1 chown root:nut /dev/ttyS1 The setup for USB ports is slightly more complicated. Device files for USB devices, such as /proc/bus/usb/002/001, are usually created "on the fly" when a device is plugged in, and disappear when the device is disconnected. Moreover, the names of these device files can change randomly. To set up the correct permissions for the USB device, you may need to set up (operating system dependent) hotplugging scripts. Sample scripts and information are provided in the scripts/hotplug and scripts/udev directories. For most users, the hotplugging scripts will be installed automatically by "make install". (If you want to try if a driver works without setting up hotplugging, you can add the "-u root" option to upsd, upsmon, and drivers; this should allow you to follow the below instructions. However, don't forget to set up the correct permissions later!). NOTE: if you are using something like devfs or udev, make sure these permissions stay set across a reboot. If they revert to the old values, your drivers may fail to start. --------------------------------------------------------------------------- 7. Create one section per UPS in /usr/local/ups/etc/ups.conf To find out which driver to use, check the "HARDWARE SUPPORT TABLE" in the README file, or data/driver.list. Once you have picked a driver, create a section for your UPS in ups.conf. You must supply values for "driver" and "port". Some drivers may require other flags or settings. The "desc" value is optional, but is recommended to provide a better description of what your UPS is supporting. A typical UPS without any extra settings looks like this: [myupsname] driver = mydriver port = /dev/ttyS1 desc = "Workstation" NOTE: usbhid-ups is a special case and ignores the "port" value. You must still set this value, but it does not matter what you set it to; you can set "port" to "auto" if you like. If you only own one local UBS UPS, the driver will find it automatically. If you own more than one UBS UPS, refer to the usbhid-ups(8) man page for more information. *** References: man pages: ups.conf(5), nutupsdrv(8), plus whatever driver(s) you intend to use. --------------------------------------------------------------------------- 8. Start the driver(s) for your hardware. /usr/local/ups/bin/upsdrvctl start Make sure the driver doesn't report any errors. It should show a few details about the hardware and then enter the background. You should get back to the command prompt a few seconds later. For reference, a successful start of the belkin driver looks like this: # /usr/local/ups/bin/upsdrvctl start Network UPS Tools - UPS driver controller 1.5.12 Network UPS Tools - Belkin Smart protocol driver 0.21 (1.5.12) Detected F6C525-SER on /dev/cuaa0 # If the driver doesn't start cleanly, make sure you have picked the right one for your hardware. You might need to try other drivers by changing the "driver=" value in ups.conf. Be sure to check the driver's man page to see if it needs any extra settings in ups.conf to detect your hardware. If it says "can't bind /var/state/ups/..." or similar, then your state path probably isn't writable by the driver. Check the permissions and mode on that directory (step 5). After making changes, try step 6 again. *** References: man pages: nutupsdrv(8), upsdrvctl(8) --------------------------------------------------------------------------- 9. Configure upsd, which serves data from the drivers to the clients. First, edit upsd.conf to allow access to your client systems. By default, upsd will only listen to localhost port 3493/tcp. If you want to connect to it from other machines, you must specify each interface you want upsd to listen on for connections, optionally with a port number. LISTEN 127.0.0.1 3493 LISTEN ::1 3493 Note: if you run a firewall of some sort, you may have to add rules to allow these incoming connections. Next, create upsd.users. For now, this can be an empty file. You can come back and add more to it later when it's time to configure upsmon or run one of the management tools. Do not make either file world-readable, since they both hold access control data and passwords. They just need to be readable by the user you created in the preparation process. The suggested configuration is to chown it to root, chgrp it to the group you created, then make it readable by the group. chown root:nut upsd.conf upsd.users chmod 0640 upsd.conf upsd.users *** References: man pages: upsd.conf(5), upsd.users(5), upsd(8) --------------------------------------------------------------------------- 10. Start the network server. /usr/local/ups/sbin/upsd Make sure it is able to connect to the driver(s) on your system. A successful run looks like this: # /usr/local/ups/sbin/upsd Network UPS Tools upsd 1.5.12 Connected to UPS [belkin]: belkin-cuaa0 Synchronizing...done # upsd prints dots while it waits for the driver to respond. Your system may print more or less depending on how many drivers you have and how fast they are. NOTE: if upsd says that it can't connect to a UPS or that the data is stale, then your ups.conf is not configured correctly, or you have a driver that isn't working properly. You must fix this before going on to the next step. *** Reference: man page: upsd(8) --------------------------------------------------------------------------- 11. Make sure that the UPS is providing good status data. /usr/local/ups/bin/upsc myupsname@localhost ups.status You should see just one line in response: OL OL means your system is running on line power. If it says something else (like OB - on battery, or LB - low battery), your driver was probably misconfigured in step 7. If you reconfigure the driver, use 'upsdrvctl stop' to stop it, then start it again in step 8. *** Reference: man page: upsc(8) --------------------------------------------------------------------------- 12. Look at all of the status data which is being monitored. /usr/local/ups/bin/upsc myupsname@localhost What happens now depends on the kind of UPS and driver you have. In the list, you should see ups.status with the same value you got above. A sample run on a MGE UPS SYSTEMS Ellipse ASR 600 looks like this: battery.charge: 82 battery.charge.low: 30 battery.runtime: 1563 driver.name: usbhid-ups driver.parameter.port: auto driver.version: 2.0.3 driver.version.data: MGE HID 0.8 driver.version.internal: 0.28 input.transfer.high: 264.0 input.transfer.low: 184.0 outlet.desc: Main Outlet outlet.id: 1 outlet.switchable: 0 outlet.1.desc: PowerShare Outlet 1 outlet.1.id: 2 outlet.1.switch: 0 outlet.1.switchable: 0 output.voltage: 230.0 ups.delay.shutdown: -1 ups.delay.start: -10 ups.load: 0 ups.mfr: MGE UPS SYSTEMS ups.model: Ellipse 600 ups.power.nominal: 600 ups.serial: AP8F15005 ups.status: OB DISCHRG *** Reference: man page: upsc(8) --------------------------------------------------------------------------- 13. Edit your startup scripts. Make sure upsdrvctl and upsd are run every time your system starts. ============================================================================ ============================================================================ ============================================================================ Configuring shutdowns for low battery events -------------------------------------------- The whole point of UPS software is to bring down the OS cleanly when you run out of battery power. Everything else is just eye candy. To make sure your system shuts down properly, you will need to perform some additional configuration and run upsmon. Here are the basics: --------------------------------------------------------------------------- 1. Create a upsd user for upsmon to use while monitoring this UPS. Edit upsd.users and create a new section. upsmon will connect to upsd and use this user name (in brackets) and password to authenticate. This example is for a user called "monuser": [monuser] password = mypass upsmon master # or upsmon slave *** References: man pages: upsd(8), upsd.users(5) --------------------------------------------------------------------------- 2. Reload upsd. Depending on your configuration, you may be able to do this without stopping upsd: /usr/local/ups/sbin/upsd -c reload If that doesn't work (check the syslog), just restart it: /usr/local/ups/sbin/upsd -c stop /usr/local/ups/sbin/upsd Later: if you want to make reloading work, see the entry in the FAQ about starting upsd as a different user. --------------------------------------------------------------------------- 3. Set the POWERDOWNFLAG location for upsmon. In upsmon.conf, add a POWERDOWNFLAG directive with a filename. upsmon will create this file when the UPS needs to be powered off during a power failure when low battery is reached. We will test for the presence of this file in a later step. POWERDOWNFLAG /etc/killpower *** References: man pages: upsmon(8), upsmon.conf(5) --------------------------------------------------------------------------- 4. Secure upsmon.conf. The recommended setting is to have it owned by root:nut, then make it readable by the group and not world. This file contains passwords that could be used by an attacker to start a shutdown, so keep it secure. chown root:nut upsmon.conf chmod 0640 upsmon.conf This step has been placed early in the process so you secure this file before adding sensitive data in the next step. --------------------------------------------------------------------------- 5. Create a MONITOR directive for upsmon Edit upsmon.conf and create a MONITOR line with the UPS definition (@), username and password from step 2, and the master or slave setting. If it's the master (i.e., it's connected to this UPS directly): MONITOR myupsname@mybox 1 monuser mypass master If it's just monitoring this UPS over the network, and some other system is the master: MONITOR myupsname@mybox 1 monuser mypass slave The number "1" here is the power value. This should always be set to 1 unless you have a very special (read: expensive) system with redundant power supplies. See big-servers.txt and data-room.txt. *** References: man pages: upsmon(8), upsmon.conf(5) --------------------------------------------------------------------------- 6. Define a SHUTDOWNCMD for upsmon. Still in upsmon.conf, add a directive that tells upsmon how to shut down your system. This example seems to work on most systems: SHUTDOWNCMD "/sbin/shutdown -h +0" Notice the presence of "quotes" here to keep it together. If your system has special needs, you may want to set this to a script which does local shutdown tasks before calling init. --------------------------------------------------------------------------- 7. Start upsmon. /usr/local/ups/sbin/upsmon If it complains about something, then check your configuration. --------------------------------------------------------------------------- 8. Look for messages in the syslog to indicate success. It should look something like this: May 29 01:11:27 mybox upsmon[102]: Startup successful May 29 01:11:28 mybox upsd[100]: Client monuser@192.168.50.1 logged into UPS [myupsname] Any errors seen here are probably due to an error in the config files of either upsmon or upsd. You should fix them before continuing. --------------------------------------------------------------------------- 9. Edit your startup scripts: add upsmon Make sure upsmon starts when your system comes up. Do it after upsdrvctl and upsd, or it will complain about not being able to contact the server. --------------------------------------------------------------------------- 10. Edit your shutdown scripts: add upsdrvctl shutdown You should configure your system to power down the UPS after the filesystems are remounted read-only. Have it look for the presence of the POWERDOWNFLAG (from upsmon.conf), using this as an example: if (test -f /etc/killpower) then echo "Killing the power, bye!" /usr/local/ups/bin/upsdrvctl shutdown sleep 120 # uh oh... the UPS power-off failed # you probably want to reboot here so you don't get stuck! # *** see the section on power races in shutdown.txt! *** fi Be careful: that upsdrvctl command will probably power off your machine. Don't use it unless your system is ready to be halted by force. If you run RAID, be sure the arrays are ready to lose power. Your kernel's power-off routines may not execute. Make sure that the filesystem(s) holding your UPS drivers and configuration details are still mounted when that part of the script is run. You need upsdrvctl, ups.conf, and any drivers for the hardware on your system. --------------------------------------------------------------------------- More information can be found in the README file, the shutdown.txt document, the upsmon(8) man page and the upsmon.conf(5) man page.