38.19 Server Reference

38.19.1 icegridregistry

The IceGrid registry is a centralized repository of information, including deployed applications and well-known objects. A registry can optionally be collocated with an IceGrid node, which conserves resources and can be convenient during devel­opment and testing. The registry server is implemented by the icegridregistry executable.

Usage

The registry supports the following command-line options:

$ icegridregistry ‑h
Usage: icegridregistry [options]
Options:
‑h, ‑‑help           Show this message.
‑v, ‑‑version        Display the Ice version.
‑‑nowarn             Don't print any security warnings.

The registry can optionally be run as a Unix daemon or Win32 service. On Unix, the following additional commands are supported:

‑‑daemon             Run as a daemon.
‑‑pidfile FILE       Write PID of deamon into FILE.
‑‑noclose            Do not close open file descriptors.
‑‑nochdir            Do not change the current working directory.

On Windows, the following additional commands are supported:

‑‑service NAME       Run as the Windows service NAME.

‑‑install NAME [‑‑display DISP] [‑‑executable EXEC] [args]
                     Install as Windows service NAME. If DISP is
                     provided, use it as the display name,
                     otherwise NAME is used. If EXEC is provided,
                     use it as the service executable, otherwise
                     this executable is used. Any additional
                     arguments are passed unchanged to the
                     service at startup.
‑‑uninstall NAME     Uninstall Windows service NAME.
‑‑start NAME [args]  Start Windows service NAME. Any additional
                     arguments are passed unchanged to the
                     service.
‑‑stop NAME          Stop Windows service NAME.

Please see Section 8.3.2 for more information on these options.

Configuring Endpoints

The IceGrid registry creates up to four sets of endpoints, configured with the following properties:

• IceGrid.Registry.Client.Endpoints

Client-side endpoints supporting the following interfaces:

• Ice::Locator

• IceGrid::Query

• IceGrid::Registry

• IceGrid::Session

• IceGrid::AdminSession

• IceGrid::Admin

There are security implications in allowing access to administrative sessions, as explained in the next section.

• IceGrid.Registry.Server.Endpoints

Server-side endpoints for object adapter registration.

• IceGrid.Registry.SessionManager.Endpoints

Optional endpoints for supporting integration with a Glacier2 router. See Section 38.14 for more information.

• IceGrid.Registry.Internal.Endpoints

Internal endpoints used by IceGrid nodes and registry replicas. This property must be defined even if no nodes or replicas are being used.

See Appendix C for more information on these properties.

Security Considerations

A client that successfully establishes an administrative session with the registry has the ability to compromise the security of the registry host. As a result, it is imperative that you configure the registry carefully if you intend to allow the use of administrative sessions.

Administrative sessions are disabled unless you explicitly configure the registry to use an authentication mechanism. To allow authentication with a user name and password, you can specify a password file using the property IceGrid.Registry.AdminCryptPasswords or use your own permis­sions verifier object by supplying its proxy in the property IceGrid.Registry.AdminPermissionsVerifier. Your verifier object must implement the Glacier2::PermissionsVerifier interface.

To authenticate administrative clients using their SSL connections, define IceGrid.Registry.AdminSSLPermissionsVerifier with the proxy of a verifier object that implements the Glacier2::SSLPermissionsVerifier interface.

Section 42.5.1 provides more information on implementing permissions veri­fier objects.

Configuring a Data Directory

You must provide an empty directory in which the registry can initialize its data­bases. The pathname of this directory is supplied by the configuration property IceGrid.Registry.Data.

The files in this directory must not be edited manually, but rather indirectly using one of the administrative tools described in Section 38.20. To clear a registry’s databases, first ensure the server is not currently running, then remove all of the files in its data directory and restart the server.

Minimal Configuration

The registry requires values for the three mandatory endpoint properties, as well as the data directory property, as shown in the following example:

IceGrid.Registry.Client.Endpoints=tcp -p 10000
IceGrid.Registry.Server.Endpoints=tcp
IceGrid.Registry.Internal.Endpoints=tcp
IceGrid.Registry.Data=/opt/ripper/registry

In addition, we also recommend defining IceGrid.InstanceName, which is discussed in Section 38.19.3.

Note that by omitting a definition for the administrative endpoints, we are denying the use of any administrative tool. Add a definition for the property IceGrid.Registry.Admin.Endpoints to allow administrative access.

The remaining configuration properties are discussed in Appendix C.

38.19.2 icegridnode

An IceGrid node is a process that activates, monitors, and deactivates registered server processes. You can run any number of nodes in a domain, but typically there is one node per host. A node must be running on each host on which servers are activated automatically, and nodes cannot run without an IceGrid registry.

The IceGrid node server is implemented by the icegridnode executable. If you wish to run a registry and node in one process, icegridnode is the execut­able you must use.

Usage

The node supports the following command-line options:

Usage: icegridnode [options]
Options:
‑h, ‑‑help           Show this message.
‑v, ‑‑version        Display the Ice version.
‑‑nowarn             Don't print any security warnings.

‑‑deploy DESCRIPTOR [TARGET1 [TARGET2 ...]]
                     Add or update descriptor in file DESCRIPTOR,
                     with optional targets.

The --deploy option allows an application to be deployed automatically as the node process starts, which can be especially useful during testing. The command expects the name of the XML deployment file, and optionally allows the names of the individual targets within the file to be specified.

The node can optionally be run as a Unix daemon or Win32 service. On Unix, the following additional commands are supported:

‑‑daemon             Run as a daemon.
‑‑pidfile FILE       Write PID of deamon into FILE.
‑‑noclose            Do not close open file descriptors.
‑‑nochdir            Do not change the current working directory.

On Windows, the following additional commands are supported:

‑‑service NAME       Run as the Windows service NAME.

‑‑install NAME [‑‑display DISP] [‑‑executable EXEC] [args]
                     Install as Windows service NAME. If DISP is
                     provided, use it as the display name,
                     otherwise NAME is used. If EXEC is provided,
                     use it as the service executable, otherwise
                     this executable is used. Any additional
                     arguments are passed unchanged to the
                     service at startup.
‑‑uninstall NAME     Uninstall Windows service NAME.
‑‑start NAME [args]  Start Windows service NAME. Any additional
                     arguments are passed unchanged to the
                     service.
‑‑stop NAME          Stop Windows service NAME.

See Section 8.3.2 for more information on these options.

Security Considerations

It is important that you give careful consideration to the permissions of the account under which the node runs. If the servers that the node will activate have no special access requirements, and all of the servers can use the same account, it is recommended that you do not run the node under an account with system privi­leges, such as the root account on Unix or the Administrator account on Windows. See Section 38.21.4 for more information on this subject.

Configuring Endpoints

The IceGrid node’s endpoints are defined by the IceGrid.Node.Endpoints property and must be accessible to the registry. It is not necessary to use a fixed port because each node contacts the registry at startup to provide its current endpoint information.

Configuring a Data Directory

The node requires an empty directory that it can use to store server files. The path­name of this directory is supplied by the configuration property IceGrid.Node.Data. To clear a node’s state, first ensure the server is not currently running, then remove all of the files in its data directory and restart the server.

When running a collocated node and registry server, we recommend using separate directories for the registry and node data directories.

Minimal Configuration

A minimal node configuration is shown in the following example:

IceGrid.Node.Endpoints=tcp
IceGrid.Node.Name=Node1
IceGrid.Node.Data=/opt/ripper/node

Ice.Default.Locator=IceGrid/Locator:tcp -p 10000

The value of the IceGrid.Node.Name property must match that of a deployed node known by the registry.

The Ice.Default.Locator property is used by the node to contact the registry. The value is a proxy that contains the registry’s client endpoints (see Section 38.4.3).

If you wish to run a collocated registry and node server, add the property IceGrid.Node.CollocateRegistry=1 and include the registry’s config­uration properties as described in Section 38.19.1.

The remaining configuration properties are discussed in Appendix C.

38.19.3 Object Identities

The IceGrid registry hosts several well-known objects. Table 38.25 shows the default identities of these objects and their corresponding Slice interfaces.

Table 38.25. IceGrid’s well-known objects.

Default Identity	Interface
IceGrid/Registry	IceGrid::Registry
IceGrid/Registry-replica	IceGrid::Registry
IceGrid/Locator	Ice::Locator
IceGrid/Admin	IceGrid::Admin
IceGrid/Query	IceGrid::Query
IceGrid/SessionManager	Glacier2::SessionManager
IceGrid/SSLSessionManager	Glacier2::SSLSessionManager
IceGrid/AdminSessionManager	Glacier2::SessionManager
IceGrid/AdminSessionManager-replica	Glacier2::SessionManager
IceGrid/AdminSSLSessionManager	Glacier2::SSLSessionManager
IceGrid/RegistryUserAccountMapper	IceGrid::UserAccountMapper
IceGrid/RegistryUserAccountMapper-replica	IceGrid::UserAccountMapper

It is a good idea to assign unique identities to these objects by configuring them with different values for the IceGrid.InstanceName property, as shown in the following example:

IceGrid.InstanceName=MP3Grid

This property changes the identities of the well-known objects to use MP3Grid instead of IceGrid as the identity category. For example, the identity of the locator becomes MP3Grid/Locator.

The client’s configuration must also be changed to reflect the new identity:

Ice.Default.Locator=MP3Grid/Locator:tcp -h registryhost -p 10000

Furthermore, any uses of these identities in application code must be updated as well.