unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-3.1)
Page:
Section:
Apropos / Subsearch:
optional field

apcupsd(8)                  System Manager's Manual                 apcupsd(8)



NAME
       apcupsd - daemon for most APC's UPS for Linux

SYNOPSIS
       /sbin/apcupsd
       /etc/apcupsd/apccontrol
       /etc/apcupsd/apcupsd.conf
       /sbin/apcaccess
       /sbin/apcnetd

DESCRIPTION
       This  document  is considerably out of date. It can be used for a brief
       overview of apcupsd, but you should consult the html manual for current
       information.  Normally this manual will be loaded on your system in the
       doc directory, which varies from system to system. Otherwise,  you  may
       find an online version at: http://www.apcupsd.com


       This  daemon  can be used for controlling the most APC UPSes.  During a
       power failure, "apcupsd" will inform the users about the power  failure
       and  that  a  shutdown  may  occur.  If power is not restored, a system
       shutdown will follow when the battery is exausted, a timeout  (seconds)
       expires,  or  runtime expires based on internal UPS calculations deter-
       mined by power consumption rates.  If the power is restored before  one
       of  the  above  shutdown  conditions  is met, apcupsd will inform users
       about this fact.

       The shutdown is made  by  script  calls  to  "/etc/apcupsd/apccontrol",
       which is called by "apcupsd".  Consequently, no changes to /etc/inittab
       are necessary.  There is no communication between apcupsd  and  init(1)
       process.   Apcupsd  modifies  the halt script so that at the end of the
       shutdown process, apcupsd will be re-executed in order to power off the
       UPS.  On  certain  platforms  (e.g. FreeBSD) there is no halt script so
       apccontrol must be modified to cause apcupsd to power off the UPS after
       a delay time.


       The  apcupsd  daemon  now  supports  two networking modes that function
       independently, but if desired they can both run at the same time.

       Most users will probably enable the first  network  mode  and  simplest
       (NIS  or  Network  Information Service), which permits apcupsd to serve
       status and event information to clients over the network.

       The second networking mode is for multiple networked machines that  are
       powered  by  the same UPS. In this mode, one machine is configured as a
       master with the UPS attached to the serial port.   The  other  machines
       (max.   20) powered by the same UPS are configured as slaves.  The mas-
       ter has a network connection with the slaves and sends them information
       about  the  UPS  status. This mode is significantly more complicated to
       setup than the NIS networking mode described above.

       For details and configurations on these networking modes please see the
       manual.


       RedHat  and  SuSE  versions  of Linux have direct install support.  All
       other flavors of Linux may need some fussing with to  get  the  install
       correct.

OPTIONS
       -c --configure
              Attempts  to  configure the UPS EPROM to the values specified in
              the configuration file "/etc/apcupsd/apcupsd.conf".  This option
              is  now  deprecated  (not  supported)  and  should  not be used.
              Instead use the apctest program, which has an interactive EEPROM
              configuration.

       -d --debug <&lt;level>&gt;
              Turns on debugging output.

       -f --config-file <&lt;file>&gt;
              Specifies  the  location of the configuration file.  The default
              is: /etc/apcupsd/apcupsd.conf

       -k --killpower
              Attempt to turn the UPS off. This option is normally  only  used
              by the daemon itself to shut the UPS off after a system shutdown
              has completed.

       -V --version
              Prints the apcupsd version number and the help.

       -? --help
              Prints a brief apcupsd help screen.


CONFIGURATION
       It may be necessary to change the configuration information in the file
       "/etc/apcupsd/apcupsd.conf"  to  meet  your  needs and to correspond to
       your configuration.  This file is a plain ASCII file and  you  can  use
       your favorite editor to change it.

       Configuration commands in /etc/apcupsd/apcupsd.conf are:


   GENERAL CONFIGURATION COMMANDS
       UPSCABLE -- <type of cable you are using>
       [ simple | 940-0020B | 940-0023A (broken) ]
       [ smart | 940-0024B | 940-0024C ]
       [ 940-0095A | 940-0095C ]
       [ ether ]
       [ usb ]

       UPSTYPE -- <Type of APCC UPS you have>
       [ dumb | apcsmart | net | usb | snmp | test ]

       DEVICE -- <name of serial port>
       Please specify which device is used for UPS communication.  The default
       is /dev/ttyS[0|1|2|3].  If you have a USB  UPS,  you  should  leve  the
       DEVICE directive blank and apcupsd will figure out where your device is
       located. If you have problems, please see the manual  as  it  has  more
       details.

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


   CONFIGURATION COMMANDS USED BY THE NETWORK INFORMATION SERVER
       NETSTATUS [on | off]
       This configuration command turns the network information server  on  or
       off. If it is on, apcupsd will spawn a child process that serves STATUS
       and EVENTS information over the network. This information is  currently
       used  by the Web based CGI programs.  The default is on. In some cases,
       for added security, you may  want  to  invoke  a  separate  information
       server  daemon from the inetd daemon. In this case, NETSTATUS should be
       off.


       STATUSPORT <port>
       This configuration command specifies the port to be used by the apcupsd
       server. The default is 3550. If you change this port, you must manually
       change the #define SERV_TCP_PORT in cgi/upsfetch.c and rebuild the  CGI
       programs.


       EVENTFILE <filename>
       If  you want the apcupsd network information server to provide the last
       10 events via the network, you must specify a file where  apcupsd  will
       save  these events. The default is: /var/log/apcupsd.events. Currently,
       apcupsd will save at most the last 50 events. When more than 50  events
       are  recorded and a network request for the events arrives, the network
       server will truncate the file to the  most  recent  10  events.  Conse-
       quently  this file will not grow indefinitely as long as the events are
       checked from time to time.



   CONFIGURATION COMMANDS USED TO CONTROL SYSTEM LOGGING
       STATTIME


       STATFILE


       DATATIME


       FACILITY




       CONFIGUATION COMMANDS USED DURING POWER FAILURES

       ANNOY -- <time in seconds>
       Please specify the time in seconds between messages  requesting  logged
       in  users to get off the system. This timer starts only when the UPS is
       running on batteries.  The default is 300 seconds (5 minutes).

       ANNOYDELAY -- <time in seconds>
       Please specify delay time in seconds before apcupsd  begins  requesting
       logged in users to get off the system. This timer starts only after the
       UPS is running on batteries.   This  timer  is  reset  when  the  power
       returns.  The  default is 60 seconds.  That is the first warning to log
       off the system occurs after 60 seconds on batteries.



       NOLOGON -- <specifies when apcupsd should create the 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  normally  until  the  system
       administrator  determines the need for dumping users.  The feature also
       allows the system administrator to hold the "ANNOY"  factor  until  the
       /etc/nologin file is added.

       disable prevents apcupsd from creating the nologin file.

       timeout  specifies  a  specific  wait  time before creating the nologin
       file.

       percent specifies the percent battery charge remaining before  creating
       the nologin file.

       minutes  specifies  the  battery  runtime remaining before creating the
       nologin file.

       always causes the nologin file to be immediately  created  on  a  power
       failure.

       BATTERYLEVEL -- <percent of battery>
       If  BATTERYLEVEL  is  specified,  during  a power failure, apcupsd will
       shutdown the system when the remaining battery charge falls  below  the
       specified percentage.  The default is 5.

       MINUTES -- <battery runtime in minutes>
       If  MINUTES is specified, during a power failure, apcupsd will shutdown
       the system when the remaining remaining runtime on batteries as  inter-
       nally calculated by the UPS falls below the time specified. The default
       is 3.


       TIMEOUT -- <time in seconds>
       After a power failure, the system will be shutdown after  TIMEOUT  sec-
       onds  have  expired.   Normally  for SMARTUPSes, this should be zero so
       that the shutdown time will be  determined  by  the  battery  level  or
       remaining  runtime  (see  above). This command is useful for dumb UPSes
       that do not report battery level or the remaining runtime. It  is  also
       useful  for  testing  apcupsd in that you can force a rapid shutdown by
       setting a small value (e.g. 60) and pulling the plug to the UPS.

       The timeout for the master is always 30 seconds longer than slaves.

       TIMEOUT, BATTERYLEVEL, and MINUTES can be set  together  without  prob-
       lems.  The  daemon  will react to the first case or test that is valid.
       Normally SmartUPS users will set TIMEOUT to zero so that the system  is
       shutdown  depending  on  the  percentage battery charge remaining (BAT-
       TERYLEVEL) or the remaining battery runtime (MINUTES).



   CONFIGURATION COMMANDS FOR SHARING A UPS
       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.

       The default is "standalone" and should be used for all machines powered
       by  the  UPS  and having a serial port connection to the UPS, but where
       there are no other computers dependent power from the same  UPS.   This
       is the "normal" case.

       Use  "netmaster",  if  and only if you have a serial port connection to
       the UPS and there are other machines deriving power from the same UPS.

       Use "netslave" if and only if you have no serial port connection to the
       UPS, but you derive power from it.

       Use  "shareslave" if and only if you are using a ShareUPS and connected
       to a BASIC Port with Simple Signal.

       Use "sharemaster", if and only if you are using  a  ShareUPS  and  con-
       nected to the ADVANCED Port Smart Signal control.


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

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

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

       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 password> for the slave machine.
       The second level of password security. It must be (17) characters  long
       without spaces. This is passed to the master machine during initializa-
       tion of sockets. This string should be different  for  each  and  every
       slave on the network. This is not at all secure as passwords are passed
       in the clear. Please protect your network by  firewalling  or  tcpwrap-
       pers.


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.

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

FILES
       /etc/apcupsd/apcupsd.conf - configuration file.
       /var/log/apcupsd.status - STATUS file
       /var/log/apcupsd.events - where up to the last 50 events are stored for
       the network information server.

EVENTS
       apcupsd generates events when certain conditions occur such as a  power
       failure, batteries exhausted, power return,

       These  events are sent to the system log, optionally sent to the tempo-
       rary events file (/var/log/apcupsd.events), and they  also  generate  a
       call to /etc/apcupsd/apccontrol which in turn will call any scripts you
       have placed in the /etc/apcupsd directory.


DATA format
       If the DATATIME configuration command is set nonzero, apcupsd will  log
       a  data  record  at  the interval defined on the DATATIME command. This
       data record is in a format similar to the PowerChute data file format.


STATUS format
       The STATUS output is in ASCII format and generally there  is  a  single
       piece  of  information on each line output.  The format varies based on
       the type of UPS that you are using.

       DATE     : 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

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

       BackUPS and NetUPS Simple Signals
       OnlineStatus BatteryStatus


SEE ALSO
       The html manual installed on your system or http://www.apcupsd.com


AUTHOR
       Andre M. Hedrick

   Retired Co-AUTHOR
       Christopher J. Reimer

   Current maintainers
       Kern Sibbald Adam Kropelin

   Contributors
       An enormous list of past and former persons who have devoted their time
       and energy to this project -- thanks.



                APC UPS management under Linux -- November 1999     apcupsd(8)