apcupsd-ups: ignore generated files

[networkupstools/kirr.git] / docs / scheduling.txt

Advanced usage and scheduling notes
===================================

upsmon can call out to a helper script or program when the device changes
state.  The example upsmon.conf has a full list of which state changes
are available - ONLINE, ONBATT, LOWBATT, and more.

There are two options, that will be presented in details:

- the simple approach: create your own helper, and manage all events and actions
yourself,
- the advanced approach: use the NUT provided helper, called 'upssched'.


The simple approach, using your own script
------------------------------------------

How it works relative to upsmon
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Your command will be called with the full text of the message as one argument.

For the default values, refer to the sample upsmon.conf file.

The environment string NOTIFYTYPE will contain the type string of whatever
caused this event to happen - ONLINE, ONBATT, LOWBATT, ...

Making this some sort of shell script might be a good idea, but the helper can
be in any programming or scripting language.

NOTE: Remember that your helper must be *executable*. If you are using a script,
make sure the execution flags are set.

For more information, refer to linkman:upsmon[8] and
linkman:upsmon.conf[5] manual pages.

Setting up everything
~~~~~~~~~~~~~~~~~~~~~

- Set EXEC flags on various things in linkman:upsmon.conf[5]:
+
        NOTIFYFLAG ONBATT EXEC
        NOTIFYFLAG ONLINE EXEC
+
If you want other things like WALL or SYSLOG to happen, just add them:
+
        NOTIFYFLAG ONBATT EXEC+WALL+SYSLOG
+
You get the idea.

- Tell upsmon where your script is

        NOTIFYCMD /path/to/my/script

- Make a simple script like this at that location:   

        #! /bin/bash
        echo "$*" | sendmail -F"ups@mybox" bofh@pager.example.com

- Restart upsmon, pull the plug, and see what happens.

That approach is bare-bones, but you should get the text content of the
alert in the body of the message, since upsmon passes the alert text
(from NOTIFYMSG) as an argument.

Using more advanced features
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Your helper script will be run with a few environment variables set.  

- UPSNAME: the name of the system that generated the change.
+
This will be one of your identifiers from the MONITOR lines in upsmon.conf.

- NOTIFYTYPE: this will be ONLINE, ONBATT, or whatever event took place which
made upsmon call your script.

You can use these to do different things based on which system has
changed state.  You could have it only send pages for an important
system while totally ignoring a known trouble spot, for example.

Suppressing notify storms
~~~~~~~~~~~~~~~~~~~~~~~~~

upsmon will call your script every time an event happens that has the EXEC flag
set.  This means a quick power failure that lasts mere seconds might generate a
notification storm.  To suppress this sort of annoyance, use upssched as your
NOTIFYCMD program, and configure it to call your command after a timer has
elapsed.


The advanced approach, using upssched
-------------------------------------

upssched is a helper for upsmon that will invoke commands for you at some
interval relative to a UPS event.  It can be used to send pages, mail out
notices about things, or even shut down the box early.

There will be examples scattered throughout.  Change them to suit your
pathnames, UPS locations, and so forth.

How upssched works relative to upsmon
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When an event occurs, upsmon will call whatever you specify as a 'NOTIFYCMD'
in your upsmon.conf, if you also enable the 'EXEC' in your 'NOTIFYFLAGS'.  In
this case, we want upsmon to call upssched as the notifier, since it will
be doing all the work for us.  So, in the upsmon.conf:

        NOTIFYCMD /usr/local/ups/bin/upssched

Then we want upsmon to actually _use_ it for the notify events, so again
in the upsmon.conf we set the flags:

        NOTIFYFLAG ONLINE SYSLOG+EXEC
        NOTIFYFLAG ONBATT SYSLOG+WALL+EXEC
        NOTIFYFLAG LOWBATT SYSLOG+WALL+EXEC
        ... and so on.

For the purposes of this document I will only use those three, but you can set
the flags for any of the valid notify types.

Setting up your upssched.conf
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Once upsmon has been configured with the NOTIFYCMD and EXEC flags, you're
ready to deal with the upssched.conf details.  In this file, you specify
just what will happen when a given event occurs on a particular UPS.

First you need to define the name of the script or program that will
handle timers that trigger.  This is your CMDSCRIPT, and needs to be above
any AT defines.  There's an example provided with the program, so we'll
use that here:

        CMDSCRIPT /usr/local/ups/bin/upssched-cmd

Then you have to define the variables PIPEFN and LOCKFN; the former
sets the file name of the FIFO that will pass communications between
processes to start and stop timers, while the latter sets the file name
for a temporary file created by upssched in order to avoid a race condition
under some circumstances. Please see the relevant comments in upssched.conf
for additional information and advice about these variables.

Now you can tell your CMDSCRIPT what to do when it is called by upsmon.

The big picture
^^^^^^^^^^^^^^^

The design in a nutshell is:

        upsmon ---> calls upssched ---> calls your CMDSCRIPT

Ultimately, the CMDSCRIPT does the actual useful work,  whether that's
initiating an early shutdown with 'upsmon -c fsd', sending a page by
calling sendmail, or opening a subspace channel to V'ger.

Establishing timers
^^^^^^^^^^^^^^^^^^^

Let's say that you want to receive a page when any UPS has been running on
battery for 30 seconds.  Create a handler that starts a 30 second timer
for an ONBATT condition.

        AT ONBATT * START-TIMER onbattwarn 30

This means "when any UPS (the *) goes on battery, start a timer called
onbattwarn that will trigger in 30 seconds".  We'll come back to the
onbattwarn part in a moment.  Right now we need to make sure that we 
don't trigger that timer if the UPS happens to come back before the
time is up.  In essence, if it goes back on line, we need to cancel it.
So, let's tell upssched that.

        AT ONLINE * CANCEL-TIMER onbattwarn

Executing commands immediately
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

As an example, consider the scenario where a UPS goes onto battery power.
However, the users are not informed until 60 seconds later - using a timer as
described above. Whilst this may let the *logged in* users know that the UPS
is on battery power, it does not inform any users subsequently logging in. To
enable this we could, at the same time, create a file which is read and
displayed to any user trying to login whilst the UPS is on battery power. If
the UPS comes back onto utility power within 60 seconds, then we can cancel
the timer and remove the file, as described above. However, if the UPS comes
back onto utility power say 5 minutes later then we do not want to use any
timers but we still want to remove the file. To do this we could use:

        AT ONLINE * EXECUTE ups-back-on-power

This means that when upsmon detects that the UPS is back on utility power it
will signal upssched. Upssched will see the above command and simply pass
'ups-back-on-power' as an argument directly to CMDSCRIPT. This occurs
immediately, there are no timers involved.

Writing the command script handler
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

OK, now that upssched knows how the timers are supposed to work, let's
give it something to do when one actually triggers.  The name of the
example timer is onbattwarn, so that's the argument that will be passed
into your CMDSCRIPT when it triggers.  This means we need to do some
shell script writing to deal with that input.

--------------------------------------------------------------------------------

        #! /bin/sh

        case $1 in
                onbattwarn)
                        echo "The UPS has been on battery for awhile" \
                        | mail -s"UPS monitor" bofh@pager.example.com
                        ;;
                ups-back-on-power)
                        /bin/rm -f /some/path/ups-on-battery
                        ;;
                *)
                        logger -t upssched-cmd "Unrecognized command: $1"
                        ;;
        esac

--------------------------------------------------------------------------------

This is a very simple script example, but it shows how you can test for
the presence of a given trigger.  With multiple ATs creating various timer
names, you will need to test for each possibility and handle it according
to your desires.

NOTE: You can invoke just about anything from inside the CMDSCRIPT.  It doesn't
need to be a shell script, either - that's just an example.  If you want to
write a program that will parse argv[1] and deal with the  possibilities, that
will work too.


Early Shutdowns
~~~~~~~~~~~~~~~

One thing that gets requested a lot is early shutdowns in upsmon.  With
upssched, you can now have this functionality.  Just set a timer for some
length of time at ONBATT which will invoke a shutdown command if it elapses.
Just be sure to cancel this timer if you go back ONLINE before then.

The best way to do this is to use the upsmon callback feature.  You can
make upsmon set the "forced shutdown" (FSD) flag on the upsd so your
slave systems shut down early too.  Just do something like this in your
CMDSCRIPT:

        /usr/local/ups/sbin/upsmon -c fsd

It's not a good idea to call your system's shutdown routine directly 
from the CMDSCRIPT, since there's no synchronization with the slave
systems hooked to the same UPS.  FSD is the master's way of saying
"we're shutting down *now* like it or not, so you'd better get ready".


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:

 1. There's a timer of some sort currently running 
 2. 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's none running.  If there's no process already running, there
are no timers to cancel, and furthermore there is no need to start a
clock-watcher.  As a result, it skips that step and exits sooner.