nut-debian/INSTALL

523 lines
18 KiB
Plaintext
Raw Normal View History

2010-03-26 01:20:59 +02:00
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
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
(<upsname>@<hostname>), 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.