APCUPSD.CONF(5)		   BSD File Formats Manual	      APCUPSD.CONF(5)

NAME
     apcupsd.conf - apcupsd(8) configuration file

DESCRIPTION
     apcupsd.conf is the configuration file for the apcupsd(8) program.	 The
     file is a plain ASCII text file which comprises a number of configura-
     tion directives which control how the apcupsd program behaves when con-
     trolling most American Power Conversion Corp (APC) UPSes.	The configu-
     ration file is also used for the apctest(8) program when bulk program-
     ming the EEPROM in a Smart-UPS model.

     It will almost certainly be necessary to customise the information in
     the configuration file to suit your particular configuration and operat-
     ing requirements.

     The configuration file directives are explained in the subsections
     below.

   GENERAL CONFIGURATION DIRECTIVES
     UPSNAME <string>

	      Specify a name for the UPS for log files, status reports etc.

     UPSCABLE [ simple | smart | ether | usb | 940-0119A | 940-0127A |
	      940-0128A | 940-0020B | 940-0020C | 940-0023A | 940-0024B |
	      940-0024C | 940-1524C | 940-0024G | 940-0095A | 940-0095B |
	      940-0095C | MAM-04-02-2000 ]

	      The type of cable used to connect the UPS to the computer.

     UPSTYPE [ dumb | apcsmart | net | usb | snmp | pcnet | test ]

	      The type of APC UPS that you have.

     DEVICE <name>

	      The name of the device used for communication between the UPS
	      and the computer. For a USB UPS, you should leave the DEVICE
	      directive blank and apcupsd will figure out where the device is
	      located.

	      ?	  apcsmart : /dev/tty** (serial connection)
	      ?	  usb : leave blank! (USB connection)
	      ?	  net : hostname:port (NIS connection)
	      ?	  snmp : hostname:port:vendor:community (SNMP connection)
	      ?	  dumb : /dev/tty** (serial connection)
	      ?	  pcnet : ipaddr:username:passphrase (AP9617 SmartSlot card)

	      If you have problems, please see the apcupsd manual for more
	      detailed information and comprehensive troubleshooting advice.

     POLLTIME <seconds>

	      The rate in seconds that the daemon polls the UPS for status.
	      This rate is automatically set to 1 second when the UPS goes on
	      battery and reset to the specified value when the utility power
	      returns. This setting applies both to directly-attached UPSes
	      and networked UPSes.  A low setting will improve the daemon's
	      responsiveness to certain events at the cost of higher CPU
	      utilisation. The default of 60 is appropriate for most situa-
	      tions.

     LOCKFILE <path>

	      apcupsd creates a lockfile for the serial or USB port in the
	      specified directory.  It must be changed when running more than
	      one copy of apcupsd on the same computer to control multiple
	      UPSes.


     SCRIPTDIR <path>

	      Directory in which apccontrol and event scripts are located.
	      Defaults to /usr/local/etc/apcupsd.  It must be changed when
	      running more than one copy of apcupsd on the same computer to
	      control multiple UPSes.

     PWRFAILDIR <path>

	      Directory in which apcupsd writes the powerfail flag file cre-
	      ated when apcupsd initiates a system shutdown. The directory is
	      checked in halt scripts to determine if turning off the UPS
	      output power is required.	 Defaults to /var/run.	It must be
	      changed when running more than one copy of apcupsd on the same
	      computer to control multiple UPSes.

     NOLOGINDIR <path>

	      Directory in which apcupsd writes the nologin file which tells
	      the OS to disallow new logins. Defaults to /var/run.  It must
	      be changed when running more than one copy of apcupsd on the
	      same computer to control multiple UPSes.

   NIS CONFIGURATION DIRECTIVES
     NETSERVER [ on | off ]

	      Turns the network information server (NIS) on or off. When on,
	      apcupsd serves status and event information over the network.
	      This information is also used by the web-based CGI monitoring
	      programs. The default is set to on.

     NISIP <IP address>

	      Specifies the IP address of the network interface on which
	      apcupsd will listen for incoming connections. The default value
	      is 0.0.0.0 which means the NIS will listen for connections on
	      all network interfaces. If the computer has more than one
	      interface, you can specify the IP of a single interface to
	      limit connections to that interface.  Specifying the loopback
	      address (127.0.0.1) will cause the NIS daemon to accept connec-
	      tions only from the local computer.

     NISPORT <port>

	      Specifies the port to be used by the NIS daemon. The default is
	      3551 which has been received from IANA as the official apcupsd
	      networking port.	It must be changed when running more than one
	      copy of apcupsd on the same computer to control multiple UPSes.

     EVENTSFILE <filename>

	      If you want NIS 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.	apcupsd will save at
	      most the last 50 events to this file. When more than 50 events
	      are saved and a network request for the events arrives, apcupsd
	      will truncate the file to the most recent 10 events.  It must
	      be changed when running more than one copy of apcupsd on the
	      same computer to control multiple UPSes.

   LOGGING CONFIGURATION DIRECTIVES
     STATTIME <seconds>

	      Specifies the time interval between writes to the status file.
	      If set to zero, the status file will not be written. The status
	      file will disappear in a future  apcupsd version as its func-
	      tionality has been replaced by the Network Information Server
	      and the apcaccess(8) program.

     STATFILE <file>

	      Specifies the file to be used when writing the status informa-
	      tion.  The default is /etc/apcupsd/apcupsd.status.  It must be
	      changed when running more than one copy of apcupsd on the same
	      computer to control multiple UPSes.

     LOGSTATS [ on | off ]

	      Activate log file. This generates a lot of output, so if you
	      turn this on, be sure that the file defined in syslog.conf(5)
	      for LOG_NOTICE is a named pipe.

     DATATIME <seconds>

	      Specifies the time interval between writes of the APC Power-
	      Chute software-like data information to the log file.

     FACILITY <log-facility>

	      Change the system logging (syslog) facility. The default is
	      daemon.  This parameter can be useful if you wish to direct the
	      apcupsd system logging information to other than your system
	      default files.  See syslog.conf(5) for details of other possi-
	      ble facilities and general system logging configuration.

   POWER FAILURE CONFIGURATION DIRECTIVES
     ONBATTERYDELAY <seconds>

	      The number of seconds from when a power failure is detected
	      until apcupsd reacts with an onbattery event.

     BATTERYLEVEL <percentage>

	      apcupsd will shutdown the system during a power failure when
	      the remaining battery charge falls below the specified percent-
	      age.  The default is 5.

     MINUTES <minutes>

	      apcupsd will shutdown the system during a power failure when
	      the remaining runtime on batteries as internally calculated by
	      the UPS falls below the specified minutes. The default is 3.

     TIMEOUT <seconds>

	      After a power failure occurs, apcupsd will shutdown the system
	      after the specified number of seconds have expired.  For a
	      Smart-UPS, this should normally be set to zero so that the
	      shutdown time will be determined by the battery level or
	      remaining runtime (see above). This command is, however, useful
	      for a Back-UPS or other simple signalling UPS which does not
	      report battery level or the remaining runtime. It is also use-
	      ful for testing apcupsd because you can force a rapid shutdown
	      by setting a small value (eg 60) and turning off the power to
	      the UPS.

	      TIMEOUT, BATTERYLEVEL, and MINUTES can all be set without prob-
	      lems.  apcupsd will initiate a shutdown when the first of these
	      conditions becomes valid.

     ANNOY <seconds>

	      Specifies the time in seconds between broadcast messages
	      requesting logged in users to log off from the system. This
	      timer starts only when the UPS is running on battery. The
	      default is 300 seconds (5 minutes).

     ANNOYDELAY <seconds>

	      Specifies the delay time in seconds before broadcast messages
	      requesting logged in users to log off from the system. This
	      timer starts only after the UPS is running on battery power.
	      This timer is reset when the power returns. The default is 60
	      seconds (ie the first request to log off occurs after 60 sec-
	      onds on battery power).

     NOLOGON [ disable | timeout | percent | minutes | always ]

	      Specifies when apcupsd should create the nologon file to pre-
	      vent users from logging on to the system.

	      "disable" prevents apcupsd from creating the nologin file.

	      "timeout" specifies a specific wait time before apcupsd creates
	      the nologin file.

	      "percent" specifies the percentage of battery charge remaining
	      before apcupsd creates the nologin file.

	      "minutes" specifies the battery runtime remaining before
	      apcupsd creates the nologin file.

	      "always" specifies that apcupsd should create the nologin file
	      immediately after a power failure occurs.

	      This directive is important for allowing systems with BIG UPSes
	      to run normally until the system administrator determines the
	      need for dumping users.  It also allows the system administra-
	      tor to hold the "ANNOY" factor until the /etc/nologin file is
	      created.

     KILLDELAY <seconds>

	      Specifies the number of seconds for which apcupsd will continue
	      running after a shutdown has been requested. After the speci-
	      fied time, apcupsd will attempt to put the UPS into hibernate
	      mode and kill the power to the computer. This is for use on
	      operating systems where apcupsd cannot regain control after a
	      shutdown (eg FreeBSD) to issue an apcupsd --killpower command.
	      Setting the delay to 0 disables it.

   SHARE-UPS CONFIGURATION DIRECTIVES
     UPSCLASS [ standalone | shareslave | sharemaster ]

	      The default is "standalone" and should be used for all comput-
	      ers powered by the UPS,  with a direct connection to the UPS
	      and where there are no other computers dependent on power from
	      the UPS. This is the "normal" case.

	      Use "shareslave" if you are using a Share-UPS interface
	      expander and connected to the BASIC port (simple signalling).

	      Use "sharemaster", if you are using a Share-UPS interface
	      expander and connected to the ADVANCED port (smart signalling).

     UPSMODE [ disable | share ]

	      Set to "disable" for normal standalone operation to indicate
	      that you are disabling the Share-UPS interface expander sup-
	      port.

	      Set to "share" for two to seven additional simple signalling
	      ports on a Share-UPS interface expander. This code may not be
	      fully tested in every new release.

   APCTEST EEPROM CONFIGURATION DIRECTIVES
     These directives have no effect on the operation of apcupsd(8) but are
     reserved for use by apctest(8) when bulk programming the values of the
     UPS EEPROM configuration variables in a Smart-UPS model.

     UPSNAME <string>

	      Name of UPS. Maximum of 8 characters.

     BATTDATE [ mm/dd/yy | dd/mm/yy ]

	      Last battery replacement date. Maximum of 8 characters.

     SENSITIVITY [ H | M | L ]

	      H : High (most sensitive setting)
	      M : Medium
	      L : Low (least sensitive setting)

     WAKEUP [ 000 | 060 | 180 | 300 ]

	      The time delay in seconds that the UPS waits after the return
	      of utility power before "waking up" and restoring power to the
	      connected equipment.

     SLEEP [ 020 | 180 | 300 | 600 ]

	      The time delay in seconds for which the UPS waits or "sleeps"
	      after it receives a request to power off the connected system.

     LOTRANSFER <voltage>

	      Low line voltage causing transfer to battery power or activa-
	      tion of SmartBoost.  Allowable values depend on the last letter
	      of the firmware or APCMODEL.  Typical values are:

		D  106	103  100  097
		M  177	172  168  182
		A  092	090  088  086
		I  208	204  200  196

	      where D = domestic (USA), M = Canada, A = Asia and I = Interna-
	      tional.

     HITRANSFER <voltage>

	      High line voltage causing transfer to battery power or activa-
	      tion of SmartTrim.  Allowable values depend on the last letter
	      of the firmware or APCMODEL.  Typical values are:

		D  127	130  133  136
		M  229	234  239  224
		A  108	110  112  114
		I  253	257  261  265

	      where D = domestic (USA), M = Canada, A = Asia and I = Interna-
	      tional.

     RETURNCHARGE [ 00 | 15 | 50 | 90 ]

	      Percentage of battery charge needed for the UPS to restore
	      power to the connected equipment.

     BEEPSTATE [ 0 | T | L | N ]

	      Alarm delay.

	      0 : Zero delay after power fails.
	      T : When power fails plus 30 seconds.
	      L : When low battery occurs.
	      N : Never.

     LOWBATT <minutes>

	      Low battery warning occurs when the specified number of minutes
	      remains before the UPS estimates battery power will be
	      exhausted. There are four user-changeable settings: 2, 5, 7, or
	      10 minutes

     OUTPUTVOLTS <voltage>

	      UPS nominal output voltage when running on battery.  Allowable
	      values depend on the last letter of the firmware or APCMODEL.
	      Typical values are:

		D  115
		M  208
		A  100
		I  230	240  220  225

	      where D = domestic (USA), M = Canada, A = Asia and I = Interna-
	      tional.

     SELFTEST [ 336 | 168 | ON | OFF ]

	      Self test interval in hours (336 = 2 weeks, 168 = 1 week, ON =
	      at power on, OFF = never).

EXAMPLES
     Note that in the following examples, the device names assume that you
     are using Linux. Device names for serial devices in *BSD and other oper-
     ating systems will be different.

   Minimal USB Configuration for a USB UPS
	  UPSCABLE usb
	  UPSTYPE usb
	  DEVICE
	  LOCKFILE /var/lock
	  UPSCLASS standalone
	  UPSMODE disable

     Notice no device name is specified.  apcupsd(8) will try all the well
     known USB ports. Only specify a specific USB device name if you know
     what you are doing. For detailed information on setting up a USB UPS,
     refer to the "USB Configuration" section of the apcupsd manual.

   Minimal Serial Configuration for a Smart UPS
	  UPSCABLE smart
	  UPSTYPE apcsmart
	  DEVICE /dev/ttyS0
	  LOCKFILE /var/lock
	  UPSCLASS standalone
	  UPSMODE disable

     Normally there would be more configuration directives to completely cus-
     tomise your installation, but this example shows the minimum required.

   Minimal Serial Configuration for a Dumb UPS
	  UPSCABLE <number of the cable used>
	  UPSTYPE dumb
	  DEVICE /dev/ttyS0
	  LOCKFILE /var/lock
	  UPSCLASS standalone
	  UPSMODE disable

     If your cable does not have low battery detection (eg such cables
     include the APC 940-0020B and 940-0023A), you will also need to define
     the TIMEOUT <seconds> configuration directive to set the number of sec-
     onds on battery during a power failure after which apcupsd will do a
     system shutdown.

     Normally there would be more configuration directives to completely cus-
     tomise your installation, but this example shows the minimum required.

FILES
     /etc/apcupsd/apcupsd.conf default configuration file

SEE ALSO
     syslog.conf(5), apcupsd(8), apctest(8).

     The HTML apcupsd manual installed on your system or available online at
     http://www.apcupsd.org/

AUTHORS
     Trevor Roydhouse (current)
     Andre M. Hedrick
     Christopher J. Reimer

apcupsd.conf v3.14.6	       January 10, 2009		 apcupsd.conf v3.14.6
