<!doctype html public "-//W3C//DTD HTML 4.0//EN">
<html>
<head>
<title>Win32 Implementation</title>
<meta name="Author" content="Kern Sibbald">
<link rel=stylesheet href="apcupsd-styles.css" type="text/css">
</head>
<body>
<h2>The Windows Version of Apcupsd</h2>
<h3>General</h3>
The Windows version of <b>apcupsd</b> has been tested on
Win95, Win98, WinMe, WinNT, WinXP, and Win2000 systems.
This version of <b>apcupsd</b> 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 source code 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 <b>apcupsd</b> 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 <b>apcupsd</b> 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.
<p>Once installed <b>apcupsd</b> 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.
<h3>Installation</h3>
Normally, you will install the Windows version of Apcupsd from the
binaries. This install is somewhat Unix like since you
do many parts of the installation by hand.
To install the binaries, you need <b>WinZip</b>.
<ul>
<li>Simply double click
on the <b>winapcupsd-3.8.5.tar.gz</b> icon. The actual name of
the icon will vary from one release version to another.
<p><img src="wininstall3.gif" width="254" height="299" border="0" alt="">
<br> <br></li>
<li>When Zip says that it has one file and asks if it should unpack it
into a temporary file, respond with <b>Yes</b>.
<p>
<img src="wininstall4.gif" width="374" height="152" border="0" alt="">
<br> <br></li>
<li>Ensure that you extract all files and that the extraction will go
into <b>C:\</b>
<p><img src="wininstall5.gif" width="486" height="246" border="0" alt="">
<p>
<br></li>
</ul>
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.
<p>This installation assumes that you do <b>not</b>
have CYGWIN installed on your computer. If you do,
and you use mount points, you may need to do a special manual installation.
<p>Once you have unzipped the binaries, open a window pointing to
the binary installation folder (normally <b>c:\apcupsd</b>). 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.
<p>Continuing the installation process:
<ul>
<li>Open the directory <b>c:\apcupsd\etc\apcupsd</b> in the Windows Explorer by
Clicking on the <b>apcupsd</b> folder then on the <b>etc</b> folder,
then on the <b>apcupsd</b> folder. Finally
double click on the file <b>apcupsd.conf</b> and edit it to contain the
values appropriate for your site. In most cases, no changes will
be needed, but if you are not using COM1 for your serial port,
you will need to set the <b>DEVICE</b> configuration directive to
the correct serial port. Note, if you are using WinNT or Win2000,
the operating system may probe the port attempting to attach a serial
mouse. This will cause <b>apcupsd</b> to be unable to communicate
with the serial port. If this happens, or out of precaution, you
can edit the <b>c:\boot.ini</b> file. Find the line that looks
something like the following:<p>
multi(0)disk(0)rdisk(0)partition(1)\WINNT="Windows NT Workstation Version
4.00"
<p>
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: <p>
multi(0)disk(0)rdisk(0)partition(1)\WINNT="Windows NT Workstation Version
4.00" /NoSerialMice:COM1
<p>
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 <b>apcupsd</b><br> <br></li>
<li>Then return to c:\apcupsd and open on the <b>bin</b>
folder so that you see its contents.<br> <br></li>
<li>To do the final step of installation, double click on the <b>setup.bat</b>
program. This script will setup the appropriate mount points for the
directories that <b>apcupsd</b> uses, it will install <b>apcupsd</b> in the
system registry, and on Windows 98, it will start <b>apcupsd</b> running.
<br> <br>
<p>If everything went well, you will get something similar to the following output in a
DOS shell window:
<br> <br>
<img src="wininstall1.gif" width="652" height="359" border="0" alt="">
<br> <br>
<p>What is important to verify in the DOS window is that the root
directory <b>\</b> is mounted on device <b>c:\</b>.
<p>The DOS window will be followed immediately by a Windows dialogue box as follows:
<br> <br>
<img src="wininstall2.gif" width="324" height="139" border="0" alt="">
<br> <br></li>
<li>On Windows 98, to actually start the service, either reboot
the machine, which is not necessary, or open a DOS shell window,
and type the following commands: <pre>
cd c:\apcupsd\bin
apcupsd /service
</pre>
Alternatively, you can go to the c:\apcupsd\bin folder with the
Explorer and double click on the <b>Start</b> icon.
<br> <br></li>
<li>On Windows NT, to start the service, either reboot
the machine, which is not necessary, or go to the Control Panel,
open the Services folder and start
the Apcupsd daemon program by selecting the
Apcupsd UPS Server and then clicking on the Start button as shown
below:
<br> <br>
<img src="wininstall6.gif" width="672" height="339" border="0" alt="">
<p></p>If the Services dialog reports a problem, it is normally because
your DEVICE statement does not contain the correct serial port
name.
</li>
</ul>
That should complete the installation process. When the system tray icon
turns from a battery <img src="onbatt.gif" width="16" height="16" border="0" alt=""> into a
plug <img src="online.gif" width="16" height="16" border="0" alt="">, right click on it
and a menu will appear. Select the <b>Events</b> 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 <b>Status</b> item, you can verify that all the
values for your UPS are correct.
<p>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
<img src="charging.gif" width="16" height="16" border="0" alt=""> to indicate
that the battery is charging.
<h3>Installation Directory</h3>
The Win32 version of apcupsd must reside in the <b>c:\apcupsd\</b> directory, and there must
be a <b>c:\tmp</b> directory on your machine. The installation will
do this automatically, and we recommend that you do not attempt
to place <b>apcupsd</b> in another directory. If you do so, you
are on your own, and you will need to do a rebuild of the source.
<h3>Testing</h3>
It is hard to over emphasize the need to do a full testing of
your installation of <b>apcupsd</b> as there are a number of
reasons why it may not behave properly in a real power failure
situation.
<p>
Please read the <a href="testing.html">Testing chapter</a> 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 <b>c:\apcupsd\etc\apcupsd\apcupsd.events</b>
where <b>apcupsd</b> 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.
<h3>Upgrading</h3>
On Win98 and Win95 systems, to upgrade to a new release, simply stop
<b>apcupsd</b> by using the tray icon and selecting the <b>Close Apcupsd</b>
menu item, or by double clicking on the <b>Stop</b> icon located in
the <b>c:\apcupsd\bin</b> directory, then apply the upgrade and
restart <b>apcupsd</b>.
<p>On WinNT systems (and Win2000 systems), you may stop <b>apcupsd</b>
as indicated abover or alternatively you may stop
<b>apcupsd</b> by using the <b>Services</b> item in the <b>Control Panel</b>.
In addition, at least on my system, there seems to be a WinNT bug that
causes the system to prevent <b>apcupsd.exe</b> 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
<b>apcupsd.exe</b> (the extract part of WinZip as described above).
To circumvent this problem (if it happens to you),
after shutting down the
running version of <b>apcupsd</b>, through the <b>Services</b> dialogue
in the <b>Control Panel</b>, first click on the <b>Stop button</b>:
<p>
<img src="wininstall6.gif" width="672" height="339" border="0" alt="">
<p>then click on the <b>Startup ...</b> button, and in the Startup dialogue
select the <b>Disabled</b> button to disable <b>apcupsd</b>:
<p>
<img src="wininstall7.gif" width="382" height="405" border="0" alt="">
<p>
After closing the dialogues, reboot the system, typical of Microsoft :-(.
When the system comes back up, <b>apcupsd</b> will not
be automatically launched as a service, and you can install the new version.
To reinstate <b>apcupsd</b> as an automatic service, using the <b>Control Panel</b>:
reset <b>apcupsd</b> to <b>Automatic</b> startup
in the Startup dialogue, then restart <b>apcupsd</b> in the <b>Services</b>
dialogue as shown above in the installation instructions. Frequently
after an upgrade, you will click on the <b>Start</b> button and after a
few seconds, the system reports that it failed to start. The cause of
this problem is unknown, but the solution is simply to click again
on the <b>Start</b> button.
<h3>Post Installation</h3>
After installing <b>apcupsd</b> 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 <b>c:\apcupsd\etc\apcupsd\apcupsd.conf</b>.
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.
<p>
The second file that you should examine is
<b>c:\apcupsd\etc\apcupsd\apccontrol</b>. This file is called by
<b>apcupsd</b> 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.
<h3>Problem Areas</h3>
In addition to possible problems of reinstallation or upgrade on WinNT
systems, as noted above, we have discovered the following problem: 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 master or a
slave configuration. In this case, when you specify the name of the
master or the slave machine(s) in your <b>apcupsd.conf</b> file,
<b>apcupsd</b> will be unable to resolve the name to a valid IP address.
To circumvent this problem, simply enter all machine addresses as an IP
address rather than a domain name, or alternatively, ensure that you
have a valid DNS server configured on your system (often not the case on
Win32 systems). For example, instead of using the directive:
<p class="tty">MASTER my.master.com
use something like:
<p class="tty">MASTER 192.168.1.54
where you replace the IP address with your actual IP address.
<p>Also, on WinNT systems, the PIF files in <b>/apcupsd/bin</b> used for
starting and stopping <b>apcupsd</b> do not work. Use the services
control panel instead.
<p>On Win95 systems, there are reports that the PIF files do not
work. If you find that to be the case, the simplest solution is to
use the batch files that we have supplied in the c:/apcupsd/bin
directory. Also, on Win95 systems, we have an unconfirmed
report that indicates that <b>apcupsd</b> does not start automatically
as a service even though the Registry has been properly updated. If you
experience this problem, a work around is to put a shortcut to
<b>apcupsd</b> in the StartUp folder.
<p>As noted above, after an upgrade, you may need to start apcupsd
several times before it will actually run.
<h3>Utility Functions</h3>
The directory <b>c:\apcupsd\bin</b> contains six utility routines (actually
.pif files) that you may find useful. They are:
<pre>
Start
Stop
Install
Uninstall
ups-events
ups-status
</pre>
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 <b>apcupsd</b> service must always be started
through the <b>Services</b> sub-dialogue of the <b>Control Panel</b>.
<p>The <b>Install</b> and <b>Uninstall</b> utilities install and uninstall
<b>apcupsd</b> from the system registry only. All other pieces (files) of
<b>apcupsd</b> remain intact. It is not absolutely necessary for <b>apcupsd</b>
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.
<p>The functions of <b>Stop</b>, <b>ups-events</b>, and <b>ups-status</b>
can be more easily invoked by right clicking on the <b>apcupsd</b> icon
in the system tray and selecting the desired function from the popup menu.
<h3>Disclaimer</h3>
Some of the features such as EEPROM programming have not been
exhaustively tested on Win32 systems. If at all possible, we recommend
not to use it as a network master on Win95, Win98, and WinMe due to the
instability of those operating systems.
<p>
Some items to note:
<ul>
<li>This version of <b>apcupsd</b> will not attempt to shut off
the UPS power when the battery is exhausted. Thus if the power
returns before the UPS completely shuts down, your computer may
not reboot automatically. This is because we do not know how
to regain control after the disks have been synced in order
to shut off the UPS power.
<p>Nevertheless, it is possible to use the <b>--kill-on-powerfail</b>
option on the <b>apcupsd</b> command line, but the
use of this option could cause the power to be cut off while your
machine is still running. See the section on
<a href="shutdown.html">Shutdown Chapter</a>
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
<b>c:\apcupsd\etc\apcupsd\apccontrol</b> under the
<b>doshutdown</b> case.
<p>An alternative to the <b>--kill-on-powerfail</b> option is to use the
<b>KILLDELAY</b> configuration directive as explained in the <a
href="configure.html#KILLDELAY">Configuration Section</a> of this
document.</p> This configuration directive is appropriate on
Windows machines where <b>apcupsd</b> continues to run even
when the machine is halted (as is the case on most NT machines).
</li><br> <br>
<li>When <b>apcupsd</b> detects important events, it calls
<b>c:\apcupsd\etc\apcupsd\apccontrol</b>, which is a Unix shell
script. You may modify this script to suit your particular needs.
Currently, it puts a Windows dialogue on the screen with a brief
explanation of the event. If these dialogues annoy you, you can
remove or comment out the calls to <b>popup</b> from this file.</li><br> <br>
</ul>
<p>
<h3>Email Notification of Events</h3>
On Win95/98 systems, it is possible to receive notification
of <b>apcupsd</b> events that are passed to <b>apccontrol</b>.
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 <b>apcupsd</b> is
running as a service under the system account (it works fine
with any user account).
<p>If you wish to try this program on Win95/98 systems, look
at the files named <b>changeme, commfailure, commok,
onbattery, and mainsback</b> in the directory <b>c:\apcupsd\examples</b>.
To use them, you must modify the SYSADMIN variable to have a
valid email address, then copy the files into the directory
<b>c:\apcupsd\etc\apcupsd</b>.
<h3>Killpower under Windows</h3>
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 <b>killpower</b> 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.
<p>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. Bacula then requests the UPS to shut off the power (killpower).
<p>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.
<p>
To implement this feature, you need to add the <b>-p</b> 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:
<pre>
c:\apcupsd\apcupsd.exe /service
</pre>
found under the key:
<pre>
HKEY_LOCAL_MACHINE Software\Microsoft\Windows\CurrentVersion\RunServices
</pre>
to
<pre>
c:\apcupsd\apcupsd.exe /service -p
</pre>
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.
<h3>Power Down During Shutdown</h3>
Our phylosophy 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.
<p>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:
<a href="http://www.sysinternals.com/ntw2k/freeware/pstools.shtml">
http://www.sysinternals.com/ntw2k/freeware/pstools.shtml</a>.
to use their shutdown program rather than the apcupsd supplied
version, you simply edit:
<pre>
c:\apcupsd\etc\apcupsd\apccontrol
</pre>
with any text editor and change our calls to shutdown to
psshutdown.
<h3>Command Line Options Specific to the Windows Version</h3> 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 <b>apcupsd</b> or you must
manually edit the system registry and modify the appropriate entries.
<p>
In order to avoid option clashes between the options necessary for
<b>apcupsd</b> to run on Windows and the standard <b>apcupsd</b>
options, all Windows specific options are signaled with a forward slash
character (/), while as usual, the standard <b>apcupsd</b> options are
signaled with a minus (-), or a minus minus (--). All the standard
<b>apcupsd</b> options can be used on the Windows version. In addition,
the following Windows only options are implemented:
<dl>
<dt>/servicehelper <dd>Run the service helper application
<dt>/service <dd>Start <b>apcupsd</b>as a service
<dt>/run <dd>Run the <b>apcupsd</b> application
<dt>/install <dd>Install <b>apcupsd</b> as a service in the system registry
<dt>/remove <dd>Uninstall <b>apcupsd</b> from the system registry
<dt>/about <dd>Show the <b>apcupsd</b> about dialogue box
<dt>/status <dd>Show the <b>apcupsd</b> status dialogue box
<dt>/events <dd>Show the <b>apcupsd</b> events dialogue box
<dt>/kill <dd>Stop any running <b>apcupsd</b>
<dt>/help <dd>Show the <b>apcupsd</b> help dialogue box
</dl>
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 <b>apcupsd</b> is installed. However, you may
note these options in some of the .pif files that have been created for
your use.
<h3>Building the Win32 Version from the Source</h3>
<p>If you have the source code, follow the standard procedures for
building <b>apcupsd</b> on Unix in the <a
href="install.html">Installation Section</a> of this manual. Please
don't forget to look at the
<a href="install.html#Win32">Win32 specific instructions</a>.
<hr>
<a href="kernel_config.html" target="_self"><img src="back.gif" border=0 alt="Back"></a>
<a href="multiUPS.html" target="_self"><img src="next.gif" border=0 alt="Next"></a>
<a href="index.html"><img src="home.gif" border=0 alt="Home"></a>
</body>
</html>
