PowerChute Network Shutdown:

Configuration for Citrix XenServer

Overview
PowerChute Network Shutdown (PCNS) is not supported when installed directly on to Citrix®
Xen® hypervisor.

As a result, in order to provide safe shutdown for any Citrix Xen hosts, PCNS must be installed
on a Windows or Linux machine that has the XenServer xe Command Line Interface (CLI)
installed. In addition, the Xen host and the PCNS machine, Windows or Linux, should be
receiving power from the same UPS.

PCNS monitors the UPS for critical events and, using the XenServer xe CLI, can run a shutdown
command file to remotely shut down any virtual machines (VM) that are switched on, and then
shut down the Xen host machine.

Notes: The instructions in this document are technical in nature and the reader is expected to
understand the administration of the targeted operating systems.

We have tested the instructions on these systems ONLY:

o Windows 2008 Server R2 with XenCenter 5.6 SP2 Windows
o RedHat Linux 5.5 Server with xe‐cli‐5.6.100‐46766p.i686.rpm
o Citrix XenServer 5.6 SP2

1
Installing xe CLI

On Windows, the xe CLI executable is installed with XenCenter management console:

http://www.citrix.com/lang/English/lp/lp_2307783.asp

On Linux the stand‐alone xe executable is available from the RPM named xe‐cli‐5.6‐
BuildNumber.i686.rpm on the Linux Pack CD: Linux Guest Support
http://www.citrix.com/lang/English/lp/lp_1688621.asp

To install standalone Linux xe:

1. Copy the RPM to your Linux machine.

2. Run the command: rpm –ivh xe‐cli‐5.6‐BuildNumber.i686.rpm
where 5.6 is an example version number, replace if necessary.

Configuring PCNS for XenServer on Windows

1. Install PCNS on a physical Windows machine that is connected to the same UPS that is
providing power to the XenServer machine.
2. Configure PCNS to communicate with the UPS using the Network Management Card,
see the Installation guide for detailed instructions.
3. Install the XenCenter management console on the same machine.
4. In order to safely shut down guest VMs that are running on XenServer, you must install
XenServer tools on each VM using the XenCenter management tool.
To do this, launch XenCenter and connect to your XenServer. Then right‐click on the VM
in XenCenter and select “Install XenServer Tools”.
5. Copy pcns_xen_shutdown.cmd to C:\Program Files\APC\PowerChute\group1 folder.
Note: In PowerChute v4.4 and higher, pcns_xen_shutdown.cmd must be copied to
C:\Program Files\APC\PowerChute\user_files.
6. Copy xenshutdown.vbs to C:\Program Files\Citrix\XenCenter and open it in a text editor
(e.g. Notepad).
7. Change the values for the following variables to match your environment:
xenHost (XenServer Hostname)
xenHostIP (XenServer IP Address)
xenUser (user name for XenServer)
xenPwd (XenServer password)
xePath (the path to the xe.exe, for example:
C:\Program Files\Citrix\XenCenter\ OR C:\Program Files (x86)\Citrix\XenCenter\).
8. Save the file.
9. It is recommended that you deny read permissions on the file xenshutdown.vbs for all
users except for Administrators and LocalSystem since the XenServer administrator

2
 credentials are stored in this file. This can be done on Windows using the Advanced
Security Settings (File Properties‐>Security‐>Advanced). On the Permissions tab, select
the Users group, click Edit, and change Read Permissions to Deny.
10. Log on to the PCNS Web user interface and select Configure Shutdown from the menu
options. Enter the full path to pcns_xen_shutdown.cmd in the text field “Run this
command file (full name):”. Then enter the required time in seconds for all VMs to shut
down and for the XenServer host to shut down.
11. Log on to the Network Management Card (NMC) Web user interface. Change the Low
Battery duration to a value greater than the shutdown time configured in the previous
step, plus an additional 2 minutes.
Please see the NMC documentation for more details on how to do this. See also
Appendix: Running xe CLI commands on Windows without Internet connectivity.

3
Configuring PCNS for XenServer on Linux

1. Install PCNS on a physical Linux machine that is connected to the same UPS that is providing
power to the XenServer machine. See Supported Operating Systems.

Note: Comply with the requirements of your OS for correct execution in the target
environment. For example, on Red Hat® Enterprise Linux® (RHEL) install the Stunnel
package also. The XenServer CLI application (xe) requires that Stunnel is available on the
same system. This enables secure connections to the XenServer management daemon.

For SUSE® 11, see RPMs for SUSE.

2. Configure PCNS to communicate with the UPS using the Network Management Card,
see the Installation guide for detailed instructions.
3. Install xe‐cli‐5.6‐BuildNumber.i686.rpm on the Linux machine,
where 5.6 is an example version number, replace if necessary.
4. In order to safely shut down guest VMs that are running on XenServer, you must install
XenServer tools on each VM using the XenCenter management tool.
To do this, launch XenCenter and connect to your XenServer. Then right‐click on the VM
in XenCenter and select “Install XenServer Tools”. Please see the Citrix Web site for
more information on installing and managing XenServer.
5. Copy xenshutdown.sh to the /opt/APC/PowerChute/group1 folder and open it using a
text editor.
6. Change the values for the following variables to match your environment:
XENHOST (XenServer hostname)
XENUSER (admin user for XenServer)
XENPASSWORD, (XenServer admin password)
7. Save the file.
8. It is recommended that you deny read permissions on the file xenshutdown.sh for all
users except the Root User account. To do this run the command chmod 700
xenshutdown.sh using su or sudo or while logged in as the root user.
9. Log on to the PCNS Web user interface and select Configure Shutdown from the menu
options. Enter the full path to xenshutdown.sh in the text field “Run this command file
(full name):” and enter the required time in seconds for all VMs to shut down and for
the XenServer Host to shut down.
10. Log on to the Network Management Card Web Interface and change the Low Battery
duration to a value greater than the shutdown time configured in the previous step, plus
an additional 2 minutes. Please see the NMC documentation for more details on how to
do this.

4
Background Information

The Linux shell script, xenshutdown.sh, can be configured to run directly as a shutdown
command file on the PCNS Configure Shutdown page.

For Windows machines, a VBScript file is required to provide additional logic that cannot be
performed using a PCNS command file. So, the pcns_xen_shutdown.cmd file executes the
VBScript file from PCNS.

The example VBScript file contains the required commands and logic to connect to the
XenServer host, shut down the VMs gracefully and then shut down the XenServer machine itself.

Warning: If a Virtual Machine running on the XenServer is in the suspended state, a graceful
shutdown cannot be performed. The scripts will force the VM to shut down in order to allow
the XenServer host to be placed in maintenance mode and then shut down.

When a critical event occurs on the UPS, PCNS will run the shutdown command file script prior
to initiating an OS shutdown on the PCNS agent machine. The shutdown scripts use the xe CLI
to securely connect to the XenServer host using TCP Port 443 and they safely shut down any
guest machines that are running (see warning above).

PCNS then puts the XenServer host in maintenance mode and shuts it down. PCNS waits 70
seconds (by default) after the shutdown command file has completed and then issues a
command to shut down the PCNS agent machine. The UPS can be configured to turn off using
the settings on the PCNS Configure Shutdown page in order to preserve the battery life.

The Citrix XenServer machine can be configured to automatically start when the UPS turns back
on using the BIOS settings. These settings vary according to the server hardware. The guest
VMs can also be configured to start automatically with the XenServer host via the Startup
Options in the VM General Properties page, see the screenshot below.

5
Note: The scripts should be tested in a non‐production environment before use on production
servers. The scripts are a sample solution for customers wishing to integrate PCNS with Citrix
XenServer. They are provided “as is” and without warranty. See a list of tested Systems at the
bottom of page 1.

Appendix: Running xe CLI commands on Windows without Internet connectivity

On a Windows machine that is not connected to the Internet, the xe CLI commands may take a
long time to complete. This is a Microsoft issue — see the following link for further details —
http://support.microsoft.com/kb/936707.

There are two ways to avoid this issue. Follow the steps below, or create a configuration file.

1. Launch Internet Explorer and click on Tools‐>Internet Options.

2. Go to the Advanced Tab and scroll to the Security Section,

3. Clear the option “Check for publisher’s certificate revocation*” and re‐start Internet Explorer.

NOTE: This will disable signature verification on a system wide basis.

Alternatively you can create a file called xe.exe.config with the following content:

<?xml version="1.0" encoding="utf-8"?>

<configuration>
<runtime>
<generatePublisherEvidence enabled="false"/>

6
 </runtime>
</configuration>

Copy the file xe.exe.config file to C:\Program Files\Citrix\XenCenter or

C:\Program Files (x86)\Citrix\XenCenter, that is, the same folder as xe.exe.

This will prevent signature checking for the xe CLI executable only.