'\" t .\" Title: upssched .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author] .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 02/19/2024 .\" Manual: NUT Manual .\" Source: Network UPS Tools 2.8.1 .\" Language: English .\" .TH "UPSSCHED" "8" "02/19/2024" "Network UPS Tools 2\&.8\&.1" "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 "ENVIRONMENT VARIABLES" .sp \fBNUT_DEBUG_LEVEL\fR sets default debug verbosity if no \fB\-D\fR arguments were provided on command line, but does not request that the daemon runs in foreground mode\&. .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 Unlike some other NUT daemons, upssched with enabled debug does not stop reporting on stderr! It forks a background process with the first call as an event handler, which exits soon after all tracked timers have elapsed and were handled (if needed)\&. .sp .5v .RE .sp \fBUPSNAME\fR and \fBNOTIFYTYPE\fR are required, as detailed above\&. They are set by upsmon when it calls upssched as its choice of NOTIFYCMD\&. .sp \fBNUT_CONFPATH\fR is the path name of the directory that contains upssched\&.conf and other configuration files\&. If this variable is not set, \fBupssched\fR uses a built\-in default, which is often /usr/local/ups/etc\&. .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: https://www\&.networkupstools\&.org/