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 /config, where 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 \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=\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=\config\icegridnode.cfg > icegridregistry --install IceGridRegistry --Ice.Config=\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.