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 development and testing. The registry server is implemented by the
icegridregistry executable.
$ icegridregistry ‑h
Usage: icegridregistry [options]
Options:
‑h, ‑‑help Show this message.
‑v, ‑‑version Display the Ice version.
‑‑nowarn Don't print any security warnings.
‑‑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.
‑‑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.
See Appendix C for more information on these properties.
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 permissions 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 43.5.1 provides more information on implementing permissions verifier objects.
You must provide an empty directory in which the registry can initialize its databases. 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 39.21. 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.
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 executable you must use.
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.
‑‑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.
‑‑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.
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 privileges, such as the root account on Unix or the Administrator account on Windows. See
Section 39.22.4 for more information on this subject.
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.
The node requires an empty directory that it can use to store server files. The pathname 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.
IceGrid.Node.Endpoints=tcpIceGrid.Node.Name=Node1
IceGrid.Node.Data=/opt/ripper/node
Ice.Default.Locator=IceGrid/Locator:tcp -p 4061
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 39.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 configuration properties as described in
Section 39.20.1.
The IceGrid registry hosts several well-known objects. Table 39.24 shows the default identities of these objects and their corresponding Slice interfaces.
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:
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 IceGrid registry and node both store information in the data directories specified by the
IceGrid.Registry.Data and
IceGrid.Node.Data properties, respectively. This section describes what the registry and node are storing and discusses backup and recovery techniques.
•
Applications deployed using the addApplication operation on the
IceGrid::Admin interface (which includes the IceGrid GUI and command-line administrative clients). Applications specify servers, well-known objects, object adapters, replica groups, and allocatable objects. Applications can be removed with the
removeApplication operation.
•
Well-known objects registered using the addObject and
addObjectWithType operations on the
IceGrid::Admin interface. Well-known objects added by these operations can be removed using the
removeObject operation.
Client and administrative sessions established with the IceGrid registry are not persistent. If the registry is restarted, these sessions must be recreated. For client sessions in particular, this implies that objects allocated using the allocation mechanism will no longer be allocated once the IceGrid registry restarts.
If the registry database environment is corrupted or lost, you must recover the deployed applications, the well-known objects, and the adapter endpoints. You do not need to worry about the internal proxies stored by the registry, as the nodes and registry replicas will eventually contact the registry again.
Depending on your deployed applications and your use of the registry, you should consider backing up the registry’s database environment, especially if you cannot easily recover the persistent information.
For example, if you rely on dynamically-registered adapters, or on well-known objects registered programmatically via the
IceGrid::Admin interface, you should back up the registry database environment because recovering this information may be difficult. On the other hand, if you only deploy a few applications from XML files, you can easily recover the applications by redeploying their XML files, and therefore backing up the database environment may be unnecessary.
Be aware that restarting the registry with an empty database may cause the server information stored by the nodes to be deleted. This can be an issue if the deployed servers have database environments stored in the node data directory. The next section provides more information on this subject.
The IceGrid node stores information for servers deployed by IceGrid applications. This information is stored in the
servers subdirectory of the node’s data directory. There is one subdirectory per server; the name of the subdirectory is the server’s ID. Each server directory contains configuration files, database environments (see
Section 39.16.4) and the distribution data of the server (see
Section 39.13). The node’s data directory also contains a
distrib directory to store per-application distribution data. This directory contains a subdirectory for each application that specifies a distribution and has a server deployed on the node.
If a server directory is deleted, the node recreates it at startup. The node will also recreate the server configuration files and the database environment directories. However, the node cannot restore the prior contents of a server’s database environment. It is your responsibility to back up these database environments and restore them when necessary. If the server or application distribution data is deleted from the node’s data directory, you can easily recover the deleted information by patching these distributions again using the IceGrid administrative tools.
If you store your server database environments outside the node’s data directory (such as in a directory that is regularly backed up), or if you do not have any database environments inside the node’s data directory, you do not need to back up the contents of the node’s data directory.
