 
#include "bacula_template.inc" title="Win32 Implementation" num=19

<h1>The Windows Version of Bacula</h1>
<h2>General</h2>
At the current time only the File daemon or Client program
has been tested on Windows. As a consequence, when we speak of the Windows
version of Bacula below, we are referring to the File daemon
only.
<p>
The Windows version of the <b>Bacula</b> File daemon has been tested on 
Win98, WinMe, WinNT, and Win2000 systems.  We have coded to support     
Win95, but no longer have a system for testing.
The Windows version of <b>Bacula</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>Bacula</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>Bacula</b> is running (status and events dialog
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>Bacula</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><a name="installation">Installation</a></h3>
Normally, you will install the Windows version of Bacula from the
binaries.  This install is somewhat Unix like since you
do some parts of the installation by hand.
To install the binaries, you need <b>WinZip</b>. 
<ul>
 <li>Simply double click on the <b>winbacula-1.xx.0.tar.gz</b> icon.  The
     actual name of the icon will vary from one release version to
     another.  <p><img src="wininstall-1.gif" border="0" alt=""
     width="126" height="50"> </li><br>&nbsp;<br>
  <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="wininstall-2.gif" width="374" height="152" border="0" alt="">
      </li><br>&nbsp;<br>
  <li>You will then be presented with a WinZip dialog that should look
       something like the following:
       <p><img src="wininstall-3.gif" border="0" alt=""></li>
       <p>
  <li>Ensure that you extract all files and that the extraction will go
      into <b>c:\</b>
      <p><img src="wininstall-4.gif" width="486" height="246" border="0" alt="">
      <p>
      </li><br>
   <li>If you have installed CYGWIN on your system (very few of you have),
       you should install <b>Bacula</b> into the <b>c:\cygwin</b> directory
       rather than c:\ as indicated above for a non-CYGWIN installation.
       This is also true if you installed CYGWIN a long time ago, unless
       you were careful to remove the CYGWIN mount points.
       <p>Even though Bacula uses the cygwin1.dll file, it needs no
       other part of CYGWIN installed.</li>
       <br>
</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 and <b>never</b> had CYGWIN installed on your computer. If you do, 
you will need to take care to observe the minor differences to 
the standard installation that we will note in this text. If you
have CYGWIN installed on your system and you use the standard
installation scripts rather than the CYGWIN specific scripts mentioned
below, they will remove your mount points (automatically setup by the
CYGWIN installation) and CYGWIN will no longer work until it is
re-installed.

<p>Once you have unzipped the binaries, open a window pointing to
the binary installation folder (normally <b>c:\bacula</b>). This
folder should contain additional folders such as <b>bin</b>. 
(For CYGWIN installations, this is <b>c:\cygwin\bacula\bin</b>, ...).
<p>Continuing the installation process:
<ul>
  <li>Open the directory <b>c:\bacula\bin\bacula-fd.conf</b> in the Windows Explorer by
      clicking on the <b>bacula</b> folder, then on the <b>bin</b> folder. Finally
      double click on the file <b>bacula-fd.conf</b> and edit it to contain the 
      values appropriate for your site. In most cases, no changes will
      be needed, but you probably should change the name to be
      something unique on your system so that you can easily distinguish
      messages coming from different daemons.  To make the conf file
      more general, we have not supplied the drive letter (e.g. <b>c:</b>)
      for the <b>WorkingDirectory</b> and the <b>Pid Directory</b> paths.
      You might consider adding explicit path specifications especially
      if you have more than one hard disk or more than one partition.<br>&nbsp;<br></li>
  <li>To do the final step of installation, double click on the <b>Install.bat</b>
       program. (For CYGWIN installations use the <b>CygwinInstall.bat</b> program.)
      <br>&nbsp;<br>
      <img src="wininstall-5.gif" width="571" height="365" border="0" alt="">
      <br>&nbsp;<br>

      This script will setup the appropriate mount points for the
      directories that <b>Bacula</b> uses, it will install <b>Bacula</b> in the
      system registry.
      <br>&nbsp;<br>

      <p>If everything went well, you will get something similar to the following output in a
      DOS shell window:
      <br>&nbsp;<br>
      <img src="wininstall-6.gif" width="440" height="248" border="0" alt="">
      <br>&nbsp;<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>. (Ignore this
      on CYGWIN installations).
      <p>The DOS window will be followed immediately by a Windows dialog box as follows:
      <br>&nbsp;<br>
      <img src="wininstall-7.gif" width="324" height="139" border="0" alt="">
      <br>&nbsp;<br></li>

  <li>On Windows 98, Windows 95, or Windows Me, to actually start the
      service, either reboot the machine, which is not necessary, or
      double click on the <b>Start</b> icon in the <b>c:\bacula\bin</b>
      folder (<b>c:\cygwin\bacula\bin</b> on CYGWIN) <br>&nbsp;<br></li>
  <li>On Windows NT, Windows 2000, or Windows XP, 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 Bacula
      Service by selecting the Bacula File Server: <br>&nbsp;<br> <img
      src="wininstall-8.gif" border="0" alt=""> 
     <p></p>Please ensure
      that the service can interact with the desktop.  To do so, click
      on the <b>Sartup...</b> button, and you should have something
      similar to the following (note, on WinXP systems the dialogs
      are significantly different, but in general have the same
      information): <br>&nbsp;<br> <img
      src="wininstall-9.gif" width="382" height="405" border="0" alt="">
      </li>
</ul>
That should complete the installation process. When the Bacula File Server
is ready to serve files, an icon 
<img src="idle.gif" width="16" height="16" border="0" alt="">
representing a cassette (or tape) will appear in the system tray; right click on it
and a menu will appear. Select the <b>Events</b> item, and the Events dialog box
should appear. There should be no error messages. By right clicking again on the
system tray cassette icon and selecting the
<b>Status</b> item, you can verify
whether any jobs are running or not.
<p>When the Bacula File Server begins saving files, the color of
the holes in the cassette icon will change from white to green         
<img src="running.gif" width="16" height="16" border="0" alt="">, 
and if there is an error, the holes in the cassette icon will change to red
<img src="error.gif" width="16" height="16" border="0" alt="">.


<h3>Installation Directory</h3>
The Win32 version of Bacula must reside in the <b>c:\bacula\</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>Bacula</b> in another directory.  If you do
so, you are on your own, and you will need to do a rebuild of the
source.  Note, on systems with Cygwin installed, Bacula should reside in
<b>c:\cygwin\bacula</b>.

<h3><a name="upgrading">Upgrading</a></h3>
On Win98 systems, to upgrade to a new release, simply stop
<b>Bacula</b> by using the tray icon and selecting the <b>Close Bacula</b>
menu item, or by double clicking on the <b>Stop</b> icon located in
the <b>c:\bacula\bin</b> directory, then apply the upgrade and
restart <b>Bacula</b>.

<p>On WinNT, WinXP, and Win2K systems,  you may stop <b>Bacula</b>
as indicated above or alternatively you may stop
<b>Bacula</b> by using the <b>Services</b> item in the <b>Control Panel</b>.

Then to restart <b>Bacula</b> after the new files have been loaded,
go to the <b>Services</b>
dialog as shown above in the installation instructions and click on
<b>Start</b>.  On WinXP systems, the <b>Services</b> dialog is
a bit different and is found by following:
<b>Control Panel -> Administrative Tools -> Component Services</b>.
Then click on <b>Services (Local)</b> in the left hand menu window
and the services should appear in the right hand window, from which
point, you can select <b>Bacula</b> and start it.

<h3>Post Installation</h3>
After installing <b>Bacula</b> and before running it, you should check
the contents of <b>c:\bacula\bin\bacula-fd.conf</b> to ensure that
it corresponds to your configuration.

<h3><a name="problems">Dealing with Problems</a></h3>
The most likely source of problems is authentication when the Director
attempts to connect to the File daemon that you installed. This can occur
if the names and the passwords defined in the File daemon's configuration
file <b>c:\bacula\bin\bacula-fd.conf</b> on the Windows machine do not
match with the names and the passwords in the Director's configuration
file <b>bacula-dir.conf</b> located on your Unix/Linux server.
<p>More specifically, the password found in the <b>Client</b> resource
in the Director's configuration file must be the same as the password
in the <b>Director</b> resource of the File daemon's configuration 
file. In addition, the name of the <b>Director</b> resource in the
File daemon's configuration file must be the same as the name in
the <b>Director</b> resource of the Director's configuration file.
<p>It is a bit hard to explain in words, but if you understand that
a Director normally has multiple Clients and a Client (or File daemon)
may permit access by multiple Directors, you can see that the names and the
passwords on both sides must match for proper authentication.
<p>One user had serious problems with the configuration file
until he realized that the Unix end of line conventions were used
and Bacula wanted them in Windows format.  This has not been
confirmed though.
<p><p>
Running Unix like programs on Windows machines is a bit frustrating
because the Windows command line shell (DOS Window) is rather
primitive. As a consequence, it is not generally possible to see
the debug information and certain error messages that Bacula 
prints. With a bit of work, however, it is possible. 
When everything else fails and you want to <b>see</b> what
is going on, try the following:
<pre>
   Start a DOS shell Window.

   cd c:\bacula\bin
   bacula-fd -t &gt;out
   type out
</pre>
The <b>-t</b> option will cause <b>Bacula</b> to read the configuration
file, print any error messages and then exit. the <b>&gt;</b> redirects
the output to the file named <b>out</b>, which you can list with the
<b>type</b> command.
<p>
If something is going wrong later, or you want to run <b>Bacula</b>
with a debug option, you might try starting it as:
<pre>
   bacula-fd -d 100 &gt;out
</pre>
In this case, <b>Bacula</b> will run until you explicitly stop it, which will
give you a chance to connect to it from your Unix/Linux server.
<p>
In addition, you should look in the System Applications log on the
Control Panel to find any
Windows errors that Bacula got during the startup process.

<a name="Compatibility"></a>
<h3>Windows Compatibility Considerations</h3>
In <b>Bacula</b> versions 1.30 and earlier, we used the
Cygwin emulation of Unix open(), read(), write(), ...
calls to access files. This worked pretty well for Win95,
Win98, and WinMe systems, but not very well for the
other systems (NT/2K/XP) because those systems have special
security and ownership information that was not saved. In addition
on the NT/2K/XP systems, older versions of Bacula were not always
able to access all files due to system permissions restrictions.
<p>
As a consequence, in Bacula version 1.31 and later, we use Windows
backup API calls by default.  Typical of Windows, programming these
special BackupRead and BackupWrite calls is a real nightmare of
complications.  The end result gives some distinct advantages and some
disadvantages.

<p>First, the advantages are
that on WinNT/2K/XP systems, the security and ownership information
is now backed up. In addition, with the exception of files in
use by another program (a major disaster for backup programs
on Windows), Bacula can now access all system files.
This means that when you restore files, the security and ownership
information will be restored on WinNT/2K/XP along with the data. 

<p>The disadvantage of the Windows backup API calls is that it
produces non-portable backups. That is files that are backed
up on WinNT using the native API calls (BackupRead/BackupWrite)
cannot be restored on Win95/98/Me or Unix systems.  In principle,
a file backed up on WinNT can be restored on WinXP, but this
remains to be seen in practice (not yet tested).

<p>As a default, Bacula backs up Windows systems using the Windows
API calls.  If you want to backup data on a WinNT/2K/XP system and
restore it on a Unix/Win95/98/Me system, we have provided a special
<b>portable</b> option that backups the data in a portable fashion by
using portable API calls.  See the 
<a href="dirdconf.html#portable">portable option</a> on the Include
statement in a FileSet resource in the Director's configuration chapter
for the details on setting this option.  However, using the portable
option means you may have permissions problems accessing files, and none
of the security and ownership information will be backed up or restored.

<p>
You should always be able to restore any file 
backed up on Unix or Win95/98/Me to any other system. On some
systems, such as WinNT/2K/XP, you may have to reset the ownership
of such restored files.  Any file backed up on WinNT/2K/XP
should in principle be able to be restored to a similar
system (i.e. WinNT/2K/XP), however, I am unsure of the 
consequences if the owner information and accounts are not
identical on both systems.  Bacula will not
let you restore files backed up on WinNT/2K/XP to any other
system (i.e. Unix Win95/98/Me) if you have used the defaults.

<p>
Finally, if you specify the <b>portable=yes</b> option on the
files you back up. Bacula will be able to restore them on
any other system. However, any WinNT/2K/XP specific security
and ownership information will be lost.
<p>The following matrix will give you an idea of what
you can expect. Thanks to Marc Brueckner for doing the tests:
<p>
<table cellspacing="2" cellpadding="2" border="3">
<tr> <th>Backup OS</th> <th>Restore OS</th> <th>Results</th> </tr>
<tr> <td>WinMe </td> <td>WinMe </td> <td>Works </td> </tr>
<tr> <td>WinMe </td> <td>WinNT </td> <td>Works (SYSTEM permissions) </td> </tr>
<tr> <td>WinMe </td> <td>WinXP </td> <td>Works (SYSTEM permissions) </td> </tr>
<tr> <td>WinMe </td> <td>Linux </td> <td>Works (SYSTEM permissions) </td> </tr>
<tr> <td>&nbsp; </td> <td>&nbsp; </td> <td>&nbsp;</td> </tr>

<tr> <td>WinXP </td> <td>WinXP </td> <td>Works </td> </tr>
<tr> <td>WinXP </td> <td>WinNT </td> <td>Works (all files OK, but got &quot;The data is invalid&quot; message)</td></tr>
<tr> <td>WinXP </td> <td>WinMe </td> <td>Error: Win32 data stream not supported. <td> </td> </tr>
<tr> <td>WinXP </td> <td>WinMe </td> <td>Works if <b>Portable=yes</b> specified during backup.</td></tr>
<tr> <td>WinXP </td> <td>Linux </td> <td>Error: Win32 data stream not supported. <td> </td> </tr>
<tr> <td>WinXP </td> <td>Linux </td> <td>Works if <b>Portable=yes</b> specified during backup.</td></tr>
<tr> <td>&nbsp; </td> <td>&nbsp; </td> <td>&nbsp;</td> </tr>

<tr> <td>WinNT </td> <td>WinNT </td> <td>Works </td> </tr>
<tr> <td>WinNT </td> <td>WinXP </td> <td>Works </td></tr>
<tr> <td>WinNT </td> <td>WinMe </td> <td>Error: Win32 data stream not supported.</td> </tr>
<tr> <td>WinNT </td> <td>WinMe </td> <td>Works if <b>Portable=yes</b> specified during backup.</td></tr>
<tr> <td>WinNT </td> <td>Linux </td> <td>Error: Win32 data stream not supported.</td> </tr>
<tr> <td>WinNT </td> <td>Linux </td> <td>Works if <b>Portable=yes</b> specified during backup.</td></tr>
<tr> <td>&nbsp; </td> <td>&nbsp;</td> <td>&nbsp;</td> </tr>

<tr> <td>Linux </td> <td>Linux </td> <td>Works </td> </tr>
<tr> <td>Linux </td> <td>WinNT </td> <td>Works (SYSTEM permissions)</td></tr>
<tr> <td>Linux </td> <td>WinMe </td> <td>Works </td> </tr>
<tr> <td>Linux </td> <td>WinXP </td> <td>Works (SYSTEM permissions) </td> </tr>

</table>



<h3>Utility Functions</h3>
The directory <b>c:\Bacula\bin</b> contains six utility routines (actually
.pif files) that you may find useful.  They are:
<pre>
Start
Stop
Install
Uninstall
CygwinInstall
CygwinUnInstall
</pre>
Any of these utilities may be used on any system, with the exception of
the Start utility, which cannot be used on WinNT, Win2000 and WinXP
systems.
On those systems, the <b>Bacula</b> service must always be started through
the <b>Services</b> sub-dialog of the <b>Control Panel</b>.
<p>The <b>Install</b> and <b>Uninstall</b> utilities install and uninstall
<b>Bacula</b> from the system registry only. All other pieces (files) of
<b>Bacula</b> remain intact. It is not absolutely necessary for <b>Bacula</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.

<h3>The Console Program</h3>
The Bacula Console program has been included in the distribution
in the Bacula bin directory. You can execute it from any Windows
DOS box.  Using this program, you can start a job on the
main server (Director) from your Windows workstation.

<h3>The testfind Program</h3>
A program named <b>testfind</b> is also included in the Bacula bin
directory. This program is documented in the <a href="progs.html#testfind">
testfind section of the Utility Tools</a> chapter of this manual.
It permits you to list the files that will be backed up given
the list of Include statements from your Director's configuration
file. Note, the important functionality of this program (i.e. listing
the files to be backed up) can be obtained by using the
<a href="console.html#estimate">estimate command</a> in
the Console program.

<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>Bacula</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>Bacula</b> to run on Windows and the standard <b>Bacula</b> options,
all Windows specific options are signaled with a forward slash character (/),
while as usual, the standard <b>Bacula</b> options are signaled with a minus (-),
or a minus minus (--).  All the standard <b>Bacula</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>Bacula</b> as a service
        <dt>/run        <dd>Run the <b>Bacula</b> application
        <dt>/install    <dd>Install <b>Bacula</b> as a service in the system registry
        <dt>/remove     <dd>Uninstall <b>Bacula</b> from the system registry
        <dt>/about      <dd>Show the <b>Bacula</b> about dialogue box
        <dt>/status     <dd>Show the <b>Bacula</b> status dialogue box
        <dt>/events     <dd>Show the <b>Bacula</b> events dialogue box (not
                            yet implemented)</dd>
        <dt>/kill       <dd>Stop any running <b>Bacula</b>
        <dt>/help       <dd>Show the <b>Bacula</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>Bacula</b> is installed. However, you may note these options in
some of the .pif and .bat 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>Bacula</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>.

<page_prev name="What to do when Bacula crashes (Kaboom)" url="kaboom.html">
<page_next name="Using Bacula to Improve Computer Security" url="verify.html">
