Citrix Winview Application Note American Power Conversion PowerChutePLUS for OS/2 and Uninterruptible Power Supply family (Back-UPS, Smart-UPS). This application note is for informational use only and Citrix makes no representations or warranties with respect to the contents or use of this document or of any third-party products discussed within. (January 3, 1995) Citrix Systems 210 University Drive Suite 700 Coral Springs, FL 33071 Phone (305) 755-0559 FAX (305) 341-6880 OVERVIEW This application note discusses installing American Power Conversion's PowerChute software (Version 2.2.2) on Citrix application server products. PowerChute for OS/2 is a software product that takes user-specified measures in the event of power problems. It warns when power is unstable (brownout) or nonexistent (blackout), and shuts down the application server if power is not restored within a specified time or if the UPS battery runs low. Refer to the APC PowerChute manual for information on making the required serial connections between the application server and the UPS. DISCLAIMER The scenarios described in this document have been tested by Citrix Systems. Variations to the scenarios described in this document may work, but have not specifically been tested by Citrix. In order to recreate the configurations, you should use the specified revision levels of all software products described in this document and stay within the bounds of the features and functions described in this document. This application note is a living document and will be modified as new information and versions of the software described herein become available. Make sure you have the latest version of this document before you begin. The latest version is always available in the Citrix Forum on Compuserve. SYSTEM REQUIREMENTS 1. Citrix application server, Version 2.21 or higher 2. American Power Conversion PowerChute for OS/2, Version 2.2.2 3. American Power Conversion UPS that supports PowerChute 4. American Power Conversion Cable (APC Part Number 940020) INSTALLATION AND CONFIGURATION Use the following steps to install and configure the APC PowerChute software on an application server: 1. Transfer the PowerChute files to the application server. 2. Create a PowerChute initialization file. 3. Create PowerChute command files. 4. Modify the CONFIG.SYS and STARTUP.CMD files. 5. Test the PowerChute software. These steps are described in detail in the following sections. STEP 1. Transfer the PowerChute Files Because the PowerChute installation program (INSTALL.EXE) is written for OS/2 Presentation Manager, you must manually copy the files from the installation diskette to a directory on the application server. The procedure below assumes that the application server boot drive is drive C. If your boot drive is another drive letter, replace each instance of C in this note with your boot drive letter. Login to the application server as an Administrator, start an OS\2 session, insert the PowerChute installation diskette into the diskette drive (drive A is assumed in the procedure below), and type the following commands: MD C:\PWRCHUTE COPY A:\*.* C:\PWRCHUTE /V COPY C:\PWRCHUTE\UPSSA.EXE C:\PWRCHUTE\UPS.EXE REGISTER C:\PWRCHUTE /ALIAS:PWRCHUTE /SYSTEM CONFIG ACCESS \API\DOSCALL.100 PWRCHUTE X /P CONFIG ACCESS \API\DOSCALL.206 PWRCHUTE X /P STEP 2. Create a PowerChute Initialization File Use the following commands to create a PowerChute initialization file: C: CD \PWRCHUTE E PWRCHUTE.INI At this point you are in the OS/2 editor program. Type in the following lines to create a PWCHUTE.INI file: ; This is the POWERCHUTE INI file. [ups] msgdelay = 5 recharge = 36 msgtime = 30 downtime = 600 lowbattruntime = 0 returnscript = c:\pwrchute\return.cmd failscript = c:\pwrchute\fail.cmd timerexpscript = c:\pwrchute\timerexp.cmd shutdownscript = c:\pwrchute\shutdwn.cmd lowbatteryscript = c:\pwrchute\lowbatt.cmd returnmsg = failmsg = shutdownmsg = lowbatterymsg = downtimemsg = logpath = c:\pwrchute\pwrchute.log logmax = 10000 cmdfile = signals = 111 voltlevels = 111 device = COM1 ; End POWERCHUTE.INI. Press F4 to save and exit the file. STEP 3. Create PowerChute Command Files PowerChute runs several different command files, depending on the event detected; e.g., power failure, UPS battery low, etc. Create these script files in the C:\PWRCHUTE directory. These scripts use the MSG utility to notify users of PowerChute events, and the SHUTDOWN utility to shutdown the application server. Here are some sample command files. Modify them to fit your requirements. A. FAIL.CMD (Power Failure) This command file runs when a power failure is detected: @ECHO off REM FAIL.CMD - PowerChute power failure script MSG * POWER FAILURE DETECTED - Please save files and log off. REM End of FAIL.CMD B. RETURN.CMD (Power Return) This command file runs when power is restored before PowerChute times out: @ECHO off REM RETURN.CMD - PowerChute power return script MSG * POWER RESTORED - Resume normal operation. REM End of FAIL.CMD C. TIMEREXP.CMD (Power Timeout) This command file runs when PowerChute's power failure timer expires before power is restored: @ECHO off REM TIMEREXP.CMD - PowerChute timer expiration script MSG * POWER FAILURE TIMEOUT - SYSTEM WILL BE SHUTDOWN REM End of TIMEREXP.CMD D. SHUTDWN.CMD (System Shutdown) This command file shuts down the system. NOTE: Do not use the /NOW or /REBOOT parameters, because they cause a reboot. @ECHO off REM SHUTDWN.CMD - PowerChute shutdown script SHUTDOWN /NOKILL /NOMSG /F REM End of SHUTDWN.CMD E. LOWBATT.CMD (Battery Low) This command file runs when the UPS battery is low: @ECHO off REM LOWBATT.CMD - PowerChute low battery script MSG ADMIN UPS battery is low. REM End of LOWBATT.CMD STEP 4. Modify the CONFIG.SYS and STARTUP.CMD Files Make the following changes to CONFIG.SYS: A. Modify the SET PATH= line to include the C:\PWRCHUTE directory. B. Add the following line to specify the path to the PWRCHUTE.INI file for the UPS.EXE program: SET PCPATH=C:\PWRCHUTE\PWRCHUTE.INI C. The PowerChute daemon, UPS.EXE, runs under the disconnected user STARTUP.CITRIX when started from STARTUP.CMD. Add the following line to C:\STARTUP.CMD to start the PowerChute daemon: START "APC PowerChute" /N /I C:\PWRCHUTE\UPS.EXE These changes will not take effect until you reboot the application server. STEP 5. Test the PowerChute Software A. Unplug the UPS from the commercial power source. The application server should continue to operate, and the FAIL.CMD command file should be executed within a few seconds. B. Plug the UPS back into the commercial power source. The command file RETURN.CMD will be executed, and the message contained within the command file displayed. C. To test the shutdown feature, you will have to remove commercial power for a length of time greater than the limit set in the PWRCHUTE.INI file. When this limit is reached, the file TIMEREXP.CMD is executed, followed by SHUTDWN.CMD. NOTES Make sure that the limit set in the PWRCHUTE.INI file allows sufficient time to shutdown the application server before the battery runs out of power. This limit depends on the capacity of the APC UPS and the power consumption of your attached system. Refer to the APC charts and manuals for information on UPS size recommendations. American Power Conversion supplies a cable (grey cable, Part Number 940020) for use with PowerChute. This cable supports the following UPS signals: Return Power, Low Battery, Line Fail & Shutdown. No other cable configuration is supported. PROBLEMS There are no known problems at this time.