Provided by: apcupsd_3.14.10-2build1_amd64 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
       information  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 annoyance
       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.

       XXXXCMD's
       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)