Table of Contents Previous Next
Logo
IceGrid : 35.20 Server Reference
Copyright © 2003-2008 ZeroC, Inc.

35.20 Server Reference

35.20.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 development 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.
readonly           Start the master registry in readonly 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 35.20.5).
Additional command line options are supported, including those that allow the registry to run as a Windows service or Unix daemon. See Appendix H for more information.

Configuring Endpoints

The IceGrid registry creates up to five 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 35.15 for more information.
• IceGrid.Registry.AdminSessionManager.Endpoints
Optional endpoints for supporting integration with a Glacier2 router. See Section 35.15 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 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 39.5.1 provides more information on implementing permissions verifier objects.

Configuring a Data Directory

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 35.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.

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 4061
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 35.20.3.
The remaining configuration properties are discussed in Appendix C.

35.20.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 executable 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.
readonly           Start the collocated master registry in
                     readonly 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 35.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.
Additional command line options are supported, including those that allow the node to run as a Windows service or Unix daemon. See Appendix H for more information.

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 privileges, such as the root account on Unix or the Administrator account on Windows. See Section 35.24.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 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.
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 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 35.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 35.20.1.
The remaining configuration properties are discussed in Appendix C.

35.20.3 Object Identities

The IceGrid registry hosts several well-known objects. Table 35.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:
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 4061
Furthermore, any uses of these identities in application code must be updated as well.

35.20.4 Persistent Data

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.

Registry

The IceGrid registry data directory contains a Freeze database environment. The databases in this environment manage the following information:
• 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.
• Adapter endpoints registered dynamically by servers using the Ice::LocatorRegistry interface. The property IceGrid.Registry.DynamicRegistration must be set to a value larger than zero to allow the dynamic registration of object adapters. These adapters can be removed using the removeAdapter operation.
• Some internal proxies used by the registry to contact nodes and other registry replicas during startup. The proxies enable the registry to notify these entities about the registry’s availability.
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.

Node

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 35.16.4) and the distribution data of the server (see Section 35.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.

35.20.5 Slave Promotion

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.
Table of Contents Previous Next
Logo