Network UPS Tools - Quick Start for Debian
------------------------------------------

If you have been directed here because of one of the following error messages:
  user "nut" already exists
  group "nut" already exists
then a previous installation of the nut package was not purged successfully or
you already have a user or group named nut that has nothing to do with the nut
package.  The fix is to delete or rename the existing nut user/group.

Anyway, here are the quick start instructions for using nut:

These Quick Start instructions are useful for a UPS connected to a single
machine.  For a UPS connected to multiple machines, additional steps must be
taken, as outlined at the end of this file, including the notice regarding
SECURITY CONSIDERATIONS.

(I) Upgrading
=============

In case of upgrading, follow instructions given in:
/usr/share/doc/nut/UPGRADING

(II) Installation
=================

Note that sample configuration files are provided in 
/usr/share/doc/nut/examples/. Simply copy these under
/etc/nut and follow the below information for tuning.

(1) /etc/nut/ups.conf (see 'man 5 ups.conf' for more information)
    Edit /etc/nut/ups.conf and add something like:
      [myups]
        driver = mge-utalk
        port = /dev/ttyS1
    Use the appropriate driver for your UPS and select the correct port.
    If you wish to test manually whether your configuration of ups.conf is
    correct, you may invoke upsdrvctl by hand:
      /sbin/upsdrvctl start [myups]
      /sbin/upsdrvctl stop [myups]

(2) serial port permissions
    The nut user need to be added to the dialout group for the serial
    communication to work.  The following command accomplishes this:
      addgroup nut dialout

    This is not done by default for security reason.

(3) /etc/nut/upsd.conf (see 'man 5 upsd.conf' for more information)
    Edit /etc/nut/upsd.conf and add something like the following:
      ACL all 0.0.0.0/0
      ACL localhost 127.0.0.1/32
      ACCEPT localhost
      REJECT all
    This will allow local access to upsd data.
    Ensure that the permissions of upsd.conf do not permit the world to
    read it.  It should already be thus, but the following command
    accomplishes this:
      chown root:nut /etc/nut/upsd.conf
      chmod 640 /etc/nut/upsd.conf

(4) /etc/nut/upsd.users (see 'man 5 upsd.users' for more information)
    Edit /etc/nut/upsd.users and add something like the following,
    without the comments, in order to define a user:
      [monmaster]
        password = blah
        allowfrom = localhost
        upsmon master
    Please use *different* usernames and passwords than you use on your
    system; see the note regarding SECURITY CONSIDERATIONS at the end
    of this file.
    Ensure that the permissions of upsd.users do not permit the world to
    read it.  It should already be thus, but the following command
    accomplishes this:
      chown root:nut /etc/nut/upsd.users
      chmod 640 /etc/nut/upsd.users

(5) /etc/nut/upsmon.conf (see 'man 5 upsmon.conf' for more information)
    Edit /etc/nut/upsmon.conf and add something like the following:
      MONITOR myups@localhost 1 monmaster blah master
      POWERDOWNFLAG /etc/killpower
      SHUTDOWNCMD "/sbin/shutdown -h +0"
    Ensure that the permissions of upsmon.conf do not permit the world to
    read it.  It should already be thus, but the following commands
    accomplishes this:
      chown root:nut /etc/nut/upsmon.conf
      chmod 640 /etc/nut/upsmon.conf

(6) /etc/default/nut
    Edit /etc/default/nut and change START_UPSD and START_UPSMON from
    'no' to 'yes'.  For example:
      START_UPSD=yes
      START_UPSMON=yes

(7) start the daemon
    Invoke '/etc/init.d/nut start' to start the daemon(s).  Check
    /var/log/syslog to ensure that upsd, appropriate drivers, and upsmon
    started up correctly.


Additional Notes for Sharing a UPS
----------------------------------
If you have multiple machines connected to the same UPS, you will need to
(a) modify the access control lists in upsd.conf on the server;
(b) add additional users to upsd.users on the server; and
(c) configure upsmon.conf on the clients.

Please note that upsmon on a client machine and upsd on a server machine need
to communicate via your network.  This means that you need to ensure that all
the networking equipment (hub, switch, router, etc.) between the client and the
server is powered by the UPS.  Otherwise, when the power goes down, the network
connection between the client machine will be broken and the client will not
be told to shut down.

SECURITY CONSIDERATIONS
-----------------------
Finally, please be aware of the following SECURITY CONSIDERATIONS:  the TCP
communications between the client daemon, upsmon, and the server daemon, upsd,
send the username and passwords defined in upsd.users and used in upsmon.conf
over the wire UNENCRYPTED.  This means that somebody could sniff the username
and password.  A version that encrypts the connection using SSL should be
available someday.

Please see the documentation in /usr/share/doc/nut/docs for more information.