Date: Fri, 29 Mar 2024 05:17:13 +0000 (UTC) Message-ID: <2141427329.24873.1711689433113@ae5f4610bf64> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_24872_417247034.1711689433112" ------=_Part_24872_417247034.1711689433112 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
On this page:
Using Glacier2 in a minimal configuration involves the following tasks:<= /p>
For the sake of example, the router's public address is 5.6.7.8 and its = private address is 10.0.0.1.
The following router configuration properties establish the necessary en= dpoint and define when a session expires due to inactivity:
Glacier2.Client.Endpoints=3Dtcp -h 5.6.7.8 -p 4063 Glacier2.SessionTimeout=3D60
The endpoint defined by Glacier2.Client.End=
points
is used by the Ice run time in a client to interact direc=
tly with the router. It is also the endpoint where requests from routed pro=
xies are sent. This endpoint is defined on the public network interface bec=
ause it must be accessible to clients. Furthermore, the endpoint uses a fix=
ed 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 f=
or Glacier2 by the Internet Assigned Numbers Authority (IANA).
This sample configuration uses TCP as the endpoint protocol, although in= most cases, SSL is p= referable.
A client must create a session in order to use a Glacier2 router. Our setting =
for the Glacier2.SessionTimeout
property ca=
uses the router to destroy sessions that have been idle for at least 60 sec=
onds. It is not mandatory to define a timeout, but it is recommended, other=
wise 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.
You must also decide which authentication scheme (or schemes) to use. A = file-based= mechanism is available, as are more sophisticated strategies.
If clients access a location service via the router, additional router configuratio= n is typically necessary.
The router's simplest authentication mechanism uses an access control li=
st in a text file consisting of user name-password pairs. The password is a=
13-character string encoded using the crypt
algorithm, simila=
r to a passwd
file on a typical Unix system.
The property Glacier2.CryptPasswords
spe=
cifies the name of the password file:
Glacier2.CryptPasswords=3Dpasswords
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 na=
me from the password. For example, the following password file contains an =
entry for the user name test
:
test xxMqsnnDcK8tw
You can use the openssl
utility (included in the OpenSSL to=
olkit) to generate crypt passwords:
$ openssl OpenSSL> passwd Password: Verifying - Password: xxMqsnnDcK8tw
At the prompt, issue the passwd
command. You are asked for =
a password, and then asked to confirm the password, at which point the util=
ity displays a crypt
-encoded version of your password that you=
can paste into the router's password file.
The crypt
-based authentication scheme is not intended for u=
se in secure applications. We recommend installing a custom permissions verifier that uses a more secure form of authenti=
cation instead.
The router supports the following command-line options:
$ glacier2router -h Usage: glacier2router [options] Options: -h, --help Show this message. -v, --version Display the Ice version. --nowarn Suppress warnings.
The --nowarn
option prevents the router from displaying war=
ning messages at startup when it is unable to contact a permissions verifie=
r object or a session manager object specified by its configuration.
Additional command line options are supported, including those that allo= w the router to run as a Windows service or Unix daemon, and Ice includes a utility= a> to help you install the router as a Windows service.
Assuming our configuration properties are stored in a file named c=
onfig
, you can start the router with the following command:
$ glacier2router --Ice.Config=3Dconfig
The following properties configure a client to use a Glacier2 router:
Ice.Default.Router=3DGlacier2/router:tcp -h 5.6.7.= 8 -p 4063 Ice.ACM.Client=3D0 Ice.RetryIntervals=3D-1
The Ice.Default.Router
property defines the router proxy. Its endpoints must match those in=
Glacier2.Client.Endpoints
.
The Ice.ACM.Client
property gove=
rns the behavior of Active Connection Management (ACM), which conserves resources by perio=
dically closing idle outgoing connections. This feature must be disabled in=
a client that uses a Glacier2 router, otherwise ACM might transparently cl=
ose a client's connection to a router and thereby terminate the router sess=
ion prematurely. ACM is enabled by default, and therefore must be disabled =
by setting this property to zero.
Finally, setting Ice.RetryIntervals
to -1 disables automat=
ic retries, which are not useful for proxies configured to use a Glacie=
r2 router.
A Glacier2 router hosts two well-known objects. The default identities o=
f these objects are Glacier2/router
and Glacier2/admin=
code>, corresponding to the
Glacier2::Router
and Glacier=
2::Admin
interfaces, respectively. If an application requires the us=
e of multiple different (that is, not replicated) routers, it is a good ide=
a to assign unique identities to these objects by configuring the routers w=
ith different values of the Glacier2.InstanceName
=
property, as shown in the following example:
Glacier2.InstanceName=3DPublicRouter
This property changes the category of the object identities, which becom=
e PublicRouter/router
and PublicRouter/admin
. The=
client's configuration must also be changed to reflect the new identity:=
p>
Ice.Default.Router=3DPublicRouter/router:tcp -h 5.= 6.7.8 -p 4063
One exception to this rule is if you deploy multiple Glacier2 routers as= replicas, for example, to gain redundancy or to distribute the message-for= warding 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 mul= tiple endpoints, such as:
Ice.Default.Router=3DPublicRouter/router:tcp -h 5.= 6.7.8 -p 4063:tcp -h 6.10.7.8 -p 4063
Session management is provided by the Glacier2::Router
inte=
rface:
module Glacier2 { exception PermissionDeniedException { string reason; }; interface Router extends Ice::Router { Session* createSession(string userId, string password) throws PermissionDeniedException, CannotCreateSessionException; Session* createSessionFromSecureConnection() throws PermissionDeniedException, CannotCreateSessionException; idempotent string getCategoryForClient(); void refreshSession() throws SessionNotExistException; void destroySession() throws SessionNotExistException; idempotent long getSessionTimeout(); }; };
The interface defines two operations for creating sessions: create=
Session
and createSessionFromSecureConnection
. The rout=
er requires each client to create a session using one of these operations; =
only after the session is created will the router forward requests on behal=
f of the client.
The createSession
operation expects a user name and passwor=
d 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.
The createSessionFromSecureConnection
operation does not re=
quire a user name and password because it authenticates the client using th=
e 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 sampl=
e code below demonstrates how to do it in C++; the code will look very simi=
lar in the other language mappings.
Ice::RouterPrx defaultRouter =3D communicator->g= etDefaultRouter(); Glacier2::RouterPrx router =3D Glacier2::RouterPrx::checkedCast(defaultRout= er); string username =3D ...; string password =3D ...; Glacier2::SessionPrx session; try { session =3D router->createSession(username, password); } catch(const Glacier2::PermissionDeniedException& ex) { cout << "permission denied:\n" << ex.reason << endl; } catch(const Glacier2::CannotCreateSessionException& ex) { cout << "cannot create session:\n" << ex.reason << en= dl; }
If the router is configured with a session manager, the createSession
and <=
code>createSessionFromSecureConnection operations may return a proxy=
for an object implementing the Glacier2::Session
interface (o=
r an application-specific derived interface). The client receives a null pr=
oxy 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 i=
s only accessible via the router. If the router is configured as the client=
's default router at the time createSession
or createSes=
sionFromSecureConnection
is invoked, as is the case in the example a=
bove, then the session proxy is already properly configured and nothing els=
e is required. Otherwise, the client must explicitly configure the session =
proxy with a router using the
If the client wishes to destroy the session explicitly, it must invoke <=
code>destroySession on the router proxy. If a client does not destro=
y its session, the router destroys it automatically when it expires due to =
inactivity. A client can obtain the inactivity timeout value by calling refreshSession
if necessary.
The getCategoryForClient
operation is used to implement callbacks over bidir=
ectional connections.
An example of a Glacier2 client is provided in the directory demo/=
Glacier2/callback
.
A Glacier2 router may be configured to destroy sessions after a period o= f inactivity. This feature allows the router, as well as a custom session manager, to rec= laim resources acquired during the session, but it requires some coordinati= on between the router and its clients.
Ideally you would select a session timeout that is lon= g 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 ina= ctivity, 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 ses=
sions 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 comfort=
able margin. Typically a client creates a dedicated thread whose only purpo=
se is keeping the session alive. It can accomplish this by invoking r=
efreshSession
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 b=
y createSession
). Ice includes helper classes that you can use to simplify the tas=
k of create a session and keeping it alive.
Note that if a session times out, the next client invocation raises
A router session is destroyed automatically when the session expires, and whe=
n a client explicitly destroys its session. The router also destroys a sess=
ion if certain connection errors occur while attempting to route a request.=
These errors are represented by the run-time exceptions SocketExcept=
ion
, TimeoutException
, and ProtocolException. In other words, if any of these exceptions occur while Glacier2 attempt=
s to establish a connection to the target back-end server, or forward a req=
uest to the target back-end server, the router automatically destroys the s=
ession.