Windows 98 and Windows NT version of Apcupsd

General

The Windows version of apcupsd has been tested on both Win95/98 and WinNT systems. It should also work on Win2000 systems in the same way it does on WinNT systems. This version of apcupsd has been built to run under the CYGWIN environment, which provides many of the features of Unix on Windows systems. It also permitted a rapid port with very few changes, which means that the Windows version is for the most part running code that has long proved stable on Unix systems. Even though the Win32 version of apcupsd is a port that relies on many Unix features, it is just the same a true Windows program. When running, it is perfectly integrated with Windows and displays its icon in the system icon tray, and provides a system tray menu to obtain additional information on how apcupsd is running (status and events dialogue boxes). If so desired, it can also be stopped by using the system tray menu, though this should normally never be necessary.

Once installed apcupsd normally runs as a system service. This means that it is immediately started by the operating system when the system is booted, and runs in the background even if there is no user logged into the system.

Installation

Normally, you will install the Windows version of Apcupsd from the binaries, which come in two forms. One is an InstallShield standard Windows install. You simply execute the apcupsd setup.exe program and follow the instructions. The advantage of this method is that it can be easily uninstalled and a menu item is put into the Program item of the Start menu.

The second binary install is more Unix like since you do many parts of the installation by hand. To install the binaries by this method, you need WinZip.

If you wish to install the package elsewhere, please note that you will need to proceed with a manual installation, which is not particularly easy as you must rebuild the source and change the configuration file as well.

This installation assumes that you do not have CYGWIN installed on your computer. If you do, and you use mount points, you may need to do a special manual installation.

Once you have unzipped the binaries, open a window pointing to the binary installation folder (normally c:\apcupsd). This folder should contain folders with the name bin, etc, examples, and manual. If and when you no longer need them, the examples and manual sub-folders of the c:\apcupsd directory may be removed.

Continuing the installation process:

That should complete the installation process. When the system tray icon turns from a battery into a plug , right click on it and a menu will appear. Select the Events item, and the Events dialogue box should appear. There should be no error messages. By right clicking again on the system tray plug and selecting the Status item, you can verify that all the values for your UPS are correct.

When the UPS switches to the battery, the battery icon will reappear in the system tray. While the UPS is online, if the battery is not at least 99% charged, the plug icon will become a plug with a lightning bolt in the middle to indicate that the battery is charging.

Installation Directory

No matter which method you choose for installing the Win32 apcupsd, it must reside in the c:\apcupsd\ directory, and there must be a c:\tmp directory on your machine. Both methods accomplish this automatically, and we recommend that you do not attempt to place apcupsd in another directory. If you do so, you are on your own, and you will need to do a rebuild of the source.

Testing

It is hard to over emphasize the need to do a full testing of your installation of apcupsd as there are a number of reasons why it may not behave properly in a real power failure situation.

Please read the Testing chapter of this document for general instructions on testing the Win32 version. However, on Win32 systems, there is no Unix system log file, so if something goes wrong, look in the file c:\apcupsd\etc\apcupsd\apcupsd.events where apcupsd normally logs its events, and you will generally find more detailed information on why the program is not working. The most common cause of problems is either improper configuration of the cable type, or an incorrect address for the serial port.

Upgrading

On Win98 and Win95 systems, to upgrade to a new release, simply stop apcupsd by using the tray icon and selecting the Close Apcupsd menu item, or by double clicking on the Stop icon located in the c:\apcupsd\bin directory, then apply the upgrade and restart apcupsd.

On WinNT systems (and possibly Win2000 systems), you must stop apcupsd by using the Services item in the Control Panel. In addition, at least on my system, there seems to be a WinNT bug that causes the system to prevent apcupsd.exe from being overwritten even though the file is no longer being used. This is manifested by an error message when attempting load a new version and overwrite the old apcupsd.exe. To circumvent this problem (if it happens to you), after shutting down the running version of apcupsd, through the Services dialogue in the Control Panel, first click on the Stop button:

then click on the Startup ... button, and in the Startup dialogue select the Disabled button to disable apcupsd:

After closing the dialogues, reboot the system, typical of Microsoft :-(. When the system comes backup, apcupsd will not be automatically launched as a service, and you can install the new version. To reinstate apcupsd as an automatic service, using the Control Panel: reset apcupsd to Automatic startup in the Startup dialogue, then restart apcupsd in the Services dialogue as shown above in the installation instructions.

Postinstallation

After installing apcupsd and before running it, you should check the contents of two files to ensure that it is configured properly for your system. The first is c:\apcupsd\etc\apcupsd\apcupsd.conf. You will probably need to change your UPSCABLE directive, your UPSTYPE and possibly your DEVICE directives. Please refer to the configuration section of this manual for more details.

The second file that you should examine is c:\apcupsd\etc\apcupsd\apccontrol. This file is called by apcupsd when events (power loss, etc) are generated. It permits the user to program handling the event. In particular, it permits the user to be notified of the events. For the Win32 version, each event is programmed to display a Windows popup dialogue box. If your machine is mostly unattended, you may want to comment out some of these popup dialogue boxes by putting a pound sign (#) in column one of the appropriate line.

Problem Areas

In addition to possible problems of reinstallation or upgrade on WinNT systems, as noted above, we have discovered the following problem: On all Windows systems, the domain resolution does not seem to work. This problem should be apparent only when running a master or a slave configuration. In this case, when you specify the name of the master or the slave machine(s) in your apcupsd.conf file, apcupsd will be unable to resolve the name to a valid IP address. To circumvent this problem, please enter all machine addresses as an IP address rather than a domain name. For example, instead of using the directive:

MASTER my.master.com use something like:

MASTER 192.168.1.54 where you replace the IP address with your actuall IP address.

Utility Functions

The directory c:\apcupsd\bin contains six utility routines (actually .pif files) that you may find useful. They are:
Start
Stop
Install
Uninstall
ups-events
ups-status
Any of these utilities may be used on any system, with the exception of the Start utility, which cannot be used on WinNT and Win2000 systems. On those systems, the apcupsd service must always be started through the Services sub-dialogue of the Control Panel.

The Install and Uninstall utilities install and uninstall apcupsd from the system registery only. All other pieces (files) of apcupsd remain intact. It is not absolutely necessary for apcupsd to be installed in the registry as it can run as a regular program. However, if it is not installed in the registry, it cannot be run as a service.

The functions of Stop, ups-events, and ups-status can be more easily invoked by right clicking on the acpupsd icon in the system tray and selecting the desired function from the popup menu.

Disclaimer

This Windows version of apcupsd is the first release. It has been rather extensively tested, so it is known to work. However, it has not been installed at many sites, so there may be some minor difficulties during the installation process. In addition, since it is a new system port, there may be features that have not been tested (for example, not tested: doing a full power down of the UPS, programming the EEPROM, or with a "dumb" UPS). It has, however, been tested on Win95, Win98, and WinNT in standalone mode as well as slave mode (to a Linux server). If at all possible, we recommend not to use it as a network master on Win95 and Win98 due to the instability of those operating systems. If you do use it in any configuration not mentioned here, please send us an email with your experiences.

Some items to note:

Email Notification of Events

On Win95/98 systems, it is possible to receive notification of apcupsd events that are passed to apccontrol. This is possible using a simple email program that unfortunately is not functioning 100% correctly. In addition, I (Kern) was not able to make this program work on WinNT while apcupsd is running as a service under the system account (it works fine with any user account).

If you wish to try this program on Win95/98 systems, look at the files named changeme, commfailure, commok, onbattery, and mainsback in the directory c:\apcupsd\examples. To use them, you must modify the SYSADMIN variable to have a valid email address, then copy the files into the directory c:\apcupsd\etc\apcupsd.

Command Line Options Specific to the Windows Version

These options are not normally seen or used by the user, and are documented here only for information purposes. At the current time, to change the default options, you must either manually run apcupsd or you must manually edit the system registry and modify the appropriate entries.

In order to avoid option clashes between the options necessary for apcupsd to run on Windows and the standard apcupsd options, all Windows specific options are signaled with a forward slash character (/), while as usual, the standard apcupsd options are signaled with a minus (-), or a minus minus (--). All the standard apcupsd options can be used on the Windows version. In addition, the following Windows only options are implemented:

/servicehelper
Run the service helper application
/service
Start apcupsdas a service
/run
Run the apcupsd application
/install
Install apcupsd as a service in the system registry
/remove
Uninstall apcupsd from the system registry
/about
Show the apcupsd about dialogue box
/status
Show the apcupsd status dialogue box
/events
Show the apcupsd events dialogue box
/kill
Stop any running apcupsd
/help
Show the apcupsd help dialogue box
It is important to note that under normal circumstances the user should never need to use these options as they are normally handled by the system automatically once apcupsd is installed. However, you may note these options in some of the .pif files that have been created for your use.

Because I have not yet figured out how to execute apcupsd after the system shutdown and before the system halt, there is as of this moment no way for apcupsd to cause the UPS to shut off the power. This means that if the UPS does not automatically shutdown, and the power returns, your system will not be automatically rebooted. This could be resolved by the use of the --kill-on-powerfail option, but the use of this option could cause the power to be cut off while your machine is still running. See the section on Shutdown Sequence in the testing chapter of this document for a more complete discussion of this subject. If you are still interested in trying to get this to work, please look at the code that is commented out in c:\apcupsd\etc\apcupsd\apccontrol under the doshutdown case.

Building the Win32 Version from the Source

If you have the source code, follow the standard procedures for building apcupsd on Unix in the Installation Section of this manual. Please don't forget to look at the Win32 specific instructions.