Upgrade Guide

Overview

This guide provides information and instructions for downloading Sablime and upgrading a existing Sablime instance. You can upgrade directly to the latest version from any previous Sablime (you do not need to do any intermediate upgrades). First-time installers of Sablime should follow the instructions in the Installation Guide.

Your existing license should continue to work with the upgraded Sablime.

The upgrade process varies somewhat depending on which version of Sablime you are upgrading from. In general, the older your current version, the more work the process has to do in order to upgrade. The upgrade will take a minute or two to update the Sablime software, and then anywhere from a few seconds to a few minutes per product to convert your Sablime databases. The time is dependent on the size of your databases and the performance capabilities of your host machine.

This guide also includes information on special upgrades: binary upgrades to NFS or TCP/IP clients; and database-only upgrades to extra databases.

Technical Notes The Sablime software and the installation process are intended for use with the Korn shell (ksh).
The installation process and Sablime itself use perl (version 5.004_01 or later). The installation process uses gunzip to uncompress the downloaded file. These, as well as tar, sed, strings, and uname must be in the installer’s $PATH.
Note for Linux users: The shell variables $SHELL and $EXECSHELL must both be set to the location of ksh (normally /bin/ksh) and exported. $PWD must also be exported: pdksh, which is usually what /bin/ksh points to, does not export $PWD by default.

Download

Download the appropriate file (sab83_architecture.gz) from the Sablime v8.3 download page. Also download the installation script sablime_install.

If you did not download it there directly, move or copy the file(s) to your UNIX or Linux Sablime host machine.

Upgrade

  1. Log into the Sablime host as the user ID that owns the Sablime binaries and databases. Please log in as this user, rather than using “su”.

  2. Verify that the package file and the installation script are present in the current directory.

    $ls sab83*.gz sablime_install
    sab83_architecture.gz
    sablime_install
    
  3. Run your old Sablime setup script for a generic in the instance you wish to upgrade.

    $. set_sablime GEN
    (... normal Sablime setup script output ...)
    

    or

    $. sablime GEN
    (... normal Sablime setup script output ...)
    

    Users upgrading from v6.2 or later probably use the set_sablime version

  4. Run the installation script

    $ksh ./sablime_install
    

    or

    $ksh ./sablime_install -master=DIR
    

    The second version is for NFS clients only. DIR should be the path to the binaries of the primary installation.

    The script will now take a few minutes to perform the upgrade and report Installation complete after a successful upgrade.

    Usage Notes for sablime_install If you are upgrading a pre-v6.1u3 installation, there are some circumstances (depending on the technical setup of your web server) where the script will not be able to activate certain ID sensitive features such as “Web-only users” and “-as_user flag”). If your setup is one of these, sablime_install will tell you that you need to get someone with the necessary permissions to do the final steps. You can use Sablime without doing this, but those features (introduced in v6.1u3) will not be available.

    Sablime_install can be restarted if it is interrupted. You do not need to set the Sablime environment again to restart. The script will verify the upgrade location with you before proceeding with the interrupted upgrade.

    If you want to back-out the upgrade, you can re-run the script with the -revert option. Please note: Upgrades to Sablime v8.3 will include a database conversion. If you want to undo the upgrade you must undo the database conversion first. Run dbconvert -rollback first, and then run sablime_install -revert.

    The script reads the current web environment, including the settings in wsab.conf and any locally installed reports, before touching any files. These settings and reports are automatically applied to the upgraded configuration.

    New files are unpacked into a subdirectory before the current installation is modified. Files being replaced are moved to a backup area. Only files distributed as part of Sablime are moved; other files (license, $sabVAR files, etc.) are left in place.

  5. Update setup script invocations as necessary

    Sablime v6.2 included a new setup script set_sablime and a simplified process for updating it. See the online document New Initialization Process for full details. Users who have the setup script being called from their login script (i.e. their .profile file) should replace “. sablime” with “. set_sablime”. Likewise, any other scripts that include a call to the Sablime setup script should be updated. Users upgrading from v6.2 or later should already have this change in place.

  6. Remove the download file and the installation script (if desired).

    $rm sab83_architecture.gz sablime_install
    
  7. Optional: Remove the working files and backup files.

    The installation script makes a directory and stores working files there. Among them is a full tar backup of all the files that it replaced or removed. Once you are satisfied that the update is performing properly, you can remove the directory and its contents.

    $cd $sabLCB
    $rm -fr oldbin
    

    It is harmless (other than the disk space usage) to keep the directory around indefinitely.

  8. Upgrade Web Sablime

    If you are upgrading from Sablime v6.0u1 or later, the Web Sablime upgrade was done automatically as part of the sablime_install operation. Your upgrade is complete.

    If you are upgrading from v6.0 (no update), or from any pre-v6.0 version of Sablime, then you need to follow the instructions in the Web Sablime Installation and Upgrade Guide.

Secondary Upgrades - NFS and TCP/IP Clients and Additional Databases

Binaries-only Upgrades

Some Sablime users have more than one set of binaries addressing the same databases, where the databases are shared (via NFS) among multiple machines that may be of different architectures.

In these cases, the databases are upgraded by running the installation process on one machine. You still run the installation process on the other machines, but it notices that the databases don’t need upgrading and proceeds accordingly.

Similarly, if you have a TCP/IP client (where there is a set of binaries, but there are no local databases), you can run sablime_install there and it will only upgrade the binaries. Note that for TCP/IP clients only, you may need to update the file net_products in the config subdirectory.

Net_products tells Sablime where to find the databases and executables for products that are not accessible on the local machine. The following is a sample net_products, with callouts describing the (semi-colon separated) fields. The file may have multiple lines.

Net Products file format graphic

Databases-only Upgrades

The upgrade process attempts to find and upgrade all the product databases associated with a Sablime instance. It will also look in Web Sablime’s prodGen file, in case there are more products detailed there. If found, it will upgrade those as well.

There are still circumstances where a database will not be found by the upgrade process. For these additional databases, you simply need to run the old setup script (i.e. . set_sablime GEN) for a generic in that database, and then re-run sablime_install. It will notice that it does not need to upgrade the binaries again, but will proceed to upgrade the database, and add it to the list of products associated with this instance.


*  UNIX is a registered trademark of The Open Group.
Linux is the registered trademark of Linus Torvalds in the U.S. and other countries.

Sablime is a registered trademark of Alcatel-Lucent Inc.
Contents copyright © 2010-2015 Alcatel-Lucent. Permission to photocopy in support of a licensed installation of Sablime is hereby granted.