For PCNS 3.1 users please see the this comment.
If you are running ESXi 4.1 and are using vMA 4 please see here.
A warning about ESXi 5.0 Update 1. There is a known issue with the autostart and autoshutdown feature for free license users. This severely impacts the ability to properly use PCNS on your VMs. A patch was released to resolve the issue and details can be found here.
To get SOAP functionality first download the latest vMA virtual machine from the VMware website. Currently the latest version is vMA-22.214.171.124-782391.
Once the OVF template has been deployed, boot the vMA machine, setup the network settings, and change the vi-admin password from the console window.
Note: vMA 5.x has stronger password requirements that require a non alphanumeric character. If you want to change the password to something less complex set a password during setup and once the vMA finishes loading run the command "sudo passwd vi-admin". You will still get the error "BAD PASSWORD: is too simple" but it will still allow you to change the password and override the requirements.
Login to the vMA using vi-admin as the user and the password you just made. Reboot the vMA for any hostname changes to take effect.
Enter your password and wait for the vMA to finish the reboot. At this point I suggest you close out of console and use an SSH client to connect to the vMA so you can copy/paste commands and avoid mistakes. If you are unable to connect to the vMA via SSH or SCP check your hostname configuration.
Download the ESXi PCNS 3.0.1 package from the APC website. You can find it by going to their website and selecting the Software & Firmware link under Popular Links to the left of the page. Once the page loads select the "Software Upgrades - PowerChute Network Shutdown" from the top drop down and click submit. Under the first 3.0.1 section click the download button to the right. Select the download button for the ESXi package, click the next download button, login to the APC site if you want to receive update notifications, or click Download to get the package.
Using SCP or WGET transfer the ESXi PCNS 3.0.1 package to the new vMA machine. I used /home/vi-admin to avoid permission issues.
Browse to the folder you transferred the files to, extract pcns301ESXi.tar.gz from the console window, and browse into the directory.
tar -xzvf pcns301ESXi.tar.gz cd ESXi
Run the install file,
Enter your vi-admin password and agree to the license terms.
Press Enter for default install path.
Type Yes and press Enter to install.
Now press Enter to install the included java package.
Next it should ask for the IP and credentials of your ESXi. You can press "q" to skip. If you put your IP in it will still work but you will get an error that it wasn't able to add and that you should manually add your host using vifp addserver. This is for vCLI functionality only and is unimportant when using SOAP. Just ignore it.
Edit the shutdown.pl file attached to the end of this post and enter your ESXi host credentials. If using a different user than root make sure they are a member of a role that has both the host and guest power options.
Host: All Privileges -> Host -> Configuration -> Power
Guest: Virtual machine -> Interaction -> Power Off
Use SCP or WGET to transfer the shutdown.pl and shutdown files to the vMA machine.
Still connected the the terminal change to the directory where you transferred the files, if same location as the PCNS package use,
Copy the shutdown.pl and shutdown files to the default setup of PCNS,
sudo cp shutdown.pl /opt/APC/PowerChute/group1/bin sudo cp shutdown /opt/APC/PowerChute/group1/bin
Create a host file and add the ESXi host IP(s). For multiple hosts use new lines for each IP. All hosts must use the same username and password. If this is not an options please see the more complicated option at the bottom of the post.
sudo vim /opt/APC/PowerChute/group1/bin/host
Press "i" to enter insert mode, type the IP address in, press Esc to exit insert mode, and type :wq to save and quit.
Contents should look similar,
Make sure the files are owned by root and set chmod 0744.
sudo chown root /opt/APC/PowerChute/group1/bin/shutdown sudo chown root /opt/APC/PowerChute/group1/bin/shutdown.pl sudo chmod 744 /opt/APC/PowerChute/group1/bin/shutdown sudo chmod 744 /opt/APC/PowerChute/group1/bin/shutdown.pl
Next configure the ESXi shutdown order. Access the vSphere client, select the ESXi host, then the configuration tab.
Click on the Virtual Machine Startup/Shutdown link. Click properties at the top right and use "Move Up" to move the VMs in the order you want leaving the vMA VM at the top. Note that the startup order is the only one displayed. Shutdown uses the startup list in reverse. If you want the VMs to start on their own move them all the way up to Automatic Startup still leaving the vMA VM at the top.
Change the Shutdown action at the top right of the window to "Guest Shutdown" and click OK. Several times after clicking OK I had duplicates of my VMs in the list. A simple refresh (F5) cleans up the list.
Next we need to install VMware Tools on each VM for the graceful shutdown to occur. Once installed edit VM to make sure its settings for shutdown are correct. Right click the VM -> Edit Settings -> Options Tab -> VMwareTools. Under Power Controls Stop should be set to "Shut Down Guest".
Connect to the IP of the vMA machine ex. https://10.0.0.9:6547/login and setup your connection and events as needed. Make sure you remove the check box in the "Turn off UPS" box under Configure Shutdown unless you have the "Restart when power is restored" option set on the APC. To fire the script configure the UPS: On Battery event by clicking the Shut Down System box (not Run Command File). Check the box to shut down the PCNS operating system and enter the time in seconds before the event fires.
To test you can either unplug utility power to your APC and use the "UPS: On Battery" event or run the following command from the vMA console window,
cd /opt/APC/PowerChute/group1/bin sudo ./shutdown.pl host
This will gracefully shutdown the VMs in the order you set before telling the ESXi host to power down. You should see the shutdown commands in the log start when connected to the ESXi host with the vSphere client. If the VM fails to gracefully shutdown check to make sure VMware Tools is running on the VM under its Summary tab in vCenter.
As a side note make sure you give each VM ample time to power off before your battery power runs out.
If you are having problems with the virtual machines not shutting down gracefully please see this VMware article here. Also a note that PCNS and most management cards do NOT accept special characters in the password. Please see this article on the APC site for details.
If you have multiple hosts and having the same username and password across the board is not an option the shutdown file will need to be modified. You will need to add a new line as well as copies of the shutdown.pl and host files to point to each host. As an example,
perl ./bin/shutdown.pl ./bin/host perl ./bin/shutdown2.pl ./bin/host2
In the example host #1 uses root and abc123. The shutdown.pl file will need these credentials entered in and host #1's IP will need to be entered in the host file. Host #2 uses root and dog1234. The shutdown2.pl file will need host #2's credentials and the host2 file will need host #2's IP Address. Running each shutdown.pl file against 1 host file with all the IPs for all of your hosts is not suggested as it generates bad password attempts on the hosts and can cause the shutdown to timeout.shutdownPCNS3.0.1.zip
Credits to lamw for the SOAP script here.