This file describes how to install the IceGrid registry, IceGrid node,
and Glacier2 router as Windows services using the sample configuration
files included in the Ice distribution.


Selecting a User Account
------------------------

Before installing a service, you should give careful consideration to
the user account that will run the service. None of the Ice services
require privileges beyond a normal user account, therefore we
recommend that you use the built-in account that Windows provides
specifically for this purpose. On Windows XP and Windows Server 2003,
the fully-qualified name for this account is
"NT Authority\LocalService"; in an English locale, its name is
displayed as "Local Service". On Windows Vista, the account name is
simply "Local Service".

Once you have chosen a user account for the service, you may need to
perform additional steps to prepare the service's resources. For
example, the IceGrid services require subdirectories in which to store
their persistent data. These subdirectories must be configured with
the proper permissions so that they can be accessed by the designated
user account. A common mistake is assuming that the service will be
able to access a file or directory that you created using your current
account. With careful planning and preparation, you can avoid failures
caused by insufficient permissions that are often difficult to
diagnose.


Configuration Files
-------------------

The sample configuration files can be found in <ice-home>/config,
where <ice-home> represents your Ice installation directory. We
recommend that you review the comments and settings in these files to
familiarize yourself with a typical configuration of each service.

You can modify a configuration file to suit your needs, copy one to
use as a starting point for your own configuration, or create an
entirely new file. You can even omit a configuration file altogether
and use command-line options to define your properties, but we do not
recommend that approach because it requires that you reinstall the
service each time you need to change its command-line options.

A service must have read access to its configuration file (the Ice run
time never writes to a configuration file). If you used a binary Ice
installer, the sample configuration files should already have the
necessary permissions. If you want to verify or modify the access
rights of a configuration file, refer to the section Filesystem
Resources below for more information.

The instructions that follow assume that you are using the sample
configuration files.


Installing a Glacier2 Router Service
------------------------------------

The Glacier2 router has no persistent state aside from an optional
configuration file that is read at startup. The sample configuration
file can be found in <ice-home>\config\glacier2router.cfg.

Follow these steps to install a Glacier2 router as a service:

1. In a command window, execute the following line:

   > glacier2router --install Glacier2Router --Ice.Config=<ice-home>\config\glacier2router.cfg

   Installing the service on Windows Vista with UAC enabled requires
   administrator privileges. In this case, run the command shell as
   administrator, right-click the command shell icon and select "Run
   as administrator", then execute the installation command.

2. Open the Services control panel from your Administrative Tools
   menu, right click on the entry for "Glacier2Router" and select
   Properties. Open the Log On tab and enter the user account you
   have chosen.

   For the Local Service account, use the name "Local Service" on
   Windows Vista and "NT Authority\LocalService" on Windows XP and
   Windows Server 2003. The password fields must be manually set to
   empty.

3. Verify that the user account you selected for the service has
   access to the configuration file and its enclosing directory, as
   described in the Filesystem Resources section below.

4. Start the service and verify that it started successfully. If
   the service failed to start, check the Event Log for error
   messages.


Installing an IceGrid Registry or Node Service
----------------------------------------------

The IceGrid registry and node services each require full access to
subdirectories. The sample configuration files contain settings that
reflect our recommendations for these directories, but you can use the
directories of your choosing. The sample configuration files are named
icegridregistry.cfg and icegridnode.cfg.

Several installation options are available for IceGrid registry and
node services. You are not required to install both a registry and
node service on every host. However, if you plan to install both
services on a host, you can optionally configure them to run as a
single service. Please consult the Ice manual if you need more
information on the purpose of each service and the relationship
between them.

Follow these steps to install the IceGrid registry and node as
services:

1. In a command window, execute the following lines:

   > icegridnode --install IceGridNode --Ice.Config=<ice-home>\config\icegridnode.cfg

   > icegridregistry --install IceGridRegistry --Ice.Config=<ice-home>\config\icegridregistry.cfg

   Installing a service on Windows Vista with UAC enabled requires
   administrator privileges. In this case, run the command shell as
   administrator, right-click the command shell icon and select "Run
   as administrator", then execute the installation commands.

2. Open the Services control panel from your Administrative Tools
   menu and edit the properties of the services "IceGridNode" and
   "IceGridRegistry". For each service, right click on the entry and
   select Properties. Open the Log On tab and enter the user account
   you have chosen.

   For the Local Service account, use the name "Local Service" on
   Windows Vista and "NT Authority\LocalService" on Windows XP and
   Windows Server 2003. The password fields must be manually set to
   empty.

3. Verify that the user account you selected for the services has
   access to the configuration files and their enclosing directories,
   as described in the Filesystem Resources section above.

4. Prepare the subdirectories for each service using the steps
   outlined in the Filesystem Resources section below. The services
   require that their subdirectories already exist.

   For the registry service, create the directory identified by the
   configuration property IceGrid.Registry.Data.

   For the node service, create the directories identified by the
   properties IceGrid.Node.Data and IceGrid.Node.Output.

5. You may need to give additional privileges to the node's user
   account. See the section IceGrid Node Performance Monitoring below
   for more information.

6. Start the services and verify that they started successfully. If
   a service failed to start, check the Event Log for error messages.


Filesystem Resources
--------------------
 
Windows services generally require access to filesystem resources, and
Ice services are no exception. For example, an Ice service typically
has a configuration file that it must have permission to read; the
service may also need the ability to create files and databases to
maintain its persistent state.

As an example, let us assume that you have decided to use the "Local
Service" user account and that you need to create the directories
required by the IceGrid services. The sample configuration files use
the following parent directory on Windows XP and Windows Server 2003
(note that this path name is locale dependent):

  C:\Documents and Settings\Local Service\Local Settings\Application Data\ZeroC\icegrid

Note that we would use a different directory on Windows Vista:

  C:\Users\Local Service\AppData\Local\ZeroC\icegrid

In the discussion below, we use the Windows XP/Windows Server 2003
directory for our examples.

Although "Local Service" is a built-in account, it may not have a
user directory yet. In a command window, we execute the following
steps to create the directory:

  > cd \Documents and Settings
  > mkdir "Local Service"

At this point we could create the rest of the directory hierarchy.
However, a newly-created directory inherits the privileges of its
enclosing directory, and we have not yet modified the privileges of
the "Local Service" directory to grant access to the "Local Service"
account. At present, the privileges of the "Local Service" directory
are inherited from "Documents and Settings" and require modification.
In general, it is better to establish the necessary access rights on
the parent directory prior to creating any subdirectories, so we will
modify the "Local Service" directory first.

On all Windows systems, we can use the command-line utility "cacls",
which is described at the link below:

  http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/en-us/cacls.mspx?mfr=true

The following command does what we need:

  > cacls "Local Service" /G "Local Service":F Administrators:F

By omitting the /E option to cacls, we have replaced all of the
prior access rights on the directory with the rights given in this
command. As a result, the "Local Service" account and anyone in the
Administrators group are granted full access to the directory,
while all others are forbidden. (We grant full access to the
Administrators group because presumably someone other than the
"Local Service" account will need to manage the subdirectory,
create the configuration file, an so on). You can verify the
directory's current privilege settings by running cacls without
options:

  > cacls "Local Service"

Now we can create the remaining subdirectories, and they will
automatically inherit the access rights we established for the "Local
Service" directory. If you want to further restrict access to files or
subdirectories, you can modify them as necessary using the cacls
utility. Note however that certain actions may cause a file to revert
back to the access rights of its enclosing directory. For example,
modifying a file using a text editor is often the equivalent of
erasing the file and recreating it, which discards any access rights
you may have previously set for the file.

On some versions of Windows XP, and on Windows Server 2003 and Windows
Vista, you can manage privilege settings interactively using Windows
Explorer. For example, right click on the "Local Service" directory,
select Properties, and select the Security tab. Next select Advanced
and Edit, uncheck "Include inheritable permissions from this object's
parent", and select Copy. Remove all permission entries, then add
entries for Local Service and the Administrators group and grant "Full
Control" to each.


IceGrid Node Performance Monitoring
-----------------------------------

The IceGrid node's user account must have permission to read the
following registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib

On Windows Server 2003 or Windows Vista, no additional action is
required if the IceGrid node runs under the "Local Service" account
(this account already has the right permissions). Otherwise, if you
use Windows XP, or if you run the IceGrid node under a different
account, you must edit the permissions of the Perflib registry key.

The simplest approach is to modify the permissions of the registry key
directly using regedit:

1. Start regedit. Navigate to the above key.

2. Right click and select "Permissions...".

3. If the user account is not already listed, click "Add...". Enter
   "LOCAL SERVICE" if you are using the "Local Service" account,
   otherwise enter the desired user account. Press OK.

3. Check the "Read" box in the Allow column to grant permission. Press
   OK to apply the changes.

Another solution is to add the user to the "Performance Monitor Users"
group. See the following Microsoft article for details:

http://technet2.microsoft.com/WindowsVista/en/library/ab3b2cfc-b177-43ec-8a4d-0bfac62d88961033.mspx?mfr=true


Windows Firewall
----------------

Your choice of user account also determines whether you receive any
notification when the Windows Firewall blocks the ports that are used
by your service. For example, if you use 'Local Service' as 
recommended above, you will not see any Windows Security Alert dialog.

See the following Microsoft article for details:

http://technet2.microsoft.com/WindowsServer/en/library/b3440a22-ae9c-45a3-8a61-da3f8a2c791f1033.mspx?mfr=true

If you are not prompted to unblock your service, you will need to
manually add an exception in Windows Firewall. For example, follow
the steps below to unblock the ports of a Glacier2 router service:

1. Open the Windows Firewall Settings panel and navigate to the
   Exceptions panel.

2. Select "Add program...".

3. Select "Browse", navigate to the Glacier2 router executable, and
   click "OK".

Note that adding an exception for a program unblocks all ports on
which the program listens. Review the endpoint configurations of your
services carefully to ensure that no unnecessary ports are opened.

For services listening on one or a few fixed ports, you could also
create port exceptions in your Windows Firewall. Please refer to the 
Windows Firewall documentation for details.
