Getting Started with Glacier2

8 min read

8 min read

8 min read

7 min read

8 min read

8 min read

8 min read

8 min read

8 min read

Using Glacier2 in a minimal configuration involves the following tasks:

  1. Write a configuration file for the router.
  2. Write a password file for the router. (Glacier2 also supports other ways to authenticate users.)
  3. Start the router on a host with access to the public and private networks.
  4. Modify the client configuration to use the router.
  5. Modify the client to create a router session.

The Glacier2 greeter demo provides a complete client and server in C++, and the configuration of the Glacier2 router between them.

The Glacier2 greeter demo provides a complete client and server in C#, and the configuration of the Glacier2 router between them.

The Glacier2 greeter demo provides a complete client and server in Java, and the configuration of the Glacier2 router between them.

The Glacier2 greeter demo provides a MATLAB client that runs against the router and server of a greeter demo written in another language.

The Glacier2 greeter demo provides a PHP client that runs against the router and server of a greeter demo written in another language.

The Glacier2 greeter demo provides a complete client and server in Python, and the configuration of the Glacier2 router between them.

The Glacier2 greeter demo provides a Ruby client that runs against the router and server of a greeter demo written in another language.

The Glacier2 greeter demo provides a complete client and server in Swift, and the configuration of the Glacier2 router between them.

The following router configuration property establish the necessary endpoint:

Properties
Glacier2.Client.Endpoints=tcp -h 5.6.7.8 -p 4063

The endpoint defined by Glacier2.Client.Endpoints is used by the Ice runtime 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).

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 configuration is typically necessary.

The simplest way for the router to authenticate clients is a password file. The property Glacier2.CryptPasswords specifies the name of this file:

Properties
Glacier2.CryptPasswords=passwords

Each non-blank line contains exactly two whitespace-separated fields, a user name and a password hash, and each user name appears only once. The icehashpassword helper script generates the hash in one of the formats the router accepts. For example, on Linux:

Shell
icehashpassword
Password:
$6$rounds=656000$PFLqAztdBNhCjPeZ$GeZ3rLbMu4FObT78zAqQ15qJu0M/DSAZVBoNJCm95AaTflH.c06IcgFNbm8fOnl1ynGcEBqa.Ftgw3lJ0jPRm0

The password file with this hash for the user name test:

test $6$rounds=656000$PFLqAztdBNhCjPeZ$GeZ3rLbMu4FObT78zAqQ15qJu0M/DSAZVBoNJCm95AaTflH.c06IcgFNbm8fOnl1ynGcEBqa.Ftgw3lJ0jPRm0

The same entry on Windows and macOS:

test $pbkdf2-sha256$29000$O4dQinGOcY7RWktJyXlvbQ$D0BZnA1kTw4Jl4xGUzdMOSxKO/vODiMCHEE9ZRLF4Gg

Assuming our configuration properties are stored in a file named config, you can start the router with the following command:

Shell
glacier2router --Ice.Config=config

The following property configures a client to use a Glacier2 router:

Properties
Ice.Default.Router=Glacier2/router:tcp -h 5.6.7.8 -p 4063

The Ice.Default.Router property defines the router proxy. Its endpoints must match those in Glacier2.Client.Endpoints.

A Glacier2 router hosts a single object, which implements the Glacier2::Router interface and has the identity Glacier2/router by default. If an application uses several different routers, as opposed to replicas, give this object a unique identity in each router by configuring the routers with different values of the Glacier2.InstanceName property, as shown in the following example:

Properties
Glacier2.InstanceName=PublicRouter

This property changes the category of the object identity, which becomes PublicRouter/router. The client's configuration must also be changed to reflect the new identity:

Properties
Ice.Default.Router=PublicRouter/router:tcp -h 5.6.7.8 -p 4063

Glacier2 routers deployed as replicas, for example to gain redundancy or to distribute the message-forwarding load over several machines, use the same instance name, and their clients use a proxy with the endpoints of all the replicas, such as:

Properties
Ice.Default.Router=PublicRouter/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 interface:

Slice
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 destroySession()
throws SessionNotExistException;
}
}

The interface defines two operations for creating sessions: createSession and createSessionFromSecureConnection. The router forwards the requests of a client only after the client creates a session with one of these operations. Both operations return a null proxy in the configuration described on this page.

The createSession operation expects a user name and password. 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 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 creates the router proxy from the communicator and then calls one of the create operations. For example:

C++
Glacier2::RouterPrx router{
communicator,
"Glacier2/router:tcp -h 5.6.7.8 -p 4063"};
optional<Glacier2::SessionPrx> session =
router->createSession(Env::getUsername(), "password");
C#
Glacier2.RouterPrx router = Glacier2.RouterPrxHelper.createProxy(
communicator,
"Glacier2/router:tcp -h 5.6.7.8 -p 4063");
Glacier2.SessionPrx? session =
await router.createSessionAsync(Environment.UserName, "password");
Java
RouterPrx router = RouterPrx.createProxy(
communicator, "Glacier2/router:tcp -h 5.6.7.8 -p 4063");
SessionPrx session;
try {
session = router.createSession(System.getProperty("user.name"), "password");
} catch (PermissionDeniedException | CannotCreateSessionException e) {
System.out.println("Could not create session: " + e.getMessage());
return;
}
JavaScript
const router = new Glacier2.RouterPrx(
communicator,
"Glacier2/router:tcp -h 5.6.7.8 -p 4063");
const session = await router.createSession(name, "password");
MATLAB
router = Glacier2.RouterPrx(communicator, ...
'Glacier2/router:tcp -h 5.6.7.8 -p 4063');
username = char(java.lang.System.getProperty('user.name'));
session = router.createSession(username, 'password');
PHP
$router = Glacier2\RouterPrxHelper::createProxy(
$communicator, 'Glacier2/router:tcp -h 5.6.7.8 -p 4063');
$username = get_current_user();
$session = $router->createSession($username, 'password');
Python
router = Glacier2.RouterPrx(
communicator,
"Glacier2/router:tcp -h 5.6.7.8 -p 4063")
session = await router.createSessionAsync(getpass.getuser(), "password")
Ruby
router = Glacier2::RouterPrx.new(
communicator,
"Glacier2/router:tcp -h 5.6.7.8 -p 4063")
username = Etc.getlogin
session = router.createSession(username, "password")
Swift
let router = try makeProxy(
communicator: communicator,
proxyString: "Glacier2/router:tcp -h 5.6.7.8 -p 4063",
type: Glacier2.RouterPrx.self)
let session = try await router.createSession(
userId: NSUserName(),
password: "password")

A Glacier2 session ends when the connection between the client and the router closes or when the client calls destroySession on the router.

A client that creates a new session, for example after losing its connection to the router, must set up its callbacks again, as described in Handling Connection Loss.

The router's idle check detects a client that disappears without closing its connection: when the router receives nothing on the connection for the idle timeout, 60 seconds by default, it aborts the connection, which ends the session. Glacier2.Client.Connection.IdleTimeout sets this timeout.

The router does not close an inactive client connection: it disables its inactivity check on these connections unless you set Glacier2.Client.Connection.InactivityTimeout. The client's own inactivity check closes a connection it has not used for 300 seconds by default, and this closure ends the session. A client that wishes to keep an unused session open can set Ice.Connection.Client.InactivityTimeout to 0.