Unix/Linux Go Back    

RedHat 9 (Linux i386) - man page for upsmon (redhat section 8)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)

UPSMON(8)			     Network UPS Tools (NUT)				UPSMON(8)

       upsmon - UPS monitor and shutdown controller

       upsmon -h

       upsmon -c command

       upsmon [-d] [-i] [-p] [-u user]

       upsmon  is the client process that is responsible for the most important part of UPS moni-
       toring - 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  mas-

       -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     Enable debugging mode.  upsmon runs in the foreground and prints debugging informa-
	      tion on stdout about the monitoring process.

       -i     Enable infinite loop at shutdown.  upsmon will keep a process running after calling
	      the shutdown command rather than exiting.  This is only useful if you have shutdown
	      scripts that complain when upsmon isn't running as they kill various processes.

       -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"

       -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=...'.  Typi-
	      cally 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.

       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].  The sim-
       plest form is just a hostname, i.e.:

	    "localhost" refers to the first UPS on the local system.

       Other possibilities include:

	    "su700@mybox" means a UPS called "su700" on a system called "mybox".

	    "elvis:1234" means the first UPS on a system called "elvis", port 1234.

       Finally, to use all of these options:

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

       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.

       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 addi-
       tional NOTIFY-related sections below for information on customizing the delivery of  these

       ONLINE The UPS is back on line.

       ONBATT The UPS is on battery.

	      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.

	      Communication with the UPS was just lost.

	      The local system is being shut down.

	      The UPS needs to have its battery replaced.

       NOCOMM The UPS can't be contacted for monitoring.

       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:

       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





       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.

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

	    NOTIFYMSG type "message"


	    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.

       The  "current overall power value" is the sum of all UPSes that are currently able to sup-
       ply 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.


       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.


       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.

       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 net-
       work) 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 immedi-
       ately invokes the local shutdown command.  This needs to happen quickly.  Once it  discon-
       nects  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 filesys-
       tem 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 mas-
       ter  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 some-
       thing 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.

       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  upss-
       ched(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

       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 val-
       ues 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.

       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 batter-
       ies,  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

       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.

       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).

       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  set-

       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.

       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 bat-
       tery  had gone critical.  This is much easier on your UPS equipment, and it beats crawling
       under a desk to find the plug.



       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.exploits.org/nut/

       NUT mailing list archives and information: http://lists.exploits.org/

					 Tue Oct 15 2002				UPSMON(8)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums

All times are GMT -4. The time now is 10:23 PM.