9.3. Regional Hotdesking

9.3.1. Regional Hotdesking Process
9.3.2. Regional Hotdesking Site Requirements
9.3.3. Providing Site Integration Logic
9.3.4. How to Configure a Site-specific Mapping Library
9.3.5. How to Use Token Readers with Regional Hotdesking
9.3.6. How to Configure the Sample Data Store

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:

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


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:

  1. 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.

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

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

  4. Otherwise, the regional hotdesking software redirects the Sun Ray Client to connect to the appropriate Sun Ray server.

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.


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.


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

    # /opt/SUNWut/sbin/utamghadm -l /opt/SUNWutref/amgh/lib/libutamghref_token.so
  • How to Configure the User Name-based Mapping Implementation Provided as a Sample

    # /opt/SUNWut/sbin/utamghadm -l /opt/SUNWutref/amgh/lib/libutamghref_username.so
  • How to Configure a Script-based Back-end Mapping

    # /opt/SUNWut/sbin/utamghadm -s /opt/SUNWutref/amgh/utamghref_script

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:







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


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.

      A sample line for this file would look like the following:

      token=MicroPayflex.5001436700130100 username=user1 host=ray-207