This page describes how to troubleshoot Windows Services.
On this page:
One failure that commonly occurs when starting a Windows service is caused by missing DLLs, which usually results in an error window stating a particular DLL cannot be found. Fixing this problem can often be a trial-and-error process because the DLL mentioned in the error may depend on other DLLs that are also missing. It is important to understand that a Windows service is launched by the operating system and can be configured to execute as a different user, which means the service's environment (most importantly its PATH
) may not match yours and therefore extra steps are necessary to ensure that the service can locate its required DLLs.
The command-line utility |
The simplest approach is to copy all of the necessary DLLs to the directory containing the service executable. If this solution is undesirable, another option is to modify the system PATH
to include the directory or directories containing the required DLLs. (Note that modifying the system PATH
requires restarting the system.) Finally, you can copy the necessary DLLs to \WINDOWS\system32
, although we do not recommend this approach.
Copying DLLs to |
Assuming that DLL issues are resolved, a Windows service can fail to start for a number of other reasons, including
Failures encountered by the Ice run time prior to initialization of the communicator are reported to the Windows event log if no other logger implementation is defined, so that should be the first place you look. Typically you will find an entry in the System
event log resembling the following message:
{zcode} The IcePatch2 service terminated with service-specific error 1. {zcode} |
Error code 1
corresponds to EXIT_FAILURE
, the value used by the Service
class to indicate a failure during startup. Additional diagnostic messages may be available in the Application
event log. See Ice::Service
Logging Considerations for more information on configuring a logger for a Windows service.
As we mentioned earlier, insufficient access rights can also prevent a Windows service from starting successfully. By default, a Windows service is configured to run under a local system account, in which case the service may not be able to access resources owned by other users. It may be necessary for you to configure a service to run under a different account, which you can do using the Services control panel. You should also review the access rights of files and directories required by the service.
Your choice of user account 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 we recommended, you will not see any Windows Security Alert dialog (see this Microsoft article for details).
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:
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. Refer to the Windows Firewall documentation for details.
The IceGrid node uses Windows' Perflib
facility to obtain statistics about the CPU utilization of its host for load balancing purposes. On Vista-derived operating systems, the IceGrid node may log the following warning message:
{zcode} warning: Unable to lookup the performance counter name {zcode} |
This message is an indication that the node does not have sufficient privileges to access a key in the Windows registry:
{zcode} HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib {zcode} |
As part of its installation procedure, the iceserviceinstall
utility modifies the permissions of this registry key to grant read access to the node's designated user account. If you are trying to change the node's user account, we recommend using the iceserviceinstall
utility to uninstall and reinstall the node. If you wish to modify the permissions of this registry key manually, follow these steps:
regedit
and navigate to the Perflib
key.Perflib
and select Permissions
.Add
to add the user account. Enter LOCAL SERVICE
if you wish to run the node in the Local Service account, otherwise enter the name of the user account. Press OK
.Read
box in the Allow
column to grant read access to the registry key and press OK
to apply the changes.Another way to grant the node's user account with the necessary access rights is to add it to the Performance Monitor Users
group.