FreeBSD Manual Pages
apcctrl.conf(5) File Formats Manual apcctrl.conf(5) NAME apcctrl.conf -- apcctrl(8) configuration file DESCRIPTION apcctrl.conf is the configuration file for the apcctrl(8) program. The file is a plain ASCII text file which comprises a number of configura- tion directives which control how the apcctrl 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 oper- ating requirements. Note that the apcctrl daemon must be restarted in order for changes to the configuration file to become active. The configuration file directives are explained in the subsections be- low. 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 | brazil ] 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 apcctrl will figure out where the device is located. • apcsmart : /dev/tty** (serial connection) • brazil : /dev/tty** (serial/USB-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 apcctrl 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> apcctrl creates a lockfile for the serial or USB port in the specified directory. It must be changed when running more than one copy of apcctrl on the same computer to control mul- tiple UPSes. SCRIPTDIR <path> Directory in which apccontrol and event scripts are located. Defaults to /usr/local/etc/apcctrl. It must be changed when running more than one copy of apcctrl on the same computer to control multiple UPSes. PWRFAILDIR <path> Directory in which apcctrl writes the powerfail flag file cre- ated when apcctrl 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 apcctrl on the same computer to control multiple UPSes. NOLOGINDIR <path> Directory in which apcctrl 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 apcctrl 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, apcctrl 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 apcctrl will listen for incoming connections. The default value is 0.0.0.0 which means the NIS will listen for connec- tions 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 con- nections 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 apc- ctrl networking port. It must be changed when running more than one copy of apcctrl on the same computer to control mul- tiple UPSes. EVENTSFILE <filename> If you want NIS to provide the last 10 events via the network, you must specify a file where apcctrl will save these events. The default is: /var/log/apcctrl.events. apcctrl 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, apcc- trl will truncate the file to the most recent 10 events. It must be changed when running more than one copy of apcctrl 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 sta- tus file will disappear in a future apcctrl 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 informa- tion. The default is /etc/apcctrl/apcctrl.status. It must be changed when running more than one copy of apcctrl 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 apcctrl system logging information to other than your sys- tem 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 apcctrl reacts with an onbattery event. BATTERYLEVEL <percentage> apcctrl will shutdown the system during a power failure when the remaining battery charge falls below the specified per- centage. The default is 5. MINUTES <minutes> apcctrl 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, apcctrl 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 re- maining 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 apcctrl 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. apcctrl will initiate a shutdown when the first of these conditions becomes valid. ANNOY <seconds> Specifies the time in seconds between broadcast messages re- questing logged in users to log off from the system. This timer starts only when the UPS is running on battery. The de- fault 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 apcctrl should create the nologon file to pre- vent users from logging on to the system. "disable" prevents apcctrl from creating the nologin file. "timeout" specifies a specific wait time before apcctrl cre- ates the nologin file. "percent" specifies the percentage of battery charge remaining before apcctrl creates the nologin file. "minutes" specifies the battery runtime remaining before apcc- trl creates the nologin file. "always" specifies that apcctrl should create the nologin file immediately after a power failure occurs. This directive is important for allowing systems with BIG UP- Ses to run normally until the system administrator determines the need for dumping users. It also allows the system admin- istrator to hold the "ANNOY" factor until the /etc/nologin file is created. KILLDELAY <seconds> Specifies the number of seconds for which apcctrl will con- tinue running after a shutdown has been requested. After the specified time, apcctrl will attempt to put the UPS into hi- bernate mode and kill the power to the computer. This is for use on operating systems where apcctrl cannot regain control after a shutdown (eg FreeBSD) to issue an apcctrl --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 ex- pander and connected to the BASIC port (simple signalling). Use "sharemaster", if you are using a Share-UPS interface ex- pander 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 apcctrl(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 let- ter 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 = Inter- national. 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 = Inter- national. 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 min- utes 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 = Inter- national. 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 op- erating 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. apcctrl(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 apcctrl 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 re- quired. 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 in- clude 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 apcctrl will do a system shutdown. Normally there would be more configuration directives to completely customise your installation, but this example shows the minimum re- quired. FILES /etc/apcctrl/apcctrl.conf default configuration file SEE ALSO syslog.conf(5), apcctrl(8), apctest(8). The HTML apcctrl manual installed on your system or available online at http://www.apcctrl.org/ AUTHORS Trevor Roydhouse (current) Andre M. Hedrick Christopher J. Reimer apcctrl.conf v3.14.6 January 10, 2009 apcctrl.conf(5)
NAME | DESCRIPTION | EXAMPLES | FILES | SEE ALSO | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=apcctrl.conf&sektion=5&manpath=FreeBSD+Ports+15.0>