Rebel IT Mumblings of a crazy programmer…


VMware PCNS ESXi 5.x Free License shutdown with APC PCNS 3.0.1 and vMA 5.x

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-

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.

sudo reboot

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,

sudo ./

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 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 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,

cd ..

Copy the and shutdown files to the default setup of PCNS,

sudo cp /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/
sudo chmod 744 /opt/APC/PowerChute/group1/bin/shutdown
sudo chmod 744 /opt/APC/PowerChute/group1/bin/

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.

ESXi Guest Shutdown Settings

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".

ESXi VM Shutdown Settings

Connect to the IP of the vMA machine ex. 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 ./ 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.

VMWare Tools Running on Debian

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 and host files to point to each host.  As an example,

perl ./bin/ ./bin/host
perl ./bin/ ./bin/host2

In the example host #1 uses root and abc123.  The 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 file will need host #2's credentials and the host2 file will need host #2's IP Address.  Running each 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.

Credits to lamw for the SOAP script here.

Filed under: VMware Leave a comment
Comments (76) Trackbacks (2)
  1. I have used your manual and it has really helped me! I would add 1 extra thing:

    SSH is default disabled in vMA 5.0. To enable it you need to vi /etc/hosts.allow. In the bottom add: sshd: ALL : ALLOW.

    • You only need to do this if your DHCP server does not provide a hostname along with the IP Address. If your hostname is set properly based on a static lease given by the DHCP server the default ALL: KNOWN will allow users on the same subnet to access the server without modification. If your DHCP server does not provide a static lease or you set your hostname wrong on setup you will need to make the modification you suggested. For instance I gave the vMA virtual machine the same IP and hostname as I was going to define on my DHCP server. After the vMA was at the login screen I collected the MAC address that the ESXi host gave the virtual machine and inserted it, the IP, and the hostname into a static lease on my DHCP server. I then rebooted the vMA and when it came up it was handed the lease by the DHCP server and I am allowed to access the vMA via SSH on the same subnet without any modifications to the hosts.allow file.

  2. Have followed the procedure, everything according to what is expected but I am not able to log into PowerChute. “Invalid User name or Password”. Have tried both my vi-admin pw and my root pw on m y host without any success. Which user and pw am I supposed to use?

    • The password is the one setup on the management card originally. You use the same username and password to setup the connection as well. Note that management cards do not accept special characters in their passwords.

      • Not sure what you mean about management card? I do not have any kind of hardware, except for my UPS connected to my EXSi 5 (free licence) via USB.

      • ok, I see what you mean. Obviously I’m using the wrong product. I’m using my system as my home server with only one single machine. I want my APC Back-UPS RS 550VA to connect directly to this machine and to shut down my vm’s via a software only solution. Clearly I have installed the wrong software. Which PowerChute sw should be used for my configuration?

        • I’m not sure about that one. I use a 1400RM with a Network Management Card with a single ESXi whitebox. I don’t think APC supports any solution for anything other than an APC with a NMC in it for ESXi servers. You could probably setup a windows virtual machine and have the USB pass through having that server shutdown last. The APC only needs the signal to shutdown and then it takes over so it may work this way however I am unsure exactly how the non enterprise APCs run PCNS. This may be a function of the NMC and I don’t have a smaller APC to test with. I have also heard of people using a USB to serial connector or a USB to Ethernet adapter and doing it that way. From what I understand this is highly experimental and APC provides no support so you are on your own.

  3. thanks you for the post. I followed it and everything is working for the one vsphere server. I have 5 other vm vsphere servers that I added to the hosts file, but I am not sure if I need to install Vma and configure powerchute on them as well. Is that needed or since they are in the hosts file on this powerchute installation on this Vma, will it shut them down as well? I guess I’m a little confused..thanks for the reply

    • If you want to use multiple hosts and they all have the same username/pass then simply adding the other host IPs will work just fine. Just make sure you leave the host with the vMA last on the list and set the shutdown order on each server. For hosts with different logins you will need to duplicate the script and add each one to the shutdown file. As an example,

      perl ./bin/ ./bin/host
      perl ./bin/ ./bin/host2
      perl ./bin/ ./bin/host3

  4. Thanks for the clear guide, made the whole process very simple :)

    One issue i have is my ESXi severs are configured with one power supply connected to the UPS and the other straight to mains from a different circuit.

    The scenario can arise where the UPS loses power and starts to run on battery, but the ESXi servers are still receiving a supply on the second PSU which has not been interrupted, however after 20 minutes(the period i specified) the UPS will send the shutdown command and the ESXi servers will shutdown.

    Is there anyway for the script to only execute the shutdown, if it sees that only 1 PSU is working (The one which is connected to the UPS) in the event of a power outage on both circuits ?

    Hope that makes sense ?

    • It makes perfect sense. I would contact APC for a suggestion to fix that as that would be a core function of PCNS and not the SOAP script. This simply changes what happens when PCNS commands the system to shut down and uses SOAP instead of CLI to communicate the shutdown commands to the ESXi server.

  5. Is configuration required to execut the command files dropped in group1/bin? It appears that by default all that wil happen is logging. Do I need to configure it as a command to run or a system shutdown?

    • Yes you need to setup an event on the web GUI for PCNS on the vMA just like you would if you were running PCNS without changing the way it commands the system to shutdown. Without it only logging occurs. Normal PCNS documentation can help you with this. I use the On Battery event to shutdown the system after 30 minutes has passed.

  6. Hello, I’m getting the following error when issuing the command:

    # sudo ./ host
    vi-admin’s password:

    An Error Occurred

    An Error Occurred
    500 Can't connect to (certificate verify failed)

    Failed to issue shutdown command to

    The IP is indeed correct, and the username and password are correct. I can’t seem to find any Google resources either. The only difference in your setup is that I’m using vMA

    Thoughts? Thanks for your write up so far.

    • That sounds like a certificate or hostname issue on the ESXi host itself. Are you getting certificate errors when connecting to the host using the vCenter client? Maybe your hostname isn’t set properly on the host? Try running one of the vMA tools to connect to the ESXi host and see if you get the same thing,

      Telnet into the vMA,
      cd /usr/lib/vmware-vcli/apps/general
      ./ –server x.x.x.x

      If you don’t get certificate errors in vCenter or when connecting to the host via the web then maybe you configured the hostname wrong on the vMA.

      • Thanks Canabalooza,

        The connect script you suggested worked fine for me, no certificate errors whatsoever.

        I didn’t discover your tutorial until after vMA was installed and I did do a few things differently. I’ll blow away the vMA and try again from scratch.

        Thanks for your time and help!

        • That is definitely a weird one. Let me know if you figure it out! I looked around but couldn’t find much at all. I would be interested in seeing what is causing the issue.

          • Hey,

            So I did everything scratch again, and still no luck. I’m getting the SSL certificate error. It seems like it the Perl library that they’re using isn’t allowing self-signed certificates. Not sure on how to proceed from here.

            Any ideas on how to reconfigure the Perl library?

    • Hi Mike

      I had the same problem. The cause is a wrong host certificate. Check if it was issued for your hostname and domain. Mine was issued on localhost and localdomain. Meanwhile the server had been renamed. If that is the case do this:
      * open SSH session to your ESX
      * /sbin/create_certificates
      * reboot ESX, close vSphere Client
      * after reboot open vSphere Client (should show new certificate warning)

      hope that helps

      By the way: very good posting – helped me a lot. I wrote a complete setup guide on my blog too (with credits to RebelIT of course). :-)

      cheers Michael

  7. Canabalooza,
    I set this up followed the instructions from APC and also looking at your site as a second guide. The problem I’m having is that the pcns sent the command in the logs of pcns to shutdown but nothing shutdown the vm’s nor the pcns and everything went down hard. Any ideas on any logs to look into what happened or testing regarding this?

    • You have to setup the startup/shutdown order/timing AND have VMWare Tools installed on each machine in order for the machines to shutdown gracefully. If the host shuts down then PCNS is working properly and your host and VMs are configured incorrectly.

  8. Nothing shuts down. APC is like it is working because it got the command and issued the command. I know everything went down hard.

    • I don’t quite understand what you are saying? Is the host shutting down without gracefully powering down the VMs? If so that’s a host config issue. If you look at each VM in vCenter it shows if VMWare Tools is running or not. If it’s not running the VM will just cut power and go down hard. You MUST setup the startup/shutdown order on the host and adjust the delays. If you’re only seeing the shutdown in the PCNS log and the host never shuts down you need to check the username/password in the SOAP script and make sure you have a shutdown event set in the PCNS web interface. Run the test via command line, if the host goes down then it’s working fine otherwise it will give you an error and the vMA will do nothing along with the host. If you’re using a paid license and PCNS without editing it to use the SOAP script you have to edit your username and password in the default shutdown file. The default install of PCNS also requires you to add the host to the vMA to use CLI to command the server. Free licenses do not work with the default install and must use the SOAP script. There is no way around a graceful shutdown without VMWare Tools installed and running on each VM.

      • sorry for the confusion but I have vmtools installed everywhere the vma is using the tools it came with. I have esxi configured to shutdown the vm’s. NOTHING shut down gracefully or even attempted. Everything went down hard. I’m on the phone with APC on this I will see what they come up with. Not sure on the soap script as I said I’m using the APC files and setup instructions but used your guide as a reference as it contained valuable information.

        I was just wondering if there were some logs in the vMA I can review.

        • Sounds like you didn’t put the host username and password in the shutdown file that comes with the default install or you never added your host to the vMA using vifp addserver. This guide is only for free license servers as the default CLI control is disabled and PCNS does not work.

  9. I have the same issue with PCNS 3.01 and Vpshere 5.0 U1
    did you find the solution ?


  10. error message :

    An Error Occurred

    An Error Occurred
    500 Can't connect to (certificate verify failed)

    Failed to issue shutdown command to

    • I would suggest you contact VMWare about the issue. I avoided Update 1 on my lab servers as there is a known issue with the autostart and autoshutdown feature on free licenses only and I cannot reproduce the SSL issue on 5.0 build 504890 using PCNS 3.0 and 3.01. It sounds like whatever changes they made messed a lot of stuff up. You can downgrade to restore the functionality and may fix the SSL issues but other than that this sounds like an ESXi Update 1 issue that should be taken care of by VMWare. If you have a paid license just submit a support ticket. If you use a free license downgrade your host until they release ESXi 5.0 Update 2 containing the fixes for free license users. You could also try something like this and see if it helps, “the work around is go to VI client->Administration->SSLSetting to disable ssl verification.”

  11. I reinstall ESXi 5.0 (without Update 1), I still have the certificate error.
    perhaps I need to reinstall also vMA (without update 1) and PCNS3.01, I will try…

    • You could try adding this to the top of the file,

      $ENV{SSL_verify_mode} = 0x00;

      Below the first comments section and see if it is a Perl SSL issue with the SDK. If that does not work and you cannot run the script manually by doing,

      cd /opt/APC/PowerChute/group1/bin
      sudo ./ host

      you could try contacting the author of the SOAP script here. He is on the VMWare forums as well.

  12. it’s works with the command

    Thanks a lot

  13. Anothers questions :
    – Can I add ESXi (under license) via vifp addserver and use your script for Free ESXi ?
    – The script is execute at last during the shutdown process ? Because my VMA is installing on my free ESXi server.

    Thanks for your feedback

    • – Can I add ESXi (under license) via vifp addserver and use your script for Free ESXi ?

      No, vifp addserver is for using vCLI functionality. Once you enter your free license it becomes useless and unavailable.

      – The script is execute at last during the shutdown process ? Because my VMA is installing on my free ESXi server.

      You can have the vMA on the machine you are shutting down. This is how I do it. When you configure the virtual machine startup/shutdown order put them all in automatic startup with the PCNS server at the top. This means that it is the first to power on and the last to power down. The order does not really matter though as once the shutdown event it fired off to the host it takes over and is going to power down the VMs and host whether or not the vMA is booted.

  14. Does this work with the paid version of ESXi 5? What do I actually put in for the command section of the PowerChute software? Under “Configure Shutdown”, I currently have “/opt/APC/PowerChute/group1/bin/ /opt/APC/PowerChute/group1/bin/host” (without the quotes) for “Run the command file (full name)” but the event log in PowerChute has “WARNING: Disabling command file execution for event ShutdownStarting due to bad parameters. Please validate the configuration.” and “ERROR: Event ShutdownStarting is enabled for command file execution, but an invalid value for ShutdownCommandFile is specified.” How do I fix this?

    • While this should work for the paid version PCNS is only for the paid license which is why SOAP must be used in it’s place. You should not need to do this if your host is licensed and has vCLI functionality.

    • I’m curious to this as well. I don’t understand what to do with the paid version of ESXi 5. Did you figure out what you needed to do?

  15. I have tried the above methods on both ESXi 5 update 01 and ESXi 4 update 03 Free License Servers, but the Host turns off abruptly and there is no graceful shutdown of VMs when i execute the command ./ host ,in the log i see these messages- Initiated host shutdown.
    I have installed VMWare Tools. Also at vmware client->Configuration->Virutal Machine Startup/Shutdown->tried changing to Manual and Automatic Startup.

    Please let me know why the host/vms are not having graceful shutdown?

    • There is a known issue with ESXi 5 Update 01 not listening to the automatic startup/shutdown list. ESXi 4 should work just fine however if you do not move the VMs to automatic they will fail to power down gracefully. Check the VMWare Tools status on each VM via vCenter. If it really is running it will say so.

  16. Hi – I’m wondering if I missed a step and maybe you can help me out. If I run the script, the vms and host shutdown. If I unplug my UPS, nothing shuts down. What calls that script? What did I miss?


  17. Hi

    I followed your instructions, but for some reason I can’t access the PowerChute Web page ( on the vma, but I can access the vma webpage on ( I’ve spent the last two hours pouring through every document about this, but it doesn’t seem to be a common problem with anyone else out there.

    Is there something I’m doing wrong

    • Is that an external IP? Firewall might be to blame. If not I would check to see if the PCNS process is running on the vMA and reboot if not. I had issues with this when I was trying to use older versions of PCNS on newer versions of the vMA as they changed the OS the new vMA’s use.

    • Hi,
      Make sure that you are installing the correct version.
      If you are setting up on ESXi5 host make sure you downloaded/used the ESXi pcns. I had the same issue when I downloaded and tried installing the ESX version of the package on an ESXi host by mistake.
      The firewall suggestion is a valid reason too but VMa 5 update 2, not sure if update 1 and before aswell, are set to allow all incomming connections. There are no firewall chains. this applies if that IP is internal

      Hope this helps.

  18. So I am assuming here the API functionality with the Paid Version of ESXi is actually what allows PCNS to communicate with the VMA and trigger the shutdown script based on an On Battery event?

    Is it possible to use the On-Battery trigger and a command with PCNS for the Free version of ESXi 5.1? Right now the only thing I can do is issue a manual shutdown from the VMA. PCNS does not recognize/run any commands when the On-Battery event is triggered?

    What is the correct syntax in PCNS under the command area?


    • The paid version uses CLI and the built in shutdown script provided by APC in the default install of PCNS with some modification (login details). Using the “Free” version of the script provided by lamw from the VMWare team you can use SOAP, same protocol that the vSphere client uses, to access and shutdown the host. The APC only needs to have the On Battery event configured to “Shut Down System”. Select the “shut down the PCNS operating system” option and set your timeframe for the event to fire. This needs to be done via the WebGUI of the PCNS client and not the APC itself. When configured properly PCNS will now call the “Free” script and request the host power down the virtual machines, provided that you setup the startup/shutdown order on the ESXi host, and then power down the host when it has been completed.

      • Ahh!

        Thanks for the quick reply. So – I think I see where I went wrong here, I actually had “Run Command on File” checked off in the PCNS Web GUI, and was using the path of lamw’s script, rather than “Shut Down System” checked.

        Unfortunately I cannot test this until Thursday of this week, but I will give it another shot then. I’ve followed the instructions to a tee, and am using and have tested the shutdown soap script from VMA CLI, and it powered off all Guests then the host successfully.

        So I am assuming here, there is a call of some sort when battery is triggered, and the Shut Down System is activated, it must run the script when PowerChute senses the shutdown alert on the VMA?

        My real question here is, everything is tested successfully with the SOAP script manually – but how does it actually tie in to PowerChute so it knows to run when the “Shut Down System” has been activated?

        Thanks for the quick response and detailed write up by the way!

        • The default install of PCNS runs the shutdown script located here (if left as default),
          from its daemon which then calls the file also located in the same directory. In the default version of the shutdown file is the login connection string which you are supposed to edit if using a paid ESXi license,

          perl ./bin/ –operation shutdown –username xxxxx –password xxxxx

          Uploading the SOAP script and changing the shutdown file to the following,

          perl ./bin/ ./bin/host

          calls our new script when the PCNS daemon fires the event instead of the default shutdown-> method. The shutdown file is simply included for ease of process.

          Keep in mind the path to test this is supposed to be different than the script put in place just like it would if you tested the default install script. The daemon runs from the folder /opt/APC/PowerChute/group1 and not inside the bin folder. Hence the default string being,
          and the modified string being,
          ./bin/ ./bin/host

          • Just an update –

            this worked perfectly. Where I went wrong was I forgot to copy over the ‘shutdown’ file in addition to ‘’. Once this was done and proper permissions were set, and credentials altered – it worked like a charm.

            Thanks again for the write up and replies!

  19. Hi,
    i have tryed to get it working. But it seems that i am missing something.
    Thanks in advance

    vi-admin@test03:/opt/APC/PowerChute/group1/bin> sudo ./ host

    An Error Occurred

    An Error Occurred
    500 Internal Server Error

    Failed to issue shutdown command to

    • Is that the IP of your ESXi host? Also did you edit your username/password into the script? 500 error usually means unable to connect.

      • In my case, the following error was caused by having a special character in the password for the root account used to shutdown the ESXI host. An “&” in the password was the culprit.

        An Error Occurred

        An Error Occurred
        500 Internal Server Error

        Failed to issue shutdown command to X.X.X.X (IP address of my ESXI host)

  20. Hi,

    A very good article and script. How can I disable HA and DRS?


    • I do believe you can disable HA via the following here and DRS here.

      • Hi,

        I meant to ask, does this script disable HA? If not, is there a way to disable it using this script?


        • Since the script uses SOAP commands and mimics the shutdown command sent from the vSphere client to the host I don’t think it disables HA. If VMWare Tools is installed on the guest it will shutdown gracefully and HA will not restart it unless it was hard powered down. Since Startup/Shutdown is disabled in an HA cluster this may cause some issues trying to power the VMs up automatically after the UPS has shutdown the host. If you are not using a free license on the hosts I would suggest using the default setup for PCNS to handle your shutdown instead of SOAP calls that mimic a manual shutdown of the host from the client.

  21. many thanks Canabalooza
    this script can work also with vsphere 5.1 u2 ( last buil of 5.1)

    thanks again Alberto

  22. Does anyone know if this procedure really works for ESXi 5.x (ie 5.5 as well as 5.0)? Or has anyone already tried and succeeded?


    • This method does still work with ESXi 5.5 (update 1 too!) and vMA 5.5 using PCNS 3.0.1. The latest version of PCNS 3.1 no longer works this way though. The files still exist in their proper locations however they are using API to connect to the host when using the “Shutdown” option in the PCNS web console.

      Free license users will see repeated “Find entity by IP” messages on their host and eventually PCNS will timeout and do nothing. Note: This can also be caused by an issue that was patched by APC here for standalone paid users. Free license users will see “com.vmware.vim25.RestrictedVersion” errors in the PCNS error.log file when using PCNS 3.1 and will not work due to licensing.

      This can all be fixed though by modifying the /opt/APC/PowerChute/group1/bin/shutdown file and replacing,

      perl ./bin/ ./bin/host


      perl /opt/APC/PowerChute/group1/bin/ /opt/APC/PowerChute/group1/bin/host

      When configuring PCNS via the web console change the “On Battery” event to “Configure Run Command File” instead of “Shutdown” and paste the following,


      The host will then execute the proper files and shutdown properly. A note here though, you will loose the ability to turn off the APC after the power down event.

      You can avoid all this though by sticking with PCNS 3.0.1 which is currently still available for download from the APC website here.

  23. Hi

    is there any chance to do similar modification in PCNS 3.1 ?
    the /opt/APC/PowerChute/group1/bin/shutdown looks quite different here.

    /sbin/shutdown -h +$1 “PowerChute Network Shutdown has initiated a system shutdown.”

    • Not very easily from what I can tell. The pcns.jar file would need to be decompiled, modified, and recompiled to strip out or modify the API calls and move things back to the old 3.0.1 method.

  24. Thank you very much.

  25. I remember fighting with this website before. The download is not accessible from within VMA to direct download the script from this website.

    vi-admin@localhost:~> wget ‘’
    HTTP request sent, awaiting response… 403 Forbidden

    But the download works on Windows web browsers for some reason.

    Why do you have to make this “easy” process so much harder, that I need to install my own FTP server to download this script into VMA?

  26. Ah, I see. This website is for some reason forbidding the WGET user agent to access this page, probably to prevent spidering access.

    For other readers of this page, to directly download the script zip into VMA, you need to tell WGET to use a different user agent, so that this website doesn’t block your access.

    This worked for me from within VMA 5.5:
    wget -U ‘Mozilla/5.0’ ‘’

  27. Hi,

    thank you for all the work on this page.
    Since I’ve installed pcns 3.1 on a vMA in a licensed ESXi 5.1 environment with three hosts I’m stucking now when trying to connect to the powerchute agent on the ESXi on port 3052 from the powerchute website (Error: no answer from website).
    Looking on the ESXi host for open ports, no process listens on udp or tcp port 3052. The firewall on ESXi is opened on the required ports.
    My question is, how can I test the remote shutdown from the vMA to ESXi host.

    Thanks in advance for answers


    • If you are trying to get into the PCNS web interface to configure your events you should connect to the IP of the vMA using port 6547. Ports 3052 (TCP/UDP) and 6547 (TCP) need to be open to the vMA. Port 80 (TCP\http) or 443 (TCP\https) needs to be open for the NMC in the APC but you can change the port to anything on these normally. There is also a PCNS Appliance that can be used as well. Nothing should get installed on the host itself. 3.1 uses an API connection to the host to request the shutdown which is configured after you connect to the vMA on the above port. In previous versions you used vifp to add the servers to the vMA. 3.1 now requires that ESXi be licensed so I have not fully tested it in my lab environment as I am using free and trial licensing for all my hosts.

  28. Hi Canabalooza.
    I get it working with PCNS 3.1.
    Only modification i must do was PCNS must be stoped when scripts are copied to /otp/Po…/bin
    This is workgin with free ESXi 5.5U1 vMA5.5 + update1 and PCSS 3.1.

  29. Hi Canabalooza,

    thank you for your reply.
    All you described is installed configured on the vMA.
    My only doubts are “ist this fully functional?” because I see no chance to test the function of graceful shutdown on the production environment.
    As far as I know, the vmware test licenses give a full function set for a certain time to test things before buying the OS, but it seems you didn’t check if powerchute ist working with that mentioned API connection.
    Don’t you have any idea, how this could be tested before being switched into productive mode?


  30. Wonderful website you have here but I waas wanting to know if you knew
    of any user discussion forums that cover the same
    topics talked about in this article? I’d really
    love to be a part of group where I ccan get comments from otherr knowledgeable people
    that share the same interest. If you have any recommendations, please let mme know.
    Thanks a lot!

  31. Fantastic document. Blows the doors off the power point slide show APC provides. But I am a little bit confused trying to reconcile your guild and the one from APC. APC has me adding all the hosts to fastpass with “vifs addserver “. Why is it your guide lacks these steps? APC also doesn’t mention a host file in the group1/bin directory. Why do these differ? You add a file. There is already a shutdown and file in the …/group1/bin directory. Am I to remove this file? How does APC/VMware know to call your file instead of the file?

    I also have a second UPS. Network Shutdown seems to only allow a Single UPS when not running in parallel or redundant mode. Can I use the signals from one UPS to shutdown servers/hosts powered by a different UPS? Can I add a second UPS to PCNS or do I have to install another vMA Server?


    • The “vifs addserver” command is used for paid ESXi hosts. So is the different file and adding the hosts file. If you have paid ESXi hosts, then this method is not required. If you have free ESXi hosts you get the error “com.vmware.vim25.RestrictedVersion” when attempting to use the normal method. Also, ff you are using PCNS 3.1 the “vifs addserver” is no longer used as it adds the hosts during the setup process.

      As for multiple APCs outside of being configured in parallel or redundant mode. I’m not completely sure about this one. I have always had a single vMA for a group of hosts that were powered by a single APC. Any other host groups on their own APC had their own vMA. You don’t need a vMA on every host if they are plugged into the same APC though unless you are worried about a single host failure causing your vMA to go down before a power outage hits. While you could indeed use a single vMA to shutdown multiple hosts on multiple APCs you would loose the ability to shutdown the extra APCs at the end of the process. Also if it happened to be a single APC failure, say an outlet dies or the breaker trips, this would cause all of your servers to get shutdown instead of just the group of hosts in the bad area.

  32. Thank you for this useful guide. As well as sharing the scripts. Shame Vmware does not make this little more simple…
    Anyway thought I’d add that I was able to get this to work with APC business edition via serial communication on Server 2008 guest. (Serial UPS cable attached directly to ESXi 5.5U2 host)

    Just followed this guide and also did the following

    VMA – Enable root account, Enable root SSH access.
    Add serial device on VM. Verify Guest/APC business edition can see UPS.
    Install Plink on VM. I put mine in c:\Program Files\APC\PowerChute Business Edition\agent\cmdfiles\
    Setup APC business edition to run command file.

    Contents of command file

    cd c:\Program Files\APC\PowerChute Business Edition\agent\cmdfiles\
    plink.exe -ssh -pw ******* root@IPaddress “/opt/APC/PowerChute/group1/bin/ /opt/APC/PowerChute/group1/bin/host”

    Command executes and shutdown guests according the VM startup/shutdown.

    Thanks again.

  33. How could I thank you more?! Hahahah :) You’re the man!!!!!

Leave a comment