C H A P T E R  3

Upgrading SGD

This chapter describes the requirements and procedures for upgrading from a previous version of SGD.

Topics in this chapter include the following:


Before You Upgrade

This section describes the things you must know and do before upgrading.

Version 4.4 and Organizational Changes

SGD version 4.4 includes a new web‐based administration tool, the SGD Administration Console, which replaces Object Manager, Array Manager, Configuration Wizard, and Session Manager. As a result, there are some significant changes to the SGD organizational hierarchy. The main changes are as follows:

When you upgrade, your existing application and host objects (and their associated group and organizational unit objects) are moved to the new organizations. As far as possible, SGD attempts to preserve the relationships between the objects, but after the upgrade some users might find that some applications are no longer on their webtop.

Before you upgrade, it is a advisable to perform a test to see how the changes affect you. You can do this by upgrading a pre-production environment that mirrors the production environment. Alternatively, detach a secondary server from the array and upgrade it.

Upgrades and Early Access Program Software

Upgrades to or upgrades from Early Access Program (EAP) software releases of SGD are not supported. EAP software releases must always be a fresh installation.

Conditions for Upgrading

Upgrades to this version of SGD are only supported from the following versions:

If you want to upgrade from any other version of SGD, or from Tarantella Enterprise 3 version 3.3 or earlier, contact Sun Support.

If are sure you want to perform an unsupported upgrade, you must create an empty file /install‐dir/var/UPGRADE before installing the new version of the software. Your SGD installation might not be upgraded correctly.

Before You Upgrade on Solaris OS Platforms

When you upgrade on Solaris OS platforms, the pkgadd command performs several checks and asks you to confirm the changes before installing the package. You can create an administration file that instructs pkgadd to bypass these checks and install the package without user confirmation.

To avoid user interaction, the administration file must contain the following lines:

conflict=nocheck
instance=unique

When you upgrade SGD, use the pkgadd -a adminfile command to specify the administration file.

If you do not specify an administration file when you upgrade, the SGD installation program creates one for you and gives you the option to quit the installation so that you can run the pkgadd command again with the -a adminfile option.

Before You Upgrade From Version 4.2 on Linux Platforms

On Linux platforms, if you are upgrading from SGD version 4.2, you must manually remove all the optional SGD software packs before upgrading.

To list all installed SGD software packs:


# rpm -qa | grep -i tta

The following are the optional SGD software packs:


Package SGD Software Pack Name
ttasecure Security Pack
tta3270 Mainframe Connectivity Pack
tta5250 AS/400 Connectivity Pack
ttafandr Andrew X fonts
ttafhang Hangul X fonts
ttaficl ICL X fonts
ttaforie Oriental X fonts
ttafscot SCO Term X fonts

To remove all optional SGD software packs:


# rpm -e package ...

Upgrades and Your Existing Configuration

When you upgrade, the following changes are applied to your existing configuration:


Performing the Upgrade

How you upgrade SGD depends on whether you are upgrading an evaluation version or a fully licensed version of SGD, and on whether you are upgrading a single-server or multiple-server array. If you have customized SGD, you might have to upgrade your customized files manually.

Upgrading Evaluation Versions of SGD

If an SGD server does not have a license key installed, or belong to an array that is fully licensed, the SGD server is in evaluation mode. After 30 days the evaluation period expires and the SGD server is in expired evaluation mode.

Upgrade an SGD server in evaluation mode or expired evaluation mode by installing the next version of the software.

An SGD server that was in expired evaluation mode remains in expired evaluation mode after the upgrade. You cannot log in to an SGD server when it is in expired evaluation mode.

To license a server when it is in expired evaluation mode, you must either use the tarantella license add command to add a valid license key, or join the server to an array that is already fully licensed.

procedure icon  How to Upgrade a Fully Licensed Single‐Server Array

  1. Make sure no webtop and emulator sessions are running in the array, including suspended sessions.

  2. Upgrade the server by installing the new version of SGD.

procedure icon  How to Upgrade a Fully Licensed Multiple‐Server Array

All SGD servers in a multiple-server array must run on the same version of the SGD software. This means that to upgrade an array, you must dismantle the array, upgrade each server independently, and then rebuild the array.

  1. Make sure no webtop and emulator sessions are running in the array, including suspended sessions.

  2. Dismantle the array.

    On the primary SGD server, detach the secondary SGD servers from the array:


    # tarantella array detach --secondary server
    



    caution icon

    Caution - Detach only one secondary SGD server at a time. Wait for the array change to be copied to all members of the array before detaching any more SGD servers. You can tell that this has happened when the tarantella status command returns the same result when you run it on each array member.



    When a secondary SGD server is detached from an array, it loses its license keys and, temporarily, you might not be able to log in to SGD on this host.

  3. Upgrade the primary SGD server by installing the new version of the software.

  4. Upgrade the secondary SGD servers by installing the new version of the software.

  5. Rebuild the array.

    On the primary SGD server, add the secondary SGD servers to the array:


    # tarantella array join --secondary server
    



    caution icon

    Caution - Add only one secondary SGD server at a time. Wait for the array change to be copied to all members of the array before adding any more SGD servers. You can tell that this has happened when the tarantella status command returns the same result when you run it on each array member.



    When a secondary SGD server is added to an array, it gains any license keys installed on the primary SGD server.

Upgrading a Customized SGD Installation

When you upgrade, the SGD installation program preserves the customized files it finds, but it does not upgrade them. These files have to be manually upgraded. Two sets of files might need to be upgraded:

Two types of customized files might need attention after you have upgraded:

Upgrading Customized SGD Web Server Files

When you upgrade, the SGD installation program backs up any customized SGD Web Server files it detects. Backed-up files and their locations are listed in the install‐dir/var/log/webservercustomized.list log file.

To upgrade the customized files, use utilities such as diff and patch to compare and merge the differences between the backed-up files and the files in the standard SGD installation.

The SGD installation program copies any bespoke SGD Web Server files it finds into the new installation. These files are not changed.

Upgrading Customized SGD Server Files

When you upgrade, the SGD installation program backs up the customized and bespoke SGD server files it detects and produces the following log files:

  • install-dir/var/log/upgraded.files - A summary of the changes.

  • install-dir/var/log/customized.list - A list of any files that an Administrator has edited or added.

  • install-dir/var/log/customizedchanged.list - A list of any files that an Administrator has edited that were changed by the upgrade.

  • install-dir/var/log/docrootjava.log - A list of new or modified Javatrademark technology files from the original installation.

Use these log files to identify the files that need to be manually upgraded.

procedure icon  How to Manually Upgrade Customized SGD Server Files

  1. Create a copy of the customized file.

  2. Identify the changes made between SGD versions.

    The customizedchanged.list log file lists the customized files that have to be manually upgraded. For each file listed in this log file, your system will have three versions of the file:

    • The old, customized version in one of the following directories:

      • install-dir/var/docroot.oldversion for classic webtop files.

      • install-dir/var/serverresources.oldversion for login scripts.

      • install-dir/etc/data.oldversion for other files such as color maps.

    • The old, uncustomized version in the install-dir/etc/templates.oldversion directory.

    • The new, uncustomized version in the install-dir/etc/templates directory.

    Use a utility such as diff to compare the old, uncustomized file with the new, uncustomized file. This highlights the changes made between SGD versions.

  3. Apply the changes to the customized file.

    Use a utility such as patch to apply the changes identified in Step 2 to the copy of your customized file.

  4. Copy the upgraded customized file into the correct location in the new SGD installation.

procedure icon  How to Manually Upgrade Bespoke SGD Server Files

  1. Create a copy of the bespoke file.

  2. Identify the changes made between SGD versions.

    The docrootjava.log and customized.list log files list the bespoke files that might have to be manually upgraded.

    The only way to upgrade bespoke files is to compare versions of the standard SGD files to identify changes that have taken place and then apply those changes to your bespoke files.

    Use a utility such as diff to compare the old, uncustomized file with the new, uncustomized file. This highlights the changes made between SGD versions.

    To identify the changes, compare the following files:

    • The old version of the standard SGD files in the install‐dir/etc/templates.oldversion directory.

    • The new version of the standard SGD files in the install-dir/etc/templates directory.

  3. Apply the changes to the bespoke file.

    Use a utility such as patch to apply the changes identified in Step 2 to the copy of your bespoke file.

  4. Copy the upgraded bespoke file into the correct location in the new SGD installation.


Upgrading Other SGD Components

This section describes how you upgrade the SGD Enhancement Module and the SGD Client.

procedure icon  How to Upgrade the SGD Enhancement Module for Microsoft Windows

procedure icon  How to Upgrade the SGD Enhancement Module for UNIX and Linux Platforms

When you upgrade the SGD Enhancement Module and you install the UNIX audio module, you might see a message that says the UNIX audio module is already running. This message displays because the SGD audio driver is currently in use and cannot be stopped. As the SGD audio driver has not changed in this release, this message can be safely ignored.

procedure icon  How to Upgrade the SGD Client Automatically

The SGD Client can only be upgraded automatically if both of the following are true:

  • The previous version of the SGD Client was installed automatically.

  • The user’s web browser has a supported Java Plug-in tool and Java technology is enabled.

  1. Close any existing web browser sessions.

  2. Start a new web browser session.

  3. Log in to SGD.

    See How to Log In to SGD.

procedure icon  How to Upgrade the SGD Client Manually

Follow this procedure only if the previous version of the SGD Client was installed manually.