nut/docs/man/upssched.8

'\" t
.\"     Title: upssched
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\"      Date: 05/31/2011
.\"    Manual: NUT Manual
.\"    Source: Network UPS Tools
.\"  Language: English
.\"
.TH "UPSSCHED" "8" "05/31/2011" "Network UPS Tools" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
upssched \- Timer helper for scheduling events from upsmon
.SH "SYNOPSIS"
.sp
\fBupssched\fR
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
\fBupssched\fR should be run from \fBupsmon\fR(8) via the NOTIFYCMD\&. You should never run it directly during normal operations\&.
.sp .5v
.RE
.SH "DESCRIPTION"
.sp
\fBupssched\fR was created to allow users to execute programs at times relative to events being monitored by \fBupsmon\fR(8)\&. The original purpose was to allow for a shutdown to occur after some fixed period on battery, but there are other uses that are possible\&.
.SH "INTEGRATION"
.sp
upssched needs to be called as the NOTIFYCMD in your \fBupsmon.conf\fR(5)\&. It determines what is happening based on the UPSNAME and NOTIFYTYPE environment variables\&. You should never have to deal with them directly\&.
.sp
Set the EXEC flag on the events that you want to see in upssched\&. For example, to make sure that upssched hears about ONLINE, ONBATT and LOWBATT events, the flags would look like this:
.sp
.if n \{\
.RS 4
.\}
.nf
NOTIFYFLAG ONLINE EXEC
NOTIFYFLAG ONBATT EXEC
NOTIFYFLAG LOWBATT EXEC
.fi
.if n \{\
.RE
.\}
.sp
If you also want to continue writing to the syslog, just add it in:
.sp
.if n \{\
.RS 4
.\}
.nf
NOTIFYFLAG ONLINE SYSLOG+EXEC
NOTIFYFLAG ONBATT SYSLOG+EXEC
NOTIFYFLAG LOWBATT SYSLOG+EXEC
.fi
.if n \{\
.RE
.\}
.sp
For a full list of notify flags, see the \fBupsmon\fR(8) documentation\&.
.SH "CONFIGURATION"
.sp
See \fBupssched.conf\fR(5) for information on configuring this program\&.
.SH "EARLY SHUTDOWNS"
.sp
To shut down the system early, define a timer that starts due to an ONBATT condition\&. When it triggers, make your CMDSCRIPT call your shutdown routine\&. It should finish by calling upsmon \-c fsd so that upsmon gets to shut down the slaves in a controlled manner\&.
.sp
Be sure you cancel the timer if power returns (ONLINE)\&.
.SH "DEBOUNCING EVENTS"
.sp
If your UPS goes on and off battery frequently, you can use this program to reduce the number of pager messages that are sent out\&. Rather than sending pages directly from \fBupsmon\fR(8), use a short timer here\&. If the timer triggers with the UPS still on battery, then send the page\&. If the power returns before then, the timer can be cancelled and no page is necessary\&.
.SH "BACKGROUND"
.sp
This program was written primarily to fulfill the requests of users for the early shutdown scenario\&. The "outboard" design of the program (relative to upsmon) was intended to reduce the load on the average system\&. Most people don\(cqt have the requirement of shutting down after \fIN\fR seconds on battery, since the usual OB+LB testing is sufficient\&.
.sp
This program was created separately so those people don\(cqt have to spend CPU time and RAM on something that will never be used in their environments\&.
.sp
The design of the timer handler is also geared towards minimizing impact\&. It will come and go from the process list as necessary\&. When a new timer is started, a process will be forked to actually watch the clock and eventually start the CMDSCRIPT\&. When a timer triggers, it is removed from the queue\&. Cancelling a timer will also remove it from the queue\&. When no timers are present in the queue, the background process exits\&.
.sp
This means that you will only see upssched running when one of two things is happening:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
There\(cqs a timer of some sort currently running
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
upsmon just called it, and you managed to catch the brief instance
.RE
.sp
The final optimization handles the possibility of trying to cancel a timer when there are none running\&. If the timer daemon isn\(cqt running, there are no timers to cancel, and furthermore there is no need to start a clock\-watcher\&. So, it skips that step and exits sooner\&.
.SH "FILES"
.sp
\fBupssched.conf\fR(5)
.SH "SEE ALSO"
.sp
\fBupsmon\fR(8)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/