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.
‑‑readonly Start the master registry in read‑only mode.
The --readonly option prevents any updates to the registry’s database; it also prevents slaves from synchronizing their databases with this master. This option is useful when you need to verify that the master registry’s database is correct after promoting a slave to become the new master (see
Section 39.20.5).
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.23. 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.
‑‑readonly Start the collocated master registry in
read‑only mode.
‑‑deploy DESCRIPTOR [TARGET1 [TARGET2 ...]]
Add or update descriptor in file DESCRIPTOR,
with optional targets.
If you are running the node with a collocated registry, the --readonly option prevents any updates to the registry’s database; it also prevents slaves from synchronizing their databases with this master. This option is useful when you need to verify that the master registry’s database is correct after promoting a slave to become the new master (see
Section 39.20.5).
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.
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.24.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.
You may need to promote a slave to be the new master if the current master becomes unavailable. For example, this situation can occur when the original master cannot be restarted immediately due to a hardware problem, or when your application requires a feature that is only accessible via the master, such as the resource allocation mechanism or the ability to modify the deployment data.
To promote a slave to become the new master, you must shut down the slave and change its
IceGrid.Registry.ReplicaName property to
Master (or remove the property altogether). On restart, the new master notifies the nodes and registries that were active before it was shut down. An inactive registry or node will eventually connect to the new master if its default locator proxy contains the endpoint of the new master registry or the endpoint of a slave that is connected to the new master. If you cannot afford any down-time of the registry and want to minimize the down-time of the master, you should run at least two slaves. That way, if the master becomes unavailable, there will always be one registry available while you promote one of the slaves.
A slave synchronizes its database upon connecting to the new master, therefore it is imperative that you promote a slave whose database is valid and up-to-date. To verify that the promoted master database is up-to-date, you can start the new master with the
--readonly command-line option. While this option is in force, the new master does not update its database, and slaves do not synchronize their databases. You can review the master database with the IceGrid administrative tools and, if the deployment looks correct, you can restart the master without the
--readonly option to permit updates and slave synchronization.
Note that there is nothing to prevent you from running two masters. If you start two masters and they contain different versions of the deployment information, some slaves and nodes might get updated with out-of-date deployment information (causing some of your servers to be deactivated). You can correct the problem by shutting down the faulty master, but it is important to keep this issue in mind when you restart a master since it might disrupt your applications.
