Ice provides the command-line tool iceserviceinstall
to assist you in installing and uninstalling the following Windows services:
Ice includes other programs that can also be run as Windows services, such as the IceBox and IcePatch2 servers. Typically it is not necessary to install these programs as Windows services because they can be launched by an IceGrid node service. However, if you wish to run an IceBox or IcePatch2 server as a Windows service without the use of IceGrid, you must manually install the service.
Here we describe how to use the Ice service installer and discuss its actions and prerequisites.
On this page:
iceserviceinstall
Command Line Optionsiceserviceinstall
supports the following options and arguments:
{zcode} iceserviceinstall [options] service config-file [property ...] Options: -h, --help Show this message. -n, --nopause Do not call pause after displaying a message. -v, --version Display the Ice version. -u, --uninstall Uninstall the Windows service. {zcode} |
The service
and config-file
arguments are required during installation and uninstallation.
The service
argument selects the type of service you are installing; use one of the following values:
icegridregistry
icegridnode
glacier2router
Note that the Ice service installer currently does not support the installation of an IceGrid node with a collocated registry, therefore you must install the registry and node separately.
The config-file
argument specifies the name of an Ice configuration file.
When installing a service, properties can be defined on the command line using the --name
=value
syntax, or they can be defined in the configuration file. The supported properties are described below.
None of the Ice services require privileges beyond a normal user account. In the case of the IceGrid node service in particular, we do not recommend running it in a user account with elevated privileges because the service is responsible for launching server executables, and those servers would inherit the node's access rights.
iceserviceinstall
Configuration FileThe Ice service installer requires that you specify the path name of the Ice configuration file for the service being installed or uninstalled. The tool needs this path name for several reasons:
IceGrid.Registry.Data
has sufficient access rights.You may still modify a service's configuration file after installation, but you should uninstall and reinstall the service if you change any of the properties that influence the service installer's actions. The table below describes the service properties that affect the installer:
Property | Service | Description |
---|---|---|
IceGrid Registry | Value appears in the service name; also included in the default display name if one is not defined. | |
IceGrid Node | Directory is created if necessary; access rights are verified. | |
IceGrid Node | Value appears in the service name; also included in the default display name if one is not defined. | |
IceGrid Registry | Directory is created if necessary; access rights are verified. | |
IceGrid Node, Glacier2 Router | The IceGrid instance name is derived from the identity in this proxy. | |
All | Specifies the name of an event log source for the service. |
The steps performed by the tool during an installation are described in detail below.
Ice includes sample configuration files for the IceGrid and Glacier2 services in the config
subdirectory of your Ice installation. 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 or copy one to use as a starting point for your own configuration.
iceserviceinstall
PropertiesThe Ice service installer uses a set of optional properties that customize the installation process. These properties can be defined in the service's configuration file as discussed above, or they can be defined on the command line using the familiar --name
=value
syntax:
{zcode} iceserviceinstall --DependOnRegistry=1 ... {zcode} |
The installer's properties are listed below:
AutoStart=num
1
.DependOnRegistry=num
Ice.Default.Locator
be defined in config-file
. If not specified, the default value is zero.Description=value
DisplayName=name
iceserviceinstall
composes a default display name.EventLog=name
Application
.ImagePath=path
iceserviceinstall
assumes the service executable resides in the same directory as itself and fails if the executable is not found.ObjectName=name
NT Authority\LocalService
.Password=value
ObjectName
. The Ice service installer performs a number of steps to install a service. As discussed earlier, you must specify the path name of the service's configuration file because the service installer uses certain properties during the installation process. The actions taken by the service installer are described below:
IceGrid.InstanceName
or Glacier2.InstanceName
. If an instance name is not specified, the default value is IceGrid
or Glacier2
, respectively. If the service being installed depends on the IceGrid registry, the IceGrid instance name is derived from the value of the Ice.Default.Locator
property.IceGrid.Node.Name
. This property must be defined when installing a node.icegridregistry.IceGrid
. Note that the service name is not the same as the display name.ObjectName
.IceGrid.Registry.Data
and ensure that the user account specified by ObjectName
has read/write access to the directory.IceGrid.Node.Data
and ensure that the user account specified by ObjectName
has read/write access to the directory.ObjectName
has read access to the following registry key:HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib
ObjectName
has read/write access to the configuration file.EventLog
.EventLog
for the source name specified by Ice.EventLog.Source
. If this property is not defined, the service name is used as the source name.--service
name
) and the absolute path name of the configuration file (--Ice.Config=
config-file
).The Ice service installer currently does not perform these tasks:
ObjectName
has the right to "Log on as a service" When uninstalling an existing service, the Ice service installer first ensures that the service is stopped, then proceeds to remove the service. The service's event log source is removed and, if the service is not using the Application
log, the event log registry key is also removed.