Introduction

This tutorial will show you how to configure a VMWare ESXi install to shutdown using an APC SmartUPS. This proven practice came about because our company was sending a Dell PowerEdge T300 server with ESXi and a APC UPS to one of our sales offices. Because it would just be this server and the UPS there, we needed a way for ESXi to shutdown the guest operating systems and then itself gracefully.

This document assumes that you have a VMWare ESXi install with VIMA running on it and an APC SmartUPS with a network management card installed.

This document includes scripts from the VMWare Communities user “lamw.” His scripts are available at http://communities.vmware.com/docs/DOC-9531 Lamw's scripts do not eed the enabling of the unsupported SSH option within ESXi.

Outline

1. Configure the SmartUPS

2. Install apcupsd on our VIMA virtual machine

3. Put lamw's scripts onto the VIMA virtual machine and configure

4. Test

1. Configure the SmartUPS

Now we need to add the VIMA virtual machine's IP address into the allowed hosts for the PowerChute Network Shutdown on the UPS.

Open the UPS's Network Management Card's web interface. Login with the username and password of “apc.” Click on the UPS name in the top left.

Click on the PowerChute link in the left panel now and add the VIMA server's IP address to the list of allowed hosts. Click "Add."

2. Install apcupsd on our VIMA virtual machine

Now we will install the latest version of apcupsd from www.apcupsd.com. The latest version as of writing is 3.14.5. Download the x86_64 version made for el5 (link).

Logon to your VIMA VM and run the following to install apcupsd.

sudo rpm -ivh apcupsd-3.14.5-1.el5.x86_64.rpm

Now we need to edit the apcupsd.conf file. Make sure to change to the IP address to the
IP of the UPS.

sudo rm /etc/apcupsd/apcupsd.conf

sudo nano /etc/apcupsd/apcupsd.conf

## apcupsd.conf v1.1 ##
UPSCABLE ether
UPSTYPE pcnet
LOCKFILE /var/lock
DEVICE UPS_IPADDRESS:apc:admin user phrase
UPSCLASS standalone
UPSMODE disable

Save and close.

Now we will have to disable the iptables firewall running on VIMA.

sudo chkconfig iptables off

sudo service iptables save 

sudo service iptables stop

Now start the apcupsd daemon

sudo /etc/init.d/apcupsd start

Check is it running

ps ax|grep apc

5332 ? Ssl 0:00 /sbin/apcupsd -f /etc/apcupsd/apcupsd.conf

Wait a few minutes and you should see:

Broadcast message from root (Thu Mar 12 03:40:28 2009):

+
Communications restored with UPS s-vima+

Run "apcaccess" to confirm connection to the UPS.

apcaccess

This command should give you back something like this if it connected successfully.

+APC : 001,051,1224
DATE : Thu Jan 08 11:32:21 GMT 2009
HOSTNAME : s-vima
RELEASE : 3.14.4
VERSION : 3.14.4 (18 May 2008) red hat
UPSNAME : S-VIMA
CABLE : Ethernet Link
MODEL : PCNET UPS Driver
UPSMODE : Stand Alone
STARTTIME: Thu Jan 08 11:32:14 GMT 2009
STATUS :
LINEV : 231.8 Volts
LOADPCT : 5.2 Percent Load Capacity
BCHARGE : 100.0 Percent
TIMELEFT : 62.0 Minutes
MBATTCHG : 10 Percent
MINTIMEL : 5 Minutes
MAXTIME : 0 Seconds
MAXLINEV : 234.7 Volts
MINLINEV : 233.2 Volts
OUTPUTV : 000.0 Volts
SENSE : High
DWAKE : 000 Seconds
DSHUTD : 090 Seconds
DLOWBATT : 05 Minutes
LOTRANS : 208.0 Volts
HITRANS : 253.0 Volts
RETPCT : 015.0 Percent
ITEMP : 29.7 C Internal
ALARMDEL : No alarm
BATTV : 27.5 Volts
LINEFREQ : 50.0 Hz
LASTXFER : Automatic or explicit self test
NUMXFERS : 0
TONBATT : 0 seconds
CUMONBATT: 0 seconds
XOFFBATT : N/A
SELFTEST : NO
STESTI : 336
STATFLAG : 0x07000000 Status Flag
REG1 : 0x40 Register 1
REG2 : 0x00 Register 2
REG3 : 0x00 Register 3
MANDATE : 12/13/03
SERIALNO : XXXXXXXXXX
BATTDATE : 12/13/03
NOMOUTV : 230 Volts
NOMBATTV : 24.0 Volts
EXTBATTS : 0
FIRMWARE : 600.3.I
APCMODEL : Smart-UPS 1000
END APC : Thu Jan 08 11:33:55 GMT 2009

3. Put lamw's scripts onto the VIMA virtual machine and configure

These steps are taken from http://communities.vmware.com/docs/DOC-9531 by lamw.

Download ghettoShutdown.pl and upsVIShutdown.pl from lamw's page. Put them into “/home/vi-admin”

Set executable.

chmod 755 /home/vi-admin/ghettoShutdown.pl

chmod 755 /home/vi-admin/upsVIShutdown.pl

Edit the following in “upsVIShutdown.pl”

Insert your ESX/ESXi host(s), use the hostname that you used to add to VIMA managment interface, if you're unsure run:

sudo vifp listserver

Remember to make sure the host that is running your VIMA VM is listed as the last entry.

my @hosts = ("esxi.host1","esxi.host2”);

Modify the logoutput of the shutdown process if you like, default will go to “/tmp/upsShutdown.log”

my $log_output = "/tmp/upsShutdown.log";

Insert the displayName of VIMA or VM that is monitoring your UPS device (case sensitive). Very important step else you could end up shutting down the VM that is executing this script, we wouldn't want that.

my $ups_vm_name = "S-VIMA";

Insert the number of seconds to delay after a guestOS has initiated to be shutdown, this will vary depending on the type of applications the VM(s) may be running, tweak this value as needed. Note, the shutdownVM() is a non-blocking function, if you set the delay to be too short the host could be powered down before the VM(s) have completed powering off (default 15secs).

my $sec_to_sleep = 15;

Now we are going to tweak the apccontrol file to change what is done when the UPS issues a shutdown command.

nano /etc/apcupsd/apccontrol

Edit the doshutdown section like so, change the IP address to the ESXi host:

doshutdown)
  echo "UPS ${2} initiated Shutdown Sequence" | ${WALL}
  /home/vi-admin/upsVIShutdown.pl
  ${SHUTDOWN} -h now "apcupsd UPS ${2} initiated shutdown"
;;

Save and close the file.

4. Test

If you go to the "Control" option on the left menu of the APC SmartUPS Network Management Card interface you can run a test to verify everything works. Change the
"Action" to "Turn UPS Off." Make sure that the ESXi server IS NOT being powered off of the UPS (just for testing).

Click "Next" and then "Intiate Control Action."

You should get this message broadcast on the VIMA server you installed apcupsd on.

Broadcast Message from root@s-vima (somewhere) at 11:50 ...
Remote Shutdown. Beginning Shutdown Sequence.
Broadcast Message from root@s-esximon (somewhere) at 11:50 ...

UPS s-vima initiated Shutdown Sequence

That's it, done.