Uninterruptable Power Supply:APC

	Skill level: Medium
	The instructions on this page require a basic knowledge of linux.

Installation of Latest Version

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'

	Note:
	SME uses Nut as standard for UPS monitoring and control and works with a more than just APC UPS models. See Uninterruptable_Power_Supply for details

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

	Tip:
	See the section below on Network Management Cards for specific settings and notes relating to using the UPS with a NMC such as AP9617 across the network

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

	Note:
	If you are using UPSCABLE usb and UPSTYPE usb, and you get a status messages such as apcupsd (pid 14420) is running... Error contacting apcupsd @ localhost:3551: Connection refused then this may be due to Nut. Make sure Nut is stopped and disabled as above. You may also need to disconnect and reconnect the USB cable after Nut has been stopped

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.

Make your settings via the web browser interface.

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.

	Note:
	The /sbin/apctest utility will not work across the network using the snmp or pcnet UPSTYPE as it does not have write access. Yo will therefore need to make the necessary configuration settings via the APC UPS web browser interface

UPSTYPE snmp

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.

	Note:
	ipaddress is the IP address assigned to the UPS. The default port is 161, default vendor is APC and default community is public

Continue as above in the Configure apcupsd section

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 server that will be momitoring 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.

	Note:
	ipaddress is the IP address assigned to the UPS. The default user is apc (and apparently can't be changed), and the AuthPhrase is the Authentication Phrase as set above

Continue as above in the Configure apcupsd section

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

	Note:
	The UPS EEPROM value for RETPCT (Return Percentage - battery charge required before UPS powers up/on after failure) should be greater than the value of BATTERYLEVEL (battery charge level that initiates a shutdown) in /etc/apcupsd/apcupsd.conf

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

	Note:
	The above sets access to the scripts to local ip addresses only. See the Web_Application_RPM#New_DB_settings for further info and settings

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 apcupsd.conf 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

---