4.9. Troubleshooting Applications

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

To troubleshoot problems with starting and ending applications, see the following:

To troubleshoot problems with using applications, see the following:

To troubleshoot problems with brokers used for dynamic launch, see the following:

4.9.1. 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 Section 4.9.1.1, “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 Section 4.9.1.2, “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

4.9.1.1. 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?

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.

4.9.1.2. 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 Section E.5, “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 Section 4.9.3, “Applications Fail To Start When X Authorization Is Enabled”.

4.9.1.2.1. 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"

4.9.1.3. 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 Section E.4, “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.

4.9.1.4. 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 Section 4.7.5, “Adding Support for System Prompts in Different Languages” 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 Section E.4.1, “Expect Timeouts” for details.

4.9.2. An Application Exits Immediately After Starting

Users might see this problem with 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

4.9.3. 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 Section 4.9.1.2, “Checking the Launch Details and Error Logs”.

Questions

  • 4.9.3.1: Is X authorization installed on the application server?

  • 4.9.3.2: Can SGD find the xauth binary?

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

Questions and Answers

4.9.3.1: 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.

4.9.3.2: 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.

4.9.3.3: 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

4.9.4. 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
Note

You must restart every SGD server in the array for changes to this attribute to take effect.

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

If an application does not end when a user closes down the application, first check the configuration of the application object, see Section 4.9.5.1, “Checking the Session Termination Setting”.

To troubleshoot problems with OpenOffice applications, see Section 4.9.5.2, “OpenOffice Applications Do Not Close Down”.

To troubleshoot problems with Windows applications, see Section 4.9.5.3, “Windows Applications Do Not Close Down”.

To troubleshoot problems with UNIX desktop sessions, see Section 4.9.5.4, “UNIX Desktop Sessions Do Not Close Down After Logging Out”.

4.9.5.1. Checking the Session Termination Setting

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.

4.9.5.2. OpenOffice Applications Do Not Close Down

When you close down an OpenOffice application, the application session might not close down. This is because OpenOffice uses a single process that is forked when other OpenOffice components are started.

In the Administration Console, go to the Launch tab for the application object and set the Session Termination attribute to Last Client Exits. Select the Keep Launch Connection Open check box.

4.9.5.3. Windows Applications Do Not Close Down

When running an application on a Microsoft Windows Remote Desktop Session Host, 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\Sun Microsystems, Inc.\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:

  • clipsrv.exe

  • conime.exe

  • csrss.exe

  • EventLog.exe

  • lmsvcs.exe

  • lsass.exe

  • MsgSvc.exe

  • nddeagnt.exe

  • netdde.exe

  • NETSTRS.EXE

  • os2srv.exe

  • proquota.exe

  • rdpclip.exe

  • screg.exe

  • smss.exe

  • spoolss.exe

  • ttaswm.exe

  • userinit.exe

  • wfshell.exe

  • win.com

  • winlogon.exe

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\Sun Microsystems, Inc.\Enhancement Module for Windows key and change the DWORD value to 1.

4.9.5.4. UNIX Desktop Sessions Do Not Close Down After Logging Out

X applications configured as a full-screen desktop session might not close down when you log out from the application using the desktop Start menu. For example, desktop applets can remain open after logging out from the application. The application then has to be closed down using the pull-down header in the application window.

The workaround is to modify the Application Command (--app) attribute for the X application object, so that the TTA_SESSION_STATE property is removed from the root window when the application is closed down.

The following example shows how to modify the Application Command for a Java Desktop System desktop session.

  • Create a simple shell script as follows:

    #! /bin/sh
    /usr/dt/config/Xsession.jds
    /usr/openwin/bin/xprop -root -remove TTA_SESSION_STATE
  • Save the script to a location on the SGD server, for example /usr/local/bin/launch.sh.

  • In the Administration Console, go to the Launch tab for the X application object and edit the Application Command field to use the path to the script.

    Alternatively, use the following command:

    $ tarantella object edit --name objname --app "/usr/local/bin/launch.sh"
    

4.9.6. Users Can Start Applications With Different User Names and Passwords

By default, users can force SGD to display the Application Authentication dialog by holding down the Shift key when they click an application's link on the webtop. This enables users to start applications with different user name and passwords.

You can disable the Shift-click behavior. In the Administration Console, go to the Global Settings → Application Authentication tab and deselect the On Shift-Click check box. Alternatively, use the following command:

$ tarantella config edit --launch-showauthdialog system

Disabling the Shift-click behavior means that the Application Authentication dialog only displays when there is a problem with the password or there is no password.

4.9.7. Using Windows Remote Desktop Services, Users Are Prompted for User Names and Passwords Too Often

If you are using Windows Remote Desktop Services, users might be prompted for a user name and password by SGD or by the Remote Desktop Session Host.

4.9.7.1. SGD Prompts the User

If SGD always prompts the user for a user name and password, the problem is usually caused by a missing domain name. If the user has no entries in the password cache that have a domain name, the Application Authentication dialog is displayed.

To fix this problem, the domain name must be provided when saving details in the password cache. You must do this even if the application server is not part of a domain.

The easiest way to configure the domain name is with the Domain Name attribute on the application server object or the application object. Users can also provide their own domain names in the Application Authentication dialog. See Section 4.7.3.3, “Windows Domains and the Password Cache”.

4.9.7.2. Remote Desktop Session Host Prompts the User

SGD sends user name and password information to Windows Remote Desktop Services to authenticate the user. If the authentication fails, Windows prompts the user again. No information is returned to SGD indicating whether authentication succeeds or fails, and the details remain in the SGD password cache whether correct or incorrect.

The user might have saved the wrong user name, password or domain name in the password cache.

To fix, the user must press Shift when clicking the link to start, the application. This displays the Application Authentication dialog, and the user can correct their user name, password, and domain name. Alternatively, delete the user's entry in the password cache so that SGD prompts the user the next time they start the application.

The Remote Desktop Session Host might also be configured to always prompt for a password when a user logs in. By default, Microsoft Windows Server 2003 and later does not prompt for a password. See Section 4.1.3.1, “Authentication Settings”.

4.9.8. Avoiding Port Conflicts for the X Protocol Engine

Application startup can take longer than expected if SGD attempts to use an X display port that is being used by another service. Application startup eventually completes successfully.

The solution is to exclude the port from use by the X Protocol Engine.

In the Administration Console, go to the Protocol Engines, X tab for each SGD server in the array and type -xport portnum in the Command-Line Arguments field, where portnum is the TCP port number to exclude.

Alternatively, use the following command:

$ tarantella config edit --xpe-args "-xport portnum"

To exclude several ports, you can specify -xport portnum multiple times, as follows:

$ tarantella config edit \
--xpe-args "-xport portnum_1" "-xport portnum_2" "-xport portnum_3"

The changes made take effect for new X Protocol Engines only. Existing X Protocol Engines are not affected.

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

Note

To use shadowing, the SGD Administrator must be a member of the ttaserv group.

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 Section 4.9.18, “Display Update Issues When Shadowing Over a Low Bandwidth Connection” for details of how to fix this.

4.9.10. 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 best solution is to use the RANDR extension to handle session resizing automatically. Alternatively, you can configure the --scalable attribute to ensure that SGD scales the kiosk window to fit the screen.

Do one of the following:

  • In the Administration Console, go to the Presentation tab for the application object and set the Window Size to RandR Extension.

    Alternatively, use the following command:

    $ tarantella object edit --name obj --xrandr true
    
    Note

    The RANDR extension must be enabled for the array. See Section 4.3.2.1, “Enabling the RANDR Extension for an SGD Array”.

  • 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
    

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

4.9.12. Disabling Shared Resources for UNIX Desktop Sessions

SGD enables similar applications to share resources, to reduce memory overhead. However, for UNIX desktop sessions, this might lead to problems when starting and using the application.

For UNIX desktop sessions, such as a Gnome desktop or a Java Desktop System desktop, it is best to disable shared resources for the X application object.

In the Administration Console, go to the Performance tab for the X application object and deselect the Share Resources Between Similar Sessions check box.

Alternatively, use the following command:

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

4.9.13. Apple Keyboard Issues

Users with Mac OS X client devices may experience the following keyboard issues when using SGD applications:

  • The required key is not present on an Apple keyboard

  • Pressing a key on the Apple keyboard does not generate the expected character

  • Pressing a key on the Apple keyboard has no effect

The workarounds for these issues depend on the type of application.

X Applications

By default, SGD attempts to detect the keyboard layout for the client keyboard automatically. However, users can configure an alternative keyboard layout by editing their client profile, as follows:

  • Disable the Try to Match the Client Keyboard Layout setting

  • Select a Keyboard Layout setting appropriate for the client keyboard

Note that alternative keyboard layouts are not available for all client keyboard types.

Windows Applications

Problems can occur because of incompatibilities between the Apple keyboard layout on the client device and the keyboard layout configured on the application server.

For example, a user might be using an Apple UK keyboard to access a Windows application that requires key presses from a Microsoft UK keyboard. The user can experience keyboard issues due to the following keyboard layout differences:

  • The following Apple keys do not exist in the standard Microsoft UK layout:

    • §

    • ±

  • The following Microsoft keys do not exist in the standard Apple UK layout:

    • #

    • ~

    Note

    These missing keys can usually be generated using a key combination. See the Apple documentation for more details.

  • Other alphanumeric and function keys may be in different places on the keyboard, or may not work as expected.

Contact Oracle Support if you need further advice on Apple keyboard issues.

4.9.14. Font Problems with X Applications

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

Questions

Questions and Answers

4.9.14.1: 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.

4.9.14.2: 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 Section 4.2.4, “X Fonts” are supplied with SGD. You can also do the following:

4.9.15. Display Problems With High Color X Applications

Several problems can occur when displaying high color X applications:

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

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

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

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

4.9.16. 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 the 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-maxheight pixels

4.9.17. Input Method Editors and Client Window Management Applications

If you are using an input method editor (IME) in a desktop session configured with a Display Type of Client Window Management and you resume the session on a smaller monitor, you might not then be able to use the IME.

The solution is to enable the RANDR extension for the desktop session. When you switch to a smaller monitor, the IME window is notified automatically of the session resizing.

To enable RANDR for the application object, go to the Presentation tab in the Administration Console and select the Window Size: RandR Extension check box.

Alternatively, use the following command:

$ tarantella object edit --name obj --xrandr 1
Note

RANDR must be enabled globally for the array. See Section 4.3.2.1, “Enabling the RANDR Extension for an SGD Array”.

4.9.18. 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:

  • In the Administration Console, go to the Protocol Engines → X tab for each SGD server in the array and type -mql 8192 in the Command-Line Arguments field.

    Alternatively, use the following command:

    $ tarantella config edit --xpe-args "-mql 8192"

    The changes made take effect for new X Protocol Engines only. Existing X Protocol Engines are not affected.

  • In the Administration Console, go to the Performance tab for the shadowed application and set the Command Execution attribute to Optimized.

    Alternatively, use the following command:

    $ tarantella config edit --name obj --execution optimized
    

    The changes made take effect when you next start the shadowed application.

4.9.19. Troubleshooting Mouse Drag Delay Issues

Mouse drag delay issues can result in a poor user experience when using drawing applications.

The solution is to reduce the mouse drag delay setting for the SGD Client. Add a new <mousethrottledelaywithbutton> entry in the <localsettings> section of the user's client profile. If the <localsettings> section is not present in the client profile, create a new section.

For example, to set the mouse drag delay to 10 milliseconds, type the following:

<localsettings>
 <mousethrottledelaywithbutton>10</mousethrottledelaywithbutton>
  ...
<localsettings>

The default value for mouse drag delay is 100 milliseconds.

Changes to client profiles only take effect for new user sessions.

4.9.20. Incorrect Time Zone Name Shown in Windows Applications

When time zone redirection is enabled on a Windows application server, the time zone name shown in Windows applications can sometimes be incorrect. The issue is seen when displaying Windows applications on UNIX platform client devices.

The solution is to manually set the $TZ time zone environment variable on the client device to the correct value for the user's location. The tzselect command can be used to list the possible time zone values for a geographical location.

See Section 4.1.3.8, “Time Zone Redirection” for more details about using time zone redirection with Windows application servers.

4.9.21. Troubleshooting Problems With CALs

When running Windows applications, users may experience problems with client access licenses (CALs). This section includes some troubleshooting topics to help you to diagnose and fix problems when using CALs.

4.9.21.1. Logging for CALs

When the SGD Client is using a CAL, messages are written to the SGD Client log file. View this log file for messages about the following:

  • License store locations

  • License store access problems

  • Invalid license errors

  • Sun Ray datastore errors

See Section 7.4.7, “SGD Client Logging” for the default SGD Client log file locations.

4.9.21.2. Using a Shared License Location

If the client device is shared by multiple users, CALs should be stored in a shared location to avoid excessive license consumption.

For best results, you should install the SGD Client manually in a system-wide location, as described in Section 6.1.5.2, “System-Wide Installation”. This ensures that CALs are stored in one of the default license locations listed in Table 4.1, “Default Locations for Storing CALs on Client Devices. The default license locations are writeable by all users.

For Linux, Oracle Solaris, and Mac OS X platforms you can override the default license location by using the <calstorepath> entry in the <localsettings> section of the client profile. This is described in Section 4.1.4, “Licensing Microsoft Windows Remote Desktop Services”.

4.9.21.3. Requirements for Sun Ray Clients

In order to obtain a license, the SGD Client must have the required permissions to access the Sun Ray datastore. The following must be true for the SGD Client binary:

  • The file must belong to the Windows Connector group (utwc)

  • The setgid bit for the file must be set

Note

If you install the SGD Client in a system-wide location, the required permissions for the SGD Client are configured automatically. See Section 6.1.5.2, “System-Wide Installation”.

Errors when accessing the Sun Ray datastore are recorded in the SGD Client log file. See Section 4.9.21.1, “Logging for CALs”.

4.9.22. Troubleshooting Broker Problems

This section includes some topics for troubleshooting problems with brokers used for dynamic launch.

4.9.22.1. Application Server List in the Chooser Page is Very Large

Sometimes when starting an application you might see a large number of application servers in the chooser page, making it difficult to select the required application server.

The User-defined SGD broker includes parameters for the Virtual Server Broker Parameters (--vsbparams) attribute that can be used to configure the application server list and to restrict users to specifying only SGD-configured application servers.

In the Administration Console, go to the General tab for the dynamic application server object and configure options for the Virtual Server Broker Parameters field as follows:

  • To hide the application server list in the chooser page.

    hideAppservers

    Note that users can still specify an application server by entering a host name in the text field on the chooser page.

  • To check that a user-specified application server is present in the local repository.

    checkAppserver

    If the user-specified application server is not present in the local repository an error message is shown.

    The checkAppserver parameter can be used to prevent users from specifying application servers which have not been configured in the local repository.

    Note

    When you enable the checkAppserver parameter, users must enter the common name of the application server object in the chooser page.

  • To hide the application server list and check that a user-specified application server is present in the local repository.

    hideAppservers,checkAppserver

4.9.22.2. Changing the Logging Level for the VDI Broker

The VDI broker uses the java.util.logging package. Because the broker runs on a Tomcat JSP container, logging can be configured by editing the following file on an SGD server:

/opt/tarantella/webserver/tomcat/tomcat-version/conf/logging.properties

By default, log output is written to the following file:

/opt/tarantella/webserver/tomcat/tomcat-version/logs/vdibroker.date.log

To change the logging level for the VDI broker, edit the following entries in the logging.properties file:

com.oracle.sgd.vsbim.level=<LOG_LEVEL>
...
1vdibroker.org.apache.juli.FileHandler.level=<LOG_LEVEL>

where <LOG_LEVEL> is the required logging level.

Restart the SGD server after making changes.

# tarantella restart

See the Oracle Java documentation for more details about configuring logging levels.

4.9.22.3. Troubleshooting Problems With Oracle VDI Certificates

The following certificate issues might be seen when you use the VDI broker to integrate with an Oracle VDI installation:

4.9.22.3.1. VDI Certificates Are Not Imported Correctly

If VDI certificates are not imported correctly on the SGD server, connections to the VDI server are refused, and error messages such as the following may be seen.

javax.net.ssl.SSLHandshakeException:
sun.security.validator.ValidatorException: PKIX path building failed:
sun.security.provider.certpath.SunCertPathBuilderException: 
unable to find valid certification path to requested target

Check for the following problems:

  • Certificates have not been imported. By default, VDI web services use a self-signed certificate. To enable the SGD server to trust a self-signed certificate, the certificate must be imported into a truststore on the SGD server.

  • The wrong certificate has been imported. Oracle VDI creates a number of self-signed certificates for its different components. The VDI broker uses the web services certificate.

4.9.22.3.2. VDI Certificates Do Not Use a Fully-Qualified Domain Name

VDI certificates may not use a fully-qualified domain name for the common name (CN) attribute on the certificate. If you configure a VDI host URL for the preferredhosts or failoverhosts parameter that is fully-qualified, the connection may be refused. This is because the common name on the certificate does not match the name of the host that you are trying to connect to.

Error messages such as the following may be seen.

  java.security.cert.CertificateException: No name matching example.uk.oracle.com found
   …
  java.io.IOException: HTTPS hostname wrong: should be <example.uk.oracle.com>

A workaround is to ensure that the host names you enter for preferredhosts and failoverhosts match the common name (CN) on the corresponding web services certificate.

A better solution is to ensure that VDI certificates use fully-qualified domain names, and are signed by a trusted Certificate Authority (CA).