Imported Upstream version 2.6.0

docs/man/upssched.txt

@@ -0,0 +1,115 @@
+UPSSCHED(8)
+===========
+
+NAME
+----
+
+upssched - Timer helper for scheduling events from upsmon
+
+SYNOPSIS
+--------
+*upssched*
+
+NOTE: *upssched* should be run from linkman:upsmon[8] via the NOTIFYCMD.
+You should never run it directly during normal operations.
+
+DESCRIPTION
+-----------
+
+*upssched* was created to allow users to execute programs at times
+relative to events being monitored by linkman:upsmon[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.
+
+INTEGRATION
+-----------
+
+upssched needs to be called as the NOTIFYCMD in your linkman:upsmon.conf[5].
+It determines what is happening based on the UPSNAME and NOTIFYTYPE
+environment variables.  You should never have to deal with them directly.
+
+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:
+
+	NOTIFYFLAG ONLINE EXEC
+	NOTIFYFLAG ONBATT EXEC
+	NOTIFYFLAG LOWBATT EXEC
+
+If you also want to continue writing to the syslog, just add it in:
+
+	NOTIFYFLAG ONLINE SYSLOG+EXEC
+	NOTIFYFLAG ONBATT SYSLOG+EXEC
+	NOTIFYFLAG LOWBATT SYSLOG+EXEC
+
+For a full list of notify flags, see the linkman:upsmon[8] documentation.
+
+CONFIGURATION
+-------------
+
+See linkman:upssched.conf[5] for information on configuring this program.
+
+EARLY SHUTDOWNS
+---------------
+
+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.
+
+Be sure you cancel the timer if power returns (ONLINE).
+
+DEBOUNCING EVENTS
+-----------------
+
+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 linkman:upsmon[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.
+
+BACKGROUND
+----------
+
+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't have the requirement of shutting down after 'N'
+seconds on battery, since the usual OB+LB testing is sufficient.
+
+This program was created separately so those people don't have to spend
+CPU time and RAM on something that will never be used in their
+environments.
+
+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.
+
+This means that you will only see upssched running when one of two things
+is happening:
+
+ - There's a timer of some sort currently running 
+ - upsmon just called it, and you managed to catch the brief instance
+
+The final optimization handles the possibility of trying to cancel a timer
+when there are none running.  If the timer daemon isn't 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.
+
+FILES
+-----
+
+linkman:upssched.conf[5]
+
+SEE ALSO
+--------
+
+linkman:upsmon[8]
+
+Internet resources:
+~~~~~~~~~~~~~~~~~~~
+The NUT (Network UPS Tools) home page: http://www.networkupstools.org/