On this page:
Using Glacier2 in a minimal configuration involves the following tasks:
- Write a configuration file for the router.
- Write a password file for the router. (Glacier2 also supports other ways to authenticate users.)
- Decide whether to use the router's internal session manager, or supply your own session manager.
- Start the router on a host with access to the public and private networks.
- Modify the client configuration to use the router.
- Modify the client to create a router session.
- Ensure that the router session remains active for as long as the client requires it.
For the sake of example, the router's public address is 188.8.131.52 and its private address is 10.0.0.1.
Configuring the Router
The following router configuration properties establish the necessary endpoint and define when a session expires due to inactivity:
The endpoint defined by
Glacier2.Client.Endpoints is used by the Ice run time in a client to interact directly with the router. It is also the endpoint where requests from routed proxies are sent. This endpoint is defined on the public network interface because it must be accessible to clients. Furthermore, the endpoint uses a fixed port because clients may be statically configured with a proxy for this endpoint. The port numbers 4063 (for TCP) and 4064 (for SSL) are reserved for Glacier2 by the Internet Assigned Numbers Authority (IANA).
This sample configuration uses TCP as the endpoint protocol, although in most cases, SSL is preferable.
A client must create a session in order to use a Glacier2 router. Our setting for the
Glacier2.SessionTimeout property causes the router to destroy sessions that have been idle for at least 60 seconds. It is not mandatory to define a timeout, but it is recommended, otherwise session state might accumulate in the router.
Note that this configuration enables the router to forward requests from clients to servers. Additional configuration is necessary to support callbacks from servers to clients.
If clients access a location service via the router, additional router configuration is typically necessary.
Writing a Password File
The router's simplest authentication mechanism uses an access control list in a text file consisting of user name-password pairs. The password is a 13-character string encoded using the
crypt algorithm, similar to a
passwd file on a typical Unix system.
Glacier2.CryptPasswords specifies the name of the password file:
The format of the password file is very simple. Each user name-password pair must reside on a separate line, with whitespace separating the user name from the password. For example, the following password file contains an entry for the user name
You can use the
openssl utility (included in the OpenSSL toolkit) to generate crypt passwords:
At the prompt, issue the
passwd command. You are asked for a password, and then asked to confirm the password, at which point the utility displays a
crypt-encoded version of your password that you can paste into the router's password file.
crypt-based authentication scheme is not intended for use in secure applications. We recommend installing a custom permissions verifier that uses a more secure form of authentication instead.
Starting the Router
The router supports the following command-line options:
--nowarn option prevents the router from displaying warning messages at startup when it is unable to contact a permissions verifier object or a session manager object specified by its configuration.
Additional command line options are supported, including those that allow the router to run as a Windows service or Unix daemon, and Ice includes a utility to help you install the router as a Windows service.
Assuming our configuration properties are stored in a file named
config, you can start the router with the following command:
Configuring a Glacier2 Client
The following properties configure a client to use a Glacier2 router:
Ice.Default.Router property defines the router proxy. Its endpoints must match those in
Ice.ACM.Client property governs the behavior of Active Connection Management (ACM), which conserves resources by periodically closing idle outgoing connections. This feature must be disabled in a client that uses a Glacier2 router, otherwise ACM might transparently close a client's connection to a router and thereby terminate the router session prematurely. ACM is enabled by default, and therefore must be disabled by setting this property to zero.
Glacier2 Object Identities
A Glacier2 router hosts two well-known objects. The default identities of these objects are
Glacier2/admin, corresponding to the
Glacier2::Admin interfaces, respectively. If an application requires the use of multiple different (that is, not replicated) routers, it is a good idea to assign unique identities to these objects by configuring the routers with different values of the
Glacier2.InstanceName property, as shown in the following example:
This property changes the category of the object identities, which become
PublicRouter/admin. The client's configuration must also be changed to reflect the new identity:
One exception to this rule is if you deploy multiple Glacier2 routers as replicas, for example, to gain redundancy or to distribute the message-forwarding load over a number of machines. In that case, all the routers must use the same instance name, and the router clients can use proxies with multiple endpoints, such as:
Creating a Glacier2 Session
Session management is provided by the
The interface defines two operations for creating sessions:
createSessionFromSecureConnection. The router requires each client to create a session using one of these operations; only after the session is created will the router forward requests on behalf of the client.
createSession operation expects a user name and password and, depending on the router's configuration, returns either a
Session proxy or nil. When using the default authentication scheme, the given user name and password must match an entry in the router's password file in order to successfully create a session.
createSessionFromSecureConnection operation does not require a user name and password because it authenticates the client using the credentials associated with the client's SSL connection to the router.
To create a session, the client typically obtains the router proxy from the communicator, downcasts the proxy to the
Glacier2::Router interface, and invokes one of the
create operations. The sample code below demonstrates how to do it in C++; the code will look very similar in the other language mappings.
If the router is configured with a session manager, the
createSessionFromSecureConnection operations may return a proxy for an object implementing the
Glacier2::Session interface (or an application-specific derived interface). The client receives a null proxy if no session manager is configured.
A non-nil session proxy returned by a
create operation must be configured with the router that created it because the session object is only accessible via the router. If the router is configured as the client's default router at the time
createSessionFromSecureConnection is invoked, as is the case in the example above, then the session proxy is already properly configured and nothing else is required. Otherwise, the client must explicitly configure the session proxy with a router using the
ice_router proxy method.
If the client wishes to destroy the session explicitly, it must invoke
destroySession on the router proxy. If a client does not destroy its session, the router destroys it automatically when it expires due to inactivity. A client can obtain the inactivity timeout value by calling
getSessionTimeout and keep the session alive by periodically calling
refreshSession if necessary.
getCategoryForClient operation is used to implement callbacks over bidirectional connections.
An example of a Glacier2 client is provided in the directory
Glacier2 Session Expiration
A Glacier2 router may be configured to destroy sessions after a period of inactivity. This feature allows the router, as well as a custom session manager, to reclaim resources acquired during the session, but it requires some coordination between the router and its clients.
Ideally you would select a session timeout that is long enough to accommodate the usage patterns of your clients. For example, a session timeout of thirty seconds is a reasonable choice for a client that invokes an operation on a back-end server once every five seconds. However, that timeout could disrupt a different client that has long periods of inactivity, such as when its invocations are prompted by human interaction.
If you cannot predict with certainty the usage patterns of your clients, we recommend modifying the clients so that they actively prevent their sessions from expiring. A client simply needs to make an invocation at regular intervals, where the period is less than the router's timeout by a comfortable margin. Typically a client creates a dedicated thread whose only purpose is keeping the session alive. It can accomplish this by invoking
refreshSession on the router proxy, or by invoking the
ice_ping operation on the proxy of any back-end object that is accessed via the router (including the
Session proxy, if one was returned by
createSession). Ice includes helper classes that you can use to simplify the task of create a session and keeping it alive.
Note that if a session times out, the next client invocation raises
ConnectionLostException. To re-establish the session, the client must explicitly re-create it. If the client uses callbacks, it must also re-create the callback adapter and re-register its callback servants.
Glacier2 Session Destruction
A router session is destroyed automatically when the session expires, and when a client explicitly destroys its session. The router also destroys a session if certain connection errors occur while attempting to route a request. These errors are represented by the run-time exceptions
ProtocolException. In other words, if any of these exceptions occur while Glacier2 attempts to establish a connection to the target back-end server, or forward a request to the target back-end server, the router automatically destroys the session.