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 page>
man -M /usr/local/ups/man upsd.conf
============================================================================
============================================================================
============================================================================
Prepare your system
===================
1. Create at least one user and a group for running this software.
You might call it "nut" or "ups". The exact name isn'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 both be "nut".
============================================================================
============================================================================
============================================================================
Build and install
=================
1. Configure the source tree for your system. Add the --with-user
switch to set the user name that you created above. If you need
any other switches for configure, add them here.
./configure --with-user=nut
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
---------------------------------------------------------------------------
3. Gain privileges for installing software if necessary.
su
---------------------------------------------------------------------------
4. Install the files to a system level directory.
make install
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
---------------------------------------------------------------------------
5. Create a directory for the driver(s) and server to use for data,
and make it owned by the user you created.
mkdir /var/state/ups
chmod 0700 /var/state/ups
chown nut: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. Serial port device names vary greatly, so yours
may be quite different.
chmod 0600 /dev/ttyS1
chown nut:nut /dev/ttyS1
NOTE: if you are using something like devfs, make sure these
permissions do not reset themselves when your system reboots.
Otherwise, your driver(s) may fail to start.
---------------------------------------------------------------------------
7. Create section(s) for your hardware in /usr/local/ups/etc/ups.conf
To find out which driver to use, check the "HARDWARE SUPPORT TABLE"
in the README file, or docs/driver.list.
Once you have picked a driver, create an entry for your UPS in
ups.conf. If the driver does not need any extra configuration
options, then it should resemble this:
[myupsname]
driver = mydriver
port = /dev/ttyS1
desc = "Workstation"
*** 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
If the driver doesn't start cleanly, make sure you're starting the
right one for your hardware. Also check the man page for the
driver to see if there are any extra values that you can set.
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.
After making changes, try step 6 again.
*** References: man pages: nutupsdrv(8), upsdrvctl(8)
---------------------------------------------------------------------------
9. Configure the network server (upsd). The files that need your
attention are upsd.conf and upsd.users. Sample versions are
installed in most cases.
At the very least, you need something like this in upsd.conf:
ACL all 0.0.0.0/0
ACL localhost 127.0.0.1/32
ACCESS grant monitor localhost
ACCESS deny all all
That much is already in the sample upsd.conf, so just copying that
to the proper name should get you started. You should add
additional ACL/ACCESS directives for other hosts/networks that need
to talk to upsd on this system.
Note: upsd.conf and upsd.users must not be world-readable, since
they control access controls and passwords. They do need to be
readable by the user you created in the preparation process.
The suggested configuration is to make it owned by that user,
mode 0400:
chown nut:nut upsd.conf upsd.users
chmod 0400 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
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.
Nothing else will work until you fix it.
*** Reference: man page: upsd(8)
---------------------------------------------------------------------------
11. Make sure that the UPS is providing good status data.
/usr/local/ups/bin/upsc myupsname@localhost
Ignore everything but "ups.status" for now. If your system is
running on line power, it should have "OL" in that field.
Otherwise, something is wrong with the driver that was configured in
step 5.
If upsc says "access denied", then your upsd.conf probably doesn't
have a good ACL/ACCESS definition for your host.
*** Reference: man page: upsc(8)
---------------------------------------------------------------------------
12. 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. Configure upsd to recognize upsmon.
First create an ACL in upsd.conf for the host that will be running
upsmon. Be sure to grant it monitor privileges with an ACCESS line.
This will allow upsmon to connect to upsd.
ACL all 0.0.0.0/0
ACL mybox a.b.c.d/32
ACCESS grant monitor mybox
ACCESS deny all all
*** References: man pages: upsd(8), upsd.conf(5)
---------------------------------------------------------------------------
2. Edit upsd.users, and create a user for upsmon to use. This will
allow upsmon to coordinate shutdowns with other systems.
[monuser]
password = mypass
allowfrom = mybox
upsmon master (or upsmon slave)
*** References: man pages: upsd(8), upsd.users(5)
---------------------------------------------------------------------------
3. Edit upsmon.conf, and create a MONITOR directive with that host,
username, and password.
MONITOR myupsname@mybox 1 monuser mypass master (or slave)
Also check the POWERDOWNFLAG to make sure it's what you want.
*** References: man pages: upsmon(8), upsmon.conf(5)
---------------------------------------------------------------------------
4. 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.
---------------------------------------------------------------------------
5. Start upsmon.
/usr/local/ups/sbin/upsmon
---------------------------------------------------------------------------
6. 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@a.b.c.d logged into UPS [myupsname]
---------------------------------------------------------------------------
7. 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.
---------------------------------------------------------------------------
8. 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
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.
