Provided by: apcupsd_3.14.14-3.1build1_amd64 bug

NAME

     apcupsd.confapcupsd(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 configuration directives which control how the
     apcupsd program behaves when controlling most American Power Conversion Corp (APC) UPSes.
     The configuration file is also used for the apctest(8) program when bulk programming 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 operating requirements.

     Note that the apcupsd daemon must be restarted in order for changes to the configuration
     file to become active.

     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 | 940-0625A | MAM-04-02-2000 ]

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

     UPSTYPE [ dumb | apcsmart | net | usb | snmp | pcnet | modbus |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)
                 modbus : /dev/tty** (serial connection)
                 modbus : leave blank (USB connection)

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

     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 created 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 connections 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 functionality 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 information.  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 PowerChute 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 possible
              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 percentage.  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 useful 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 problems.  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 seconds on battery power).

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

              Specifies when apcupsd should create the nologon file to prevent 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 administrator 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 specified 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 computers 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 support.

              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 activation 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 = International.

     HITRANSFER <voltage>

              High line voltage causing transfer to battery power or activation 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 = International.

     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 = International.

     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 operating 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 customise 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 seconds on battery during a power failure after which apcupsd will do a
     system shutdown.

     Normally there would be more configuration directives to completely customise 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