Provided by: nut_2.0.3-4build1_i386 bug

NAME

       upsmon - UPS monitor and shutdown controller

SYNOPSIS

       upsmon -h

       upsmon -c command

       upsmon [-D] [-p] [-u user]

DESCRIPTION

       upsmon is the client process that is responsible for the most important
       part of UPS monitoring ‐ shutting down the system when the  power  goes
       out.   It  can  call  out  to  other  helper  programs for notification
       purposes during power events.

       upsmon can monitor multiple systems using a single process.  Every  UPS
       that  is defined in the upsmon.conf(5) configuration file is assigned a
       power value and a type (slave or master).

OPTIONS

       -h     Display the help message.

       -c command
              Send the command command to the existing upsmon process.   Valid
              commands are:

              fsd ‐ shutdown all master UPSes (use with caution)

              stop ‐ stop monitoring and exit

              reload   ‐   reread   upsmon.conf(5)  configuration  file.   See
              "reloading nuances" below if this doesn’t work.

       -D     Raise the debugging level.  upsmon will run  in  the  foreground
              and  prints  information on stdout about the monitoring process.
              Use this multiple times for more details.

       -K     Test for the shutdown flag.  If it exists and contains the magic
              string  from  upsmon,  then  upsmon will exit with EXIT_SUCCESS.
              Any other condition will make upsmon exit with EXIT_FAILURE.

              You can test for a  successful  exit  from  upsmon  -K  in  your
              shutdown  scripts to know when to call upsdrvctl(8) to shut down
              the UPS.

       -p     Run privileged all the time.  Normally upsmon  will  split  into
              two processes.  The majority of the code runs as an unprivileged
              user, and only a tiny stub  runs  as  root.   This  switch  will
              disable  that  mode,  and  run  the  old "all root all the time"
              system.

              This is not the recommended mode, and you should  not  use  this
              unless you have a very good reason.

       -u user
              Set  the user for the unprivileged monitoring process.  This has
              no effect when using -p.

              The default user  is  set  at  configure  time  with  ’configure
              --with-user=...’.    Typically   this  is  ’nobody’,  but  other
              distributions will probably have a specific ’nut’ user for  this
              task.   If  your  notification scripts need to run as a specific
              user, set it here.

              You can also set  this  in  the  upsmon.conf(5)  file  with  the
              RUN_AS_USER directive.

UPS DEFINITIONS

       In  the  upsmon.conf(5), you must specify at least one UPS that will be
       monitored.  Use the MONITOR directive.

            MONITOR system powervalue username password type

       The   system   refers   to   a   upsd(8)   server,    in    the    form
       upsname@hostname[:port].  Some examples follow:

        ‐ "su700@mybox" means a UPS called "su700" on a system called "mybox".
       This is the normal form.

        ‐ "fenton@bigbox:5678" is a UPS called "fenton"  on  a  system  called
       "bigbox" which runs upsd(8) on port "5678".

       The  powervalue  refers  to  how many power supplies on this system are
       being driven this UPS.  This is typically set to 1, but see the section
       on power values below.

       The  username  is  a  section  in  your  upsd.users(5)  file.  Whatever
       password you set in that section must match the password  set  in  this
       file.

       The  type set in that section must also match the type here ‐ master or
       slave.  In general, a master process is one running on the system  with
       the  UPS  actually  plugged  into a serial port, and a slave is drawing
       power from the UPS but can’t talk to it directly.  See the  section  on
       UPS types for more.

NOTIFY EVENTS

       upsmon  senses several events as it monitors each UPS.  They are called
       notify events as they can be used to tell the users  and  admins  about
       the change in status.  See the additional NOTIFY‐related sections below
       for information on customizing the delivery of these messages.

       ONLINE The UPS is back on line.

       ONBATT The UPS is on battery.

       LOWBATT
              The UPS battery is low (as determined by the driver).

       FSD    The UPS has been commanded into the "forced shutdown" mode.

       COMMOK Communication with the UPS has been established.

       COMMBAD
              Communication with the UPS was just lost.

       SHUTDOWN
              The local system is being shut down.

       REPLBATT
              The UPS needs to have its battery replaced.

       NOCOMM The UPS can’t be contacted for monitoring.

NOTIFY COMMAND

       In upsmon.conf(5), you can configure a  program  called  the  NOTIFYCMD
       that will handle events that occur.

            NOTIFYCMD "path to program"

            NOTIFYCMD "/usr/local/bin/notifyme"

       Remember to wrap the path in "quotes" if it contains any spaces.

       The program you run as your NOTIFYCMD can use the environment variables
       NOTIFYTYPE and UPSNAME to know what has happened and on which UPS.   It
       also  receives  the  notification message (see below) as the first (and
       only) argument, so you can deliver a preformatted message too.

       Note that the NOTIFYCMD will only be called for a given event when  you
       set the EXEC flag by using the notify flags, below:

NOTIFY FLAGS

       By  default,  all  notify  events (see above) generate a global message
       (wall) to all users, plus they are logged  via  the  syslog.   You  can
       change this with the NOTIFYFLAG directive in the configuration file:

            NOTIFYFLAG notifytype flags

            Examples:

            NOTIFYFLAG ONLINE SYSLOG

            NOTIFYFLAG ONBATT SYSLOG+WALL

            NOTIFYFLAG LOWBATT SYSLOG+WALL+EXEC

       The flags that can be set on a given notify event are:

       SYSLOG Write this message to the syslog.

       WALL   Send this message to all users on the system via ’wall’.

       EXEC   Execute the NOTIFYCMD.

       IGNORE Don’t  do anything.  If you use this, don’t use any of the other
              flags.

       You can mix these flags.  "SYSLOG+WALL+EXEC" does all three for a given
       event.

NOTIFY MESSAGES

       upsmon  comes  with  default  messages  for  each of the NOTIFY events.
       These can be changed with the NOTIFYMSG directive.

            NOTIFYMSG type "message"

            Examples:

            NOTIFYMSG ONLINE "UPS %s is getting line power"

            NOTIFYMSG ONBATT "Someone pulled the plug on %s"

       The first instance of %s is replaced with the  identifier  of  the  UPS
       that  generated  the event.  These messages are used when sending walls
       to the  users  directly  from  upsmon,  and  are  also  passed  to  the
       NOTIFYCMD.

POWER VALUES

       The  "current  overall  power  value"  is the sum of all UPSes that are
       currently able to supply power to the system hosting upsmon.   Any  UPS
       that  is  either on line or just on battery contributes to this number.
       If a UPS is critical (on battery and low battery) or has been put  into
       "forced shutdown" mode, it no longer contributes.

       A  "power  value" on a MONITOR line in the config file is the number of
       power supplies that the UPS runs on the current system.

            MONITOR upsname powervalue username password type

       Normally, you only have one power supply, so it will be set to 1.

            MONITOR myups@myhost 1 username mypassword master

       On a large server with redundant power supplies, the power value for  a
       UPS  may  be  greater  than 1.  You may also have more than one of them
       defined.

            MONITOR ups-alpha@myhost 2 username mypassword master

            MONITOR ups-beta@myhost 2 username mypassword master

       You can also set the power value for a UPS to 0 if it does  not  supply
       any  power to that system.  This is generally used when you want to use
       the upsmon notification  features  for  a  UPS  even  though  it’s  not
       actually  running  the  system  that  hosts  upsmon.  Don’t set this to
       "master" unless you really  want  to  power  this  UPS  off  when  this
       instance of upsmon needs to shut down for its own reasons.

            MONITOR faraway@anotherbox 0 username mypassword slave

       The  "minimum power value" is the number of power supplies that must be
       receiving power in order to keep the computer running.

            MINSUPPLIES value

       Typical PCs only have 1, so most users will leave this at the  default.

            MINSUPPLIES 1

       If  you have a server or similar system with redundant power, then this
       value will usually be  set  higher.   One  that  requires  three  power
       supplies to be running at all times would simply set it to 3.

            MINSUPPLIES 3

       When  the  current  overall  power  value drops below the minimum power
       value, upsmon starts the shutdown sequence.  This design allows you  to
       lose  some  of  your  power  supplies  in a redundant power environment
       without bringing down the entire system while  still  working  properly
       for smaller systems.

UPS TYPES

       upsmon  and upsd(8) don’t always run on the same system.  When they do,
       any UPSes that are directly attached  to  the  upsmon  host  should  be
       monitored  in  "master"  mode.   This  makes upsmon take charge of that
       equipment, and it will wait for slaves to  disconnect  before  shutting
       down  the  local  system.   This allows the distant systems (monitoring
       over the network) to shut down cleanly before upsdrvctl  shutdown  runs
       and turns them all off.

       When  upsmon  runs  as  a slave, it is relying on the distant system to
       tell it about the state of the UPS.  When that UPS  goes  critical  (on
       battery  and  low  battery),  it immediately invokes the local shutdown
       command.  This needs to happen quickly.  Once it disconnects  from  the
       distant  upsd(8)  server, the master upsmon will start its own shutdown
       process.  Your slaves must all shut down before the  master  turns  off
       the power or filesystem damage may result.

       upsmon  deals  with  slaves that get wedged, hang, or otherwise fail to
       disconnect from upsd(8) in a timely manner  with  the  HOSTSYNC  timer.
       During  a shutdown situation, the master upsmon will give up after this
       interval and it will shut down anyway.   This  keeps  the  master  from
       sitting  there  forever  (which  would  endanger  that host) if a slave
       should break somehow.  This defaults to 15 seconds.

       If your master system is shutting down too quickly, set the  FINALDELAY
       interval  to  something greater than the default 15 seconds.  Don’t set
       this too high, or your UPS battery may run  out  of  power  before  the
       master upsmon process shuts down that system.

TIMED SHUTDOWNS

       For those rare situations where the shutdown process can’t be completed
       between the time that low battery is signalled  and  the  UPS  actually
       powers  off  the load, use the upssched(8) helper program.  You can use
       it along with upsmon to schedule a shutdown based on the  "on  battery"
       event.   upssched can then come back to upsmon to initiate the shutdown
       once it’s run on battery too long.

       This can be complicated and messy, so stick to the default critical UPS
       handling if you can.

REDUNDANT POWER SUPPLIES

       If  you  have  more  than one power supply for redundant power, you may
       also have more than one UPS feeding your computer.  upsmon  can  handle
       this.   Be  sure  to  set  the  UPS  power values appropriately and the
       MINSUPPLIES value high enough so that it keeps running until it  really
       does need to shut down.

       For  example,  the  HP  NetServer  LH4  by default has 3 power supplies
       installed, with one bay empty.  It has two power cords, one per side of
       the  box.  This means that one power cord powers two power supply bays,
       and that you can only have two UPSes supplying power.

       Connect UPS "alpha" to the cord feeding two  power  supplies,  and  UPS
       "beta"  to  the  cord  that feeds the third and the empty slot.  Define
       alpha as a powervalue of 2, and beta as a powervalue  of  1.   Set  the
       MINSUPPLIES to 2.

       When  alpha goes on battery, your current overall power value will stay
       at 3, as it’s still supplying power.  However, once  it  goes  critical
       (on  battery and low battery), it will stop contributing to the current
       overall power value.  That means the value  will  be  1  (beta  alone),
       which  is  less  than  2.   That is insufficient to run the system, and
       upsmon will invoke the shutdown sequence.

       However, if beta goes critical, subtracting its contribution will  take
       the  current  overall  value  from 3 to 2.  This is just high enough to
       satisfy the minimum, so the system will continue running as before.  If
       beta  returns  later, it will be re‐added and the current value will go
       back to 3.   This  allows  you  to  swap  out  UPSes,  change  a  power
       configuration,  or  whatever, as long as you maintain the minimum power
       value at all times.

MIXED OPERATIONS

       Besides being able to monitor multiple UPSes, upsmon can  also  monitor
       them  as  different  roles.   If  you have a system with multiple power
       supplies serviced by separate UPS batteries,  it’s  possible  to  be  a
       master  on one and a slave on the other.  This usually happens when you
       run out of serial ports and need to do the monitoring  through  another
       system nearby.

       This is also complicated, especially when it comes time to power down a
       UPS that has gone critical but doesn’t supply the  local  system.   You
       can  do  this  with some scripting magic in your notify command script,
       but it’s beyond the scope of this manual.

FORCED SHUTDOWNS

       When upsmon is forced to bring down the local system, it sets the "FSD"
       (forced  shutdown) flag on any UPSes that it is running in master mode.
       This is used to synchronize slaves in the event that a master UPS  that
       is  otherwise OK needs to be brought down due to some pressing event on
       the master.

       You can manually invoke this mode on  the  master  upsmon  by  starting
       another copy with ’-c fsd’.  This is useful when you want to initiate a
       shutdown before the critical stage through some external means, such as
       upssched(8).

DEAD UPSES

       In  the  event  that  upsmon  can’t reach upsd(8), it declares that UPS
       "dead"  after   some   interval   controlled   by   DEADTIME   in   the
       upsmon.conf(5).  If this happens while that UPS was last known to be on
       battery, it is assumed to have gone critical and no longer  contributes
       to the overall power value.

       upsmon  will  alert you to a UPS that can’t be contacted for monitoring
       with a "NOCOMM" notifier by default every 300  seconds.   This  can  be
       changed with the NOCOMMWARNTIME setting.

RELOADING NUANCES

       upsmon  usually  gives up root powers for the process that does most of
       the  work,  including  handling  signals  like  SIGHUP  to  reload  the
       configuration  file.   This  means  your  upsmon.conf(8)  file  must be
       readable by the non‐root account that upsmon switches to.

       If you want reloads to work, upsmon must run  as  some  user  that  has
       permissions  to  read the configuration file.  I recommend making a new
       user just for this purpose, as making the  file  readable  by  "nobody"
       (the default user) would be a bad idea.

       See the RUN_AS_USER section in upsmon.conf(8) for more on this topic.

       Additionally,   you  can’t  change  the  SHUTDOWNCMD  or  POWERDOWNFLAG
       definitions with a reload due  to  the  split‐process  model.   If  you
       change those values, you must stop upsmon and start it back up.  upsmon
       will warn you in the syslog if you make  changes  to  either  of  those
       values during a reload.

SIMULATING POWER FAILURES

       To  test  a  synchronized  shutdown  without  pulling  the plug on your
       UPS(es), you need only set the forced shutdown (FSD) flag on them.  You
       can do this by calling upsmon again to set the flag ‐ i.e.:

            upsmon -c fsd

       After  that,  the  master  and  the slaves will do their usual shutdown
       sequence as if the battery had gone critical.  This is much  easier  on
       your  UPS  equipment,  and  it  beats crawling under a desk to find the
       plug.

FILES

       upsmon.conf(5)

SEE ALSO

   Server:
       upsd(8)

   Clients:
       upsc(8), upscmd(8), upsrw(8), upsmon(8)

   CGI programs:
       upsset.cgi(8), upsstats.cgi(8), upsimage.cgi(8)

   Internet resources:
       The NUT (Network UPS Tools) home page: http://www.networkupstools.org/

                                Wed Nov 26 2003                      UPSMON(8)