C H A P T E R  4

Configuring Applications

This chapter contains advice on configuring applications that users can run through Sun Secure Global Desktop (SGD), and how to diagnose and fix problems with applications.

This chapter includes the following topics:


Supported Applications

You can use SGD to access the following types of applications:

SGD supports the following protocols:

Supported Installation Platforms for the SGD Enhancement Module

The SGD Enhancement Module is a software component that can be installed on an application server to provide the following additional functionality when using applications displayed through SGD:

The following are the supported installation platforms for the SGD Enhancement Module:


Operating System Supported Versions
Microsoft Windows

(Intel® x86 32-bit and Intel x86 64-bit)

Windows Server 2003

Windows Server 2008

Microsoft Windows XP Professional

Microsoft Windows Vista Ultimate

Microsoft Windows Vista Business

Solaris OS on SPARC® platforms 8, 9, 10, 10 Trusted Extensions
Solaris OS on x86 platforms 10, 10 Trusted Extensions
OpenSolaristrademark on x86 platforms 2008.11 or later
Red Hat Enterprise Linux (Intel x86 32-bit) 5

Note the following limitations:

Application servers that are not supported platforms for the SGD Enhancement Module can be used with SGD to access a supported application type using any of the supported protocols.


Windows Applications

This section describes how to configure Windows application objects.

This section includes the following topics:

Configuring Windows Application Objects

You use a Windows application object if you want to give a Microsoft Windows graphical application to users.

In the Administration Console, the configuration settings for Windows application objects are divided into the following tabs:

The following table lists the most commonly used settings for configuring Windows application objects, and how to use them.


Attribute Description
Name The name that users see.
Icon The icon that users see.
Application Command The full path to the application that runs when users click the link.

The application must be installed in the same location on all application servers.

Leave this field blank if you want to run a Windows desktop session.

Arguments for Command Any command-line arguments to use when starting the application.
Windows Protocol The mechanism SGD uses to connect to the application.

Select the Try Running from Client First check box to run the application on the user’s client device. See Running Windows Applications on Client Devices.

Select the Microsoft RDP Protocol option to run an application using Microsoft Terminal Services. This option gives users the best experience when using Windows applications displayed through SGD. A wider range of features, such as client drive mapping, audio, and smart cards, are supported. See Using Microsoft RDP.

Select the Citrix ICA Protocol to run an application using the Citrix ICA protocol.

Domain Name The Windows domain to use for the application server authentication process.

This can be left blank. The domain can also be configured on either the application server or the user profile. See also Windows Domains and the Password Cache.

Number of Sessions The number of instances of an application a user can run. The default is three.
Application Resumability For how long the application is resumable. The following options are available:
  • Never – The application can never be resumed

  • During the User Session – The application keeps running and is resumable until the user logs out of SGD

  • General – The application keeps running for a time, controlled by the Timeout setting, after the user logs out of SGD, and can be resumed when the user next logs in

Window Type How the application is displayed to the user.

Use Kiosk for full-screen desktop sessions. Selecting the Scale to Fit Window check box for the Window Size enables SGD to scale the application window to fit the client device display.

For Independent Window, you must specify a Height and Width for the Window Size or select the Client’s Maximum Size check box.

Use Seamless Window mode to the application in the same way it displays on the Windows application server, regardless of the user’s desktop environment. See Seamless Windows.

Color Depth The application’s color depth.

See Color Depth for more details.

Application Load Balancing How SGD chooses the best application server to run the application.

See Application Load Balancing for more details.

Hosting Application Servers tab Use the Editable Assignments table to select the application servers, or group of application servers, that can run the application.

The application must be installed in the same location on all application servers

Assigned User Profiles tab Use the Editable Assignments table to select the users that can see the application. Selecting Directory or Directory (light) objects enables you to give the application to many users at once. You can also use a Lightweight Directory Access Protocol (LDAP) directory to assign applications. See LDAP Assignments.

In addition to this configuration, you can also configure the following:

Creating Windows Application Objects on the Command Line

On the command line, you create an Windows application object with the tarantella object new_windowsapp command. You can also create multiple Windows application objects at the same time with the tarantella object script command. See Populating the SGD Organizational Hierarchy Using a Batch Script.

Windows application objects can only be created in the o=applications organizational hierarchy.

Using Microsoft RDP

This section covers advanced configuration for Windows application objects that use Microsoft RDP as the Windows protocol.

This section includes the following topics:

Configuring Microsoft Windows Terminal Services for Use With SGD

Selecting Microsoft RDP Protocol as the Windows Protocol for a Windows application object enables you to use Microsoft Windows Terminal Services.



Note - From Windows Server 2008 R2, Terminal Services is renamed Remote Desktop Services.



The following table shows the Terminal Services features supported by SGD and the application server platforms on which they are supported.


Terminal Services Feature Windows Server 2003 Windows Server 2008 Windows XP Professional Windows Vista Ultimate Windows Vista Business
Audio redirection
Clipboard redirection
COM port mapping
Encryption level
Session directory
Smart card device redirection
Time zone redirection
Windows printer mapping

There are many possible configuration settings for Microsoft Windows Terminal Services. For detailed information on configuring Terminal Services, see your system documentation. To use Terminal Services with SGD, the settings you might have to configure include the following:



Note - Changes to your Terminal Services configuration only take effect for new Windows Terminal Server sessions.



Authentication Settings

You must configure Windows Terminal Services so that it does not prompt for a password when a user logs in.

By default, Windows 2000 Server always prompts for a password when users log in, whether or not SGD supplies the password for the application server from its password cache. By default, Windows Server 2003 or later, does not prompt for passwords.

Session Resumability and Session Directory

With Windows Terminal Services, users’ sessions can continue to run following a connection loss.

If you are not using Session Directory, it is best to disable this feature on the Windows Terminal Server, and let SGD handle session resumability. This prevents unnecessary use of resources on the application server, and ensures that if users share accounts on the application server, they do not resume each other’s Windows sessions. To disable this feature, you must select End Session for the When Session Limit Is Reached Or Connection Is Broken option in Terminal Services Configuration.

If you are using Session Directory to handle session resumability, you must select Suspend Session for the When Session Limit Is Reached Or Connection Is Broken option in Terminal Services Configuration. To use Session Directory, you must also configure the Window Close Action attribute for Windows application objects to End Application Session.

Windows Printer Mapping

To support printing to client printers from a Windows Terminal Server session, Windows printer mapping must be enabled. Windows printer mapping is enabled by default.

Encryption Level

You can only use the Low, Client-compatible, or High encryption levels with SGD. SGD does not support the Federal Information Processing Standards (FIPS) encryption level.

Multiple Terminal Services Sessions

By default, a Microsoft Windows Server only allows users to start one Terminal Services session. If a user starts another desktop session, or another instance of an application with the same arguments, the second Terminal Services session grabs the first session and disconnects it. This means that it is not possible to start two desktop sessions, or two instances of the same application, on the same Windows Server.

On Microsoft Windows Server 2003 or later application servers, you can enable support for multiple Terminal Services sessions.

Remote Desktop Users

For Microsoft Windows Server 2003 or later application servers, users can only use Terminal Services if they are members of the Remote Desktop Users group.

Time Zone Redirection

Client computers can redirect their time zone settings to the Terminal Server, so that users see the correct time for their time zone in their desktop or application sessions. Terminal Services uses the server base time on the Terminal Server and the client time zone information to calculate the time in the session. This feature is useful if you have clients devices in different time zones. By default, this feature is disabled.

In the Administration Console, the Time Zone Map File attribute on the Global Settings -> Client Device tab specifies a file that contains mappings between UNIX platform client device and Windows application server time zone names.

Audio Redirection

To play audio from a Windows Terminal Server session, audio redirection must be enabled on the application server. By default, audio redirection is disabled.

Smart Card Device Redirection

To use a smart card reader from a Windows Terminal Server session, smart card device redirection must be enabled on the application server. By default, smart card device redirection is enabled.

COM Port Mapping

To access the serial ports on the client device from a Windows Terminal Server session, COM port mapping must be enabled on the application server. By default, COM port mapping is disabled.

Color Depth

SGD supports 8‐bit, 16‐bit, and 24‐bit color depths in a Windows Terminal Server session.

15-bit and 32-bit color depths are not supported. If these color depths are specified on the Terminal Server, SGD automatically adjusts the color depth to 8-bit (for 15-bit) and 24-bit (for 32-bit).

Transport Layer Security

From Microsoft Windows Server 2003 and later, you can use Transport Layer Security (TLS) for server authentication, and to encrypt Terminal Server communications. SGD does not support the use of TLS.

Terminal Services Group Policies

For Windows Server 2003 and later, Terminal Services settings can be configured using Group Policy, as follows:

  • Individual Windows Terminal Servers can be configured using a Local Group Policy Object (LGPO). In the Group Policy Object Editor, the Terminal Services settings are at: Local Computer Policy\Computer Configuration\Administrative Templates\Windows Components\Terminal Services

  • Multiple Windows Terminal Servers can be configured using a Group Policy Object (GPO), linked to a domain or organizational unit (OU).

To improve performance, you might want to configure some or all of the following policies:

  • Keep-Alive Connections. This policy specifies a keep alive time interval for the Terminal Services session. See also Keep Alive Configuration for Windows Terminal Servers.

  • Limit Maximum Color Depth. This policy controls the display color depth on client devices. See Microsoft Knowledge Base article 278502 for details of how to set this policy.

Keep Alive Configuration for Windows Terminal Servers

If you find that the connection between the SGD server and the Windows Terminal Server is being dropped unexpectedly, you might need to configure the keep alive mechanism for the Windows Terminal Server.

How to do this is described in Microsoft Knowledge Base article 216783.

Microsoft Windows Remote Desktop

Some editions of Microsoft Windows include a Remote Desktop feature that enables you to access a computer using Microsoft RDP. You can use SGD and Remote Desktop, for example, to give users access to their office PC when they are out of the office.

Remote Desktop is supported on the following platforms:

  • Microsoft Windows XP Professional

  • Microsoft Windows Vista Ultimate

  • Microsoft Windows Vista Business

Before introducing SGD, ensure that the Remote Desktop connection to the Microsoft Windows computer is working.

You configure SGD for use with Remote Desktop as follows:

  • Create an application server object for each Microsoft Windows computer.

  • Create Windows application objects.

    Only full Windows desktop sessions are supported. You cannot run a specific application on the Windows computer. Seamless windows are not supported. To ensure users access their own computer, you have to create separate Windows desktop application objects for each Microsoft Windows computer.

  • To use client drive mapping, install the SGD Enhancement Module for Windows on the Microsoft Windows computer.

See Using My Desktop for details of how to run a full-screen desktop session, without displaying the SGD webtop.

Seamless Windows

With seamless windows, the Microsoft Windows application server manages the display of the application. This means an application’s windows behave in the same way as an application displayed on the application server, regardless of the user’s desktop environment. The window can be resized, stacked, maximized, and minimized. The Windows Start Menu and Taskbar are not displayed when using seamless windows.

Seamless windows are not suitable for displaying Windows desktop sessions. Use a kiosk or independent window instead.

The following are the conditions for using seamless windows:

  • The application server must be a Windows 2000 Server or later.

  • The SGD Enhancement Module for Windows must be installed on the application server.

  • The Windows application object must be configured to use Microsoft RDP as the Windows Protocol, and the Window Type must be seamless window.

If any of the above conditions are not met, SGD displays the Windows application in an independent window instead.

Notes and Tips on Using Seamless Windows

The following are some notes and tips on displaying applications in seamless windows:

  • If an application is displayed in a seamless window, you can toggle between a seamless window and an independent window by pressing the Scroll Lock key. This does not work if the SGD Client is in Integrated Mode.

  • Applications that have non-rectangular windows, for example, a media player with a customized skin, display in a rectangular window.

  • On Windows client devices, seamless windows are not affected by the Cascade, Tile Windows Horizontally, or Tile Windows Vertically window commands.

  • If a screen saver or the Windows Security dialog displays, the window automatically switches to an independent window. Unlocking the application automatically restores the window to a seamless window.

  • If a seamless window application is resumed on a display that is larger or smaller in size than the original session, the application is displayed in an independent window.

  • Each application displaying in a seamless window has its own RDP connection.

  • Applications configured to display in seamless windows might not display correctly when accessed from a Gnome 2.0.0 Desktop. This is caused by an unpatched version of the Metacity Window Manager. The solution is to install the Gnome 2.0.0 Window Manager patch. Patch ID: 115780, available from the Sun Support Center at http://www.sun.com/support.

Key Handling for Windows Terminal Services

You can configure how SGD handles keyboard presses on the client device in a Windows Terminal Services session, as follows:

Supported Keyboard Shortcuts for Windows Terminal Services

SGD supports the following keyboard shortcuts for Windows Terminal Services sessions.


Keyboard Shortcut Description
Ctrl-Alt-End Displays the Windows Security dialog.
Alt-Page Up Switches between windows, from left to right.
Alt-Page Down Switches between windows, from right to left.
Alt-Insert Cycles through windows, in the order they were opened.
Alt-End Displays the Windows Start menu.
Alt-Delete Displays the pop-up menu for the current window.
Ctrl-Alt-Minus Use the Minus (-) key on the numeric keypad.

Places a snapshot of the active client window on the Windows Terminal server clipboard.

Provides the same functionality as pressing Alt-PrintScrn on a local computer.

Ctrl-Alt-Plus Use the Plus (+) key on the numeric keypad.

Places a snapshot of the entire client window area on the Windows Terminal server clipboard.

Provides the same functionality as pressing PrintScrn on a local computer.

Alt-Ctrl-Shift-Space Minimizes the active window. Only applies for kiosk mode.

The Windows Key and Window Management Keys

In SGD Windows Terminal Services sessions, the Windows key and keyboard shortcuts for managing windows can be sent either to the remote session or acted on locally. By default, they are acted on locally.

For Windows applications objects that are configured to display in kiosk mode, the Window Management Keys (--remotewindowkeys) attribute controls keyboard shortcut behavior. To send the Windows key and window management keys to the remote session, do either of the following:

  • In the Administration Console, go to the Client Device tab for the Windows application object and select the Window Management Keys check box.

  • Use the following command:


    $ tarantella object edit --name obj --remotewindowkeys 1
    

If the Windows key and window management keys are sent to the remote session, use the key sequence Alt‐Ctrl‐Shift‐Space to exit kiosk mode. This minimizes the kiosk session on the local desktop. Alternatively, to exit kiosk mode you can use the Kiosk Mode Escape (--allowkioskescape) attribute to enable a pull-down header for the application window. The pull-down header includes icons for minimizing and closing the kiosk session.

For Windows applications objects that are not configured to display in kiosk mode, you can force the Windows key to be sent to the remote session by using the -windowskey option for the SGD Terminal Services Client. To send the Windows key to the remote session, do either of the following:

  • In the Administration Console, go to the Launch tab for the Windows application object and type -windowskey on in the Arguments for Protocol field.

  • Use the following command:


    $ tarantella object edit --name obj --protoargs “-windowskey on”
    

Configuring Windows Keyboard Maps

The process of configuring Windows keyboard maps in SGD is the same as that used for configuring keyboard maps for X applications. See also Keyboard Maps.



Note - For Windows applications, the keyboard layout must be the same on the client device and the application server.



Returning Client Device Information for Windows Terminal Services Sessions

By default, when you run a Windows application through SGD using the Microsoft RDP protocol, the host name of the client device is returned in the %CLIENTNAME% environment variable for the Windows Terminal Services session. When you use a Sun Ray Desktop Unit (DTU) client device, the DTU ID is returned in the %CLIENTNAME% environment variable. The DTU ID is the hardware address of the Sun Ray.

The DTU ID can be used to specify the name of the client device in the wcpwts.exp login script. SGD uses this login script for all Windows applications that connect using the Microsoft RDP protocol.

The SGD Terminal Services Client

The SGD Terminal Services Client, also known as ttatsc, is a client program that handles the connection between the SGD server and the Windows Terminal Server.

The syntax for running ttatsc from the command line is as follows:

ttatsc [-options..] server.example.com

where server.example.com is the name of a Windows Terminal Server.

You can use the ttatsc to configure Windows Terminal Services sessions in the following ways:

  • Configure the Arguments for Protocol (--protoargs) attribute of the Windows application object. Using this attribute, you can specify ttatsc command options used for a Windows application object.

  • Edit the wcpwts.exp login script, and specify ttatsc command options. Any changes you make to this file are used for all Windows applications that connect using the Microsoft RDP protocol.

The following options are supported for the ttatsc command.


Option Description

-application application

The application to run in the Terminal Services session.

-audioquality low|medium|high

Sets the quality of the audio redirection.

-bulkcompression on|off

Enable or disable data compression for the connection.

-console

Instead of starting a normal RDP session, connect to the console session.

-crypt on|off

Configures encryption for the connection. The default setting, on, gives the best user experience.

-defaultdepth

Whether to let the Terminal Server set the default color depth of the X session.

-desktop

Whether to display a full screen desktop session.

-dir working_dir

Working directory for the Terminal Services session. This can be overridden by the application.

-display X
display

The X display to connect to.

-domain domain

Domain on the Terminal Server to authenticate against.

-keyboard language_tag

Input locale. Specify an RFC1766 language tag.

-name client
name

Name of the client device.

-netbiosname name

NetBIOS name for the client device. This is used for the redirected printer names on the Terminal Server.

-noaudio

Disables audio redirection.

-nofork

Do not run ttatsc as a background process.

-opts file

Read command options from a file. See Using a Configuration File for details.

-password password

Password for the Terminal Services user.

-perf disable 
wallpaper|fullwindowdrag
|menuanimations|theming|
cursorshadow|cursorsettings

Disable display options, to improve performance. The available settings are:
  • wallpaper – Disable the desktop wallpaper

  • fullwindowdrag – Disable the option to show window contents when moving a window

  • menuanimations – Disable transition effects for menus and tooltips

  • theming – Disable desktop themes

  • cursorshadow – Disable the mouse pointer shadow

  • cursorsettings – Disable mouse pointer schemes and customization

To disable multiple display options, use multiple -perf disable options.

-port port

RDP port to connect to on the Terminal Server. The default setting is 3389.

-printcommand command

This option is deprecated.

-sharedcolor

Do not use a private color map.

-size width height

Display width and display height for the Terminal Services session, in pixels.

-spoil

This option is deprecated.

-stdin

Read command options from standard input. Used by the login scripts to pass command options to ttatsc.

-storage data_dir

This option is deprecated.

-swmopts on|off

Enable local window hierarchy for applications that use seamless windows. Needed for some Borland applications.

-timeout connect secs

Timeout for connecting to the Terminal Server, in seconds.

-timeout establish secs

Timeout for establishing an RDP connection, in seconds.

-uncompressed

This option is deprecated.

-user username

User name for the Terminal Services user.

-windowskey on|off

Whether to enable or disable Windows key for the Terminal Services session. The default setting is on.

Using a Configuration File

A configuration file is a text file containing the ttatsc command-line options to be used for the connection. Each option must be on a separate line without the leading dash (-). The argument and its value are separated by whitespace. Use either single or double quotes to enclose any literal whitespace.

The escape character is \.The following escape sequences are supported:

  • \n is a new line (0xA)

  • \r is a carriage return (0xD)

  • \t is a tab (0x9)

  • \\ is a literal \

  • \" is a literal double quote not used for delimiting quoted arguments

  • \'is a literal single quote not used for delimiting quoted arguments

The following is an example configuration file:

u "Indigo Jones"
p "Wh1teh4ll"
a "C:\\program files\\notepad.exe"
naples.indigo-insurance.com

Running Windows Applications on Client Devices

You can run a Windows application on a client device, instead of displaying it through SGD. If the application is not available on the client device, and the Try Running from Application Server check box is selected, SGD tries to run it on the application server using the configured Windows Protocol.

Applications that run on client devices are not resumable, even if the Application Resumability and Windows Protocol attributes are configured.

The application must be installed in the same location on all client devices.


X Applications

This section describes how to configure X application objects.

This section includes the following topics:

Configuring X Application Objects

In the Administration Console, the configuration settings for X application objects are divided into the following tabs:

The following table lists the most commonly used settings for configuring X application objects and how to use them.


Attribute Description
Name The name that users see.
Icon The icon that users see.
Application Command The full path to the application that runs when users click the link.

The application must be installed in the same location on all application servers.

The following are commonly used commands for desktop sessions:

  • /usr/dt/config/Xsession.jds – For a Sun Java Desktop System desktop

  • /usr/bin/gnome-session – For a Gnome desktop

  • /usr/bin/startkde – For a K Desktop Environment (KDE) desktop

See also Configuring Common Desktop Environment Applications, and Configuring VMS Applications.

Arguments for Command Any command-line arguments to use when starting the application.

Note - Never specify a -display argument. This is set by SGD.

Connection Method The mechanism SGD uses to connect to the application server, for example telnet or ssh.
Number of Sessions The number of instances of an application a user can run. The default is three.
Application Resumability For how long the application is resumable. The following options are available:
  • Never – The application can never be resumed

  • During the User Session – The application keeps running and is resumable until the user logs out of SGD

  • General – The application keeps running for a time, controlled by the Timeout setting, after the user logs out of SGD, and can be resumed when the user next logs in

Session Termination The circumstances when the SGD server ends the application session.
Window Type How the application is displayed to the user.

Use Kiosk for full-screen desktop sessions. Selecting the Scale to Fit Window check box for the Window Size enables SGD to scale the application window to fit the client device display.

Use Client Window Management to display the application as though it is running on the client device.

For other window types, you must specify a Height and Width for the Window Size or select the Client’s Maximum Size check box.

Color Depth The application’s color depth.

SGD supports X applications with multiple color depths. So you can run an 8-bit application within a 24-bit desktop session by selecting 24/8-bit, for example

Application Load Balancing How SGD chooses the best application server to run the application.

See Application Load Balancing for more details.

Hosting Application Servers tab Use the Editable Assignments table to select the application servers, or group of application servers, that can run the application.

The application must be installed in the same location on all application servers.

Assigned User Profiles tab Use the Editable Assignments table to select the users that can see the application. Selecting Directory or Directory (light) objects enables you to give the application to many users at once. You can also use an LDAP directory to assign applications. See LDAP Assignments.

In addition to this configuration, you can also configure the following:

Creating X Application Objects on the Command Line

On the command line, you create an X application object with the tarantella object new_xapp command. You can also create multiple X application objects at the same time with the tarantella object script command. See Populating the SGD Organizational Hierarchy Using a Batch Script.

X application objects can only be created in the o=applications organizational hierarchy.

Supported X Extensions

SGD supports the following X extensions for X applications:

The following X extensions are not supported:

X Authorization

By default, SGD secures X displays using X authorization. This prevents users from accessing X displays that they are not authorized to access.

For information about troubleshooting X authorization for X applications, see Applications Fail To Start When X Authorization Is Enabled.

X Fonts

SGD includes the standard X Window System fonts in compiled (.pcf) and compressed form, together with some additional fonts required by different UNIX systems. See Fonts in X11R6.8.2 for details. The fonts are installed in the /opt/tarantella/etc/fonts directory.

The following X fonts and font directories are available with SGD.


Directory Description
75dpi Variable-pitch 75 dpi fonts.
100dpi Variable-pitch 100 dpi fonts.
andrew Fonts from the Andrew toolkit, required by some IBM applications.
CID A placeholder for CID-keyed fonts. If you want to add your own CID fonts for use with SGD, install them in this directory.
cyrillic Cyrillic fonts.
encodings A set of encoding files used by the Type1 and TrueType font handlers
hangul Korean fonts.
hp Fonts required by some Hewlett-Packard applications.
icl Fonts required by some ICL applications.
misc Fixed-pitch fonts, cursor fonts, and fonts for compatibility with older versions of X.
oriental Kanji and other oriental fonts.
scoterm Cursor fonts.
TTF True Type fonts.
Type1 PostScripttrademark Type 1 fonts.

Using Your Own X Fonts

You can make your own X fonts available through SGD in the following ways:

After making the X fonts available, you must configure each SGD server in the array to use the fonts, see How to Configure SGD to Use Your Own X Fonts.

Using a Font Directory

To use a font directory, copy your fonts in .pcf format to a directory on each SGD server in the array and include a fonts.dir file that maps filenames to X logical font descriptions. The fonts can be compressed or gzipped.

The following is an example line from a fonts.dir file:


COURBO10.pcf -Adobe-Courier-Bold-0-Normal-10-100-75-75-M-60-ISO8859-1

If your font directory does not include a fonts.dir file, you can use a program such as mkfontdir, which is available for most UNIX systems, to create one.

You can also include a fonts.alias file, that specifies aliases for the fonts in the directory. This file maps aliases to X logical font descriptions. For example:


variable *-helvetica-bold-r-normal-*-*-140-*

Using a Font Server

A font server is a program that makes fonts on a host available on the network. Font servers make font administration easier by centralizing fonts, reducing duplication.

To name a font server in a font path, you need to know the name of the font server and the port on which fonts are being served. For example, if the font server boston uses Transmission Control Protocol (TCP) port 7100, add the font path entry tcp/boston:7100.

procedure icon  How to Configure SGD to Use Your Own X Fonts

Ensure that no users are logged in to the SGD server, and that there are no application sessions, including suspended application sessions, running on the SGD server.

  1. In the Administration Console, go to the Secure Global Desktop Servers tab and select an SGD server.

  2. Go to the Protocol Engines -> X tab.

  3. In the Font Path field, type the path to the directory containing your X fonts, or the location of the font server.

    Each SGD server in the array can use a different font path. However, to avoid inconsistent display of applications, ensure that the same fonts, in the same order, are available to all SGD servers.

  4. Click Save.

  5. Restart the SGD server.

  6. Check the validity of the font path.

    Use the xset command to see if the font path is set.


    $ xset q
    

Keyboard Maps

SGD uses a keyboard map, or keymap, file to process keyboard input for X applications. A keymap file contains a list of keys for the keyboard and the corresponding characters produced when you press the keys.

By default, an SGD server uses the keymap file corresponding to the locale specified by the Keyboard Map attribute on the Protocol Engines -> X tab for the SGD server in the Administration Console.

The available locale settings are:

You can override the locale for a particular user, by setting the Keyboard Map (--keymap) attribute for the user profile object

To prevent an application from changing the default keyboard mappings, set the Keyboard Map: Locked (--lockkeymap) attribute for the application object.

Keymap files are located in the /opt/tarantella/etc/data/keymaps directory on the SGD server. This directory contains keymap files for the most common keyboard layouts. The keymap files in this directory have a file name beginning with x. For example, xuniversal.txt keymap file is used to map the keys of a Universal (English US) keyboard.

SGD uses the /opt/tarantella/etc/data/keymaps/xlocales.txt file to find the keymap file for the specified locale. This file maps locales to keymap files. For example, the xlocales.txt specifies the xuniversal.txt keymap file for a locale setting of en_US.


Character Applications

This section describes how to configure character application objects. Terminal emulator mappings are also discussed.

This section includes the following topics:

Configuring Character Application Objects

You use a character application object if you want to give a VT420, Wyse 60, or SCO Console character application to users.

In the Administration Console, the configuration settings for character application objects are divided into the following tabs:

The following table lists the most commonly used settings for configuring character application objects and how to use them.


Attribute Description
Name The name that users see.
Icon The icon that users see.
Application Command The full path to the application that runs when users click the link.

The application must be installed in the same location on all application servers.

See also Configuring VMS Applications for details of how to configure Virtual Memory System (VMS) character applications.

Arguments for Command Any command-line arguments to use when starting the application.
Connection Method The mechanism SGD uses to connect to the application server, for example telnet or ssh.
Number of Sessions The number of instances of an application a user can run. The default is three.
Application Resumability For how long the application is resumable. The following options are available:
  • Never – The application can never be resumed

  • During the User Session – The application keeps running and is resumable until the user logs out of SGD

  • General – The application keeps running for a time, controlled by a timeout value, after the user logs out of SGD, and can be resumed when the user next logs in

Window Close Action What happens if the user closes the main application window using the Window Manager decoration. This attribute only applies for applications that use an Independent Window.
Window Type How the application is displayed to the user.

If Independent Window is selected, you must specify a Height and Width for the Window Size or select the Client’s Maximum Size check box.

Specify the number of Columns and Lines to display in the terminal window.

Emulation Type The type of character application to emulate. SGD supports VT420, Wyse 60, or SCO Console character applications.
Terminal Type The application’s terminal type. Accept the default terminal type, or type you own type in the Custom field.
Application Load Balancing How SGD chooses the best application server to run the application.

See Application Load Balancing for more details.

Hosting Application Servers tab Use the Editable Assignments table to select the application servers, or group of application servers, that can run the application.

The application must be installed in the same location on all application servers.

Assigned User Profiles tab Use the Editable Assignments table to select the users that can see the application. Selecting Directory or Directory (light) objects enables you to give the application to many users at once. You can also use an LDAP directory to assign applications. See LDAP Assignments.

To use and display the euro character, the terminal session must be capable of displaying 8-bit characters. To ensure this, enter the command stty -istrip. Also, the client device must be capable of entering the euro character.

Creating Character Application Objects on the Command Line

On the command line, you create a character application object with the tarantella object new_charapp command. You can also create multiple character application objects at the same time with the tarantella object script command. See Populating the SGD Organizational Hierarchy Using a Batch Script.

Character application objects can only be created in the o=applications organizational hierarchy.

Terminal Emulator Keyboard Maps

The SGD terminal emulators associate keys on the user’s client keyboard with keys found on a real terminal. For each type of terminal emulator: SCO Console, Wyse 60, and VT420, there is a default keyboard mapping.

To change the default mappings or define additional mappings for a particular application, you can specify your own keyboard map file using an object’s Keyboard Map attribute.

Default Mappings

The emulators have built-in keyboard maps, which are equivalent to the following sample keymap files in the /opt/tarantella/etc/data/keymaps directory:

  • ansikey.txt – For the SCO Console emulator

  • vt420key.txt – For the VT420 emulator

  • w60key.txt – For the Wyse 60 emulator



Note - Modifying these keyboard maps does not alter the default mappings used by SGD. The only way to do this is to specify a keyboard map in an application object’s Keyboard Map attribute.



Creating a Keyboard Map

To create your own keyboard map, make a copy of one of the sample keyboard map files, and modify it to suit your application. You can modify a keyboard map in any text editor.

The format of a mapping is:

ClientKeys=Translation

Where ClientKeys is the key, or keys, that the user presses on the client device, and Translation is the keystroke, or keystrokes, sent to the application on the application server. For example:

PageDown=Next

With this mapping, when the user presses the Page Down key the emulator sends the keystroke Next to the application server.

If a particular key has a user-defined mapping, the default settings are overridden. If no user-defined mapping is present, the default mapping is sent to the application server.

You can send complete strings on a single key press, by surrounding the string in straight quotation marks. For example:

F1="hello world"

To enter non-printable characters when mapping strings, use the code shown in the table below:


Code Meaning
\r Carriage return
\n Line feed
\" Straight quotation marks
\e Escape
\t Tab
\nnn The character with octal value nnn
\xHH The character with hex value HH

To specify modifier keys, such as Shift, Control, and Alt, in a mapping, separate the keys with the plus sign, +. For example:

Shift+NUMLOCK=INSLINE
Shift+F1="\0330a"
Alt+Shift+Control+DELETE="\003[33~"

Key Names

The following are lists of key names that are valid in SGD keyboard maps. The Client Device Keys list shows the key names that represent keys on the user’s client device. These are the keys that can be mapped to the emulator key names given in Application Server Keystrokes, which are the keystrokes ultimately sent to the application on the application server.



Note - The default mappings between these key names are as found in the keyboard maps supplied with SGD. If a key is not in a keyboard map, then it is not mapped.



Client Device Keys

SGD supports the following keys on the user’s client device:

  • CURSOR_DOWN

  • CURSOR_LEFT

  • CURSOR_RIGHT

  • CURSOR_UP

  • DELETE

  • END

  • F1 to F12

  • HOME

  • INSERT

  • KP0 to KP9

  • KPADD

  • KPDELETE

  • KPDIVIDE

  • KPENTER

  • KPMULTIPLY

  • KPSUBSTRACT

  • NUMLOCK

  • PAGEDOWN

  • PAGEUP

Application Server Keystrokes

The following application server keystrokes are supported for SCO Console applications:

  • CURSOR_DOWN

  • CURSOR_LEFT

  • CURSOR_RIGHT

  • CURSOR_UP

  • DELETE

  • END

  • F1 to F12

  • HOME

  • INSERT

  • KP0 to KP9

  • KPADD

  • KPDIVIDE

  • KPDOT

  • KPMULTIPLY

  • KPSUBSTRACT

  • NUMLOCK

  • PAGEDOWN

  • PAGEUP

The following application server keystrokes are supported for VT420 applications:

  • CURSOR_DOWN

  • CURSOR_LEFT

  • CURSOR_RIGHT

  • CURSOR_UP

  • F1 to F20

  • FIND

  • INSERT

  • KP0 to KP9

  • KPCOMMA

  • KPDOT

  • KPENTER

  • KPMINUS

  • NEXT

  • PF1 to PF4

  • PREV

  • REMOVE

  • SELECT

The following application server keystrokes are supported for Wyse 60 applications:

  • CLRLINE

  • CLRSCR

  • CURSOR_DOWN

  • CURSOR_LEFT

  • CURSOR_RIGHT

  • CURSOR_UP

  • DELCHAR

  • DELETE

  • DELLINE

  • F1 to F16

  • HOME

  • INSCHAR

  • INSERT

  • INSLINE

  • KP0 to KP9

  • KPCOMMA

  • KPDELETE

  • KPENTER

  • KPMINUS

  • NEXT

  • PREV

  • PRINT

  • REPLACE

  • SEND

  • SHIFTHOME

Terminal Emulator Attribute Maps

Terminal emulator attribute maps enable you to change how character attributes such as bold or underline are displayed in the SGD terminal emulators. For example, you can specify that text that normally appears bold and underlined appears red in the SGD terminal emulators, but not red and bold and underlined.

SGD provides a default attribute map /opt/tarantella/etc/data/attrmap.txt. This maps character attributes to the logical color Color_15 (white). You can also create your own attribute map.

procedure icon  How to Create Your Own Attribute Map

  1. As superuser (root), create a copy of /opt/tarantella/etc/data/attrmap.txt to work on.

  2. Edit the new file, so that character attributes map to your chosen colors.

  3. Use the name of the file for the application object’s Attribute Map attribute.

Editing Character Attributes

The SGD attribute maps enable you to map the following attributes:

  • Normal

  • Bold

  • Dim

  • Blinking

  • Underline

  • Inverse

To map combinations of attributes, separate the attributes with the plus sign +, for example, Bold+Underline.

To display colors in the terminal emulators, SGD maps logical colors to RGB values. For example, the logical color Color_9 maps to the RGB value 128 0 0 (red).

When mapping attributes to colors in your attribute map, specify the logical color name. For example:

  • To change bold underlined text to red text:

    Bold+Underline=Color_9

  • To change inverse blinking text to light red text:

    Inverse+Blinking=Color_1

For a complete list of logical color to RGB value mappings, refer to the comments in attrmap.txt.

You can change the default color mappings by editing the color map used by the terminal emulators. See Terminal Emulator Color Maps.



Note - Wyse 60 terminals display only black and white colors. However, you can use the SGD Wyse 60 terminal emulator to display colors in your Wyse 60 applications. You can do this by using the attribute map to map character attributes in the Wyse 60 application to colors.



Terminal Emulator Color Maps

SCO Console (ANSI) and VT420 terminals support 16 colors. The SGD terminal emulator uses a color map to determine how these colors are presented in an application session.



Note - Wyse 60 terminals are monochrome. You can only switch the background and foreground colors, black and white, using the color map. However, you can map character attributes such as bold or underline to any of the 16 logical colors supported by the terminal emulator. See Terminal Emulator Attribute Maps.



The color map maps the logical colors Color_0 through to Color_15, inclusive, to colors and the RGB values that SGD uses to represent those colors. The default mappings are as follows:


Logical Color Terminal Color RGB Value Used by SGD
Color_0 Black 0 0 0
Color_1 Light red 255 0 0
Color_2 Light green 0 255 0
Color_3 Yellow 255 255 0
Color_4 Light blue 0 0 255
Color_5 Light magenta 255 0 255
Color_6 Light cyan 0 255 255
Color_7 High white 255 255 255
Color_8 Gray 128 128 128
Color_9 Red 128 0 0
Color_10 Green 0 128 0
Color_11 Brown 128 128 0
Color_12 Blue 0 0 128
Color_13 Magenta 128 0 128
Color_14 Cyan 0 128 128
Color_15 White 192 192 192

To alter the defaults for a particular application, create your own color map, and specify it in the application object’s Color Map attribute.

A default text-format color map /opt/tarantella/etc/data/colormap.txt is provided.

Examples of Using Color Maps

  • To make the color red brighter, change the RGB setting of Color_9 to 192 0 0.

  • To change items that appear in light green to appear yellow, change the RGB setting of Color_2 to 255 255 0, the RGB value of yellow.

  • One common color change is to switch the foreground and background colors between black and white. When you do this, you are not changing the foreground or background color as such, you are changing the way black (Color_0) and white (Color_15) are displayed. Therefore, if your application has a white background and you want to change it to a black background, change the value of Color_15 to 0 0 0, the RGB value of black.


Tips on Configuring Applications

This section contains tips on configuring applications and documents for use with SGD. This section includes the following topics:

Starting an Application or Desktop Session Without Displaying a Webtop

With SGD, you can start a single application or a full-screen desktop session without displaying the webtop. You can do this in any of the following ways:



Note - If an application is not assigned to a user they cannot start the application. This applies whether the application is assigned directly to the user, or indirectly, for example, by inheritance.



Using My Desktop

My Desktop enables users to log in and display a full-screen desktop without displaying a webtop.

To be able to use My Desktop, the user must be assigned an application object called My Desktop (cn=My Desktop). This object is created automatically when SGD is installed. By default, the object is configured to run the default desktop application available on the SGD server, for example, Sun Javatrademark Desktop System (Java Desktop System). You can reconfigure this object to run any application you want, but it works best with full-screen desktop applications. If users require different desktop applications, you can create additional My Desktop objects as required. However, users must be assigned only one My Desktop application.

Users access My Desktop at http://server.example.com/sgd/mydesktop, where server.example.com is the name of an SGD server. This Uniform Resource Locator (URL) displays the SGD Login page. Once the user has logged in, the desktop session is displayed. If the user has paused print jobs, the user sees a message in the browser window which enables them to resume printing. After the user has logged in, the browser window can be closed.

Alternatively, users can click the My Desktop link on the SGD web server Welcome Page, at http://server.example.com.



Note - Users can be assigned any number of applications, but the My Desktop URL only gives users access to the My Desktop application.



Using the SGD Client in Integrated Mode

You can use the SGD Client in Integrated mode to run applications or a full-screen desktop without displaying a webtop. Once a user has performed an initial log in, displayed a webtop, and configured Integrated mode, the applications they can run display in the desktop Start or Launch menu. The user then does not have to display a webtop when starting applications or full-screen desktop sessions. See Integrated Mode for more details.

Using SGD Web Services

You can use SGD web services to develop your own application launcher, to start a single application from a URL. You can use this method to start an application from a bookmark or a favorite. SGD provides an example application that shows what is possible using SGD web services.

The URL for using the SGD example application is:

http://server.example.com/sgd/launcher.jsp?o=application&u=username&p=password&e=true|false

where server.example.com is the name of an SGD server.

The URL has the following parameters:


Parameter Description
o=application The name of the application object. This does not have to be a fully-qualified name.
u=username The user name to use to log in to SGD.
p=password The password to use to log in to SGD.
e=true|false true means display an edit page where users can override some of the application attributes. false means do not display edit page.



Note - All of the parameters are optional.



For example, the following URL starts the Write-o-Win application using the configuration for the application object defined in the Administration Console.

http://server.example.com/sgd/launcher.jsp?o=Write-o-Win&u=indigo&p=purple&e=false

Using Multihead Or Dual Head Monitors

You can use multihead or dual head monitors with SGD. However, if any of your applications are configured with a Window Type (--displayusing) setting of Client Window Management, you might have to change the application and monitor configuration to be able to use multiple monitors.

See also Configuring X Application Objects.

To configure multiple monitors to work with applications that have a Window Type setting of Client Window Management, perform the following configuration steps:

  1. Disable shared resources.

  2. Configure the correct desktop size.

  3. Set up the monitors.

Disabling Shared Resources

SGD enables similar applications to share resources, to reduce memory overhead. This feature must be disabled for any applications that you want to display using multiple monitors.

In the Administration Console, go to the Performance tab for the application that is displayed on multiple monitors and deselect the Share Resources Between Similar Sessions check box.

Alternatively, use the following command:


$ tarantella object edit --name obj --share false

Repeat the configuration for each application that is displayed on multiple monitors.

Configuring the Correct Desktop Size

You must ensure that the SGD server sends the client enough space to display all the monitors on the desktop.



Note - This increases the amount of memory used on the client device and on the SGD server.



You must configure your SGD servers so that they send the size of the entire desktop area to the client device, and not just the size of the primary monitor. The size of the entire desktop area is shown by the “virtual screen” in the following diagram.

Virtual Screen Size for Multihead Monitors

For example, if the dimensions of Monitor 1 in the diagram are 1200 x 768 and the dimension of Monitor 2 are 800 x 600, then the desktop size that needs to be configured is 2000 x 768.

In the Administration Console, go to the Protocol Engines -> X tab for the SGD server. For Client Window Size, type the dimensions in pixels of the virtual screen in the Maximum Height and Maximum Width fields.

Alternatively, use the following command:


$ tarantella config edit --array \
--xpe-cwm-maxwidth pixels --xpe-cwm-maxheight pixels

Repeat this configuration for each SGD server in the array.

Setting Up the Monitors

Set up the monitors so that all the secondary monitors are to the right of the primary monitor, as shown in the previous diagram.

You have to do this because the X server cannot handle negative screen coordinates.

Improving the Performance of Windows Desktop Sessions

When using Windows Terminal Services, the performance of Windows desktop sessions might be poor. This is caused by using animation effects and other desktop settings in the Windows session. Performance is affected because these features require more screen updates and can greatly increase the bandwidth used. The problem is more severe on slower connections.

The causes of these problems can include the following:

By default, the SGD Terminal Services Client, ttatsc, enables these features.

You can turn off these features by configuring one or more -perf disable option command arguments in the Arguments for Protocol attribute (--protoargs) for the Windows application object. The option can be one of the following.


Option Description
wallpaper Disables the desktop wallpaper. Disabling the wallpaper can reduce the amount of data that is updated when users move items around the desktop.
fullwindowdrag Disables the option to show the contents of a window while it is moved.
menuanimations Disables transition effects for menus and tooltips.
theming Disables desktop themes.
cursorshadow Disables the shadow on the mouse pointer.
cursorsettings Disables mouse pointer schemes and customizations.

See also The SGD Terminal Services Client.

Improving the Performance of Java Desktop System Desktop Sessions or Applications

This section includes some tips on how to get the best user experience when using SGD with Java Desktop System.

You can improve performance of Java Desktop System desktop sessions and applications in the following ways:

Configuring the X Application Object for Java Desktop System

For a Java Desktop System desktop session or application, ensure that you specify the correct command path for the X application object. Set the Application Command (--app) attribute to /usr/dt/config/Xsession.jds. Using a path of /usr/bin/gnome‐session results in some Java Desktop System configuration parameters being lost and gives a poorer user experience.

To improve the display of animated effects, you can configure performance settings for the X application object. See An Application’s Animation Appears ‘Jumpy’.

Disabling Default Java Desktop System Settings

The performance of Java Desktop System desktop sessions and applications can be affected by animation effects and other default desktop settings. Performance is affected because these features require more screen updates and can greatly increase the bandwidth used. The problem is more severe on slower connections.

Performance can often be improved by turning off, or modifying, some of the following Java Desktop System desktop features:

  • Anti-aliased fonts

  • Large fonts

  • Login screen, splash screen, About screen, and Logout screen

  • Animations

  • Desktop applets

  • Showing window contents when dragging

  • Desktop wallpaper

  • Themes

Documents and Web Applications

A document object can refer to any URL. This can be any document on the web, including StarOfficetrademark software documents, or Adobetrademark Acrobat files. A document can also refer to a web application.

As it is the user’s client device that actually fetches the URL, firewalls, or other security measures can prevent a user from accessing a document.

You can use SGD to access web applications. A web application is simply a web page, or any URL, that requires the user to supply a user name and password for access. To give users access to a web application, you create a document object that links to the URL of the web application.

Unlike passwords for application servers, SGD cannot cache the user names and passwords for accessing web applications. However, you can configure web server authentication, so that users can access SGD from a web application without having to log in again. See Web Server Authentication for details. Alternatively, you can authenticate SGD users to the web application.

When accessing web applications, use a secure (HTTPS) web server, so that all communication is encrypted using SSL before transmission.

Creating a Virtual Classroom

This section describes how to configure application objects for use in a virtual classroom.

You can use SGD shadowing to create a virtual classroom, where the pupils in the classroom shadow an application being demonstrated by a teacher.

To be able to do this, you have to create a teacher’s application object and a classroom application object.

The teacher must start their application first, then the pupils start their classroom application to shadow the teacher. The classroom can only shadow Windows applications or X applications.

Only one person can use the teacher’s application at any one time. If more than one person starts the teacher’s application, the classroom shadows the application that was started last. For this reason, only give the teacher’s application to one user. If you have several teachers, create separate application objects for each of them.

The classroom application must have a color depth of at least 16-bit. The display size of the classroom application must be at least the size of the teacher’s application. For the best results, use an independent window for the classroom.

When the teacher starts their application, information is stored on the SGD server about which application can be shadowed by the classroom. This information is not copied to the other members of the array. This means that if the classroom application is started on a different SGD server to the teacher’s application, the classroom application fails because the information about which application can be shadowed is not available. You can use load balancing groups to guarantee that the teacher and classroom applications are started on the same SGD server. You must set the load balancing group for the application server and the SGD server. Otherwise, only use classroom shadowing in an SGD array containing a single SGD server.

See also Using Shadowing to Troubleshoot a User’s Problem.

procedure icon  How to Create the Teacher’s Application Object

  1. In the Administration Console, create a new Windows application object or X application object.

  2. Go to the Launch tab and type one of the following in the Login Script field:

    • unixclass.exp – If the application is an X application

    • winclass.exp – If the application is a Windows application

  3. Click Save.

  4. Configure any other settings you want for the teacher’s application.

  5. Click the Hosting Application Servers tab and select the application servers that can run the application.

  6. On the Assigned User Profiles tab, assign the teacher’s user profile to the application.

procedure icon  How to Create the Classroom Application

  1. In the Administration Console, create a new X application object.



    Note - The classroom application is an X application, even if the teacher’s application is a Windows application.



    The General tab is displayed.

  2. Go to the Launch tab and configure the application as follows:

    1. In the Application Command field, type /opt/tarantella/bin/bin/ttashadow.

    2. In the Arguments For Command field, type -readonly -silent -pointer $SHADOWDISPLAY.

    3. In the Login Script field, type pupil.exp.

    4. In the Environment Variables field, type MYCLASS="name_of_teacher’s_application", for example, MYCLASS=".../_ens/o=applications/ou=Finance/cn=XClaim"

  3. Click Save.

  4. Go to the Presentation tab.

  5. For Color Depth, select 16-bit - thousands of colors and click Save.

  6. Configure any other settings you want for the classroom application.

  7. Go to the Hosting Application Servers tab and select the application servers that can run the application.

    The ttashadow application is only available on servers where SGD is installed.

  8. Go to the Assigned User Profiles tab, assign the user profiles of all users in the class to the classroom application.

Configuring Common Desktop Environment Applications

The configuration required for Common Desktop Environment (CDE) applications depends on whether you want to run a desktop session or an individual application.

For CDE desktop sessions configured with a Connection Method of ssh, problems can occur when a user tries to exit from the CDE session. The CDE session might hang, making it impossible to log out normally from the system. See Using CDE and SSH.

Configuring a CDE Desktop Session

To run a CDE desktop session through SGD, create an X application object with the settings shown in the following table.


Attribute Setting
Application Command The full path to the Xsession application, for example, /usr/dt/bin/Xsession.

On the command line, use --app pathname.

Keep Launch Connection Open Select the Enabled check box.

On the command line, use --keepopen true.

Session Termination Select Login Script Exit from the list.

On the command line, use --endswhen loginscript.

Window Type Select Kiosk from the list.

On the command line, use --displayusing kiosk

Window Size Select the Scale to Fit Window check box.

Use this setting only if users suspend and resume the application on displays of different sizes.

On the command line, use --scalable true


Configuring a CDE Application

To run a CDE application directly, rather than from the CDE Front Panel, create an X application object with the settings shown in the following table.


Attribute Setting
Application Command The full path to the application you want to run.

On the command line, use --app pathname.

Keep Launch Connection Open Deselect the Enabled check box.

On the command line, use --keepopen false.

Note - This is the default value for this attribute.

Session Termination Select No Visible Windows from the list.

On the command line, use --endswhen nowindows.

Note - This is the default value for this attribute.

Window Type Select Client Window Management from the list.

On the command line, use --displayusing clientwm

Window Manager Type the following in the field:

/usr/dt/bin/dtwm -xrm "Dtwm*useFrontPanel: false" -xrm "Dtwm*ws0*backdrop*image: none"

On the command line, use --winmgr '/usr/dt/bin/dtwm -xrm "Dtwm*useFrontPanel: false" -xrm "Dtwm*ws0*backdrop*image: none"'


Using CDE and SSH

For CDE desktop sessions configured with a Connection Method of ssh, problems can occur when a CDE desktop user tries to exit from the CDE session. The CDE session might hang, making a proper logout from the system impossible.

The CDE session displays a TT_ERR_NO_MATCH error message.

The workaround for this issue is as follows:

  • Log in to the CDE host as superuser (root) and type the following commands:


    # mkdir /etc/dt
    # mkdir /etc/dt/config
    # cp /usr/dt/config/sessionetc /etc/dt/config
    # cp /usr/dt/config/sessionexit /etc/dt/config
    # cp /usr/dt/config/sys.dtprofile /etc/dt/config
    # chgrp bin /etc/dt/config
    # chmod 555 /etc/dt/config/*
    # chown bin:bin /etc/dt/config/*
    

  • Add the following lines to the /etc/dt/config/sessionetc file:


    if [ "$SSH_TTY" != "" ]
    then
    SSHPTTY=‘echo $SSH_TTY | cut -c6-15‘
    ps -ef | grep -v grep | grep $SSHPTTY | grep Xsession | awk ’{print $3}’ >
    /var/dt/tmp/$DTUSERSESSION/sshd_pid
    fi
    

  • Add the following lines to the /etc/dt/config/sessionexit file:


    if [ -f /var/dt/tmp/$DTUSERSESSION/sshd_pid ]
    then
    /bin/kill -HUP ‘/bin/cat /var/dt/tmp/$DTUSERSESSION/sshd_pid‘
    /bin/rm /var/dt/tmp/$DTUSERSESSION/sshd_pid
    fi
    

  • Add the following line to the /etc/dt/config/sys.dtprofile file:


    dtstart_session[0]="/usr/local/bin/ssh-agent /usr/dt/bin/dtsession"
    

Configuring VMS Applications

You can use SGD to access X applications and character applications on a VMS application server.

To configure SGD to access applications on a VMS server, you have to perform the following configuration steps:

  1. Configure the login script used for the application.

  2. Configure the transport variable in the login script.

  3. Disable X security.

Configuring the Login Script Used for the Application

The login script used for the X application or character application must be configured.

In the Administration Console, go to the Applications -> Launch tab for the application object you want to configure. In the Login Script box, type one of the following:

  • vms.exp – If telnet or ssh is selected as the Connection Method

  • vmsrexec.exp – If rexec is selected as the Connection Method

Alternatively, use the following command:


$ tarantella object edit --name obj --login vms.exp | vmsrexec.exp

Configuring the Transport Variable in the Login Script

By default, the vms.exp or vmsrexec.exp login scripts set the transport variable to TCPIP. This setting is correct for Digital Transmission Control Protocol/Internet Protocol (TCP/IP) stacks, including Ultrix Communications Extensions (UCX).

If you need to change this variable, edit the transport variable setting in the login script. The transport variable is set by the following entry in the login script:


set transport "TCPIP"

The login scripts are located in the /opt/tarantella/var/serverresources/expect directory.

Disabling X Security

To use VMS X applications, you must disable X security in SGD. This is because VMS does not support X authorization.

In the Administration Console, go to the Global Settings -> Security tab and deselect the X Authorization for X Display check box.

Alternatively, use the following command:


$ tarantella config edit --security-xsecurity 0

3270 and 5250 Applications

SGD uses the third-party emulator application, TeemTalk for Unix, for 3270 and 5250 applications. See the TeemTalk for Unix User’s Guides supplied with SGD for details.

The first time a user runs the 3270 or 5250 emulator, the tta3270.nv configuration file is created in the user’s home directory on the SGD server.


Troubleshooting Applications

This section describes some typical problems that users might have with their applications, and how to fix them.

Using Shadowing to Troubleshoot a User’s Problem describes how an SGD Administrator and a user can see and use an application simultaneously.

The following troubleshooting topics are covered:

To troubleshoot problems with authentication when starting an application, see Troubleshooting Application Authentication.

Using Shadowing to Troubleshoot a User’s Problem

If a user is having difficulty with an application, you can use the Administration Console to find the user’s application session and then shadow it. Shadowing enables the user and an SGD Administrator to see and use the application simultaneously.

To find a user’s application session, go to the Application Sessions tab for their user profile object. Alternatively, go to the Application Sessions tab for the application object. This lists the users who are currently running the application.

Select the application session in the Application Sessions List table. Click the Shadow button to commence shadowing.

The user sees a dialog box, asking whether to allow you to shadow the session. If the user agrees, a new window appears on your screen, showing the running application. Both you and the user can control the mouse pointer and use the application.

When you have fixed the user’s problem, close the shadowing window, but do not close the application. The user sees a dialog box, saying that nobody is currently shadowing the session.

The Application Sessions tab shows other application session information, such as the date and time the session started, and whether the session is suspended or currently active.

You can only shadow Windows applications and X applications. The application must not be suspended.

If the user has application sessions for two or more applications that are using shared resources, all applications that are sharing resources are displayed when you shadow the session. The button bar on the shadowing window enables you to toggle between the applications.

You can also shadow a user’s session from the command line, using the tarantella emulatorsession shadow command.

If you are shadowing over a low bandwidth connection and have display update problems, see Display Update Issues When Shadowing Over a Low Bandwidth Connection for details of how to fix this.

An Application Does Not Start

If an application does not start when a user clicks a link, first check the configuration of the application object, see Checking the Configuration of the Application Object.

If this does not resolve the problem, check the launch details or the log files for a launch error message, see Checking the Launch Details and Error Logs.

If users cannot log in to SGD or start applications, do a warm restart of the SGD servers by running the following command:


# tarantella restart sgd --warm

Checking the Configuration of the Application Object

Check the configuration of the application object in the Administration Console.

First, check the Hosting Application Servers tab for the application object. You must specify at least one application server to run the application. Check that the listed application servers are available.

Next, check the Launch tab for the application object. Check the attributes shown in the following table.


Attribute What to Check
Application Command Does the command contain the full path name of the application’s executable?

For Windows application objects, does the command also include the correct filename extension?

Does the path name point to a Windows shortcut? If so, change it to the full path name of the application itself.

Is the application installed in the same location on every application server listed in the Hosting Application Servers tab?

Arguments for Command Are the command arguments correct?
Connection Method For X and Character application objects, is the selected Connection Method appropriate for the type of application server?
Windows Protocol For Windows application objects, is the correct Windows Protocol used for the type of application server?
Login Script Is a login script set?

Is the login script appropriate for the application type?

Environment Variables Are all the environment variables required for the application set correctly?

If the application object is configured correctly, check that the application itself actually runs on all the application servers.

Checking the Launch Details and Error Logs

When an application fails to start, SGD displays an error message in the details area of the Connection Progress dialog. The error message is output to the SGD Client log file (tcc.txt) in the user’s home directory.

The error messages are also output to the following log files:

  • /opt/tarantella/var/log/execpePID_error.log

    This file contains log output from the Execution Protocol Engine process.

  • /opt/tarantella/var/log/launchhelperPID_error.log

    This file contains additional log output if the connection method for the application object is SSH.

The error messages have the following form:

ErrorMessage
Script process-id exited with code error-code and signal signal

The ErrorMessage and error-code can be used to troubleshoot problems. The following are the most common error messages:

For a complete list of error messages and codes and troubleshooting information, see Login Script Error Messages.

If the launch details or log files show error messages such as “Failed to find xauth“ or “Attempt to run xauth failed”, see Applications Fail To Start When X Authorization Is Enabled.

Increasing the Log Output

If you are still unable to resolve the problem, you can increase the amount of information that is output to the log files. To do this, you amend the log filters for the Execution Protocol Engine, and, for X and character applications only, enable debugging in the login script.

To amend the log filter for the Execution Protocol Engine, use the following command:


$ tarantella config edit \
  --tarantella-config-execpeconfig-logfilter \
  "execpe/*/*" "pem/*/*" "launchhelper/*/*"

To enable debugging in the login scripts, edit the following files:

  • The login script configured for the application object.

    Remove the comment mark (#) from the start of the startdebug line.

    The login script is usually either unix.exp, securid.exp, vms.exp, unixclass.exp, or pupil.exp.

  • procs.exp

    Insert a comment mark (#) at the start of the stopdebug line.

When you have resolved the problem, remember to reset the log filter for the Execution Protocol Engine back to the default, and disable logging in the login scripts. Use the following command to reset the log filter:


$ tarantella config edit \
  --tarantella-config-execpeconfig-logfilter \
  "execpe/*/*error" "pem/*/*error" "launchhelper/*/*error"

Troubleshooting ErrApplicationServerTimeout Errors

If starting an application results in an ErrApplicationServerTimeout error, this usually means a login script has timed out before it can log the user in.

You can fix this by increasing the login script timeouts. See Login Script Timeouts for details of the available timeouts.

When changing the timeouts, increase the Expect timeouts first. If the application still fails to start, one of the client timers might be too short. If the application is particularly slow to start, increase all the client timers.

Increasing the login script timeouts slows down application start times. Only change the timeouts if you are experiencing problems, and tune the timeouts to the capabilities of the application server.



Note - None of the timeouts, apart from the Execution Protocol Engine timeout, apply when running a Microsoft Windows application that is configured to use the Microsoft RDP protocol.



Troubleshooting ErrApplicationServerLoginFailed Errors

If starting an application results in an ErrApplicationServerLoginFailed error, the login script failed to log into the application server.

Check that you can log into the application server manually.

If you can log in, check that the application server’s system prompt is recognized by the login script. Unusual system prompts are a common reason for this failure, and can be caused by the following:

  • System prompts in a language other than English

  • Message-of-the-day (/etc/motd) or issue messages (/etc/issue)

  • The user’s login profile is configured to run a menu

By default, SGD supports English system prompts on application servers. Administrators can add support for system prompts in other languages. See Supporting Users in Different Locales for details.

If you are using the standard SGD login scripts, check the system prompts defined in the vars.exp login script.

If a message-of-the-day or a menu causes a login script to fail, you must configure the login script to handle this situation. Alternatively, contact Technical Support for help.

The login script might also be timing out. If you see “echo SYNC” in the launch details or log files, and the system prompt ends in the normal way with $, %, #, or >, try increasing the timeouts(prelogin) value in the vars.exp login script. See Expect Timeouts for details.

An Application Exits Immediately After Starting

Users might see this problem with Windows applications or X applications. The solution is to keep open the network connection used to start the application.

In the Administration Console, select the Keep Launch Connection Open check box on the Launch tab for the application object.

Alternatively, use the following command:


$ tarantella object edit --name obj --keepopen true

Applications Disappear After About Two Minutes

If users find that their applications disappear unexpectedly after about two minutes, a proxy server might be timing out the connections. Proxy servers drop a connection after a short period of time if there is no activity on the connection.

SGD sends keepalive packets to keep the connection open and by default this is every 100 seconds. If applications are disappearing, you can increase the frequency at which keepalive packets are sent to keep the connection open.

In Administration Console, go to the Global Settings -> Communication tab for the application object and set the AIP Keepalive Frequency to a smaller value than the default, for example, 60.

Alternatively, use the following command:


$ tarantella config edit --sessions-aipkeepalive secs

An Application Session Does Not End When the User Exits an Application

In the Administration Console, go to the Launch tab for the application object and check the value of the Session Termination attribute. If No Visible Windows is selected, the application session ends when there are no visible windows.

When running an application on a Microsoft Windows Terminal Server, closing the application does not always result in the session closing. This is because the SGD Enhancement Module for Windows is still running. The solution is to configure the SGD Enhancement Module to ignore certain system processes so that it closes. To do this, edit the System processes value for the HKEY_LOCAL_MACHINE\Software\Tarantella\Enhancement Module for Windows key in the registry on the application server. This value is a string that contains a comma-separated list of .exe binaries that the SGD Enhancement Module can ignore. You must amend this value by listing the processes that were running when the session failed to close. To do this, open Task Manager, while you have a session that has failed to close, and go to the Processes tab. Make a list of all the .exe processes that are running. Do not include the following processes:

If you are running a single application session, you might find that the session still does not exit, even after editing the System processes registry setting. To force the session to exit, amend the Logoff application sessions setting for the HKEY_LOCAL_MACHINE\Software\Tarantella\Enhancement Module for Windows key and change the DWORD value to 1.

Applications Fail To Start When X Authorization Is Enabled

In a default SGD installation, X authorization is enabled. If there are any problems with X authorization, users cannot start applications. If applications fail to start because of X authorization, the message “Failed to find xauth” or “Attempt to run xauth failed” displays in the application launch details and in the log files.

Use the following checklist to establish why X authorization causes application to fail to start. If this does not resolve the issue, check the log files as described in Checking the Launch Details and Error Logs.

Is X authorization installed on the application server?

For SGD to be able to use X authorization, xauth must be installed on every application server.

If xauth is not installed, you must either install it or disable the use of X authorization for every application. To disable X authorization, deselect the X Authorization for X Display check box on the Global Settings -> Security tab in the Administration Console.

Can SGD find the xauth binary?

If the message “Failed to find xauth” displays in the application launch dialog or log files, SGD cannot find the xauth binary. By default, SGD searches the following locations for the xauth binary:

  • /usr/bin/X11/xauth

  • /usr/X/bin/xauth

  • /usr/X11R6/bin/xauth

  • /usr/bin/X/xauth

  • /usr/openwin/bin/xauth

  • /usr/bin/xauth

If the xauth binary is in a different location, you must add its location to the /opt/tarantella/var/serverresources/expect/vars.exp login script. Look for the line beginning “set xauthcmds”.



Note - If the xauth binary is only in one location, you can speed up application launches by removing the other locations from the vars.exp login script.



Does the user have a UNIX system account on the application server?

When the user starts an application, the X Protocol Engine process generates a cookie and stores it in the .Xauthority file in the user’s home directory on the application server. The cookie is used to validate whether or not the user has permission to connect to the X display.

If the user does not have a home directory, the cookie cannot be stored in the user’s .Xauthority file and so the user cannot be validated.

You can do any of the following:

  • Create a home directory for the user on the application server

  • Disable X authorization

    Deselect the X Authorization for X Display check box on the Global Settings -> Security tab in the Administration Console. Alternatively, use the following command:


    $ tarantella config edit --security-xsecurity 0
    

  • Edit configuration files on the application server, so that the cookie is stored in a temporary directory.

    Add the following lines to the /etc/profile file on the application server:


    XAUTHORITY=/tmp/.Xauthority.$LOGNAME
    export XAUTHORITY
    

    Create the following SSH daemon configuration file, /etc/ssh/sshrc, on the application server:


    HOME=/tmp
    XAUTHORITY=$HOME/.Xauthority.$USER
    export XAUTHORITY
     
    if read proto cookie && [ -n "$DISPLAY" ]
    then
           if [ ‘echo $DISPLAY | cut -c1-10‘ = ’localhost:’ ]
           then
                   # X11UseLocalhost=yes
                   echo add unix:‘echo $DISPLAY |
                   cut -c11-‘ $proto $cookie
           else
                   # X11UseLocalhost=no
                   echo add $DISPLAY $proto $cookie
           fi | /usr/openwin/bin/xauth -q -
     fi
    

A Kiosk Application Is Not Appearing Full-Screen

If an application that is configured to display in a kiosk window is resumed on a display that is larger or smaller than the original display, the application no longer fits the screen exactly.

The solution is to ensure that SGD scales the kiosk window to fit the screen.

In the Administration Console, go to the Presentation tab for the application object and set the Window Size to Scale to Fit Window.

Alternatively, use the following command:


$ tarantella object edit --name obj --scalable true

An Application’s Animation Appears ‘Jumpy’

Changing an application object’s performance settings can improve the display of animation effects in the application session.

In the Administration Console, go to the Performance tab for the application object and set the Command Execution attribute to In Order. Deselect the Delayed Updates check box.

Alternatively, use the following command:


 $ tarantella object edit --name obj \
--execution inorder --delayed false

Font Problems with X Applications

If users see font problems with X applications, check the following:

Is the font size wrong?

In the Administration Console, go to the Client Device tab for the X application object and check the value of the Monitor Resolution attribute. Display the Protocol Engines -> X tab for each SGD server in the array and check the value of the Monitor Resolution attribute.

The Monitor Resolution attributes are used to specify the monitor resolution, in dots per inch, that SGD reports to X applications that ask for this information. Some X applications need this value to determine what font size to use.

The default resolution can cause the X application to choose a font size larger than it normally chooses. If this happens, try reducing the resolution by specifying a smaller value, for example, 75.

Are the wrong fonts displayed?

In the Administration Console, go to the Protocol Engines -> X tab for each SGD server in the array and check that the Font Path attribute is correct.

Some X Fonts are supplied with SGD. You can also configure your own X fonts. See How to Configure SGD to Use Your Own X Fonts.

Display Problems With High Color X Applications

Several problems can occur when displaying high color X applications:

The X Application Fails With a Color Planes Error

If an X application fails to run and exits with errors such as “Cannot Allocate Enough Color Planes”, the application probably only displays 8-bit color. Check the display specification of the application and adjust the color depth of the application object.

In the Administration Console, go to the Presentation tab for the application object and set the Color Depth to 8-bit - 256 colors.

Alternatively, use the following command:


$ tarantella object edit --name obj --depth 8

The Colors Appear Strange

If there are any problems with appearance in 16-bit or 24-bit color applications, change the color quality of the application object.

In the Administration Console, go to the Performance tab for the application object and set the Color Quality to 16-bit, for 16-bit applications, or 24-bit, for 24-bit applications.

Alternatively, use the following command:


$ tarantella object edit --name obj --quality 16 | 24

The X Application Uses Too Much Bandwidth

If bandwidth is critical, try reducing the color quality of the application object.

In the Administration Console, go to the Performance tab for the X application object and set the Color Quality to 9-bit, or 6-bit.

Alternatively, use the following command:


$ tarantella object edit --name obj --quality 9 | 6



Note - There is no absolute guarantee of a bandwidth saving when you make this configuration change. Also, the appearance of the application might be affected adversely.



8-bit Applications Exit With a PseudoColor Visual Error

If you run an 8-bit application within a 16-bit or 24-bit high color X application session, for example from a CDE desktop, you might find the application exits with an error such as "Cannot find a matching 8-bit PseudoColor visual".

To fix this, change the color depth of the X application so that it supports multiple color depths.

In the Administration Console, go to the Presentation tab for the X application object and set the Color Depth to 16/8-bit - Thousands of Colors, or 24/8-bit ‐ Millions of Colors.

If the 8-bit application requires the primary color depth to be 8-bit, set the Color Depth to 8/16-bit - Thousands of Colors, or 8/24-bit - Millions of Colors.

Alternatively, use the following command:


$ tarantella object edit --name obj --depth 16/8 | 24/8



Note - There are memory and performance effects of using these settings.



If the application still exits after changing the color depth, a workaround is to create a separate X application object for the application and set the color depth to 8-bit.

Clipped Windows With Client Window Management Applications

If users see clipped windows when using X applications that are configured to use Client Window Management, this means that users have displays with a greater resolution than expected.

The solution is to increase display resolution for the X Protocol Engine.

In the Administration Console, go to the Protocol Engines -> X tab for each SGD server in the array and change the Client Window Size settings. In the Maximum Height and Maximum Width fields, type the highest display resolution you expect to support.



Note - Increasing the Maximum Width and Maximum Height attributes increases the memory requirements for Client Window Management applications on both client devices and SGD servers.



Alternatively, use the following command:


$ tarantella config edit --array \
--xpe-cwm-maxwidth pixels \
--xpe-cwm-maxwidth pixels

Emulating a Sun Keyboard

Some applications accept input from the left-hand keypad on a Sun workstation. To emulate these keys using Shift-Function key strokes on the client device, you must use a custom keymap file.

Log in to SGD as root (superuser) and make a copy of the xuniversal.txt keymap file. This file is located in the /opt/tarantella/etc/data/keymaps directory on the SGD server. Rename the file to xsunkey.txt.

Edit the Function key definitions in the xsunkey.txt file, as follows:


112  F1 Cancel NoSymbol NoSymbol 0x3b
113  F2 Redo NoSymbol NoSymbol 0x3c
114  F3 0x1005ff70 NoSymbol NoSymbol 0x3d
115  F4 Undo NoSymbol NoSymbol 0x3e
116  F5 0x1005ff71 NoSymbol NoSymbol 0x3f
117  F6 0x1005ff72 NoSymbol NoSymbol 0x40
118  F7 0x1005ff73 NoSymbol NoSymbol 0x41
119  F8 0x1005ff74 NoSymbol NoSymbol 0x42
120  F9 Find NoSymbol NoSymbol 0x43
121  F10 0x1005ff75 NoSymbol NoSymbol 0x44
122  F11 Help NoSymbol NoSymbol 0x57

This maps the client device Function keys to Sun workstation keys, as shown in the following table.


Function Key Sun Workstation Key
Shift-F1 Stop
Shift-F2 Again
Shift-F3 Props
Shift-F4 Undo
Shift-F5 Front
Shift-F6 Copy
Shift-F7 Open
Shift-F8 Paste
Shift-F9 Find
Shift-F10 Cut
Shift-F11 Help

On the application server that runs the application, add the following line to the /usr/dt/lib/bindings/xmbind.alias file:


"Sun Microsystems, Inc."           sun

In the Administration Console, go to the Client Device tab for the user profile object. Select the Custom Value option for the Keyboard Map attribute and type xsunkey.txt in the field.

Alternatively, use the following command:


$ tarantella object edit --name obj --keymap xsunkey.txt



Note - The new keyboard map is used for all graphical applications for the specified user.



In Some X Applications, the Alt and AltGraph Keys Do Not Work

The X keyboard maps used by SGD include support for the Meta key on a Sun keyboard, as follows:


199  Meta_L NoSymbol NoSymbol NoSymbol
200  Meta_R NoSymbol NoSymbol NoSymbol

Some X applications choose to use the Meta key in preference to the Alt or AltGraph keys when both keys are made available in the X keyboard map.

Edit the keyboard map file used with the application. Replace the Meta key definitions, as follows:


199  NoSymbol NoSymbol NoSymbol NoSymbol
200  NoSymbol NoSymbol NoSymbol NoSymbol

Display Update Issues When Shadowing Over a Low Bandwidth Connection

Display update issues might be seen when shadowing a user who has a low bandwidth connection to SGD.

The solution is to increase the X Protocol Engine queue length and optimize command execution, as follows: