Provided by: apcupsd_3.14.2-1build1_i386 bug

NAME

       apcupsd - daemon for Most APCC’s UPS support under Linux and UNIX

SYNOPSIS

       /sbin/apcupsd
       /sbin/powersc
       /etc/apcupsd.conf
       /sbin/apcaccess

DESCRIPTION

       This  daemon  can  be  used  for controlling the APC SmartUPS. During a
       power failure, "apcupsd" will inform the users about power  status.  If
       the  power  is  restored  before valid test return TRUE, "apcupsd" will
       inform users about this fact.  If  power  is  not  restored,  a  system
       shutdown  will follow when the battery is exausted, a timeout (seconds)
       expires, or runtime minutes based on internal  values  based  on  power
       consumption  rates.  The  whole shutdown is now made by script calls to
       the "/sbin/powersc" file called by "apcupsd",  so  no  changes  in  the
       inittab are necessary.  There is now no communication between "apcupsd"
       and init(1) process.

       The "apcupsd" daemon now supports the networking mode.  In  this  mode,
       one  machine is configured as a master, with UPS attached to the serial
       port. Other machines (max. 20) are configured as a slaves. Master has a
       network  connection  with  slaves  and send them informations about UPS
       status. Both Master and Slaves  open  and  close  there  sockets  on  a
       regular basis. If someone gets lost nobody gets to upset.

       Hewlett  Packard  :  HP  PowerTrust  2997A  UPS  has  been  tested as a
       "smartups" with cable Hewlett Packard part number 5061-2575 as "CUSTOM-
       SMART".

       Slackware, RedHat, S.u.S.E., Debian, and UNIFIX "FLAVORS" of Linux have
       direct  install support.  All other "FLAVORS" of Linux will  need  some
       fussing with to get the install correct. Please send me all new install
       methods that are not listed above or corrections to  these  for  future
       versions before the final release.

CONFIGURATION

       It   is   necessary   to   write   configuration   info   to  the  file
       "/etc/apcupsd.conf".  This file is a plain ASCII file and you  can  use
       your  favorite  editor for configuration. For simple configuration, see
       enclosed sample file.

       Configuration commands in /etc/apcupsd.conf are:

       CONTROL -- <path|filename> /sbin/powersc
       Name of control script called by "apcupsd".

       UPSCABLE -- <cable model>
       [ simple | 940-0020B | 940-0023A (broken) ]
       [ smart | 940-0024B | 940-0024C | 940-0024G ]
       [ 940-0095A | 940-0095C ]
       [ ether ]

       UPSTYPE -- <Type of APCC UPS>
       [ backups | sharebasic ] : Simple
       [ netups ] : Network Simple Signals
       [ backupspro | smartvsups ] : Sub(barely)Smart
       [ newbackupspro | backupspropnp ] : Sub(very)Smart
       [ smartups | matrixups | sharesmart ] : Smart

       [ backups | netups | backupspro | smartvsups ] and
       [ newbackupspro | smartups | matrixups ] are tested.
       [ sharebasic | sharesmart ] models are being tested.

       UPSCLASS -- <class of operation>
       [ standalone | shareslave | sharemaster ] and
       [ netslave | netmaster ] are valid types.
       [ standalone | netslave | netmaster ] are tested classes.
       [ shareslave | sharemaster ] classes are being tested.

       Default for all machines is "standalone". Change to "shareslave" if and
       only  if  you  are  using a ShareUPS and connected to a BASIC Port with
       Simple Signal. Change to "sharemaster", if and only if you are using  a
       ShareUPS  and  connected  to  the  ADVANCED  Port Smart Signal control.
       Change to "netslave" if and only if you are not  connected  to  an  UPS
       other than for power.  Change to "netmaster", if and only if you are on
       a TCP/UDP network and connected to an UPS of any kind with other  Linux
       Boxes.

       UPSMODE -- [ disable | share | net | sharenet ] are valid types.

       [ disable | net ] are the only known and tested classes.
       [ share | sharenet ] classes is being tested.

       BETA [ share ] For two or seven (2/7) additional simple signal ports on
       a SmartAccessories(tm) (internal/external box) for SmartUPSes.

       DEVICE -- <name of serial port>
       Please specify which device is used for UPS communication.  The default
       is /dev/ttyS[0|1|2|3].

       LOCKFILE -- <path to lockfile>
       By supplying this argument, "apcupsd" tries to create a lockfile in the
       specified directory.

       ACCESS -- [ true | false ]
       This enables the use of "apcaccess" interface, on all machines, but for
       accessing or changing configurations of a running "apcupsd".

       ANNOY -- <time in seconds>
       Please specify time in seconds for "apcupsd" to harrass logged in users
       to get off the system.

       DELAY -- <time in seconds>
       Please specify time in seconds for "apcupsd" to delay harrassing logged
       in  users to get off the system. This rate is reset if there is a power
       state change. If "ANNOY == DELAY" then "DELAY" is disabled.

       NOLOGON -- <method of setting nologon file>
       [ disable | timeout | percent | minutes | always ] are valid types.
       Based on Ten (10) percent of a setting.  This allows one to define  the
       point  when  the  /etc/nologin  file  is  added.  This is important for
       allowing systems  with  BIG  UPSes  to  run  as  normal  until  the  SA
       determines  the  need for dumping users. The feature also allows the SA
       hold of the "ANNOY" factor until the /etc/nologin file is added.

       PROCFS -- <time in seconds>
       Please specify time in seconds for "apcupsd" to update the psuedo  proc
       fs  file  "/etc/apcupsd.status". This rate is reset if there is a power
       state change.

       This will be  replaced  with  "apcaccess  ’status’"  calls.  This  will
       prevent fragmenting and disk access.

       LOGGING -- <time in seconds>
       Please  specify  time  in  seconds for "apcupsd" to update the log file
       "/var/log/apcupsd.log". This rate is reset if there is  a  power  state
       change.
       Future  additions will allow one to select the location of the logfile.

       TIMEOUT -- <time in seconds>
       This is the timeout between power failure  and  system  shutdown.   The
       timeout for master is always 30 seconds longer than slaves.

       BATTERYLEVEL -- <percent of battery>
       Valid for UPSes capable of Internal EPROM programming.
       Instead  of setting "TIMEOUT", apcupsd can react based on the remaining
       charge left in the batteries.

       MINUTES -- <battery runtime in minutes>
       Valid for UPSes capable of Internal EPROM programming.
       Instead of setting "TIMEOUT", apcupsd can react based on  the  internal
       calculations  of  runtime  in  minutes  as related to power consumption
       being drawn on the UPS.

       SENSITIVITY -- <sets sensitiviy level>
       Valid for UPSes capable of Internal EPROM programming.
       (H)igh, (M)edium, (L)ow

       WAKEUP -- <set wakeup delay>
       Valid for UPSes capable of Internal EPROM programming.
       The power restart  delay  value  in  [0,60,180,300]  Cycles.   This  is
       important  for  those who have high RPM drives that need to spindown or
       they will fault out when booting. Some SCSI models are  very  sensitive
       to this problem. Cycles(*)

       SLEEP -- <set sleep delay>
       Valid for UPSes capable of Internal EPROM programming.
       Delay  in  [20,180,300,600]  Cycles  before the actual killpower event.
       Cycles(*)

       LOTRANSFER -- <sets lower limit of ups batt. transfer>
       Valid for UPSes capable of Internal EPROM programming.
       This sets the low line voltage point to switch over.
       There are four values that can be selected, but they vary based on  the
       UPS  model,  classification, and manufacture date. Thus a value ranging
       from 0-3 are assigned the learned and bubble sorted values.

       HITRANSFER -- <sets upper limit of ups batt. transfer>
       Valid for UPSes capable of Internal EPROM programming.
       This sets the high line voltage point to switch over.
       There are four values that can be selected, but they vary based on  the
       UPS  model,  classification, and manufacture date. Thus a value ranging
       from 0-3 are assigned the learned and bubble sorted values.

       RETURNCHARGE -- <sets min. batt. charge level>
       Valid for UPSes capable of Internal EPROM programming.
       There are four values that can be selected, but they vary based on  the
       UPS  model,  classification, and manufacture date. Thus a value ranging
       from 0-3 are assigned the learned and bubble sorted values.

       BEEPSTATE -- <sets alarm beep state>
       Valid for UPSes capable of Internal EPROM programming.
       This allows the setting of the  noise  maker  that  many  have  removed
       because  of the annoiance factor.  These settings are based on discrete
       events related to the remaining capacity of the UPS.
       0 always
       T low batt + 30
       L low batt
       N never

       UPSNAME -- <string>
       Only valid for UPSes capable of Internal EPROM  programming.   This  is
       normally  an  eight  character  string,  but  it currently only handles
       seven.

       XXXXCMDs
       All of the following commands are used to execute external  scripts  of
       programs  that  "apcupsd"  does  not  handle  internally.  Specifically
       something like calling a pager or sending email to a System or  Network
       Admin.
       [ BATTCMD | TIMECMD | LOADCMD | LIMITCMD ]
       [ PWRCMD | RETCMD | REMOTECMD ]
       are the seven external commands that can access and report events.

       BATTCMD -- <path|filename>
       Name of the program to run when the battery fails.

       TIMECMD -- <path|filename>
       Name of the program to run when "TIMEOUT" has expired.

       LOADCMD -- <path|filename>
       Name  of  the  program to run when the "BATTERYLEVEL" has dropped below
       the set limits.

       LIMITCMD
       Name of the program to run when the "MINUTES" runtime has dropped below
       the set limits.

       PWRCMD -- <path|filename>
       Name of the program to run when the power fails.

       RETCMD -- <path|filename>
       Name of the program to run when the power returns.

       REMOTECMD -- <path|filename>
       Name of the program to run when a remote shutdown is called.

       NETTIME -- <time in seconds>
       The  rate  in  seconds  that  broadcasts information to Slave machines.
       This rate is reset if there is a power state change. This value is  now
       passed to the slaves to sync. the openning of a socket by the slave for
       the master.

       NETPORT -- <TCP|UDP port number>
       This unix service port number must be set in the /etc/services file  as
       follows:
               tab     tab(spacejunk)  tab     tab
       name                    (stuff)/xxp             #
       apcupsd         NETPORT/tcp             #
       apcupsd         NETPORT/udp             #

       MASTER -- <name of master> for Slave machine.
       The  name  of  the  master which is authorized to send commands to this
       slave.

       SLAVE -- <name of slave(s)> for Master machine.
       The name of the slave machine attached to the  master.   There  can  be
       max. 20 slaves attached to one master.

       USERMAGIC -- < user defined magic> for Slave machine.
       The  second  level  of  magic security. It must be (17) characters long
       without  spaces.  This  is  passed  to  the   master   machine   during
       initialization of sockets. This string should be different for each and
       every slave on the network.

SMARTUPS

       If you start getting the follow message:
       Emergency, Batteries Have Failed!!!!
       Change Them NOW!!!
       Act upon it quickly. It means what it says.
       Also, not all "SmartUPS" models are eqaully smart.  A  non-NET  or  old
       class  of "SmartUPS" has a subset of the full UPSlink(TM) language, and
       can not be polled for its control codes.

       TIMEOUT,  BATTERYLEVEL,  and  MINUTES  can  be  set  togather   without
       problems.  The  daemon  will  react  to  the first case or test that is
       valid.

SHAREUPS

       Special note for ShareUPS users, TIMEOUT, BATTERYLEVEL, and MINUTES are
       disabled  or set to default values. Currently, there is not a known way
       of early signals to be sent to BASIC Ports. MINUTES are set to 0.

CABLES

       Firstly, you will need the cable between APC Smart UPS and PC  computer
       running  Linux.  You can use either the special cable which is enclosed
       with the PowerChute (TM) software  or  you  can  make  your  own  cable
       connected as follows:

               SMART-CUSTOM
               PC (9 pin)      APC (9 pin)
               2 RxD           2
               3 TxD           1
               5 GND           9

               SIMPLE-CUSTOM
        DB9/25F PC Side                DB9M UPS Side
         4/20   DTR (5vcc)                  nc    (*)
          8/5   CTS (low-batt)               5    (*)
          2/3   RxD (other line-fail)        3    (*)
          5/7   Ground (Signal)              4
          1/8   CD (line-fail from ups)      2
          7/4   RTS (shutdown ups)           1
         nc/1   Frame/Case Gnd (optional)    9

       List if componets one needs to make this CABLE:
       1) One (1) DB9 use solder type connector only.
       2) One (1) DB9/25F use solder type connector only.
       3) two (2) 4.7K ohm 1/4 watt %5 resistors.
       4) one (1) foot of 3/32" (inch) shrink wrap/boot.
       5) rosin core solder.
       6) three (3) to five (5) feet of 22AWG multi-stranded five
          (5) conductor cable.

       First  solder  both of the resistors into pin# (4) DB9 or (20) DB25 the
       DTR.  This will be used as the Vcc  pull-up  voltage  for  testing  the
       outputs  on  any  "UPS by APC" ONLY in Simple Signal mode. This may not
       work on a BackUPS Pro if the default communications  are  Smart  Signal
       mode.  This  cable is valid for "ShareUPS" BASIC Port mode if there are
       no other cables that can be gotten.

       Next bend each of the resistors so that one connects to (8) DB9 or  (5)
       DB25  the  CTS (aka battery low signal) and the other to (2) DB9 or (3)
       DB25 the RxD (aka another line fail signal). This line is not currently
       used, but it will be in the near future.

       (*) 8/5 is also wire to pin# 5 on UPS cable side.
       (*) 2/3 is also wire to pin# 3 on UPS cable side.
       (*) we use the DTR as our +5 volts power for the circuit.

       If  you have one of the following cables supplied by APCC, apcupsd will
       support off the shelf cables.
       940-0020B     Simple Signal Only, all models.
       940-0024[B/C/G]  SmartMode Only, SU, BPPro and BKPro only.
       940-0095[A/C]  PnP (Plug and Play), all models.
       940-0023A     Simple Signal UNIX, [BROKEN STILL].

FILES

       /etc/apcupsd.conf - configuration file.
       /etc/apcupsd.status - psuedo procfs-type file.
       /var/log/apcupsd.log - the UPS status is logged.

FILE FORMAT

       Both "apcupsd.log" and "apcupsd.status" are  simple  ascii  files  with
       several  floating point numbers on one line. The format varies based on
       the type of UPS that you are using.

       /etc/apcupsd.status
       APC      : time and date of last update
       CABLE    : cable type used
       UPSMODEL : ups type or signal method
       UPSMODE  : tells apcupsd what to check
       SHARE    : if ShareUPS is used, this determines what

       SmartUPS and MatrixUPS Smart Signals
       ULINE    : Current (observed) Input Line Voltage
       MLINE    : Max (observed) Input Line Voltage
       NLINE    : Min (observed) Input Line Voltage
       FLINE    : Line Freq (cycles)
       VOUTP    : UPS Output Voltage
       LOUTP    : Percent Load of UPS Capacity
       BOUTP    : Current Charge Voltage of Batteries
       BCHAR    : Batteries Current Charge Percent of Capacity
       BFAIL    : UNSIGNED INT CODE (ups state)
       UTEMP    : Current UPS Temp. in Degrees Cel.
       DIPSW    : Current DIP switch settings for UPS.

       Newer BackUPS Pro Smart Signals
       ULINE    : Current (observed) Input Line Voltage
       MLINE    : Max (observed) Input Line Voltage
       NLINE    : Min (observed) Input Line Voltage
       FLINE    : Line Freq (cycles)
       VOUTP    : UPS Output Voltage
       LOUTP    : Percent Load of UPS Capacity
       BOUTP    : Current Charge Voltage of Batteries
       BCHAR    : Batteries Current Charge Percent of Capacity
       BFAIL    : UNSIGNED INT CODE (ups state)

       BackUPS Pro and SmartUPS v/s Smart Signals
       LINEFAIL : OnlineStatus
       BATTSTAT : BatteryStatus
       MAINS    : LineVoltageState
       LASTEVNT : LastEventObserved

       BackUPS and NetUPS Simple Signals
       LINEFAIL : OnlineStatus
       BATTSTAT : BatteryStatus

       /var/log/apcupsd.log
       SmartUPS and MatrixUPS Smart Signals
       LineVoltage LineMax LineMin LineFreq OutputVoltage UPSLoad  BattVoltage
       BatteryLoad UPSLoad UPSTemp

       Newer BackUPS Pro Smart Signals
       LineVoltage  LineMax LineMin LineFreq OutputVoltage UPSLoad BattVoltage
       BatteryLoad UPSLoad

       BackUPS Pro and SmartUPS v/s Smart Signals
       OnlineStatus BatteryStatus LineVoltageState LastEventObserved

       BackUPS and NetUPS Simple Signals
       OnlineStatus BatteryStatus

AUTHOR

       Andre M. Hedrick <hedrick@astro.dyer.vanderbilt.edu>

   Retired Co-AUTHOR
       Christopher J. Reimer <reimer@doe.carleton.ca>

   The Brave Unnamed PATCH-WORKS and TESTERS
       "Daniel Quinlan" <quinlan@pathname.com>
       "Tom Kunicki" <kunicki@surgery.wisc.edu>
       "Karsten Wiborg" <4wiborg@informatik.uni-hamburg.de>
       "Jean-Michel Rouet" <JM.ROUET@maisel-gw.enst-bretagne.fr>
       "Chris Adams" <cadams@ro.com>
       "Jason Orendorf" <orendorf@sprintmail.com>
       "Neil McAllister" <pcm2@sentient.com>
       "Werner Panocha" <WPanocha@t-online.de>
       "Lee Maisel" <martian@rt66.com>
       "Brian Schau" <bsc@fleggaard.dk>

   The Information HELPERS and TESTERS.
       "Eric S. Raymond" <esr@snark.thyrsus.com>
       "Chris Hanson" <cph@martigny.ai.mit.edu>
       "Pavel Alex" <pavel@petrolbank.mldnet.com>
       "Theo Van Dinter" <felicity@kluge.net>
       "Thomas Porter" <txporter@mindspring.com>
       "Alan Davis" <davis@ele.uri.edu>
       "Oliver Hvrmann" <ollo@compuserve.com>
       "Scott Horton" <Scott.Horton1@bridge.bellsouth.com>
       "Matt Hyne" <mhyne@tip.CSIRO.AU>
       "Chen Shiyuan" <csy@hjc.edu.sg>

   OTHER CREDITS
       "Miquel van Smoorenburg" <miquels@drinkel.cistron.nl>
       "The Doctor What" <docwhat@itek.net>
       "Pavel Korensky" <pavelk@dator3.anet.cz>

BUGS AND LIMITATIONS

       Any other name will cause an error when loading the "/etc/apcupsd.conf"
       file.  There  are  some  known problems and limitations. There can be a
       problem with the newest types of APC Smart UPS  add-ons.  Any  and  All
       Network  Modes  is  not supported, yet. No bugs in standard stuff. I am
       sure, well pretty sure. Possible bugs in all ShareUPS mode  types.   If
       anyone  has had success at all with any ShareUPS models, please report.

EtherUPS/NetUPS

       This is fully functional as of version 3.4.0.

                   APCC UPS management under Linux and UNIX         apcupsd(8)