head	1.5;
access;
symbols;
locks; strict;
comment	@# @;


1.5
date	97.02.20.14.21.38;	author alexis;	state Exp;
branches;
next	1.4;

1.4
date	95.12.13.08.26.21;	author alexis;	state Exp;
branches;
next	1.3;

1.3
date	95.12.12.17.36.03;	author alexis;	state Exp;
branches;
next	1.2;

1.2
date	95.12.12.16.58.17;	author alexis;	state Exp;
branches;
next	1.1;

1.1
date	95.12.12.16.45.53;	author alexis;	state Exp;
branches;
next	;


desc
@MANUAL PAGE FOR UPSD(8)
@


1.5
log
@Updated my email address.
@
text
@.TH UPSD 1 "11 December 1995"
.SH NAME
upsd \- shutdown in event of power failure
.br
.\"
.\" we don't need a .br/.ne 5 here since there
.\" isn't any chance really, that we're already
.\" anywhere near the end of the first page.
.\"
.\" Version information
.\" $Id: upsd.8,v 1.4 1995/12/13 08:26:21 alexis Exp alexis $
.\"
.SH SYNOPSIS
.B "upsd \-V"
.br
.B "upsd"
[ 
.B \-d
.I level
| -v ] [
.B \-ic
] [ 
.B \-iw
] [ 
.B \-is
] [ 
.B \-pc
.I program
] [ 
.B \-pw
.I program
] [ 
.B \-ps
.I program
] 
.I port
.br
.\"
.\" we don't need a .br/.ne 5 here since there
.\" isn't any chance really, that we're already
.\" anywhere near the end of the first page.
.\"
.SH DESCRIPTION
This man page documents 
.I upsd 
version 1.18.
.PP
.I Upsd
is intended to be run in the manner of a 
daemon. It monitors the signal lines provided
on an external UPS and shuts down the machine in the
event of a mains power failure.
.PP 
In the event of a mains power failure, 
.I upsd
first calls
.I wall\fR(1)
to regularly inform users of the situation and of 
how much of the shutdown interval time remains. 
Once this time has elapsed,
.I upsd
calls 
.I shutdown\fR(8)
with appropriate options to immediately shut down the
machine. In the event that mains power is restored
before the shutdown interval has elapsed, then 
.I upsd
calls 
.I wall\fR(1)
again to inform users of the change in situation.
.PP
.I Upsd
honours 
.I uucp\fR(1)
style lock files generated by other programs
is capable of detecting stale locks files. 
.PP
Once
.I upsd
has processed all options and is about to settle
down to its monitoring cycle, then all notable events
are recorded via 
.I syslog\fR(8).
.br
.ne 5
.SH OPTIONS
.\"  This indents everything after the next line by 25 somethings.
.TP 25
.B \-V
Print the version number and exit.
.TP
.B \-d \fIlevel
Sets the debug level. If 
.I level
is set to 0, then not even 
error messages will be reported.
If 
.I level 
is set to 1, then only error messages will be reported.
If 
.I level
is set to 2, which is the default, then
error and warning messages will be reported. If
.I level
is set to 3, then additional informational messages 
will also be reported. If 
.I level
is set to 4 or greater then additional debugging 
messages are reported.
.TP
.B \-v
Equivalent to 
.B \-d
3.
.TP
.B \-ic \fIsecs
Sets the interval between mains power checks to 
\fIsecs\fR seconds. The default is 1 second.
.TP
.B \-iw \fIsecs
Sets the intervals between warning messages sent to
users in the event of a mains power failure to \fIsecs\fR
seconds. The default is 30 seconds.
.TP
.B \-is \fIsecs
Sets the interval between mains power failure and 
system shutdown to \fIsecs\fR seconds. The default
is 240 seconds.
.TP
.B \-pw \fIprogram
Specifies that \fIprogram\fR should be run when
otherwise a message would be sent to all users 
warning of an impending shutdown. \fIprogram\fR
is called without command line parameters but
with status information set in the environment.
See ENVIRONMENT below for more details.
.TP
.B \-pc \fIprogram
Specifies that \fIprogram\fR should be run when
otherwise a message would be sent to all users 
informing them that the impending shutdown has
been cancelled. \fIprogram\fR
is called without command line parameters but
with status information set in the environment.
See ENVIRONMENT below for more details.
.TP
.B \-ps \fIprogram
Specifies that \fIprogram\fR should be run when
otherwise the system would be shut down. \fIprogram\fR
is called without command line parameters but
with status information set in the environment.
See ENVIRONMENT below for more details.
.PD
.br
.ne 5
.SH EXAMPLES
It is envisaged that 
.I upsd
will be started from 
.B /etc/rc.local
(See 
.I rc\fR(8)) with a command such as:
.IP
.nf
/usr/local/bin/upsd -is 300 /dev/tty00
.fi
.PP
or perhaps in a country where English is not
the spoken language:
.IP
.nf
/usr/local/bin/upsd -is 300 -pw /usr/local/bin/upsd.warn -pc \\
    /usr/local/bin/upsd.canc /dev/tty00
.fi
.PP
where the shutdown interval is appropriate to the length
of time that the UPS can deliver battery power after a mains power failure.
.br
.ne 5
.SH DIAGNOSTICS
Most of the messages produced by 
.I upsd
are self-explanatory, those that are not
are described here:
.PD 0
.TP 25
.B upsd: ERROR: can't find user 'uucp'
Depending on the environment in which 
.I upsd
was built,
.I upsd
may try to set the owner of any lock file it creates to 'uucp'.
If such a user does not exist on your system then 
.I upsd
will report an error.
.br
.ne 5
.PD
.SH WARNINGS
None.
.br
.ne 5
.SH FILES
.PD 0
.TP 25
.B /etc/passwd
Used to identify the user 'uucp.'
.TP 25
.B /var/spool/uucp/LCK..\fIport
Lock file created by 
.I upsd\fR.
.PD
.br
.ne 5
.SH ENVIRONMENT VARIABLES
.I Upsd
does not make use of any enviroment variables itself, but does
add the following to the enviroment before calling any of 
the programs specified
with the \fI-pw\fR, \fI-pc\fR or \fI-ps\fR options:
.PD 0
.TP 25
.B UPSD_STATE
Set to \fBimpending\fR, \fBcancelled\fR or \fBimmediate\fR
in correspondance with the shutdown scheduled as a 
result of mains power failure.
.TP 25
.B UPSD_INTERVAL
If 
.B UPSD_STATE
is set to
.B impending
then this environment variable is set to the interval 
after which the shut down will activated. The interval
is measured in seconds.
.PD
.br
.ne 5
.SH SEE ALSO
shutdown(8),
passwd(5),
uucico(8),
wall(1),
write(1)
.br
.ne 5
.SH STATUS
Very unstable, only just written!
.br
.ne 5
.SH AUTHOR
Alexis Huxley <alexis@@danae.demon.co.uk>
.br
.ne 5
.SH BUGS
.I Upsd
does not understand that after mains power has been restored
before the shutdown interval has elapsed, that the UPS will 
not be capable of delivering battery power for the same
warning interval
should the mains power fail a second time before the batteries
in the UPS have been fully recharged.
.br
.ne 5
.SH FUTURE DEVELOPMENT
Secure support for shutting down remote machines should be added.
.PP
.I Upsd
should create a sensible /etc/nologin.
@


1.4
log
@Fixes missing backslash on continued line.
Name of lockfile.
Added RCS string.
@
text
@d11 1
a11 1
.\" $Id$
d252 1
a252 1
Alexis Huxley <alexis@@uvt.tuzvo.sk>
@


1.3
log
@Bumped upsd version number.
@
text
@d10 3
d172 2
a173 2
/usr/local/bin/upsd -is 300 -pw /usr/local/bin/upsd.warn -pc
/usr/local/bin/upsd.canc /dev/tty00
d209 1
a209 1
.B /var/spool/uucp/LCK../\fIport
@


1.2
log
@Added info specifying default times and
that upsd.c has bumped version number
as a result of interval changes.
@
text
@d43 1
a43 1
version 1.17.
@


1.1
log
@Initial revision
@
text
@d43 1
a43 1
version 1.16.
d115 1
a115 1
\fIsecs\fR seconds.
d120 1
a120 1
seconds.
d124 2
a125 1
system shutdown to \fIsecs\fR seconds.
@