A P P E N D I X E |
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.
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.
You configure the login script that is used for an application as follows:
In the Administration Console, use the Login Script script attribute on the Launch tab for the application object.
On the command line, use the --login script command option with the tarantella object commands.
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.
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.
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.
The following Tcl commands and procedures are used to control the display of the SGD Application Authentication dialog when starting applications:
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. |
The following example displays a dialog box that says the password is incorrect.
authrequest -normal |
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 ] |
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 |
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 |
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 |
The following Tcl commands are used to control the display of the SGD progress dialog when starting applications:
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 [ 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 |
This Tcl command cancels the clienttimer command. This command has no arguments.
The following Tcl commands are used to control the connection to the application server:
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. |
setbuffer -buffer 1000 |
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.
locallaunch -abort |
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 |
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.
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 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.
The following guaranteed variables are also defined in runsubscript.exp. These are variables used by the SGD server when starting applications:
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.
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. |
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.
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.
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. |
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 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 |
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.
The total time from receiving the first shell prompt until all of the application server environment variables have been exported.
The total time from setting the last environment variable to starting the main application.
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. |
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. |
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 |
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. |
10 | ErrApplicationServerTimeout
The login script timed out when trying to connect to the application server. |
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. |
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. |
33 | ErrUnknown |
34 | ErrInternalError |
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. |
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 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. |
Copyright © 2008, Sun Microsystems, Inc. All rights reserved.