Installing PowerChute Network Shutdown (PCNS) for Virtual Machines using Virtual Management Assistant (VMA)

Background Info:

The following is a step by step guide for configuring virtual machines to auto shut-down using PCNS and the free version of VMWare ESXi. These steps will work also work for the paid licensed version. If you're already familiar with VMware feel free to skip the next paragraph.

VMWho?

If you're completely new to VMWare and don't have the foggiest of where to start or what's what, read on. Firstly you'll need ESXi installing on a server. ESXi acts like an operating system on the server, so instead of booting into windows it will boot into ESXi. If set-up properly you should be able to navigate to the IP address of the Host Server (The server ESXi is installed on) and be greeted with an information page. On this page will be links to download the relevant client to create and manage our virtual machines. In this instance we'll be using the vSphere Client.

VMWare Licensing

There are a few differences between the paid licensed and free licensed versions of ESXi but for the sake of this guide, there is only one that is relevant to us. That is that with the free version, we don't have access to certain things we need to run the shut-down file that comes with PCNS. The paid version should work with PCNS straight out of the box, however there is no reason the below steps won't work with it either.

Software used in this procedure:

Software	Version	OS	Link to Website
VMware vSphere Client	4.1	Windows
VMware ESXi	4.1	N/A	VMware ESXi 4.1
VMA	4.1	VMware ESXi	VMA 4.1
WinSCP	4.3.6	Windows	WinSCP
PowerChute Network Shutdown	3.0	VMware ESXi

Files used in this procedure:

You will need 3 files for this procedure.

1. shutdown
2. shutdownViaSOAPAPICall.pl
3. host

shutdown comes with PCNS and will be discussed later in the procedure.

shutdownViaSOAPAPICall.pl can be downloaded here: http://communities.vmware.com/docs/DOC-11623

host you need to create yourself with the following simple steps.

• create a txt file and enter the IP address of your ESXi host server.
• save the txt file with the name 'host', removing the .txt file extension

For the below procedure to work you must have VMware Tools installed on each Virtual Machine on the ESXi host.

Installing VMA

Install VMware vSphere Client on the machine that is to manage the Virtual Machines.

1. Log into the host server
2. Navigate to ‘File à Deploy OVF Template…’

3. Select the VMA OVF file
4. Go through the setup wizard

Configuring VMA

If installation was successful, you should have another virtual machine entry with the name you just defined for the VMA.

1. Right click and power on the VMA
2. With VMA highlighted, navigate to the console window

Once powered up, the VMA will run through a series of questions, asking you to configure the IP Address, SubNets, Gateway, DNS Servers and hostnames. Complete these as desired. A static IP for the VMA will be required.

You will now need to set the password for the VMA. If you are asked to enter the old password, just press enter.

The VMA set-up should now be complete.

Installing PCNS on VMA

Make sure you have the correct version of PCNS for the VMA. The version you need should say ‘ESXi’ in the file name.

1. Connect to the VMA using WinSCP
2. Leave ‘Private key’ file empty and change file protocol to ‘SCP’

If you get a prompt about the host key not matching, press update and it will let you continue.

3. Copy the installation zip folder to <root> /tmp
4. Go back to the consol window of the VMA

Press ‘Alt + F2’ and log into the VMA in the console window and type the following commands (commands are case sensitive);

5. sudo chmod 777 /etc/rc.d
6. sudo mkdir /etc/rc.d/init.d
7. cd /tmp
8. sudo gunzip pcns300ESXi.tar.gz
9. sudo tar -xvf pcns300ESXi.tar
10. cd ESXi
11. sudo ./install_en.sh

Next;

12. Press any key to display and scroll through the End User License Agreement
13. Type ‘yes’ to the question;
• 'Do you agree to the above license terms? [yes or no]'
14. Press enter to accept the default installation directory
15. Type yes to the question:
• 'Are you sure you want to install PCNS to /opt/APC/PowerChute [Yes|No]?'
16. Type ‘/usr/java/jre-vmware/bin’ to the question:
• 'Please enter java directory if you want to use your system java or press enter to install the bundled Java:'

Next you will be prompted to enter the ESXi host IP, press ‘q’ to skip this step as we’ll configure this later. Installation of PCNS is now complete.

Configuring PCNS on ESXi

Now we need to add the ESXi host to VMA so that the PCNS software can communicate with it.

1. Type: vifp addserver <ip address of host machine>
• EG: vifp addserver 192.168.0.1
2. Enter the password for the ESXi host when prompted
3. Type: ‘vifp listservers’

If adding the host server has been successful, you should see the server listed.

Now we need to set-up the PCNS software.

4. Navigate to https://<ipaddress you defined for VMA>:6547
5. EG, https://192.168.0.1:6547
6. Go through the set-up wizard as required

Next

7. Log into PCNS and navigate to ‘Configure Events’ on the left hand menu.
8. Select ‘Shut Down System’ on ‘UPS: On Battery’

9. Tick ‘Yes, I want to shut dwon the PCNS operating system.’
10. Enter how long you wish PCNS to wait whilst the UPS is on battery, before initiating a shutdown.
11. Navigate to 'Configure Shutdown'.
12. Enter the following for 'Run this command file (full name)'
• /opt/APC/PowerChute/group1/bin/shutdown
13. Enter ‘120’ in the ‘The command file needs this much time to complete (seconds)’ field

Pulling it all together

Next we need to amend the permissions so that we can change the existing shutdown files, as the ones that come with do not work with the unlicensed version of ESXi.

1. With the VMA highlighted in vSphere, go to the ‘console’ tab
2. Click in the window to make it active
3. Press ‘Alt + F2’ to go to the VMA login screen
• Username: vi-admin
• Password:
4. Type the following commands (commands are case sensitive)
• sudo chown vi-admin /opt/APC/PowerChute/group1/bin/shutdown
• sudo chown vi-admin /opt/APC/PowerChute/group1/bin/
• sudo chmod 744 /opt/APC/PowerChute/group1/bin/shutdown
• sudo chmod 744 /opt/APC/PowerChute/group1/bin/

vi-admin should now have write access to both the shutdown file and folder.

5. Edit the shutdownHostViaSOAPAPICall.pl file so that it includes your ESXi hostname and password.
6. Edit the host file (open with notepad) so that it contains the IP Address of the ESXi host
7. Using WinSCP, navigate to /opt/APC/PowerChute/group1/bin
8. Edit the shutdown file and replace the current file path with the following  (all on one line, see below image) ;

perl /opt/APC/PowerChute/group1/bin/shutdownHostViaSOAPAPICall.pl /opt/APC/PowerChute/group1/bin/host 

9. Now using WinSCP, copy
• shutdownHostViaSOAPAPICall.pl
• and ‘host’ to /opt/APC/PowerChute/group1/bin/
10. IMPORTANT: Make sure to set the Transfer settings to ‘Text’

Finally, we need to amend the way the ESXi host manages the virtual machines when it’s told to shutdown. Do the following.

11. Highlight the ESXi host (left hand side) in the vSphere Client
12. Navigate to the ‘configuration’ tab (right hand side)
13. Select ‘Virtual Machine Startup/Shutdown’

14. Select ‘Properties’ (top right)
15. tick ‘Allow virtual machines to start and stop automatically with the system’
16. Set the ‘Default Shutdown Delay’ to 30 seconds
17. Set the ‘Default Shutdown Action’ to ‘Suspend’ or ‘Guest Shutdown’
18. Edit the VMA shutdown settings so the shutdown action is ‘Power Off’

19. Add each of the Virtual Machines to ‘Automatic Startup’, making sure that the VMA is number 1

Note: The settings detail in steps 13 – 15 (above) are configurable dependant on user preference. There are 3 things that you must do regardless of the settings you apply.

• Make sure VMA is listed first in automatic startup
• Make sure you have enough ‘Shutdown Delay’ for the machines to shutdown before the host does.
• Make sure the VMA is set to power off on shutdown, setting it to suspend will mean the PCNS service will not restart 

Your Virtual Machines and UPS should now be configured to shutdown automatically in the event of a power outage.