Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
APCUPSD.CONF(5)		  FreeBSD 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 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 di-
	      rective blank and	apcupsd	will figure out	where the device is
	      located.

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

	      If you have problems, please see the apcupsd manual for more de-
	      tailed 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 util-
	      isation. 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 UP-
	      Ses.

     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 out-
	      put 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	inter-
	      face, you	can specify the	IP of a	single interface to limit con-
	      nections 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 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 PowerChute
	      software-like data information to	the log	file.

     FACILITY <log-facility>

	      Change the system	logging	(syslog) facility. The default is dae-
	      mon.  This parameter can be useful if you	wish to	direct the
	      apcupsd system logging information to other than your system de-
	      fault 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 un-
	      til 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 shut-
	      down 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	set-
	      ting 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 re-
	      questing 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	cre-
	      ated.

     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	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 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 con-
	      nected 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 = 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 ex-
	      hausted. 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 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 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	TIME-
     OUT <seconds> configuration directive to set the number of	seconds	on
     battery during a power failure after which	apcupsd	will do	a system shut-
     down.

     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

NAME | DESCRIPTION | EXAMPLES | FILES | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=apcupsd.conf&sektion=5&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help