---
title: "Getting Started with Glacier2"
url: https://docs.zeroc.com/ice/3.8/services/glacier2/getting-started-with-glacier2
language: csharp
docs_index: https://docs.zeroc.com/llms.txt
---

> For an index of every page, see [llms.txt](https://docs.zeroc.com/llms.txt).

# Getting Started with Glacier2

Programming language: C#. Other languages: [C++](https://docs.zeroc.com/ice/3.8/services/glacier2/getting-started-with-glacier2/cpp.md), [Java](https://docs.zeroc.com/ice/3.8/services/glacier2/getting-started-with-glacier2/java.md), [JavaScript](https://docs.zeroc.com/ice/3.8/services/glacier2/getting-started-with-glacier2/js.md), [MATLAB](https://docs.zeroc.com/ice/3.8/services/glacier2/getting-started-with-glacier2/matlab.md), [PHP](https://docs.zeroc.com/ice/3.8/services/glacier2/getting-started-with-glacier2/php.md), [Python](https://docs.zeroc.com/ice/3.8/services/glacier2/getting-started-with-glacier2/python.md), [Ruby](https://docs.zeroc.com/ice/3.8/services/glacier2/getting-started-with-glacier2/ruby.md), [Swift](https://docs.zeroc.com/ice/3.8/services/glacier2/getting-started-with-glacier2/swift.md).

## Using Glacier2

Using Glacier2 in a minimal configuration involves the following tasks:

1. Write a [configuration file](#configuring-the-router) for the router.
2. Write a [password file](#writing-a-password-file) for the router. (Glacier2 also supports [other ways](https://docs.zeroc.com/ice/3.8/services/glacier2/securing-a-glacier2-router/csharp.md) to authenticate users.)
3. [Start the router](#starting-the-router) on a host with access to the public and private networks.
4. Modify the [client configuration](#configuring-a-glacier2-client) to use the router.
5. Modify the client to create a [router session](#glacier2-sessions).

> **Note**
>
> 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 [Glacier2 greeter demo](https://github.com/zeroc-ice/ice-demos/tree/3.8/csharp/Glacier2/Greeter) provides a complete client and server in C#, and the configuration of the Glacier2 router between them.

## Configuring the Router

The following router configuration property establish the necessary endpoint:

```config
Glacier2.Client.Endpoints=tcp -h 5.6.7.8 -p 4063
```

The endpoint defined by [Glacier2.Client.Endpoints](https://docs.zeroc.com/ice/3.8/property-reference/glacier2-properties.md) 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**
>
> This sample configuration uses TCP as the endpoint protocol, although in most cases, [SSL is preferable](https://docs.zeroc.com/ice/3.8/services/glacier2/securing-a-glacier2-router/csharp.md).

Note that this configuration enables the router to forward requests from clients to servers. Additional configuration is necessary to support [callbacks](https://docs.zeroc.com/ice/3.8/services/glacier2/callbacks-through-glacier2/csharp.md) from servers to clients.

You must also decide which authentication scheme (or schemes) to use. A [file-based](#writing-a-password-file) mechanism is available, as are [more sophisticated strategies](https://docs.zeroc.com/ice/3.8/services/glacier2/securing-a-glacier2-router/csharp.md).

If clients access a [location service](https://docs.zeroc.com/ice/3.8/services/glacier2/icegrid-and-glacier2-integration.md) via the router, additional router configuration is typically necessary.

## Writing a Password File

The simplest way for the router to authenticate clients is a password file. The property [Glacier2.CryptPasswords](https://docs.zeroc.com/ice/3.8/property-reference/glacier2-properties.md#glacier2.cryptpasswords) specifies the name of this file:

```config
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](https://docs.zeroc.com/ice/3.8/services/glacier2/securing-a-glacier2-router/csharp.md#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`:

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

The same entry on Windows and macOS:

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

> **Note**
>
> This authentication scheme is intended for use in simple applications with a few users. Most applications should install their own custom [permissions verifier](https://docs.zeroc.com/ice/3.8/services/glacier2/securing-a-glacier2-router/csharp.md).

## Starting the Router

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
```

## Configuring a Glacier2 Client

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

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

The [Ice.Default.Router](https://docs.zeroc.com/ice/3.8/property-reference/ice-default-properties/csharp.md#ice.default.router) property defines the router proxy. Its endpoints must match those in `Glacier2.Client.Endpoints`.

## Glacier2 Object Identities

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](https://docs.zeroc.com/ice/3.8/property-reference/glacier2-properties.md#glacier2.instancename) property, as shown in the following example:

```config
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:

```config
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:

```config
Ice.Default.Router=PublicRouter/router:tcp -h 5.6.7.8 -p 4063:tcp -h 6.10.7.8 -p 4063
```

> **Note**
>
> A client can discover a router's proxy at run time using the [RouterFinder interface](https://docs.zeroc.com/ice/3.8/services/glacier2/advanced-glacier2-client-configurations/csharp.md).

## Glacier2 Sessions

### Glacier2 Session Creation

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](https://docs.zeroc.com/ice/3.8/services/glacier2/securing-a-glacier2-router/csharp.md) 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:

```csharp
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");
```

### Glacier2 Session Destruction

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](https://docs.zeroc.com/ice/3.8/services/glacier2/callbacks-through-glacier2/csharp.md#handling-connection-loss).

The router's [idle check](https://docs.zeroc.com/ice/3.8/runtime/connection-management/connection-closure/csharp.md#the-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](https://docs.zeroc.com/ice/3.8/property-reference/glacier2-properties.md#glacier2.client.adapterproperty) sets this timeout.

The router does not close an inactive client connection: it disables its [inactivity check](https://docs.zeroc.com/ice/3.8/runtime/connection-management/connection-closure/csharp.md#the-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](https://docs.zeroc.com/ice/3.8/property-reference/ice-connection-properties/csharp.md#ice.connection.name.inactivitytimeout) to `0`.

## See Also

- [Callbacks Through Glacier2](https://docs.zeroc.com/ice/3.8/services/glacier2/callbacks-through-glacier2/csharp.md)
- [Securing a Glacier2 Router](https://docs.zeroc.com/ice/3.8/services/glacier2/securing-a-glacier2-router/csharp.md)
- [Glacier2 Session Management](https://docs.zeroc.com/ice/3.8/services/glacier2/glacier2-session-management.md)
- [Glacier2.\*](https://docs.zeroc.com/ice/3.8/property-reference/glacier2-properties.md)
- [Windows Services](https://docs.zeroc.com/ice/3.8/background-servers/windows-services.md)
