Regional hotdesking, previously referred to as Automatic
Multi-Group Hotdesking (AMGH), is required when users need to
move from one location to another, such as between corporate
headquarters and various branch offices, and they want access to
their existing session across multiple failover groups.

Multiple failover groups are useful for various reasons, such
as:

Availability - It is sometimes advantageous to have
multiple, geographically-separate locations, each with a
failover group, so that if an outage occurs at one location,
another location can continue to function.

Organizational Policies - Some sites have different
administrative policies at different locations. It can be
advantageous to keep separate failover groups at these
locations.

For further technical detail, please refer to the
utamghadm(8),
ut_amgh_get_server_list(3), and
ut_amgh_script_interface(3) man pages.

Note

Regional hotdesking is not enabled for multihead groups.

9.3.1. Regional Hotdesking Process

Once regional hotdesking is configured, user login information
and sessions are handled as follows:

When a smart card is inserted or removed from the system
or a user logs in via the greeter GUI, parameters such as
the user name (if known at the time), smart card token,
and terminal identifier are passed to a piece of site
integration logic.

The site-integration software uses these parameters to
determine to which Sun Ray servers it should direct the
Sun Ray Client.

If the smart card token is associated with a local
session, then that session gets preference, and regional
hotdesking is not invoked.

Thus, if the user has an existing session, the client connects
to that session; if not, the regional hotdesking software
creates a new session for that user.

9.3.2. Regional Hotdesking Site Requirements

To use regional hotdesking, a site must provide some site
integration logic that can utilize enterprise data to
determine which users or Sun Ray Clients should connect to
which failover groups. This is ordinarily provided through the
use of a dynamic C library or a shell script that implements a
particular interface used by regional hotdesking software. Sun
Ray Software provides some reference code that you use as an
example or adapt as required. An administrator must configure
the regional hotdesking software to utilize a specified
library or shell script, then implement the PAM stack of the
login applications, as described below.

Note

To ensure continuous operation, be sure to include enough
servers in the target group to provide availability for
session location and placement in the event that a
particular server becomes unavailable. Two servers should be
minimally sufficient for most sites; three servers provide a
conservative margin of error.

9.3.3. Providing Site Integration Logic

To determine where given Sun Ray Clients or users should be
connected when creating or accessing sessions, you must
utilize enterprise data. Sun Ray Software includes the
following software for this purpose:

Man pages, such as
ut_amgh_get_server_list(3), which
describe the appropriate C API for a shared library
implementation.

A shell-script API,
ut_amgh_script_interface(3), which can
be used as an alternative.

Reference C code and script code, located at
/opt/SUNWutref/amgh. This code can
serve as example or be directly adapted for use.

A functional Makefile.

9.3.4. How to Configure a Site-specific Mapping Library

For each site, you must determine what mapping library to use.
It may be a site-specific implementation, or one of the sample
implementations provided with the Sun Ray Software.

Note

If you are using Oracle Linux, library mapping for the
32-bit platform should be
/opt/SUNWutref/amgh/lib, as shown below,
and library mapping for the 64-bit platform should be
/opt/SUNWutref/amgh/lib64.

After configuring the library, you must perform a cold restart
of the Sun Ray services using either the
utstart CLI or the Admin GUI.

How to Configure the Token-based Mapping Implementation
Provided as a Sample

9.3.5. How to Use Token Readers with Regional Hotdesking

To utilize token readers with regional hotdesking based on Sun
Ray pseudo-tokens, use the Site-specific Mapping Library to
produce the desired behavior for them.

Configured token readers should have the following value
formats:

Key

Value

insert_token

pseudo.MAC_address

token

TerminalId.MAC_address

If a registered policy is in place, use the
insert_token key instead of the token key,
which is not globally unique.

Note

The RHA security feature does not affect token readers. It
is assumed that token readers are deployed in physically
secure environments.

9.3.6. How to Configure the Sample Data Store

Each site must configure a data store to contain site-specific
mapping information for regional hotdesking. This data store
is used by the site mapping library to determine whether
regional hotdesking should be initiated for the parameters
presented. The data store can be a simple flat file. The
sample implementations included with the Sun Ray Software
require a simple flat file configuration.

To create the back-end database file under
/opt/SUNWutref/amgh/back_end_db on the Sun
Ray server, do the following:

For a token-based mapping, use entries of the form:

token=XXXXXXX [username=XXXXX] host=XXXXX

Comments (lines beginning with #) are ignored.

username is optional. If the same
token is associated with more than one non-null
username, an error is returned.

For a user name-based mapping, use entries of the form:

username=XXXXX host=XXXXX

Comments (lines beginning with #) are ignored.

Key/value pairs other than those mentioned above are
ignored.

The order of key/value pairs is not significant.

For a combined mapping, use entries of the form:

Any combination of TOKEN BASED and USERNAME BASED lines.

Comments (lines beginning with #) are ignored.

A token match is attempted first.

If no token match is made (or if no
username is included in the
matches) the user is prompted for a
username.

A lookup is made for this username.
If there is no match, a local session is created;
otherwise, the Sun Ray Client is forwarded to the
first host reported as available.