Uninterruptable Power Supply:APC
Installation of apcupsd
Introduction
Apcupsd can be used for power management and controlling most of APC's UPS models on Unix and Windows machines. Apcupsd works with most of APC's Smart-UPS models as well as most simple signalling models such a Back-UPS, and BackUPS-Office. During a power failure, apcupsd will inform the users about the power failure and that a shutdown may occur. If power is not restored, a system shutdown will follow when the battery is exhausted, a timeout (seconds) expires, or runtime expires based on internal APC calculations determined by power consumption rates. Apcupsd is licensed under the GPL version 2.
The latest version of apcupsd is 3.14.8-1 (January 2010) and is available from sourceforge in two rpms - one for the UPS daemon and one for the web based monitoring scripts. Neither of these install exactly in line with the SME way, and neither does the older version available on DAG.
These installation instructions make some additional modifications for SME. They have been tested on SME 7.5 and an APC SmartUPS 1500i with both a usb and a 940-0024C smart serial cable. They have also been tested with an AP9617 Network Management Card using both the snmp and pcnet UPSTYPE drivers'
Download and install
Get the rpms from sourceforge
wget https://sourceforge.net/projects/apcupsd/files/rpms%20-%20Stable/3.14.8/apcupsd-3.14.8-1.el4.i386.rpm/download wget https://sourceforge.net/projects/apcupsd/files/rpms%20-%20Stable/3.14.8/apcupsd-multimon-3.14.8-1.el4.i386.rpm/download
Install with yum
yum localinstall apcupsd-3.14.8-1.el4.i386.rpm apcupsd-multimon-3.14.8-1.el4.i386.rpm
Configure apcupsd
General
Link the startup file and enable the service
ln -s /etc/init.d/e-smith-service /etc/rc.d/rc7.d/S38apcupsd config set apcupsd service status enabled
Copy the original conf file
cp /etc/apcupsd/apcupsd.conf /etc/apcupsd/apcupsd.conf.orig
Edit the /etc/apcupsd/apcupsd.conf file and make relevant changes for your UPS and requirements. The file is reasonably well documented and as a minimum you will probably want to set
UPSNAME UPSCABLE UPSTYPE DEVICE BATTERYLEVEL MINUTES TIMEOUT
You may also consider some additional security by only listening for connections on the localhost for monitoring and incoming events (assuming you have only one UPS directly connected). In this instance set
NISIP 127.0.0.1
Now make sure Nut isn't running and start the service
config setprop nut status disabled /etc/init.d/nut stop /etc/rc.d/rc7.d/S38apcupsd start
To check its running and view status information (you may need to wait 30 seconds to ensure initialisation and communications have completed)
/etc/init.d/apcupsd status
Network Management Cards
If you have a Network Management Card installed in the UPS such as the AP9617 card, you can use snmp or pcnet for UPSTYPE with the following configurations
NMC Setup
The NMC default configuration searches for an IP address using BOOTP and DHCP. It expects a device specific cookie to be returned with the DHCP response, so even if you create a local hostname in Server-manager - Hostnames and Addresses, initial install will fail. Use the APC Device IP Configuration Wizard to discover the UPS and assign IP/Subnet/Gateway settings. You can then access the UPS configuration in a browser using the IP given.
The network TCP/IP settings will be set to manual with the values provided in the wizard above. To use DHCP in future goto the Administration - Network Tab and under TCP/IP select DHCP for configuration and press Next. On the following page deselect the tick box against Require vendor specific cookie to accept DHCP Address and Apply. DHCP configuration via the Hostnames and addresses panel in Server-manager should now work.
Make any other settings you require via the web browser interface.
UPSTYPE snmp
For this UPSTYPE to work you will need to make some changes to the NMC via the web browser interface first
Under the Administration and Notification tabs goto SNMP Trap Receivers and press Add Trap Reciever. On the next page add the IP address of your SME server that will be monitoring the UPS and ensure SNMP v1 is selected, Community is public and Authenticate traps is enabled. Now press Apply.
Edit /etc/apcupsd/apcupsd.conf and set the following
UPSCABLE ether UPSTYPE snmp DEVICE ipaddress:161:APC:public
Make any other changes required and save the file.
Continue as above in the Configure apcupsd section - but note the requirements in the snmp and pcnet Killpower section below.
UPSTYPE pcnet
For this UPSTYPE to work you will need to make some changes to the NMC via the web browser interface first
Under the UPS tab, goto PowerChute - Configuration. Enter an Authentication Phrase (This must be at least 15 characters long to be valid) such as
My hidden auth phrase
and Apply
Now under PowerChute - Clients press Add Clients. On the subsequent page add the IP address of your SME server that will be monitoring the UPS and Apply
Edit /etc/apcupsd/apcupsd.conf and set the following
UPSCABLE ether UPSTYPE pcnet DEVICE ipaddress:apc:AuthPhrase
Make any other changes required and save the file.
Continue as above in the Configure apcupsd section - but note the requirements in the snmp and pcnet Killpower section below.
snmp and pcnet Killpower
The standard rpm install copies the /etc/init.d/halt script to /etc/init.d/halt.old and then inserts the following code fragment near the end just after the file systems are remounted read only.
# See if this is a powerfail situation. # ***apcupsd*** if [ -f /etc/apcupsd/powerfail ]; then # ***apcupsd*** echo # ***apcupsd*** echo "APCUPSD will now power off the UPS" # ***apcupsd*** echo # ***apcupsd*** /etc/apcupsd/apccontrol killpower # ***apcupsd*** echo # ***apcupsd*** echo "Please ensure that the UPS has powered off before rebooting" # ***apcupsd*** echo "Otherwise, the UPS may cut the power during the reboot!!!" # ***apcupsd*** echo # ***apcupsd*** fi # ***apcupsd***
Thus for normal operation with a USB or serial cable, a killpower instruction is sent to the UPS just before the server powers down. The UPS then waits for the DSHUTD (Delayed shutdown) period (usually 60 or 90 seconds) and powers off, by which time the final server shutdown and power off should be complete.
With the snmp and pcnet UPSTYPE however, communication is across the network and the /etc/init.d/halt script will have killed the network service before the above code instructs the UPS to power down. In order for the UPS to receive a killpower signal therefore it is necessary to edit /etc/init.d/halt and move the code fragment shown above to nearer the beginning of the script, inserting it as below.
case "$1" in
*start)
;;
*)
echo $"Usage: $0 {start}"
exit 1
;;
esac
# See if this is a powerfail situation. # ***apcupsd***
if [ -f /etc/apcupsd/powerfail ]; then # ***apcupsd***
echo # ***apcupsd***
echo "APCUPSD will now power off the UPS" # ***apcupsd***
echo # ***apcupsd***
/etc/apcupsd/apccontrol killpower # ***apcupsd***
echo # ***apcupsd***
echo "Please ensure that the UPS has powered off before rebooting" # ***apcupsd***
echo "Otherwise, the UPS may cut the power during the reboot!!!" # ***apcupsd***
echo # ***apcupsd***
fi # ***apcupsd***
# Kill all processes.
[ "${BASH+bash}" = bash ] && enable kill
runcmd $"Sending all processes the TERM signal..." /sbin/killall5 -15
sleep 5
runcmd $"Sending all processes the KILL signal..." /sbin/killall5 -9
The UPS will therefore be instructed to power down before the network service is terminated.
This is much earlier in the server shutdown process however and it is important to set the shutdown delay to at least 180 seconds i.e. greater than the time it actually takes your SME server to shutdown following a halt signal. Therefore via the NMC web browser interface goto the UPS tab and under Configuration - Shutdown select the appropriate value for Shutdown Delay of 180 seconds or greater.
Usage of apcupsd
The file /etc/apcupsd/apcupsd.conf controls the configuration of the apcupsd daemon and is well documented. In addition to this /etc/apcupsd/apccontrol is called by the daemon whenever a UPS event occurs, and determines the standard action taken. User configurable actions can be taken by creating/editing files in /etc/apcupsd with names corresponding to relevant events, and these are called first by apccontrol. For example, a file called onbattery will be called by apccontrol whenever an ON BATTERY event occurs, and if onbattery returns an exit code of 99, then apccontrol will not take its own default action.
To view the UPS status of settings and monitored values you can use
/sbin/apcaccess
To configure the UPS EEPROM values you can use
/etc/init.d/apcupsd stop /sbin/apctest
Follow the command line menu to make selections and set UPS configuration vales. The menu varies depending upon if you are using usb or serial communications, but generally allows for querying the UPS status, running a battery calibration, programming the EEPROM values and communicating directly with the UPS in TTY mode.
Don't forget to restart the daemon when you are finished with apctest
/etc/init.d/apcupsd start
See the documentation for further details
Configure Multimon etc Scripts
The apcupsd-multimon rpm contains four cgi scripts that can be run via the webserver to monitor the UPS(s). The rpm does not install them correctly for SME however so the following modifications are needed.
mkdir -p /opt/apcupsd chown root:www /opt/apcupsd mv /var/www/cgi-bin/multimon.cgi /opt/apcupsd mv /var/www/cgi-bin/upsstats.cgi /opt/apcupsd mv /var/www/cgi-bin/upsfstats.cgi /opt/apcupsd mv /var/www/cgi-bin/upsimage.cgi /opt/apcupsd chown root:www /opt/apcupsd/* chmod 750 /opt/apcupsd/* mkdir -p /etc/e-smith/templates-custom/etc/httpd/conf/httpd.conf cd /etc/e-smith/templates-custom/etc/httpd/conf/httpd.conf
Now edit and create a new file 92apcupsdmon with the following content
{
$OUT = "";
my $allow = 'all';
my $pass = '0';
my $satisfy = 'all';
my $name = $apcupsd{'Name'} || 'APC UPS Daemon Monitoring';
for ('exit-if-none')
{
if ($apcupsd{'PublicAccess'})
{
if ($apcupsd{'PublicAccess'} eq 'none')
{
next;
}
elsif ($apcupsd{'PublicAccess'} eq 'local')
{
$allow = $localAccess;
$pass = 0;
$satisfy = 'all';
}
elsif ($apcupsd{'PublicAccess'} eq 'local-pw')
{
$allow = $localAccess;
$pass = 1;
$satisfy = 'all';
}
elsif ($apcupsd{'PublicAccess'} eq 'global')
{
$allow = 'all';
$pass = 0;
$satisfy = 'all';
}
elsif ($apcupsd{'PublicAccess'} eq 'global-pw')
{
$allow = 'all';
$pass = 1;
$satisfy = 'all';
}
elsif ($apcupsd{'PublicAccess'} eq 'global-pw-remote')
{
$allow = $localAccess;
$pass = 1;
$satisfy = 'any';
}
}
$OUT .= "#------------------------------------------------------------\n";
$OUT .= "# apcupsd multimon - $name\n";
$OUT .= "#------------------------------------------------------------\n";
{
if ((exists $apcupsd{'URL'}) && ($apcupsd{'URL'} ne '')) {
$OUT .= "Alias /$apcupsd{'URL'} /opt/apcupsd\n";
}
}
$OUT .= "Alias /apcupsd /opt/apcupsd\n";
$OUT .= "\n";
$OUT .= "<Directory /opt/apcupsd>\n";
$OUT .= " DirectoryIndex upsstats.cgi\n";
$OUT .= " Options +ExecCGI\n";
$OUT .= " order deny,allow\n";
$OUT .= " deny from all\n";
$OUT .= " allow from $allow\n";
if ($pass)
{
$OUT .= " AuthName $name\n";
$OUT .= " AuthType Basic\n";
$OUT .= " AuthExternal pwauth\n";
$OUT .= " require valid-user\n";
$OUT .= " Satisfy $satisfy\n";
}
$OUT .= "</Directory>\n";
}
}
Configure databases and expand the template
db accounts set apcupsd reserved config setprop apcupsd PublicAccess local /sbin/e-smith/expand-template /etc/httpd/conf/httpd.conf
Restart the web server
sv t httpd-e-smith
Usage of Multimon etc Scripts
Now go to http://yourdomain.tld/apcupsd to see the statistics for the UPS at localhost, or https://yourdomain.tld/apcupsd/multimon.cgi for an overview of the UPS(s).
By editing /etc/apcupsd/hosts.conf and adding additional network UPS details, multimon.cgi can be used to monitor more than one UPS. By default only the localhost is monitored.
Uninstall
Use the following commands to stop apcupsd and remove/uninstall it
/etc/init.d/apcupsd stop config delete apcupsd db accounts delete apcupsd rm /etc/e-smith/templates-custom/etc/httpd/conf/httpd.conf/92apcupsdmon expand-template /etc/httpd/conf/httpd.conf sv t httpd-e-smith rm -fr /opt/apcupsd rm /etc/rc.d/rc7.d/S38apcupsd yum remove apcupsd apcupsd-multimon rm -fr /etc/apcupsd
References
See the apcupsd main site.
See the apcupsd manual for further configuration and testing options.
See Uninterruptable_Power_Supply for standard SME use of Nut for UPS monitoring
See original forum post
Original Instructions (DAG)
The following instructions are based on the original forum post http://forums.contribs.org/index.php?topic=45923.0 and the use of an rpm from the DAG repository.
Setup the DAG repository
The following command will configure the Dag repository on SME Server. EDIT NOT COMPLETE!
To create an entry in the database for the epel repository we open put the following commands in a terminal
window or in a shell window:
/sbin/e-smith/db yum_repositories set epel repository \
Name 'SME Server - epel' \ BaseURL 'http://<http://download.fedoraproject.org/pub/epel/7/$basearch' \ EnableGroups yes \ GPGCheck yes \ Visible no \ status disabled
To enable the changes:
signal-event yum-modify
Just to be sure, give yum a fresh start:
yum clean all
After adding it to the database we have to update the changes to the configuration file:
signal-event yum-modify
Installation
Install apcupsd
yum install --enablerepo=dag --enablerepo=base apcupsd
Copy original conf file
cp /etc/apcupsd.conf /etc/apcupsd.conf.orig
Copy CGI files
cp /var/www/apcupsd/* /home/e-smith/files/ibays/Primary/cgi-bin/
Link the startup script
ln -s /etc/rc.d/init.d/e-smith-service /etc/rc.d/rc7.d/S99apcupsd
Set the Service in SME
config set apcupsd service status enabled
Configuration
Edit /etc/apcupsd/apcupsd.conf. The conf file has good detail on setup options.
Suggest setting the TIMEOUT to 600 seconds; You shouldn't let UPS batteries run down to 5% (default) as this massively shortens their life. Set TIMEOUT to 10 for testing.
Reboot or
/etc/init.d/apcupsd start
to start the service.
Usage
http://yourdomain.tld/cgi-bin/multimon.cgi gives a nice look at the UPS status, including a log of past events