# Network UPS Tools - upssched.conf sample file
#
# NOTE: Contents of this file should be pure ASCII (character codes
# not in range would be ignored with a warning message).
#

# ============================================================================
# DEBUG_MIN <num>
#
# Optionally specify a minimum debug level for `upssched` daemon or client,
# e.g. for troubleshooting a deployment without a need to edit consumer
# configuration.
# Note that command-line option `-D` can only increase this verbosity level.
# Also note that the configuration file is processed line by line, so you
# may want to set this option early on.
#
# DEBUG_MIN 6

# ============================================================================
#
# CMDSCRIPT <scriptname>
#
# This script gets called to invoke commands for timers that trigger.
# It is given a single argument - the <timername> in your
# AT ... START-TIMER defines.
#
# *** This must be defined *before* the first AT line.  Otherwise the
#     program will complain and exit without doing anything.
#
# A shell script with a big case..esac construct should work nicely for this.
# An example has been provided to help you get started.

CMDSCRIPT /usr/bin/upssched-cmd

# ============================================================================
#
# PIPEFN <filename>
#
# This sets the file name of the FIFO that will pass communications between
# processes to start and stop timers.  This should be set to some path where
# normal users can't create the file, due to the possibility of symlinking
# and other evil.
#
# Note: if you are running Solaris or similar, the permissions that
# upssched sets on this file *are not enough* to keep you safe.  If
# your OS ignores the permissions on a FIFO, then you MUST put this in
# a protected directory!
#
# Note 2: by default, upsmon will run upssched as whatever user you have
# defined with RUN_AS_USER in upsmon.conf.  Make sure that user can
# create files and write to files in the path you use for PIPEFN and
# LOCKFN.
#
# My recommendation: create a special directory for upssched, make it
# owned by your upsmon user, then use it for both.
#
# This is commented out by default to make you visit this file and think
# about how your system works before potentially opening a hole.
#
# PIPEFN /var/lib/nut/upssched/upssched.pipe

# ============================================================================
#
# LOCKFN <filename>
#
# REQUIRED.  This was added after version 1.2.1.
#
# upssched needs to be able to create this filename in order to avoid
# a race condition when two events are dispatched from upsmon at nearly
# the same time.  This file will only exist briefly.  It must not be
# created by any other process.
#
# You should put this in the same directory as PIPEFN.
#
# LOCKFN /var/lib/nut/upssched/upssched.lock

# ============================================================================
#
# AT <notifytype> <upsname> <command>
#
# Define a handler for a specific event <notifytype> on UPS <upsname>.
#
# <upsname> can be the special value * to apply this handler to every
# possible value of <upsname>.
#
# Run the command <command> via your CMDSCRIPT when it happens.
#
# Note that any AT that matches both the <notifytype> and the <upsname>
# for the current event will be used.

# ============================================================================
#
# Possible AT commands
#
# - START-TIMER <timername> <interval>
#
#   Start a timer called <timername> that will trigger after <interval>
#   seconds, calling your CMDSCRIPT with <timername> as the first
#   argument. Each invocation starts an independent timer, even if the
#   <timername> was already registered and started (note this can mess
#   up subsequent CANCEL-TIMER operations).
#
#   Example:
#   1) Start a timer that will execute when communication with any UPS (*) has
#   been gone for 10 seconds
#
#   AT COMMBAD * START-TIMER upsgone 10
#
#   2) Start a timer that will execute when any UPS (*) has been running
#   on battery for 30 seconds
#
#   AT ONBATT * START-TIMER onbattwarn 30

#   -----------------------------------------------------------------------
#
# - START-TIMER-SHARED <timername> <interval>
#
#   Start a timer called <timername> that will trigger after <interval>
#   seconds, calling your CMDSCRIPT with <timername> as the first
#   argument. Each invocation checks if the <timername> was already
#   started, and if so -- appends the current event's `UPSNAME`,
#   `NOTIFYTYPE` and `NOTIFYMSG` to the list of unique values it would
#   report via environment variables (as a comma-separated string) when
#   the timer does execute.
#
#   NOTE: Currently this updates the first seen instance with the
#   <timername> (in case you managed to start many).
#
#   Example:
#   1) Start or update a timer that will execute when communication
#   with any UPS (*) has been gone for 10 seconds (since the first
#   started and not yet elapsed timer named <upsgone>):
#
#   AT COMMBAD * START-TIMER upsgone 10

#   -----------------------------------------------------------------------
#
# - CANCEL-TIMER <timername> [cmd]
#
#   Cancel a running timer called <timername>, if possible. If the timer
#   has passed then pass the optional argument <cmd> to CMDSCRIPT.
#
#   Example:
#   1) If a specific UPS (myups@localhost) communication is restored, then stop
#   the timer before it triggers
#
#   AT COMMOK myups@localhost CANCEL-TIMER upsgone
#
#   2) If any UPS (*) reverts to utility power, then stop the timer before it
#   triggers
#
#   AT ONLINE * CANCEL-TIMER onbattwarn

#   -----------------------------------------------------------------------
#
# - CANCEL-TIMER-MATCHED <timername> [cmd]
#
#   Similar to the above, but tries to only cancel the <timername> if it
#   refers to the `UPSNAME` and `NOTIFYTYPE` values passed by caller (the
#   `NOTIFYMSG` is ignored in this context).
#
#   1) If any UPS (*) reverts to utility power, then stop the timer before it
#   triggers ONLY if that UPS is associated with the already scheduled timer:
#
#   AT ONLINE * CANCEL-TIMER-MATCHED onbattwarn

#   -----------------------------------------------------------------------
#
# - EXECUTE <command>
#
#   Immediately pass <command> as an argument to CMDSCRIPT.
#
#   Example:
#   If any UPS (*) reverts to utility power, then execute
#   'ups-back-on-line' via CMDSCRIPT.
#
#   AT ONLINE * EXECUTE ups-back-on-line
