 		POWERD-2.0
		==========

			Alessandro Rubini  --  rubini@ipvvis.unipv.it


Note that this document is updated less frequently than the soft.  If
this doc tells something is there, it is there. If it tells something
is still missing, it may be there as well. I hope to remember to
upgrade README before releasing the true 2.0, though I may forget to.

						September 25th 1995

What's new
----------

This release of powerd is meant to replace and upgrade the simple
powerd-1.1 which comes in the package "SysVInit-2.5" by Miquel van
Smoorenburg. I didn't manage to reach Miquel to agree about distribution.
I hope he's happy with this program. Miquel, are you there?

The main goal of this program is to avoid hacking the source code of
powerd to tailor it to the specific ups used. powerd-2.0 is designed to
handle different sources of information, and its modular design
should allow ease extension by those who have a peculiar setup.

The powerd daemon can be told to accept connection on a TCP socket, so that
other powerd's can benefit from an ups-aware one. Powerd can connect to
another powerd as a client. This is a better approach than a broadcast
notification of power status, because the latter can be easily faked.

Since some ups's allow shutting down, to preserve their battery in
order to correctly handle glitches when the power comes back, you can
specify to shutdown the ups by toggling some lines on the serial
cable. If you know other ways to shutdown the ups, please tell me,
and I'll implement it (or send me the code to get a note in the
CREDITS file ;-)

A "powerd.conf" file is used to exactly specify how to behave.


An Alternative
--------------

If you're going to control a single computer from your ups, perhaps you'd
better look at genpower, by Tom Webster (on sunsite and mirrors in the
directory system/UPS). Tom's package is very well documented and quite
easy to setup. However, it doesn't manage network connections.

Since we (Tom and me) are planning to merge the two packages, we'd be
happy to have some feedback about pros and cons of each product. Unfortunately,
it could take some time before we have time to merge our works.



Agents
------

An "agent" is a program section which monitors a source of information,
and tells the main program what to do. Powerd uses a single agent to
get information about powerd lines, but several of them are compiled in,
to allow runtime selection. The following agents are supported:

* Network client: powerd connects to another host and waits for
	information. It uses an udp socket, and can be configured to poll
	the server (every few minutes or so) in order to "keep connected"
	the connectionless link. Powerd can act as a network server,
	independently of the agent being used.

* Serial line: the daemon monitors a serial wire. This is what
	powerd-1.1 used to do, and works with relay-base ups's.
	You can specify which line to monitor and what is the meaning of
	the line voltages.

* Fifo: powerd monitors a fifo node on the filesystem. This is the easiest way
	to fake power glitches in order to test shutdown and reboot of the
	system. Note that current kernels deny writing to a fifo on a 
	read-only filesystem. This is a problem in complete testings.
	The fifo agent is best used in "disabled" mode, to drive a network
	server.

* External program: spawn an executable and monitor its standard output.
	The program is executed through "popen", so you can specify a
	full commandline, complete with stdin redirection.
	This agent is meant for those who have
	an ups which talks to a real serial connection, and to relief me from
	serial setup. Obviously, if you want to write an agent for a true
	serial connection, I'll	include it in the next powerd.



What's missing
--------------

The interface to "init" suits SysVInit-2.4 for Linux and later.  I'd
like to make this tool as portable as possible, but I've no spare
workstations to shut down -- when I'm so lucky to be root I can't
shutdown anything, except my own Linux box. The source is almost ready
to be portable, I just lack information to do it.

I would like to ease addition and removal of agents, by specifying a
clean interface between the main body and the agents (I'm dreaming
abot dynamic loading). Currently, the main problem is the centralized
static variable-set.  I don't know if I'll ever do it, I suppose it
depends on the amount of feedback I get.



Powerd.conf
-----------

Browse the sample configuration file. Some skeletal information is in the
manual page, but the sample file is still the reliable doc.



Command line
------------

The following invocations work:

powerd
	Read /etc/powerd.conf and go for it. the configuration file
	can specify any of the following behaviours, if needed. Ideally,
	your bootstrap files should invoke powerd with no arguments, while
	the commandline is meant to be used for testing purposes.

powerd [anything] -host <host> <port>
	Be a client. Wait for the strings "OK" and "FAIL". The
	configuration file is not read.

powerd [anything] -port port
	Be the server. This is independent of the agent used, which is
	specified by the previous options or by the configuration
	file.

powerd <file> [options]
	If "file" is a regular one, use it as config file; if it is a char
	device, emulate powerd-1.1 (monitor DCD going low, after asserting
	DTR high); if it is a fifo, use the fifo agent on it.

powerd "<variable>=<value>" [...]
	Any agument embedding an equal sign is used like it was a line
	of the configuration file.

As an example, the following two commandlines make a fifo-controlled
client/server pair to try workings


./powerd debug=y disabled=y readfifo=/var/run/upsctl -port 2065

./powerd debug=y disabled=y delay=0 pollingstep=2 -host localhost 2065



Installing
----------

Just "make" and "make install", the executable will go in /sbin and
the configuration file in /etc.  The man page is not installed (my
fault).  To install under /usr/sbin and /usr/etc just "make
PREFIX=/usr" and "make install PREFIX=/usr". Same for /usr/local;
specifying the prefix during compilation is only needed to instruct
the program to use the right powerd.conf as a default case. Note that
powerd and powerd.conf must reside in the root filesystem in order fro
your computer to be able to wake up from singleuser-ness.

During installation, an existing powerd executable will be
orerwritten, while an existing configuration file will be preserved.



How to setup your bootstrap files
---------------------------------

You should modify your initialization files in the following way.
I use the file names of my old slackware installation, you should 
modify the corresponding files of your system. Each file gets its role
from its appearing in /etc/inittab.


/etc/rc.d/rc.K (the file appearing in the "su:S:wait:" inittab line)

	This script is executed when going down to single-user mode.
	You should invoke powerd at the end of this script: you'll
	need the daemon to awake the system when power is back, or to
	shutdown the ups to actually put the system to sleep. If the ups
	is not shutdown, your computer will turn off at battery exaustion.

/etc/rc.d/rc.S (the file appearing in the "si:S:sysinit" inittab line)

	This is the first script that gets executed at system boot.
	You should invoke powerd at the end of this script. rc.S is not
	executed during recovery from a single-user shutdown, but when that
	happens the daemon invoked by rc.K is still alive and well.

/etc/rc.d/rc.M (the file appearing in the "rc:45:wait" inittab line)

	Remember to put a "/sbin/swapon -a" in *this* file.
	Slackware puts it in rc.S (wise thing, anyways, but not sufficient).
	Otherwise you'll recover from a power fail without any swap
	(my small machine just hangs). There's no need to invoke powerd from
	this file, it would be a second instance of the program.
	To avoid an error message of "device busy" on first system boot,
	you could use "/sbin/swapon -a 2> /dev/null" instead; otherwise
	you could remove swapon invocation from rc.S. 


The preferred way to invoke powerd from the rc files is the following:

	if [ -f /sbin/powerd ]; then
		echo "Running powerd"
		/sbin/powerd &
	fi

It is important to put the daemon to the background, because
if you forgot debugging enabled in /etc/powerd.conf you'll hang your computer
before any login is spawned.



Testing your cable
------------------

If your ups is a relay-based one, it is most likely that you don't
know how your serial cable has to be set up. The program
"setserialbits", in this distribution, is a small yet effective tool
to probe your serial connection. The program should be
self-explicative, so I won't discuss it here.

Sure you need some knowledge of how to setup a serial line. Since
Tom's documentation is really complete (see above: "An alternative").
I won't duplicate the information here. SysVInit-2.50 holds some
explanation of it as well, and the UPS-HOWTO may be another helpful
document.


Additional tips
---------------

The serial line doesn't need to have a dedicated interrupt line,
you can add "setserial /dev/cua2 irq 0" or sth similar to your rc files.

Be careful about the owner and the permission of the serial port, fifo
or external daemon you use. Malicious users could fake a powerfail to
bring the system down.

If your ups cannot be turned off, you'd better not put the console
display under the ups: when the computer is in single-user mode, the
console holds a root shell. An unattended console with a root shell is 
something slightly unsecure. I didn't analyze the problem, but I think
this is harwired in init.

Be careful about time delays if you use the network to shutdown multiple
computers: you should be careful not to turn off the ups before *all*
of your computers unmount their disks. This time interval depends on
the pollingstep of the clients. A future release of powerd may
handle some client-server dialog to agree about this. 


Enjoy
-----

Go for it. Please report any bugs to me.


/alessandro

