The Windows version of apcupsd has been tested on Win95, Win98, WinMe, WinNT, WinXP, and Win2000 systems. This version of apcupsd has been built to run natively on Windows (no Cygwin or other emulation layer needed). 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).
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.
Normally, you will install the Windows version of apcupsd from the binaries. Starting with version 3.11.15, the Windows binaries are distributed with a full GUI installer (driven by NSIS, the Nullsoft Scriptable Install System).
Installation is very simple and straight-forward: Simply double-click the installer executable and follow the instructions.
If you are installing Apcupsd for the first time, the installer will give you an opportunity to edit the apcupsd.conf configuration file to contain the values appropriate for your site. (Subsequent installations will maintain your existing apcupsd.conf, so you need not edit it again unless there are new features or syntax changes that must be accounted for.)
The default configuration calls for a USB connected UPS. This is the most common connection for modern UPSes, especially those used with Windows computers. All other apcupsd drivers are available (apcsmart, dumb, net, snmp, pcnet) and can be used simply by editing the configuration file UPSCABLE, UPSTYPE, and DEVICE settings as described elsewhere in this manual.
Note that on Windows, serial ports are specified using COM1, COM2, etc. notation instead of the UNIX-style /dev/tty* notation.
Note also if you are using WinNT or Win2000, the operating system may probe the serial port attempting to attach a serial mouse. This will cause apcupsd to be unable to communicate with the serial port. If this happens, or out of precaution, you can edit the c:\boot.ini file. Find the line that looks something like the following:
multi(0)disk(0)rdisk(0)partition(1)\WINNT="Windows NT Workstation Version 4.00"
and add the following to the end of the line: /NoSerialMice:COM1 (or COM2 depending on what you want to use). The new line should look similar to...
multi(0)disk(0)rdisk(0)partition(1)\WINNT="Windows NT Workstation Version 4.00" /NoSerialMice:COM1
...where the only thing you have changed is to append to the end of the line. This addition will prevent the operating system from interferring with apcupsd
The installer will give you an opportunity start the Apcupsd service immediately. If you choose to start it manually, you may do so by selecting the "Start Apcuspd" link from the Start ->Programs -> Apcupsd folder.
On Windows NT/2000/XP, you may alternatively go to the Control Panel, open the Services folder, select Apcupsd UPS Server, and then click on the Start button as shown below:
If the Services dialog reports a problem, it is normally because your DEVICE statement does not contain the correct serial port name.
You probably should also click on the Startup... button to ensure that the correct defaults are set. The dialogue box that appears should have Startup Type set to Automatic and Logon should be set to System Account with Allow Service to Interact with Desktop checked. If these values are not set correctly by default, please change them otherwise apcupsd will not work.
For WinXP and Win2K systems, the dialogs are a bit different from those shown here for WinNT, but he concept is the same. You get to the Services dialog by clicking on: Control Panel -> Administrative Tools -> Component Services. The apcupsd service should appear in the right hand window when you click on Services (Local) in the left hand menu window.
That should complete the installation process. When the system tray icon turns
from a question mark 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 appear 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.
apctray has the capability of monitoring multiple apcupsd instances using apcupsd's Network Information Server (NIS). It will create a new icon for each instance being monitored. By default, apctray monitors the local apcupsd (localhost on port 3551). To add additional monitors, use the command line "/add" command as follows:
apctray /host myserver /add
To specify a non-default port, include the /port switch:
apctray /host myserver /port 1234 /add
To remove a monitor from the tray, right-click the tray icon and choose "Remove this instance" or run the add command again with the "/del" switch instead of "/add". Note that deleting the last monitor also configures apctray to not start by default. Using "/add" to create a new monitor will enable automatic startup again. To close a monitor temporarily, right-click the tray icon and choose "Close this instance".
apctray also aupports the "/refresh" switch which allows you to specify the interval (in seconds) at which apctray will poll the apcupsd NIS for status. If you do not specify "/refresh", the default is 1 second. For example, this command will add a monitor configured to refresh every 15 seconds:
apctray /host myserver /refresh 15 /add
apctray can be installed standalone (without apcupsd) if you wish to use it only to monitor remote apcupsd instances. This can be convenient for keeping an eye on a room full of UPSes from your desktop. Download and run the normal apcupsd installer and simply uncheck all components except apctray. Then use the "/add" command described above to add as many monitors as you wish.
It would be hard to overemphasize 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 Testing Apcupsd 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. Additionally, check the application event log, if you're running a platform that supports it such as Windows 2000 or XP.
An upgrade may be accomplished by uninstalling the old version (using the Add/Remove Programs Control Panel or clicking the "Uninstall Apcupsd" link from Start -> Programs -> Apcupsd. Near the end of the uninstall you will be prompted about removing configuration and event files. You should answer "No" in order to preserve your existing apcupsd.conf file.
After the uninstall completes you may install the new version of Apcupsd as described above. If you preserved your existing apcupsd.conf file, the new apcupsd.conf will be installed as apcupsd.conf.new.
After installing apcupsd and before running it, you should check the contents of the config file 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.
On some Windows systems, the domain resolution does not seem to work if you have not configured a DNS server in the Network section of the Control Panel. This problem should be apparent only when running a slave configuration. In this case, when you specify the name of the master in your apcupsd.conf file, apcupsd will be unable to resolve the name to a valid IP address. To circumvent this problem, simply enter the address as an IP address rather than a hostname, or alternatively, ensure that you have a valid DNS server configured on your system.
On WinNT, WinXP, and Win2K systems, you can examine the System Applications log to which apcupsd writes Windows error messages during startup.
Regardless of which Windows system you are running, apcupsd logs most error messages to c:\apcupsd\etc\apcupsd\ apcupsd.events. This type error messages such as configuration file not found, etc are written to this file. Note that on some systems (WinXP, possibly others) Apcupsd is unable to write to this file when running as a service.
Some items to note:
Nevertheless, it is possible to use the --
kill-on-powerfail option on
the apcupsd command line, but the use of this option could cause the power to
be cut off while your machine is still running. See
Shutdown Sequence 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.
An alternative to the --
kill-on-powerfail option is to use the KILLDELAY
(see
KILLDELAY <time in
seconds>) configuration
directive.
This configuration directive is appropriate on Windows machines where apcupsd continues to run even when the machine is halted (as is the case on most NT machines).
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.
If your batteries become exhausted during a power failure and you want your machine to automatically reboot when the power comes back, it is useful to implement the killpower feature of the UPS where apcupsd sends the UPS the command to shut off the power. In doing so, the power will be cut to your PC and if your BIOS is properly setup, the machine will automatically reboot when the power comes back. This is important for servers.
This feature is implemented on Unix systems by first requesting a system shutdown. As a part of the shutdown, apcupsd is terminated by the system, but the shutdown process executes a script where apcupsd is recalled after the disks are synced and the machine is idle. Apcupsd then requests the UPS to shut off the power (killpower).
Unfortunately on Windows, there is no such shutdown script that we are aware of and no way for apcupsd to get control after the machine is idled. If this feature is important to you, it is possible to do it by telling apcupsd to immediately issue the killpower command after issuing the shutdown request. The danger in doing so is that if the machine is not sufficiently idled when the killpower takes place, the disks will need to be rescanned (and there is a possibility of lost data however small). Generally, UPSes have a shutdown grace period which gives sufficient time for the OS to shutdown before the power is cut.
To implement this feature, you need to add the -p option to the apcupsd command line that is executed by the system. Currently the procedure is manual. You do so by editing the registry and changing the line:
c:\apcupsd\apcupsd.exe /service
found under the key:
HKEY_LOCAL_MACHINE Software\Microsoft\Windows\CurrentVersion\RunServices
to
c:\apcupsd\apcupsd.exe /service -p
If you have a Smart UPS, you can configure the kill power grace period, and you might want to set it to 3 minutes. If you have a dumb UPS, there is no grace period and you should not use this procedure. If you have a Back-UPS CS or ES, these UPSes generally have a fixed grace period of 2 minutes, which is probably sufficient.
Our philosophy is to shutdown a computer but not to power it down itself (as opposed to having the UPS cut the power as described above). That is we prefer to idle a computer but leave it running. This has the advantage that in a power fail situation, if the killpower function described above does not work, the computer will continue to draw down the batteries and the UPS will hopefully shutoff before the power is restore thus permitting an automatic reboot.
Nevertheless some people prefer to do a full power down. To do so, you might want to get a copy of PsShutdown, which does have a power down option. You can find it and a lot more useful software at: http://www.sysinternals.com/ntw2k/freeware/pstools.shtml. to use their shutdown program rather than the apcupsd supplied version, you simply edit:
c:\apcupsd\etc\apcupsd\apccontrol
with any text editor and change our calls to shutdown to psshutdown.
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:
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.