Attachmate Worldwide  |   Contact Us  |   NetIQ.com
Home » Support » Solution Library

Technical Notes

Upgrading to Host Integrator 5.5 in a Linux/UNIX Environment
Technical Note 40022
Last Reviewed 21-Jul-2006
Applies To
Verastream Host Integrator version 4.5 through 5.5
Summary

This technical note provides detailed steps to upgrade Verastream Host Integrator to version 5.5 in a Linux/UNIX environment. The upgrade process includes backing up files, removing the existing installation, installing version 5.5, and migrating the existing configurations and host application models.

This document contains two primary sections:

Before You Begin
Steps to Upgrade

Before You Begin

The Host Integrator 5.5 installation requires the previous installation to be removed; however, the Steps to Upgrade enable you to preserve your existing configurations and host application models.

We strongly recommend that you upgrade all components to version 5.5 because some earlier components are not compatible with the 5.5 components. If you have questions about upgrading your Host Integrator installation, contact Attachmate Technical Support, http://support.attachmate.com/contact/, before you begin.

Supported Platforms and System Requirements

Before you upgrade, review the following platforms, components, and versions supported in Host Integrator 5.5.

Host Integrator Components
Supported Linux/UNIX Platforms and Requirements
Host Integrator server
(includes AADS, Administrative WebStation, Session Server, Web Server, Host Emulator, Help, Log Viewer, Session Monitor)
Sun Solaris 8 (SunOS 2.8) or higher
Red Hat Linux (for Intel X86) versions 7.3 and 8
Red Hat Enterprise Linux 3.0 (supported in Verastream Host Integrator version 5.5.500 starting in June 2004)
Web client requirements
(to run the Administrative WebStation and applications generated by the Web Builder)
Mozilla 1.4 on Red Hat Linux 7.3 and 8 or Red Hat Enterprise Linux 3.0, with the Java plug-in installed with Mozilla
Mozilla 1.5 on Sun Solaris 8 (SunOS 2.8) with the Java plug-in installed with Mozilla
Java requirements

JRE version 1.4
Tomcat version 4.1
Java browser plug-in version 1.4

Note the following:

  • The Development Kit, which includes the Design Tool and Web Builder, is supported only on Windows platforms. See Technical Note 40021 for upgrading Host Integrator components in a Windows-based environment.
  • Beginning with version 5.5, IBM AIX and HP-UX are no longer supported.

Upgrade Overview

In the Linux/UNIX environment, upgrading Host Integrator to version 5.5 requires this sequence of steps, which are detailed in the remaining sections of this note.

1. Back up the existing files.
2. Remove the existing installation.
3. Install all Host Integrator 5.5 components—except the server.
4. Migrate the AADS settings.
5. Install the Host Integrator server.
6. Migrate the Administrative WebStation.
7. Migrate the host application models.
8. Start all components and verify the success of the upgrade.

Steps to Upgrade

This set of steps assumes the following simple Host Integrator scenario:

  • All Host Integrator components are installed on the same Linux/UNIX machine.
  • The Authentication, Administration, and Directory Services (AADS) is not linked to any other Host Integrator servers on any other machines.
  • The models will be migrated now and upgraded in the Design Tool (on a Windows PC) at a later time.

If your Host Integrator installation is more complex (with more than one AADS, for example), contact Attachmate Technical Support (http://support.attachmate.com/contact/) before proceeding with the steps in this technical note.

Follow these steps to upgrade your Host Integrator components to version 5.5.

  1. Log in as root on your Linux/UNIX machine.

Back up the existing files

Although you can install the Host Integrator files to a directory of your choice, the steps in this technical note refer to the install directory as /usr/vhi.

  1. Back up the following files from the existing installation:
    1. Copy the /usr/vhi/etc directory to a temporary directory. In this technical note, the temporary directory is /tmp/vhi.
mkdir /tmp/vhi
cp -r /usr/vhi/etc /tmp/vhi

    1. If you are upgrading an Administrative WebStation, look for the console.install file in /usr/vhi/lib/java.

This file exists only if the Administrative WebStation was run locally in a browser on the machine where the Host Integrator server is installed. If console.install is not present, skip to step 2c.

Copy the console.install file to the temporary directory:

cp /usr/vhi/lib/java/console.install /tmp/vhi

    1. Copy the models directory, /usr/vhi/models, to a location outside of the existing Host Integrator installation directory, such as the temporary directory:
cp -r /usr/vhi/models /tmp/vhi
  1. Before you uninstall the existing Host Integrator installation, make a note of the current settings:

On the Linux/UNIX machine:

    • The location of the existing Host Integrator installation

In the Administrative WebStation:

    • Host Integrator domain server settings
    • LDAP authentication settings (Note: The LDAP settings cannot be migrated; you will need to restore these after the upgrade.)
    • AADS list
    • Security: enabled or disabled

Remove the existing installation

  1. Stop all running services:
/usr/vhi/bin/atstart -stop all

  1. Remove the existing Host Integrator installation:

Run the Verastream Host Integrator 5.5 Setup to uninstall Host Integrator. Respond yes when prompted to completely remove the existing Verastream Host Integrator Installation.

sh install.sh -clean

Install all Host Integrator 5.5 components–except the server


When upgrading in the Linux/UNIX environment, the AADS must be installed and the AADS settings migrated before the Host Integrator server is installed.

  1. Run the Verastream Host Integrator 5.5 Setup to install all components except the server.
    1. Install version 5.5 into the same directory where the previous version was installed. This technical note refers to the install directory as /usr/vhi.

Use the command below to install all components except the server. Or, edit the line to install only the components you want to install now.

Choose from this list of components:

aads—AADS server
apicpp—Appconn Connector for C
apijava—AppConn Connector for Java
help—product help
hostemul—Host Emulator
logutils—Log Viewer and Export utility
smonitor—Session Monitor
webstation—Administrative WebStation
sh install.sh -installdir /usr/vhi –components
aads:apicpp:apijava:help:hostemul:logutils:smonitor:webstation

    1. Accept the defaults and proceed with the installation.
    2. When prompted, do not start the AADS.
  1. When Setup is complete, confirm that all of the components are stopped:
/usr/vhi/bin/atstart -stop all

Migrate the AADS settings

  1. To preserve the AADS configuration, copy the saved files (that you backed up in step 2) to the new installation directory. (Some of these files may not exist in your installation):
cp /tmp/vhi/etc/aads/.bindings /usr/vhi/etc/aads
cp /tmp/vhi/etc/aads/.keystore /usr/vhi/etc/aads
cp /tmp/vhi/etc/aads/aads.properties /usr/vhi/etc/aads
cp /tmp/vhi/etc/aads/cert.fingerprint /usr/vhi/etc/aads
cp /tmp/vhi/etc/aads/domains/.bindings /usr/vhi/etc/aads/domains
cp /tmp/vhi/etc/aads/servers/.bindings /usr/vhi/etc/aads/servers
cp /tmp/vhi/etc/aads/profiles/.bindings /usr/vhi/etc/aads/profiles
  1. Use the shell script below to run the java program, com.wrq.apptrieve.aads.apps.ConfigureAADS, which upgrades the aads.properties file.
    1. Copy and paste this shell script into a Linux/UNIX editor and save the file as upgrade-aads.sh.

If you prefer, you can download the upgrade-aads.sh script from the Download Library to your Linux/UNIX machine.

Note: You must use a Linux/UNIX editor to create and save this shell script in order to avoid misinterpreted line terminations.

#!/bin/sh
# turn on xtrace (useful for debugging)
set -x 
if [ ! -f /etc/vhi/installdir.txt ] ; then
  echo 1>&2 "Cannot find VHI installation"
  exit 1
else
  rootcontext=`cat /etc/vhi/installdir.txt`
fi
server=""
while [ $# -gt 0 ]
do
  case $1 in
    help|-h*)
      echo 1>&2 "usage: $0 <AADS machine name>"
      echo 1>&2 "Migrate AADS configuration to 5.5 format"
      exit 1
      ;;
    *)            
      server=$1        
      break
      ;;
  esac
  shift
done
if [ "$server" = "" ] ; then
  echo 1>&2 "usage: $0 <AADS machine name>"
  echo 1>&2 "Migrate AADS configuration to 5.5 format"
  exit 1
fi
# set up the classpath
for i in $rootcontext/lib/java/*.jar
do
  cp=$i:$cp
done
# run the program itself - backslashes must be followed 
# immediately by carriage returns (no intervening characters)
$rootcontext/jre/bin/java -cp $cp \
com.wrq.apptrieve.aads.apps.ConfigureAADS \
-upgrade \
-server  $server \
-rootcontext $rootcontext
set +x
exit $?

    1. Invoke the script by typing the following command, where <AADS> is the fully-qualified name of the AADS running on the server.
sh upgrade-aads.sh <AADS>

If you did not install an Administrative WebStation, skip to Install the Host Integrator server.

Migrate the Administrative WebStation

  1. Restore the Administrative WebStation configuration file:
cp /tmp/vhi/console.install /usr/vhi/lib/java/console.install

  1. Start the Administrative WebStation:
/usr/vhi/bin/atstart -start webstation

Install the Host Integrator server

  1. To install the Verastream Host Integrator 5.5 server:
sh install.sh –installdir /usr/vhi –components server

Do not start the server when prompted. If the server starts before the model files are migrated, errors will be logged.

  1. Restore the session server configuration file:
cp /tmp/vhi/etc/sesssrvr.config /usr/vhi/etc

Migrate the host application models


The steps in this section direct you to migrate the model files to preserve existing settings. However, to take advantage of the 5.5 model features, such as event handling, each model must be opened and saved in the Design Tool (on a Windows PC) at a later time.

  1. The migration to 5.5 requires that model names be lower case and that the model and deploy directory names exactly match the corresponding model file name. If there are any mixed-case names (such as CCSDemo) or mis-matched directory names, the model names and the associated directories must be changed to lower case; then the files must be moved to the deploy directory.

To correct the model file names and case, you can either Run a script for multiple models or Manually edit and move individual files, using the steps outlined below.

Run a script for multiple models

Follow the steps in Appendix A: Renaming and Moving Multiple Models to change the model names to lower case and copy the model files to the deploy directory.

The steps also instruct you to edit the session server configuration (sesssrvr.config) file.

Manually edit and move individual files

Follow these steps to manually edit the model file name, edit the model directory, move the model files, and edit the session server configuration file.

These steps refer to an example of an existing model with a mixed-case name: /usr/vhi/models/CCSDemo/CCSDemo.model

    1. Copy the model directories from your temp directory (saved in step 2c) into the /usr/vhi/models directory. For example:
cp –r /tmp/vhi/models/CCSDemo /usr/vhi/models
    1. Rename the model file to a lower-case name:
mv /usr/vhi/models/CCSDemo/CCSDemo.model /usr/vhi/models/CCSDemo/ccsdemo.model
    1. Rename the model directory to match the model name:
mv /usr/vhi/models/CCSDemo /usr/vhi/models/ccsdemo
    1. Confirm that the Host Integrator server is not running. (If the server starts and finds an invalid model configuration in its configuration file, the config file will be ignored and appropriate error(s) will be logged.)

Copy each saved model to the Host Integrator 5.5 deploy directory. For example, to copy ccsdemo:

cp -r /usr/vhi/models/ccsdemo/ccsdemo.model /usr/vhi/deploy/ccsdemo/ccsdemo.model
    1. Edit the session server configuration (sesssrvr.config) file to change every instance of the model name to lower case. Follow the steps in Appendix B: Editing the Session Server Configuration File.

Start all components

  1. Use this command to start all components, including the Host Integrator server:
/usr/vhi/bin/atstart -start all

At this point, the Host Integrator server is expected to recognize the original model file/directory structure and upgrade the models in the 5.5 deploy directory. Models are automatically moved to version-numbered subdirectories.

  1. Open the Administrative WebStation to confirm that your models are activated and to confirm or restore the settings that you noted in step 3:

Host Integrator domain server settings

LDAP authentication settings

Security: Enabled

Note: If you did not install an Administrative WebStation on the Linux/UNIX machine, you can use an Administrative WebStation on a different machine and point to the Linux/UNIX server.


Appendix A: Renaming and Moving Multiple Models

Follow these instructions to change multiple model names to lower case and then move them to the deploy directory on the Linux/UNIX machine.

  1. Copy the models you saved in the temp directory (from step 2c) and save them into the /usr/vhi/models folder.
cp –r /tmp/vhi/models /usr/vhi

Note: Before you run the script (below), confirm that Host Integrator server has been upgraded to 5.5 and that the session server is stopped.

  1. Copy and paste the following shell script into a Linux/UNIX editor and save the file as deploy_models.sh.

If you prefer, you can download the deploy_models.sh script from the Download Library to your Linux/UNIX machine.

Note: You must use a Linux/UNIX editor to create and save this shell script in order to avoid misinterpreted line terminations.

#!/bin/sh

# Obtain the VHI install directory here.
installdir=`cat /etc/vhi/installdir.txt`
echo "VHI Installation directory : $installdir"

# Create a newmodels/ directory, to which a copy of down-cased 
# and consistently named model files will be made.
rm -r $installdir/newmodels
mkdir $installdir/newmodels

# For each model file in <VHI InstallDir>/models/*/*.model
files=`ls -d $installdir/models/*/*.model`
for modelFile in $files
do
# Obtain the model file's base name and convert to lower case
  base=`basename $modelFile .model | tr '[A-Z]' '[a-z]'`

# Create the destination directory for deployment
  echo Creating directory "$installdir/deploy/$base"
  mkdir $installdir/deploy/$base    
# Create destination directory for newmodels/
  mkdir $installdir/newmodels/$base

# Copy our model file into the deploy directory.
  echo "    Copying $modelFile  ==> $installdir/deploy/$base/$base.model"
  cp $modelFile $installdir/deploy/$base/$base.model
  cp $modelFile $installdir/newmodels/$base/$base.model
done
#
# Rename the models/ and newmodels directory
# mv -f models/ oldmodels/
# mv –f  newmodels/ models/
#

  1. Run the script.
  2. After you run the script, rename /installdir/models to oldmodels/.
  3. Rename /installdir/newmodels to models/.
  4. Continue with Appendix B: Editing the Session Server Configuration File.

Appendix B: Editing the Session Server Configuration File

Edit the server configuration (sesssrvr.config) file to change every instance of the ModelName “model” entry from mixed case to lower case.

Note: In addition to the Model configuration shown here, you must also revise the ModelName “model” entry under the Session Pool configuration section, if applicable.

In this sample sesssrvr.config file, change the model name (highlighted in red) from mixed case (CCSDemo) to lower case (ccsdemo).

Sample session server configuration file:

Model
    ModelName "CCSDemo"
    Version "Aug 21 10:51:18 2001"
    ValidationStr "Apptrieve 4.5.1 Model v0998416278:1:0439122554 "
    Host "myhost"  
    HostPortID 1099
/Model


The corrected string appears as follows:

Model
    ModelName "ccsdemo"
    Version "Aug 21 10:51:18 2001"
    ValidationStr "Apptrieve 4.5.1 Model v0998416278:1:0439122554 "
    Host "myhost"   
    HostPortID 1099
/Model


After you run this script, continue with the steps to Start all components.

Related Technical Notes
10028 Features Introduced in Verastream Host Integrator 5.5
10030 Supported Platforms and Systems Requirements for Verastream Host Integrator
40021 Upgrading Host Integrator 5.0 to 5.5 in a Windows-Based Environment
40023 Compatibility Settings in Verastream Host Integrator
40030 Upgrading to Host Integrator 6.5 in a Linux/UNIX Environment
40999 Verastream Host Integrator Technical Notes

Did this technical note answer your question?

Yes    No    Somewhat     Not sure yet

Additional comments about this tech note:

Need further help? For technical support, please contact Support.