A P P E N D I X  E

Login Scripts

This appendix contains reference information about the Sun Secure Global Desktop (SGD) login scripts. You can use this information to customize the standard SGD login scripts, or to develop your own login scripts.

This appendix includes the following topics:


Login Scripts Supplied With SGD

All login scripts supplied with SGD are stored in the /opt/tarantella/var/serverresources/expect directory.

SGD login scripts are written in Tcl (version 8.4) and Expect (version 5.43). Expect extends Tcl and provides additional commands for interacting with programs.

For more information about Tcl, see the Tcl Developer Exchange.

For more information about Expect, see The Expect Home Page.

The login scripts can be divided into the scripts that can be used when configuring applications and the scripts that contain common code. The available scripts are described in the following sections.

Login Scripts Used When Configuring Applications

You configure the login script that is used for an application as follows:

The following table lists the login scripts supplied with SGD that you can set as the Login Script attribute for an application object, and a description of what they are used for.


Script Name Description
unix.exp The standard login script for character and X applications.

If the Login Script attribute is blank, this script is used by default.

Can be used with all application Connection Methods.

securid.exp Replacement for unix.exp if you are using SecurID for application server authentication.

See Using RSA SecurID for Application Authentication.

windows.exp The standard login script for Windows applications

If the Login Script attribute is blank, this script is used by default.

Calls other login scripts depending on the Windows Protocol attribute.

3270.exp The standard login script for 3270 applications.

If the Login Script attribute is blank, this script is used by default.

Can be used with all application Connection Methods.

The script builds a command to run the TeemTalk for UNIX terminal emulation software.

5250.exp The standard login script for 5250 applications.

If the Login Script attribute is blank, this script is used by default.

Can be used with all application Connection Methods.

The script builds a command to run the TeemTalk for UNIX terminal emulation software.

vms.exp Used for X or character applications running on Virtual Memory System (VMS) application servers.

Can be used for all application Connection Methods except rexec.

See Configuring VMS Applications.

vmsrexec.exp Used for X or character applications running on VMS application servers.

Can only be used if the application Connection Method is rexec.

See Configuring VMS Applications.

unixclass.exp Script used to create a shadowable UNIX session, for use in a virtual classroom situation.

See Creating a Virtual Classroom.

winclass.exp Script used to create a shadowable Windows session, for use in a virtual classroom situation.

See Creating a Virtual Classroom.

pupil.exp Script used by the pupils when shadowing a teacher in a virtual classroom situation.

See Creating a Virtual Classroom.


Login Scripts Containing Common Code

The following table lists the login scripts supplied with SGD that contain common code and a description of what they are used for. These scripts must not be set as the Login Script attribute for an application object.


Script Name Description
runsubscript.exp The standard wrapper login script used to call all the other SGD login scripts.

Sets the environment variables the login scripts are allowed to use.

procs.exp Called by other scripts.

Defines common Tcl procedures.

vars.exp Called by other scripts.

Defines the variables, messages, and timeouts used by the other login scripts.

securid-vars.exp Called by securid.exp.

Defines additional variables and messages needed for SecurID authentication.

xauth.exp Called by procs.exp and classroom.exp.

Used to handle the X authorization process, including the X authorization permissions for shadowing.

classroom.exp Called by unixclass.exp, winclass.exp, and pupil.exp.

Defines common procedures for retrieving the X display to shadow.

unixwin.exp Called by windows.exp for Windows applications configured to use the Citrix Independent Computing Architecture (ICA) Windows Protocol.

This script assumes that the user’s PATH includes the directory where the Merge or ICA UNIX client software is installed.

Although SGD no longer supports the SCO Merge protocol, legacy windows application objects can continue to use it.

wcpwts.exp Called by windows.exp for Windows applications configured to use the Microsoft Remote Desktop Protocol (RDP) Windows protocol.
wincenter.exp Called by windows.exp for Windows applications configured to use the WinCenter or Citrix UNIX Integration Services Windows Protocol.

Although SGD no longer supports the WinCenter and Citrix UNIX Integration Services protocols, legacy Windows application objects can continue to use them.



Login Script Tcl Commands and Procedures

The login scripts supplied with SGD use several Tcl commands and procedures for communication with the application server.

The Tcl commands are commands that are defined in the Execution Protocol Engine component of SGD. The commands can be used in your own login scripts to provide control over the connection to the application server, and the display of the SGD Application Authentication and Progress dialogs.

The Tcl procedures are defined in the login scripts only. The procedures can be used to provide more control over the SGD Application Authentication dialog.

Controlling the SGD Application Authentication Dialog

The following Tcl commands and procedures are used to control the display of the SGD Application Authentication dialog when starting applications:

authrequest


authrequest
 [ -normal | -changed ]
   -showuser 0|1
   -title title
   -message message
   -customuserlabel 0|1
   -userlabel label
   -custompasswdlabel 0|1
   -passwdlabel label
   -showpasscache 0|1
   -showsmartcard 0|1
   -isuserdialog 0|1|2

This Tcl command displays a dialog box that indicates a problem with the user name or password.

Typically you do not call the authrequest command directly in your login scripts. Instead, you use the defined Tcl procedures to call this command with the required arguments.

This command has the following arguments.


Argument Description
-normal Specifies that the password is incorrect.
-changed Specifies that the password has expired.
-showuser Specifies that the user name field is displayed.
-showpasswd Specifies that the password field is displayed.
-title Specifies the title used for the authentication dialog.
-message Specifies the message that is displayed in the authentication dialog.
-customuserlabel Specifies whether to use a customized label for the user name field.
-userlabel Specifies the customized label to use for the user name field.
-custompasswdlabel Specifies whether to use a customized label for the password field.
-passwdlabel Specifies the customized label to use for the password field.
-showpasscache Specifies whether the Save This Password check box is displayed.
-showsmartcard Specifies whether the smart card option is displayed.
-isuserdialog 0|1|2 Specifies whether a customized authentication dialog is used.

Specify one of the following:

  • 0 - Do not check whether the user name has changed

  • 1 - Check whether the user name has changed and reconnect to the application server if necessary

  • 2 - Use the default SGD behavior if the user name has changed


The following example displays a dialog box that says the password is incorrect.


authrequest -normal

authenticate

Displays a dialog box that indicates a problem with the user name or password.

This Tcl procedure calls the authrequest command with the following options.


authenticate [ -normal | -changed ]

authenticate2

Displays a dialog box that indicates a problem with the user name or password. You can use your own title for the dialog and display your own message. You can also control whether the user name and password fields display.

This Tcl procedure calls the authrequest command with the following arguments.


authenticate2
 [ -normal | -changed ]
   -showuser 0|1
   -showpasswd 0|
   -title title
   -message message

customauthenticate

Displays a dialog box that indicates a problem with the user name or password. You can fully customize the authentication dialog.

With this procedure, the Execution Protocol Engine does not check the text the user types in the user name field. If Secure Shell (SSH) is used as the connection method for the application and the user changes the user name, the Execution Protocol Engine does not break the connection and reconnect as the new user name. This can cause applications to fail to start. If you are using SSH and allow the user to change the user name, use the userauthenticate procedure instead.

This Tcl procedure calls the authrequest command with the following arguments.


customauthenticate
 [ -normal | -changed ]
   -showuser 0|1
   -title title
   -message message
   -customuserlabel 0|1
   -userlabel label
   -custompasswdlabel 0|1
   -passwdlabel label
   -showpasscache 0|1
   -showsmartcard 0|1

userauthenticate

Displays a dialog box that indicates a problem with the user name or password. You can fully customize the authentication dialog.

This procedure is the same as customauthenticate except that it does check whether the user has changed the user name. If the user name is changed, the Execution Protocol Engine breaks the connection to the application server and reconnects as the changed user.

This Tcl procedure calls the authrequest command with the following arguments:


userauthenticate
 [ -normal | -changed ]
   -showuser 0|1
   -showpasswd 0|1
   -title title
   -message message
   -customuserlabel 0|1
   -userlabel label
   -custompasswdlabel 0|1
   -passwdlabel label
   -showpasscache 0|1
   -showsmartcard 0|1

Controlling the SGD Progress Dialog

The following Tcl commands are used to control the display of the SGD progress dialog when starting applications:

loaderror


loaderror error

You can use this Tcl command to override the error message returned by the login script. You can use this function, for example, to replace the standard login script error messages with your own message. If the application fails to start, the error is displayed in the progress dialog and in the log files. See Login Script Error Messages.

clienttimer


clienttimer [ time ] [ message ] [ timers ]

This Tcl command displays message in the progress dialog box for the specified time. The progress bar has timers sections in total. The following is an example.


clienttimer 10 "Launching the application" 4

canceltimer


canceltimer

This Tcl command cancels the clienttimer command. This command has no arguments.

progress


progress [ message ]

This Tcl command displays message in the progress dialog box. The following is an example.


progress "Initializing..."

Controlling the Connection to the Application Server

The following Tcl commands are used to control the connection to the application server:

setbuffer


setbuffer [ -buffer num ] [ -output 0|1 ]

This Tcl command defines the number of bytes to read from the application server.


Argument Description
-buffer num Specifies the number of bytes. Default is 1.
-output 0|1 Turns output on (1) or off (0). Default is 1.

The following is an example.


setbuffer -buffer 1000

locallaunch


locallaunch [ -start ] [ -abort ] [ -user launchspec -root launchspec ]

This Tcl command starts an application when the application server is also the SGD server. This is known as an optimized launch.


Argument Description
-start Starts an optimized launch.
-abort Stops the optimized launch and reverts to the standard connection method.
-user launchspec Defines the connection methods to use for starting applications on the SGD server when the user is not the UNIX or Linux root user.

You can specify different behavior for applications that are detached on launch, background applications, and those that are not, foreground applications.

The launchspec can be one of the following:

  • 0 - Starts all applications using the Connection Method defined for the application object

  • 1 - Background applications use /bin/su. Foreground applications use the application object’s Connection Method

  • 2 - Background applications use the application object’s Connection Method. Foreground applications use /bin/su

  • 3 - Starts all applications using /bin/su

The default is 1.

-root launchspec Defines the connection methods to use for starting applications on the SGD server when the user is the UNIX or Linux root user.

You can specify different behavior for applications that are detached on launch, background applications, and those that are not, foreground applications.

The launchspec can be one of the following:

  • 0 - Starts all applications using the Connection Method defined for the application object

  • 1 - Background applications use /bin/su. Foreground applications use the application object’s Connection Method

  • 2 - Background applications use the application object’s Connection Method. Foreground applications use /bin/su

  • 3 - Starts all applications using /bin/su

  • 4 - Starts all applications using the Connection Method defined for the application object

The default is 3.


The following is an example.


locallaunch -abort

tarantella


tarantella -nosocket -portnumber num -thirdtiershell shell

This Tcl command is used to configure the connection to the application server. You must configure the connection before you use the sgdconnect command.


Argument Description
-nosocket Specifies that the application is to be started by some other means and must be implemented by whoever is creating the script, for example by using Expect’s spawn command. This can only be done with applications that do not require a permanent connection, such as X applications. This command is useful if you have an unusual application server, or if you need to integrate with an existing application start mechanism.
-portnumber num Overrides the port used to make the connection to the application server. If you use this option, you must execute the tarantella command before the sgdconnect command, otherwise the port number is ignored.
-thirdtiershell shell Specifies the shell to use on the application server, for example /bin/sh.

The following example connects to the application server on TCP port 5999.


tarantella -portnumber 5999

sgdconnect


sgdconnect

Instructs the Execution Protocol Engine to connect to the application server. This command has no arguments.

Most of the SGD login scripts use sgdconnect to make the connection. If you want to handle the connection to the application server yourself, you must ensure that your script does not use this command.

The wcpwts.exp standard login script is an example of a login script that does not use this command to connect to an application server.


Login Script Variables

SGD login scripts use and support a number of variables. The variables can be divided into guaranteed variables, that are always available, and optional variables, that are only available if they have a value.

To be able to use a variable in a login script, it must be defined in the runsubscript.exp login script.

The following sections list the guaranteed and optional variables, and a description of their purpose.

Guaranteed Login Script Variables

Guaranteed variables store the names of commands to run, the application server to log in to, and the connection method to use.

All login scripts use at least some of the guaranteed variables.

Guaranteed variables always exist, though they might have a null value.


Variable Description
ALTDISPLAY The fully qualified Domain Name System (DNS) name of the user’s client device and the display number being used.
DISPLAY The Internet Protocol (IP) address of the user’s client device and the display number being used.
TTA_AGEDPASSWORD Whether to use the manual or dialog method of dealing with aged passwords.
TTA_ALLOWTHIRDTIERDIALOG Whether to show a dialog box on the application server if the user’s password is aged, missing or incorrect. This variable can have the following values:
  • user - If the user holds down the Shift key when they click an application’s link or if there is a password problem

  • system - Only when there is a password problem

  • none - Never show a dialog box

TTA_AUXCOMMANDS Any auxiliary commands to run on the application server. This corresponds to the application object’s Window Manager attribute.
TTA_CLIENT_IPADDR The IP address of the user’s client device. This is the IP address obtained by the SGD Client.
TTA_COMMAND The command to run on the application server. This corresponds to the application object’s Application Command attribute.
TTA_CONNECTIONSERVICE The transport used to connect to the application server. This corresponds to the application object’s Connection Method attribute.
TTA_ENVIRONMENT Any environment variable settings required on the application server. This corresponds to the application object’s Environment Variables attribute.
TTA_HOSTNAME The application server that the login script connects to. This is chosen by application load balancing, from those listed on the Hosting Application Servers tab for the application object.
TTA_HOSTPROBE The path to the ttahostprobe binary. Used to check whether an application server is available.
TTA_IPADDRESS The application server’s IP address.
TTA_LOGFILE The name of a file where error and diagnostic messages are logged.

By default, this has the form scriptID.log, where script is the name of the login script and ID is its process ID on the SGD server.

If set to null, messages are not stored.

To log messages in this file, include the following code in your login script:

log_file $env(TTA_LOGFILE)

TTA_PORT The port used to connect to the application server for the Connection Method configured for the application object.
TTA_PRIMARY_DNSNAME The primary SGD server’s fully qualified DNS name.

This lets the login script choose the correct SGD printer when setting the default printer value. It is used to differentiate between multiple entries in the /etc/ttaprinter.conf file.

TTA_SCRIPT The Expect script that runs after runsubscript.exp, for example unix.exp.
TTA_SECOND_TIER_DNSNAME The fully qualified DNS name of the SGD server hosting the application session.

Used with TTA_THIRD_TIER_DNSNAME to determine whether the application server and the SGD server are the same, and use an optimized launch process if they are.

TTA_THIRD_TIER_DNSNAME The fully qualified DNS name of the application server hosting the application.

Used with TTA_SECOND_TIER_DNSNAME to determine whether the application server and the SGD server are the same, and use an optimized launch process if it they are.

TTA_THIRD_TIER_VARS The list of variables to export to the environment on the application server.
TTA_STDERR A temporary error file.
TTA_WILLDISCONNECT Whether the connection is broken once the command is executed.
TTA_XLAUNCH Whether the application is an X application. The value of this variable is 0 or 1.

The following guaranteed variables are also defined in runsubscript.exp. These are variables used by the SGD server when starting applications:

Optional Login Script Variables

Optional variables store additional information about the application, the user, and their session.

Optional variables are often used to test conditions and modify the login script’s behavior accordingly. Optional variables only exist if they have a value. For example, the TTA_ResumeTimeOut variable only exists if the application object’s Application Resumability attribute has a value.

Most optional variables contain the values of object attributes. The application being started has its application object’s attributes made available as optional variables. Similarly, the attributes of the user profile are also made available in the same way. Other optional variables contain additional information about the user’s session.


Variable Description
TTA_Appearance Corresponds to a character application object’s Border Style attribute.
TTA_AppletHeight Corresponds to the application object’s Window Size: Height attribute.
TTA_AppletWidth Corresponds to the application object’s Window Size: Width attribute.
TTA_ApplicationName The application object’s fully qualified name.
TTA_ApplicationPlacement Corresponds to the application object’s Window Type attribute.

This variable can have the value multiplewindows - client window management, awtwindow - independent window, kiosk - kiosk, localx - local X server, and seamlesswindows - seamless window.

TTA_Arguments Corresponds to the application object’s Arguments For Command attribute.
TTA_AudioQuality Corresponds to the Windows Audio Quality attribute on the Global Settings -> Client Device tab in the Administration Console.

This variable can have the value low, medium, and high.

TTA_Autowrap Corresponds to the character application object’s Line Wrapping attribute.
TTA_BackgroundColor Corresponds to the Background Color attribute for a 3270 or 5250 application object.
TTA_ButtonLevels Corresponds to the 3270 or 5250 application object’s Displayed Soft Buttons attribute.

This variable can have the value 0 - No Buttons), 1 - 2 Rows, 2 - 4 Rows, 3 - 6 Rows, and 4 - 8 Rows.

TTA_CachePassword Whether the user selected the Save This Password? box when they supplied a user name and password for the application server.
TTA_CodePage Corresponds to the character application object’s Code Page attribute.

This variable can have the value 437, 850, 852, 860, 863, 865, 8859‐1, 8859‐2, Multinational, Mazovia, or CP852.

TTA_ColorMap Corresponds to the character application object’s Color Map attribute.
TTA_Columns Corresponds to the character application object’s Window Size: Columns attribute.
TTA_Compression Corresponds to the application object’s Command Compression attribute.

This variable can have the value automatic, on, or off.

TTA_ContinuousMode Corresponds to the application object’s Command Execution attribute.

This variable can have the value automatic, on, or off.

TTA_ControlCode Corresponds to the character application object’s Escape Sequences attribute.

This variable can have the value 7-bit, or 8-bit.

TTA_Cursor Corresponds to the character application object’s Cursor attribute.

This variable can have the value off, block, or underline.

TTA_CursorKeyMode Corresponds to the character application object’s Cursor Key Codes Modification attribute.

This variable can have the value application, or cursor.

TTA_DelayedUpdate Corresponds to the application object’s Delayed Updates attribute.
TTA_DisplayEnginePage Corresponds to the application object’s Emulator Applet Page attribute.

Note - This attribute is no longer used.

TTA_DisplayName Corresponds to the user profile’s Name attribute.
TTA_Domain Corresponds to the application object’s Domain Name attribute.
TTA_EuroMapping Corresponds to the application object’s Euro Character attribute.

This variable can have the value iso8859-15, or unicode.

TTA_FilePath Corresponds to the application object’s Application Command attribute.
TTA_FixedFontSize Corresponds to the character application object’s Font Size: Fixed attribute.
TTA_FontFamily Corresponds to the character application object’s Font Family attribute.

This variable can have the value courier, helvetica, or timesroman.

TTA_FontSize Corresponds to the character application object’s Font Size attribute.
TTA_ForegroundColor Corresponds to the 3270 or 5250 application object’s Foreground Color attribute.
TTA_GraphicsAcceleration Corresponds to the application object’s Graphics Acceleration attribute.
TTA_Height Corresponds to the application object’s Window Size: Height attribute.

This variable provides the same information as TTA_AppletHeight.

TTA_HostLocale Corresponds to the application server object’s Prompt Locale attribute.
TTA_HostName The application server that the login script connects to.

This is chosen by application server load balancing, from those listed on the Hosting Application Servers tab for the application object.

TTA_IBMHostName Corresponds to the 3270 or 5250 application object’s Server Address attribute.
TTA_Icon Corresponds to the application object’s Icon attribute.
TTA_InstanceName The application session ID.
TTA_InterlacedImages Corresponds to the application object’s Interlaced Images attribute.

This variable can have the value automatic, on, or off.

TTA_KeyboardType Corresponds to the 3270 or 5250 application object’s Keyboard Type attribute.

This variable can have the value pc, sun4, sun5, and hp.

TTA_KeymapLock Corresponds to the application object’s Keyboard Map attribute.
TTA_KeypadMode Corresponds to the character application object’s Numpad Codes Modification attribute.

This variable can have the value application, or numeric.

TTA_Lines Corresponds to the character application object’s Window Size: Lines attribute.
TTA_LocalAddr The IP address of the SGD host.
TTA_LoginScript Corresponds to the application object’s Login Script attribute.
TTA_Maximise Corresponds to the 3270 or 5250 application object’s Window Size attribute.
TTA_MiddleMouseTimeout Corresponds to the application object’s Middle Mouse Timeout attribute.
TTA_ParentName The application object’s fully qualified name.

This variable provides the same information as TTA_ApplicationName.

TTA_PortNumber Corresponds to the 3270 or 5250 application object’s Server Port attribute.
TTA_ProtocolArguments Corresponds to the Windows application object’s Arguments for Protocol attribute.
TTA_RemoteAddr The IP address of the application server used to run the application.
TTA_RequiresDisplayEngine Whether or not the application requires a display engine.
TTA_ResumeTimeOut Corresponds to the application object’s Application Resumability: Timeout attribute.
TTA_RootColor Corresponds to the application object’s Window Color: Custom Color attribute.
TTA_RootType Corresponds to the application object’s Window Color attribute.

This variable can have the value default, or color.

TTA_ScrollStyle Corresponds to the character application object’s Scroll Style attribute.

This variable can have the value normal, jump, or smooth.

TTA_SecureConnection Corresponds to the user profile’s Security tab.
TTA_SessionExit Corresponds to the application object’s Session Termination attribute.

This variable can have the value lastclient - Last Client Exit, windowmanager - Window Manager Exit, windowmanageralone - Only Window Manager Remaining), loginscript - Login Script Exit), loginscript - Login Script Exit), nowindows - No Visible Windows, and loginscriptnowindows - Login Script exit or No Visible Windows.

TTA_SettingsItem Corresponds to the 3270 or 5250 application object’s ‘File’ and ‘Settings’ Menus attribute.
TTA_StatusLine Corresponds to the character application object’s Status Line attribute.

This variable can have the value none, indicator, and host writable, standard, or extended.

TTA_Suspend Corresponds to the application object’s Application Resumability attribute.

This variable can have the value never, session (means User Session), and forever (means Always).

TTA_TerminalClass Corresponds to the character application object’s Emulation Type attribute.

This variable can have the value scoconsole, vt420, or wyse60.

TTA_TerminalType Corresponds to the character application object’s Terminal Type attribute.
TTA_TNClose Corresponds to the 3270 or 5250 application object’s Connection Closed Action attribute.

This variable can have the value 0 - Prompt User for Action, 1 - Exit Emulator, 2 - Reconnect, and 3 - Close Connection.

TTA_TopMenuBar Corresponds to the 3270 or 5250 application object’s Menu Bar attribute.
TTA_Transport Corresponds to the application object’s Connection Method attribute.

This variable can have the value rexec, telnet, or ssh.

The guaranteed variable TTA_CONNECTIONSERVICE also provides this information.

TTA_UserName The fully qualified name of the user this application session is for.
TTA_UserSecurityEquivalent Corresponds to the user profile’s User Name attribute.
TTA_UNIXAUDIO_QUALITY Corresponds to the UNIX Audio Quality attribute on the Global Settings -> Client Device tab in the Administration Console.

This variable can have the value low, medium, and high.

TTA_UNIXAUDIOPRELOAD Corresponds to the X application objects Audio Redirection Library attribute.
TTA_ViewHostReply Corresponds to the application object’s Keep Launch Connection Open attribute.
TTA_WebTop Corresponds to the Webtop Theme attribute.

Note - This attribute is no longer used.

TTA_Width Corresponds to the application object’s Window Size: Width attribute.

This variable provides the same information as TTA_AppletWidth.

TTA_WinCursor Corresponds to the application object’s Use Windows Cursor attribute.

Note - This attribute is no longer used.

TTA_WindowsApplicationServer Corresponds to the Windows application object’s Windows Protocol attribute.

This variable can have the value wincenter, wincentermf - Citrix UNIX Integration Services, merge - SCO Merge, winframe - Citrix ICA), wcpwts - Microsoft RDP, or none. Only Citrix ICA and Microsoft RDP are supported. The other protocols can only be used with legacy SGD Windows application objects.

TTA_WindowsApplicationSupport Corresponds to the Windows application object’s Windows Protocol: Try Running From Client First attribute.


Login Script Timeouts

SGD uses several timeouts when starting applications. The following timeouts are available:



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



Expect Timeouts

The Expect timeouts are defined in the vars.exp login script. The following table lists the available Expect timeouts and their default values.


Timeout Default Value
timeouts(hostprobe) 30 seconds
timeouts(prelogin) 40 seconds
timeouts(loggedin) 20 seconds

If an Expect timeout expires, the script attempts to guess the prompt, and then continues to start the application.

timeouts(hostprobe)

The timeouts(hostprobe) timeout is called by the unix.exp login script. This is the time to wait for a response from the ttahostprobe binary. The ttahostprobe binary is used to check whether an application server is available.

The ttahostprobe binary outputs its response to standard output (stdout), and returns y for success or n for failure.

timeouts(prelogin)

The time allowed for each Expect command to match a required string during the login phase.

For example, after the connection is made to the application server, the script has 40 seconds by default to match the login prompt before it times out. Every successful match resets the timer. During a login, the timeout is usually reset for the login prompt, the password prompt, and the shell prompt.

Increasing this timeout increases the time allowed for each phase of the login. This timeout must be large enough to allow for the longest phase of the login to be completed.

If the timeout expires, the script assumes that it is logged in and has failed to match the shell prompt and sends “echo SYNC” to the application server to guess the prompt string. If the user is not logged in when the timer fires, the application fails to start. Otherwise, the shell prompt is set to whatever the application server sent immediately after the “echo SYNC” and the application startup continues.



Note - If you see “echo SYNC” and the shell prompt ends in the normal way with $, %, #, or >, the timeouts(prelogin) value is too short.



timeouts(loggedin)

The time allowed for each Expect command to match a required string once the user is logged in.

If the timeout expires, the script moves on to the next command. This can cause commands to be sent before the prompt has returned.

The most common occurrence of this timeout is if the script incorrectly sets the shell prompt. By default, this causes each command to wait 20 seconds before moving to the next command and can trigger one of the client timers.

Client Timers

Client timers are set using the clienttimer Tcl command (see clienttimer). If a client timer expires, the application start is canceled with a fatal ErrApplicationServerTimeout error.

The client timers are defined in the vars.exp login script.

The following table lists the available client timers and their default values.


Timer Default Value
timers(login) timeouts(prelogin) + 10 seconds
timers(env) 40 seconds
timers(runmain) 40 seconds
timers(build) 25 seconds
timers(total) 5 seconds

timers(login)

The total time for the complete login phase, from making the connection to receiving the first shell prompt.

The timers(login) timer must be large enough to cover all of the login phases. Each individual phase of the login (login prompt, password prompt, shell prompt) might last up to the number of seconds defined for the timeouts(prelogin) timeout. The value of this timer must always be greater than timeouts(prelogin) Expect timeout.

If you increase the timeouts(prelogin) Expect timeout, increase the timers(login) timer as well so that the difference between them is never less than 10.

timers(env)

The total time from receiving the first shell prompt until all of the application server environment variables have been exported.

timers(runmain)

The total time from setting the last environment variable to starting the main application.

timers(build)

The total time taken to build the command line to be executed. This timer is only used when starting Windows applications that use the SCO Merge protocol.



Note - The SCO Merge protocol is no longer supported and can only be used by legacy SGD Windows application objects.



timers(total)

The total number of client timers. Only change this setting if you add or remove a client timer.

Other Timeouts

The procs.exp login script includes a 3-second timeout when issuing commands. This is defined in the proc wait_for_prompt procedure.

The Execution Protocol Engine has a default timeout of 180 seconds (3 minutes). This timeout starts when the request to start an application is received and removed when the application startup has completed successfully. If it expires, the application startup is canceled. This timeout is specific to each SGD server.

Use the following command to change this timeout:


$ tarantella config edit \
  --tarantella-config-execpeconfig-maxlaunchtime secs



Note - Use the --array option with this command to change this timeout for all the SGD servers in the array.




Login Script Error Messages

The following table lists the error codes and messages that can occur with login scripts, and a description of what to do about them. Use this information to diagnose why a login script is failing.


Code Error Message and Description
0 ErrOK

The login script successfully connected to the application server and started the application.

1 ErrApplicationServerResourceFailure

The login script failed due to a lack of system resources on the application server.

Ensure that the application server is capable of running the application.

2 ErrApplicationServerNoLicenseAvailable

No licenses were available on the application server.

Ensure that the application server has sufficient licenses for the number of connections you expect to make.

3 ErrFaultInExecutionScript

The login script contains a syntax error.

Review the login script.

4 ErrApplicationServerLoginFailed

The login script failed to log into the application server.

See see Troubleshooting ErrApplicationServerLoginFailed Errors.

5 ErrApplicationServerLoginIncorrect

The user name and password supplied to the application server were not accepted.

Check that the user name and password are valid on that application server.

6 ErrApplicationServerPasswordAged

The user’s password on the application server has expired.

Ensure that the user has a valid password on the application server.

To avoid seeing this error, configure SGD to handle aged passwords. You configure this on the Global Settings -> Application Authentication tab in the Administration Console.

7 ErrCommandExecutionFailed

The login script successfully logged in to the application server but could not run the application.

Ensure that the application object’s Application Command attribute contains a valid command.

Ensure that the user has write permissions for the /tmp directory on the application server.

8 ErrApplicationServerConnectionFailed

The login script failed to log in to the application server.

Check that you can log into the application server manually.

9 ErrApplicationServerEndOfFileOnConnection

The login script encountered an End of File error (EOF) on connection to the application server.

Investigate why an EOF error is returned.

10 ErrApplicationServerTimeout

The login script timed out when trying to connect to the application server.

See Troubleshooting ErrApplicationServerTimeout Errors.

12 ErrInvalidDesktopSize

The width and height defined for a Windows application is not valid.

Check the application object’s Window Size: Width and Window Size: Height attributes.

14 ErrCouldNotPipe

The login script was unable to create a pipe between the parent and child processes in the Execution Protocol Engine.

This error might indicate that there is not enough memory on the application server. Check the number of other applications running on the server and increase size of memory if necessary.

15 ErrCouldNotFork

The login script was unable to fork a child process in the Execution Protocol Engine.

This error might indicate that there is not enough memory on the application server. Check the number of other applications running on the server and increase the amount of memory if necessary.

16 ErrScriptRead

The login script produced an error when trying to read from the script process in the Execution Protocol Engine.

Try to run the application again. If the error persists, contact Sun Support.

17 ErrScriptWrite

The login script produced an error when trying to write to the script process in the Execution Protocol Engine.

Try to run the application again. If the error persists, contact Sun Support.

18 ErrThirdTierWrite

The login script produced an error when trying to write to the application server in the Execution Protocol Engine.

This error usually means the connection to the application server was lost. Check the application server is available and try to run the application again.

19 ErrThirdTierRead

The login script produced an error when trying to read from the application server in the Execution Protocol Engine.

This error usually means the connection to the application server was lost. Check the application server is available and try to run the application again.

21 ErrTransportNotAvailable

The login script was unable to connect to the application server using the requested connection method method.

Check that the application server supports the connection method. Check that the application server is available.

22 ErrLogFileError

This is not an application startup error. SGD was unable to create a log file for the Protocol Engine Manager.

If the error persists, contact Sun Support.

27 ErrThirdTierFailure

Something has gone wrong on the application server.

Check that the server is available and that you can run the application manually.

30 ErrLoginPasswordNotAvailable

The login script was unable to supply the application server with a password.

This error usually means the Execution Protocol Engine timeout has been triggered. See for details of how to increase the Execution Protocol Engine timeout.

31 ErrRequestNotSupported

The login script cannot execute the requested auxiliary commands.

Check that the Arguments for Command attribute for the application object is configured correctly and that the additional commands work on the application server.

32 ErrRequestNotImplemented

The login script cannot execute the requested operation because it has not been implemented.

If the error persists, contact Sun Support.

33 ErrUnknown

An error occurred in the Execution Protocol Engine.

Check the log file and try to run the application again.

34 ErrInternalError

An error in the Protocol Engine Manager.

Check the log file and try to run the application again.

37 ErrProtocolEngineDied

The Protocol Engine process failed.

Check the log file for the process ID of the protocol engine and try running the application again. If the problem persists, contact Sun Support.

43 ErrExpectInitialisationFailed

SGD was unable to initialize the Expect interpreter and so the script was not run.

Try to run the application again. If the problem persists, contact Sun Support.

44 ErrEvalFileFailed

The login script file does not exist or contains a syntax error that is causing the Expect interpreter to fail.

Check that the login script is in the specified directory. All login scripts supplied by SGD are stored in the /opt/tarantella/var/serverresources/expect directory. Check the Execution Protocol Engine error log file for details of any errors with the script.

45 ErrCreateInterpreterFailed

SGD was unable to initialize the Tcl interpreter and so the script was not run.

Try to run the application again. If the error persists, contact Sun Support.

46 ErrChdirFailed

The login script failed to change to the directory containing the script.

Check the path to the script.

47 ErrReadError

The login script produced an error when trying reading from the protocol connection between the parent and child processes in the Execution Protocol Engine.

Try to run the application again. If the error persists, contact Sun Support.

49 ErrEndOfFile

The login script read an unexpected end of file on a connection.

Try to run the application again. If the error persists, contact Sun Support.

51 ErrBadMessage

The login script received an invalid message, probably due to a corruption of the data packet.

Try to run the application again. If the error persists, contact Sun Support.

52 ErrStaleCookie

The client connected to the application but the cookie needed for the application startup has expired.

Try to run the application again.

If this fails, increase the lifetime of the cookie. You do this with the following command:

$ tarantella config edit --tarantella-config-applaunch-reconnecttimeout seconds

The default value is 60 (60 seconds). If the error persists, contact Sun Support.

53 ErrEatenCookie

The client connected to the application but the cookie needed for the application startup has already been used, probably by the user running multiple sessions.

Try to run the application again. If the error persists, contact Sun Support.

54 ErrDifferentCookie

The client connected to the application but the cookie supplied does not match the one required for the application startup.

Try to run the application again. If the error persists, contact Sun Support.

55 ErrLaunchPolicyNotFound

SGD was unable to find the details needed to run the application.

This error might never occur. Try to run the application again. If this fails, stop the SGD server, start it again, and then run the application again. If the error persists, contact Sun Support.

56 ErrBadLength

The login script received a message that was not the correct length, probably due to a corruption of the data packet.

Try to run the application again. If the error persists, contact Sun Support.

57 ErrInvalidConfigObject

The configuration data provided by SGD did not contain all the required information.

This error might never occur. Try to run the application again. If this fails, stop the SGD server, start it again and then run the application. If the error persists, contact Sun Support.

58 ErrSessionCircuitNotFound

The connection between the protocol engine and the Protocol Engine Manager was lost.

Try to run the application again. If this fails, stop the SGD server, start it again and then run the application. If the error persists, contact Sun Support.

59 ErrExecutionCircuitNotFound

The connection between the Protocol Engine Manager and the Execution Protocol Engine was lost.

Try to run the application again. If this fails, stop the SGD server, start it again, and then run the application. If the error persists, contact Sun Support.

61 ErrCircuitNotFound

The Protocol Engine Manager cannot find a circuit (connection).

Try to run the application again. If this fails, stop the SGD server, start it again and then run the application. If the error persists, contact Sun Support.

62 ErrCreateFailed

The create request to the protocol engine failed and SGD was unable to run the application.

The definition of the application is missing some attributes. Check the log file for details of the missing attributes and correct these errors before trying to run the application again

63 ErrComplete

This is not an error. It is a message from Execution Protocol Engine to the Protocol Engine Manager to indicate the launch process was completed.

65 ErrNonZeroConnectresult

When the SGD Client connected to the protocol engine, an error occurred.

If possible, log out. Otherwise, close the web browser and end the SGD Client processes on the client device. Try to run the application again.

66 ErrUserAbort

This is not an error. The user canceled the application launch.

67 ErrClientEndOfFileOnConnection

The connection to the SGD Client was lost.

If possible, log out. Otherwise, close the web browser and end the SGD Client processes on the client device. Try to run the application again.

68 ErrNothingToDo

This is not an error.

This message indicates that the launch request sent to the Protocol Engine Manager does not require any protocol engines.

71 ErrIoError

The login script was unable to write to stderr.

Try to run the application again. If the error persists, contact Sun Support.

73 ErrTscLicenseError

There are not enough Windows Terminal Services licenses available to be able to run the application.

Increase the number of Windows Terminal Services licenses.