SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE




YUM REPOSITORY

 
 

apcupsd

Section: Maintenance Commands (8)
Updated: APC UPS management under Linux -- November 1999
Index 

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 usedfor a brief overview of apcupsd, but you should consult thehtml manual for current information. Normally this manualwill be loaded on your system in the doc directory, whichvaries from system to system. Otherwise, you may findan 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 thepower failure and that a shutdown may occur. If power is notrestored, a system shutdown will follow when the battery isexausted, a timeout (seconds) expires, or runtime expires basedon internal UPS calculations determined by power consumptionrates. If the power is restored before one of the above shutdownconditions 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 isno communication between apcupsd and init(1) process. Apcupsdmodifies the halt script so that at the end of the shutdownprocess, apcupsd will be re-executed in order to power off theUPS. On certain platforms (e.g. FreeBSD) there is no halt scriptso apccontrol must be modified to cause apcupsd to power offthe UPS after a delay time.

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

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

The second networking mode is for multiple networked machines that arepowered by the same UPS. In this mode, one machine is configured as amaster with the UPS attached to the serial port. The other machines(max. 20) powered by the same UPS are configured as slaves. The masterhas a network connection with the slaves and sends them informationabout the UPS status. This mode is significantly more complicatedto setup than the NIS networking mode described above.

For details and configurations on these networking modes please seethe manual.

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

OPTIONS

-c --configure
Attempts to configure the UPS EPROM to the values specified in theconfiguration file "/etc/apcupsd/apcupsd.conf".This option is now deprecated (not supported) and should notbe used. Instead use the apctest program, which has an interactiveEEPROM configuration.
-d --debug <level>
Turns on debugging output.
-f --config-file <file>
Specifies the location of the configuration file. The defaultis: /etc/apcupsd/apcupsd.conf
-k --killpower
Attempt to turn the UPS off. This option is normally onlyused by the daemon itself to shut the UPS off after asystem 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 yourconfiguration. This file is a plain ASCII file and you can use yourfavorite editor to change it.

Configuration commands in /etc/apcupsd/apcupsd.confare:

 

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 apcupsdwill figure out where your device is located. If you haveproblems, please see the manual as it has more details.

LOCKFILE-- <path to lockfile>
By supplying this argument, "apcupsd" tries to create a lockfilefor 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 serveron or off. If it is on, apcupsd will spawn a child process thatserves STATUS and EVENTS information over the network. Thisinformation is currently used by the Web based CGI programs.The default is on. In some cases, for added security, you maywant to invoke a separate information server daemon from the inetddaemon. In this case, NETSTATUS should be off.

STATUSPORT <port>
This configuration command specifies the port to be used by theapcupsd server. The default is 3551.

EVENTFILE <filename>
If you want the apcupsd network information server to providethe last 10 events via the network, you must specify afile where apcupsd will save these events. The default is:/var/log/apcupsd.events. Currently, apcupsd will saveat most the last 50 events. When more than 50 events arerecorded and a network request for the events arrives,the network server will truncate the file tothe most recent 10 events. Consequently this filewill not grow indefinitely as long as the events arechecked 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 requestinglogged in users to get off the system. This timer starts only whenthe 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 requestinglogged in users to get off the system. This timer startsonly after the UPS is running on batteries.This timer is reset when the power returns. The defaultis 60 seconds. That is the first warning to log off thesystem 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 thepoint when the /etc/nologin file is added. This is important forallowing systems with BIG UPSes to run as normally until the systemadministrator determines the need for dumping users. The feature alsoallows 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 creatingthe nologin file.

minutes specifies the battery runtime remaining before creating thenologin file.

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

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

MINUTES-- <battery runtime in minutes>
If MINUTES is specified, during a power failure, apcupsd willshutdown the system when the remaining remaining runtime on batteriesas internally 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 secondshave expired. Normally for SMARTUPSes, this should be zero so that theshutdown time will be determined by the battery level or remaining runtime (see above). This command is useful for dumb UPSes that do not reportbattery level or the remaining runtime. It is also useful fortesting apcupsd in that you can force a rapid shutdown by settinga 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 MINUTEScan be set together without problems. The daemon will react to thefirst case or test that is valid. Normally SmartUPS users will setTIMEOUTto zero so that the system is shutdown depending on the percentage battery charge remaining (BATTERYLEVEL)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 portconnection to the UPS, but where there are no other computersdependent power from the same UPS. This is the "normal" case.

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

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

Use "shareslave" if andonly if you are using a ShareUPS and connected to a BASIC Port withSimple Signal.

Use "sharemaster", if and only if you are using aShareUPS and connected 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 signalports 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 valueis now passed to the slaves to sync. the openning of a socketby the slave for the master.

NETPORT-- <TCP|UDP port number>
This unix service port number must be set in the /etc/services fileas 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 longwithout spaces. This is passed to the master machine duringinitialization of sockets. This string should be different foreach and every slave on the network. This is not at all secure aspasswords are passed in the clear. Please protect your network byfirewalling or tcpwrappers.

 

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 oldclass 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 MINUTESare disabled or set to default values. Currently, there is not a knownway 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 storedfor 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 sentto the temporary events file (/var/log/apcupsd.events),and they also generate a call to /etc/apcupsd/apccontrolwhich 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 definedon the DATATIME command. This data record is in a formatsimilar to the PowerChute data file format.

 

STATUS format

The STATUS output is in ASCII format and generally thereis 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 LineVoltageStateLastEventObserved

BackUPS and NetUPS Simple Signals
OnlineStatus BatteryStatus

 

SEE ALSO

The html manual installed on your system orhttp://www.apcupsd.com

 

AUTHOR

Andre M. Hedrick 

Retired Co-AUTHOR

Christopher J. Reimer 

Current maintainers

Kern SibbaldAdam Kropelin 

Contributors

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


 

Index

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
CONFIGURATION
GENERAL CONFIGURATION COMMANDS
CONFIGURATION COMMANDS USED BY THE NETWORK INFORMATION SERVER
CONFIGURATION COMMANDS USED TO CONTROL SYSTEM LOGGING
CONFIGURATION COMMANDS FOR SHARING A UPS
SMARTUPS
SHAREUPS
FILES
EVENTS
DATA format
STATUS format
SEE ALSO
AUTHOR
Retired Co-AUTHOR
Current maintainers
Contributors

This document was created byman2html,using the manual pages.