Exit Print View

Oracle Secure Global Desktop Administration Guide for Version 4.6

Document Information

Preface

1.  Networking and Security

2.  User Authentication

3.  Publishing Applications to Users

4.  Configuring Applications

5.  Client Device Support

6.  SGD Client and Webtop

7.  SGD Servers, Arrays, and Load Balancing

A.  Global Settings and Caches

B.  Secure Global Desktop Server Settings

C.  User Profiles, Applications, and Application Servers

D.  Commands

E.  Login Scripts

Login Scripts Supplied With SGD

Login Scripts Used When Configuring Applications

Login Scripts Containing Common Code

Login Script Tcl Commands and Procedures

Controlling the SGD Application Authentication Dialog

authrequest

authenticate

authenticate2

customauthenticate

userauthenticate

Controlling the SGD Progress Dialog

loaderror

clienttimer

canceltimer

progress

Controlling the Connection to the Application Server

setbuffer

locallaunch

tarantella

sgdconnect

Login Script Variables

Guaranteed Login Script Variables

Optional Login Script Variables

Login Script Timeouts

Expect Timeouts

timeouts(hostprobe)

timeouts(prelogin)

timeouts(loggedin)

Client Timers

timers(login)

timers(env)

timers(runmain)

timers(build)

timers(total)

Other Timeouts

Login Script Error Messages

F.  Third-Party Legal Notices

Glossary

Index

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