The SGD Client is the part of SGD that is installed on client devices. The SGD Client is required to run applications.
This section includes details of how you can install and run the SGD Client.
This section does not apply for tablet devices, or when using the tablet workspace on a desktop platform.
With tablet devices, or when using the tablet workspace on a desktop platform, the SGD Client software is not installed on the client device. Instead, an HTML5 web page is used to display the workspace and enable the user to run applications.
This section includes the following topics:
The SGD Client operates by using a browser to display a special web page, called a workspace. The workspace lists the applications a user can run through SGD and provides controls for managing application sessions and printing. This is the default way of using SGD.
See the Oracle Secure Global Desktop User Guide for more details about the workspace.
Depending on the client platform, users may see an icon in the System tray or Workspace switcher when the SGD Client is running.
On the tablet workspace, the SGD Client icon is not displayed.
The SGD Client performs the following functions:
Gets information about the client device, such as the operating system, local printers, and client drives.
Manages the display of applications.
Maintains a communication connection with the SGD server, using the Adaptive Internet Protocol (AIP) protocol.
Receives and acts on events from the SGD server. For example, the arrival of a print job.
The SGD Client needs to be configured so that it can connect to an SGD server. The connection settings for the SGD Client are defined in a client profile. The client profile is stored on the client device.
Client profiles are not available when using the tablet workspace.
The client profile controls things such as the URL that the SGD Client connects to when it starts, and the operating mode of the SGD Client.
See Section 6.2, “Client Profiles” for more information about how SGD uses client profiles and the settings you can configure for a client profile.
When using a browser with Java technology enabled, the SGD Client is supported by the SGD Client Helper.
The SGD Client Helper is a Java applet that performs the following functions:
Downloads and installs the SGD Client. This only applies if automatic installation is used. See also Section 6.1.3, “Automatic Installation of the SGD Client”.
Obtains proxy server settings from the browser and sends them to the SGD Client. This depends on the settings in the user's client profile.
Starts the SGD Client. This only happens when a user starts a browser and goes to the login URL.
Responds to instructions received from the SGD Client. For example, prompting the browser to redraw the screen.
Use of the SGD Client Helper is optional. See Section 6.1.3.1, “Using and Configuring Java Web Start” if your browser does not use Java Plug-in software, or Section 6.1.7.1, “How to Use the SGD Client Without Java Technology” if you do not want to use Java technology on the client device.
The SGD Client Helper is not used with the tablet workspace.
The SGD Client can be installed in the following ways:
Automatic installation. The SGD Client is downloaded to the client device and installed automatically. See Section 6.1.3, “Automatic Installation of the SGD Client”.
Manual installation. The SGD Client can be downloaded to the client device and installed manually. See Section 6.1.5, “Manual Installation of the SGD Client”.
With automatic installation, the SGD Client is
downloaded and installed automatically when you go to the
https://
URL, where server.example.com
/sgdserver.example.com
is the
name of an SGD server.
Automatic installation can be done in one of the following ways:
Using a browser with Java technology enabled. This option is for browsers that are using Java Plug-in software.
You can configure SGD to not use Java Plug-in software for automatic installation with specific client browsers. See Section 6.1.3.2, “Disabling Automatic Installation Using Java Plug-in Software for Specific Browsers”.
NoteWhen using the tablet workspace, Java technology is not used for automatic installation.
Using Java Web Start software. This option is for browsers that do not use Java Plug-in software.
See Section 6.1.3.1, “Using and Configuring Java Web Start” for more information about using and configuring Java Web Start.
With automatic installation of the SGD Client, different versions of the SGD Client are installed in separate directories. This means the following:
Users only have to log in to an upgraded SGD server in order to upgrade the SGD Client
Users who log in to different SGD servers always run the correct SGD Client for the version of SGD
The SGD Client is installed in the following directories:
Microsoft Windows client devices. The user's Home folder. For example:
C:\Users\
username
\AppData\Local\Temp\Oracle Secure Global Desktop\clients\version
Users with Microsoft Windows client devices can have roaming user profiles. Roaming user profiles provide the user with the same working environment, no matter which Microsoft Windows computer they use.
If Microsoft Windows users have roaming user profiles, the SGD Client is installed in the following directory:
C:\Users\
username
\AppData\Roaming\Temp\Oracle Secure Global Desktop\clients\version
For details of how to configure SGD to work with roaming user profiles, see Section 6.1.4, “How to Enable Automatic Installation for Roaming User Profiles”.
UNIX or Linux platform client devices. The user's home directory:
$HOME/.tarantella/clients/
arch
/version
where
arch
is the client architecture.Mac OS X platform client devices. The user's home directory:
$HOME/.tarantella/clients/
version
If you want to use automatic installation and have more control over where the SGD Client is installed, you can develop your own web application for installing the SGD Client and use SGD web services to specify the installation location.
Java Web Start software is an Oracle technology for delivering Java applications to clients without using applets or browser plug-in software. See https://www.java.com/en/download/faq/java_webstart.xml for more information.
Java Web Start provides an alternative to the usual method of installing the SGD Client automatically, where a Java applet is downloaded and installed using Java Plug-in software running in a browser. Using Java Web Start means that automatic installation can still be used, even if the browser does not support Java Plug-in software.
To use Java Web Start, Java software must be installed on the client device. Some browsers or client devices may need additional configuration to use Java Web Start.
If Java software is installed on the client device, Java Web Start is used automatically for browsers where Java Plug-in software is not installed or is disabled.
Timeout Configuration for Java Web Start
To avoid timeout problems when using Java Web Start over a slow connection, Administrators can increase the time allowed for downloading of the SGD Client binary.
Add a MAX_TCCCHECK_TIMEOUT
context
parameter setting in the following file:
/opt/tarantella/webserver/tomcat/
.
tomcat-version
/webapps/sgd/WEB-INF/web.xml
The default value for this setting is 180000 milliseconds (3 minutes). Configure a higher value, for example:
<context-param> <param-name>MAX_TCCCHECK_TIMEOUT</param-name> <param-value>360000</param-value> </context-param>
In some SGD deployments you may want to disable automatic installation using Java Plug-in software for specific browsers, or for all browsers. SGD then does not attempt to use Java Plug-in software to download and install the SGD Client automatically, even if Java Plug-in software is enabled on the client browser.
Add a disallowjavauseragentmatch
context
parameter setting in the following file:
/opt/tarantella/webserver/tomcat/
.
tomcat-version
/webapps/sgd/WEB-INF/web.xml
The value of disallowjavauseragentmatch
is
a regular expression that matches the
User-Agent
header of the browser used on
the client device.
For example, to disable automatic installation using Java Plug-in software for all browsers, use the following setting:
<context-param> <param-name>disallowjavauseragentmatch</param-name> <param-value>.*</param-value> </context-param>
For example, to disable automatic installation using Java Plug-in software for all Firefox browsers, use the following setting:
<context-param> <param-name>disallowjavauseragentmatch</param-name> <param-value>.*firefox.*</param-value> </context-param>
Restart the SGD web server after making changes
to the web.xml
file.
To enable the SGD Client to be installed automatically in a directory that is roamed, perform the following procedure on each SGD server in the array.
Ensure that no users are logged in to the SGD server, and that there are no application sessions, including suspended application sessions, running on the SGD server.
Log in as superuser (root) on the SGD host.
Change to the
jsp
directory.# cd /opt/tarantella/webserver/tomcat/
tomcat-version
/webapps/sgd/resources/jspEdit the
webtopsession.jsp
file.Change the
tccRoaming
line inwebtopsession.jsp
, as follows:String tccRoaming="true";
Save the change.
Restart the SGD web server.
# tarantella restart webserver
With manual installation, you have full control over where the SGD Client is installed.
Manual installation is not supported on tablet devices.
Different versions of the SGD Client are installed in separate directories.
You can install the SGD Client manually in the following ways:
User-specific installation. The SGD Client is installed in a user-specified location.
See Section 6.1.5.1, “User-Specific Installation” for more details.
NoteUser-specific installation is not supported on Mac OS X platforms.
System-wide installation. The SGD Client is installed in a system-wide location. This option is available for Administrators only.
See Section 6.1.5.2, “System-Wide Installation” for more details.
You download and install the SGD Client from the
SGD web server Welcome page. The SGD
web server Welcome page is at
https://
,
where server.example.com
server.example.com
is the name
of an SGD server.
Click the Install the Oracle Secure Global Desktop Client link on the Welcome page. The Oracle Secure Global Desktop Client download page has instructions for downloading and installing the SGD Client.
On Microsoft Windows client devices, a shortcut for the SGD Client is added to the Windows Start Menu.
For a user-specific installation, the user must have permissions to write to the install location.
The default locations for a user-specific installation are as follows:
Microsoft Windows client devices. The user's Home folder. For example:
C:\Users\
username
\AppData\Local\Programs\Oracle\Secure Global Desktop Client\clients\version
UNIX or Linux platform client devices. The user's home directory:
$HOME/Oracle Secure Global Desktop/clients/
arch
/version
where
arch
is the client architecture.A configuration file containing a list of SGD Clients installed on the system is created at
$HOME/.tarantella/clients.conf
. See Section 6.1.5.3, “Installing the SGD Client in a Non-Default Location” for more details about this file.Mac OS X platform client devices.
User-specific installation is not supported on Mac OS X platforms.
This installation method can be used on a shared file system.
The default locations for a system-wide installation are as follows:
Microsoft Windows client devices:
C:\Program Files\Oracle\Secure Global Desktop Client\clients\
version
UNIX or Linux platform client devices:
/opt/Oracle Secure Global Desktop/clients/
arch
/version
where
arch
is the client architecture.A system-wide configuration file containing a list of SGD Clients installed on the system is created at
/etc/opt/Oracle Secure Global Desktop/clients.conf
. See Section 6.1.5.3, “Installing the SGD Client in a Non-Default Location” for more details about this file.Mac OS X platform client devices:
/Applications/Oracle Secure Global Desktop Client/
version
/Oracle Secure Global Desktop Client.app
With manual installation, you can install the SGD Client in a non-default location.
When you are connecting to an SGD server using a browser with Java technology enabled, the SGD Client Helper looks for the SGD Client on the client device. To enable this, SGD maintains a record of the location of all SGD Clients installed manually on the client device.
SGD Client locations are recorded on the client device as follows:
Microsoft Windows platforms. A key in the registry, as follows:
User-specific installation:
HKEY_CURRENT_USER\Software\Oracle\Secure Global Desktop Client\VERSION
System-wide installation:
HKEY_LOCAL_MACHINE\Software\Oracle\Secure Global Desktop Client\VERSION
UNIX and Linux platforms. A configuration file, as follows:
User-specific installation:
$HOME/.tarantella/clients.conf
System-wide installation:
/opt/Oracle Secure Global Desktop/clients.conf
Mac OS X platforms. Non-default install locations are not recorded on the client device. So, the SGD Client Helper is not able to find SGD Clients installed in non-default locations.
Before attempting to download the SGD Client from an SGD server, the SGD Client Helper checks the above locations to see if the same version of the SGD Client is already installed on the client device.
The above locations are also searched if the SGD Client Helper is unable to download and install the SGD Client automatically. For example, if there is a network problem. In this case, the SGD Client Helper checks if there is a compatible version of the SGD Client already installed on the client device, by looking in one of the locations shown.
Typically, users log in to SGD by starting a
browser and visiting the
https://
URL, where server.example.com
/sgdserver.example.com
is the
name of an SGD server.
Connecting to SGD in this way, automatically downloads and starts the SGD Client. However, you can also start the SGD Client from the command line and connect to an SGD server.
Running the SGD Client from the command line is not available on tablet devices.
You start the SGD Client with the
tcc
command on Microsoft Windows client
platforms, or the ttatcc
command on UNIX,
Linux, or Mac OS X client platforms, as follows:
tcc [ -profilename
] [ -loginurlurl
] [ -prompt ] [ -preferredlanguagelang
] [ -logdirfile
] [ -use-java ] [ -version ]
The following table lists the arguments for the tcc and ttatcc commands.
Argument | Description |
---|---|
| The name of the profile to use when starting the SGD Client. Currently there is only one profile for each SGD server, called Default.
To specify the profile for a particular server, use
Note Profile names are case sensitive. |
| The login URL. This overrides the URL defined in the profile. Use a fully qualified domain name. |
| Display the connection dialog, showing a list of SGD servers that the SGD Client has previously connected to. The user can select a server from the list. |
| The language to use in any dialogs and messages displayed by the SGD Client. This overrides the language defined in the profile. The following are the supported languages:
|
| The directory where the SGD Client log file is created. |
| Enable the detection of Java technology in the SGD Client. |
| Displays the version number of the SGD Client. |
| Displays help information. This option is only available on UNIX, Linux, or Mac OS X client platforms. |
The arguments are case-sensitive.
The command line does not allow you to supply a user name and password.
The command line for the SGD Client can be used to create your own shortcuts and shell scripts.
The following are some examples of running the SGD Client from the command line.
The following example starts the SGD Client and uses the settings defined in the Default profile, available from the user's profile cache.
$ ttatcc
If there is no profile, or the profile does not contain a login URL, the SGD Client starts but it cannot connect to an SGD server.
If the user has previously connected to more than one SGD server, the SGD Client connects to the last SGD server the user connected to, using the profile for that server.
Use this command to start the SGD Client if the user always connects to the same SGD server.
The following example starts the SGD Client and
uses the settings defined in the profile for
server.example.com
, available
from the user's profile cache.
$ ttatcc -profile server.example.com
::Default
If there is no profile available in the cache for
server.example.com
, the
SGD Client prompts for connection settings.
Use this command to start the SGD Client if the user might connect to different SGD servers.
The following example starts the SGD Client and uses the settings defined in the Default profile, available from the user's profile cache, but connects to the specified URL.
$ tcc -loginurl url
where url
is the URL of a login
page on an SGD server, for example
http://server.example.com/sgd
.
Depending on the URL, this can be used to start an application.
Use this command to start the SGD Client and connect to a single SGD server, but connect to different web applications on that server.
The SGD Client also supports the following command-line arguments. These arguments are useful only when developing applications with SGD web services.
Argument | Description |
---|---|
| The port on which the SGD Client connects to the SGD server. Usually, this is TCP port 5307 when the user has a secure connection to SGD. |
| The base network route the SGD Client uses to traverse a SOCKS proxy server. |
| Indicates that the SGD server is using firewall traversal. Connections to the SGD server and the workspace both use the same port, usually TCP port 443. |
| Supplies the cookie used by the SGD server to identify the user session which the SGD Client is being used for. |
| The name of a file where the SGD Client writes its listening port number. |
| The fully qualified domain name of the SGD server. |
| Do not start a browser when starting the SGD Client. |
| When starting the SGD Client, do not check that the SGD Client and SGD server versions are compatible. |
The arguments are case-sensitive.
If your organization prefers not to use Java technology, users can access SGD from a tablet device, or you can deploy the tablet workspace on desktop platforms, as shown in Section 6.3.2, “Deploying the Tablet Workspace on Desktop Platforms”.
On desktop client platforms, you can still use the SGD Client without Java technology, but with the following limitations:
The SGD Client must be manually downloaded and installed.
To log in to SGD, users must start the SGD Client first, either from the command line or from the shortcut in the desktop Start menu. Users cannot log in by starting a browser first.
Proxy server settings must be configured in users' client profiles. The settings cannot be obtained automatically from a browser.
The workspace must be reloaded manually to show the current state.
The following procedure describes the steps needed to use the SGD Client without Java technology.
This procedure does not apply when using a tablet device.
Download and install the SGD Client.
You download the SGD Client from the SGD web server Welcome page, for example at
https://
, whereserver.example.com
server.example.com
is the name of an SGD server.Click the link to Install the Oracle Secure Global Desktop Client.
The download page and the Oracle Secure Global Desktop User Guide have details of how to install the SGD Client.
Start the SGD Client and connect to SGD.
Use either of the following methods:
Start the SGD Client from the shortcut in the desktop Start menu.
The first time you start the SGD Client, it prompts you for the URL to connect to. This is normally
https://
, whereserver.example.com
/sgdserver.example.com
is the name of an SGD server. The SGD Client also prompts you for the proxy server settings to use.When the SGD Client connects, it starts your default browser and displays the SGD login page.
Start the SGD Client from the command line.
See Section 6.1.6, “Running the SGD Client From the Command Line” for more details.
Log in to SGD.
The SGD workspace is displayed.
Edit the profile for your client device.
On the workspace, click the Edit button in the Applications area of the workspace. Go to the Client Settings tab and edit the client profile.
See also Section 6.2.4, “Client Profile Settings”.
Configure the proxy server settings.
You must specify the proxy server settings in the profile, because these settings cannot be obtained from the browser. See Section 1.3.2, “Configuring Client Proxy Settings”.
Click Save.
NoteSGD Administrators can preconfigure many of these settings for users, by editing the profile for an organization or organizational unit.
Log out of SGD.
Java archive (JAR) files for the SGD Client and the SGD Client Helper are located by default in the following directory:
/opt/tarantella/webserver/tomcat/
.
tomcat-version
/webapps/sgd/tcc/java
In some circumstances, you might want to use a different archive location on the SGD server. For example, if the default location is secured in your deployment, you may sometimes experience issues with automatic installation of the SGD Client.
To change the archive location, configure the
tccBaseURL
context parameter setting in the
webapps/sgd/WEB-INF/web.xml
deployment
descriptor file.
Archive files should be located within a
/java
subdirectory of the specified
tccBaseURL
path.