Upgrading Host Integrator from 7.0 to 7.x on UNIX/Linux

  • Document ID:7021582
  • Creation Date:13-May-2011
  • Modified Date:11-Mar-2018
    • Micro Focus Products:
      Verastream Host Integrator (VHI)

Environment

Verastream Host Integrator version 7.1 or higher

Situation

This technical note provides detailed steps to migrate Verastream Host Integrator (VHI) from version 7.0 to version 7.1 or higher in a Linux, Solaris, or AIX environment.

Note: If you are upgrading from version 6.6 or earlier, see KB 7021551 instead. If you are upgrading from version 7.1.221 or higher, see KB 7021586 instead.

Resolution

Use the following procedure to upgrade Verastream Host Integrator from version 7.0 to version 7.1 or higher on a Linux, Solaris, or AIX system. This document assumes a typical installation, which includes the Session Server, Management Server, Connector API, and Host Emulator components.

  1. From a Windows Server Kit or Development Kit version 7.0, run Administrative Console and connect to your Linux/Solaris management server with administrative profile credentials.
  2. Make a note of your existing administrative password (set during original installation, or changed in Management > Servers > Management Cluster > Change Admin Password), and review your existing 7.0 configuration.
  3. On your UNIX system (logged in with root privileges), make a note of your existing 7.0 installation directory:
cat /etc/vhi/installdir.txt

Note: In this document, substitute /opt/attachmate/verastream with the output from the above command.

  1. Stop the Host Integrator services:
cd /opt/attachmate/verastream
./hostintegrator/bin/atstart -stop all

Note: In a multiple-server installation environment(with management server failover cluster, as described in KB 7021563), it is strongly recommended that you stop services on all servers before proceeding.

  1. Back up your existing files:
    1. The following command will package up the required files and directories. Backslash characters are used at the end of a line for continuation.
cd /opt/attachmate/verastream
tar cvf /tmp/vhi7_config.tar \
hostintegrator/etc/sesssrvr.config \
hostintegrator/deploy \
hostintegrator/etc \
managementserver/services/directory/data \
managementserver/services/directory/META-INF/replicadata.xml \
managementserver/services/peermgmt/data \
managementserver/etc

The resulting vhi7_config.tar file includes existing session server configuration, deployed models, model debug messages and session server log (if using default locations), and management server data.

Note: Do not restart the system until completing the remaining steps, as this may clear the /tmp directory contents.

    1. If you are using SSL/TLS encryption for host connections, and the host requires a client certificate, back up your certificate.pem file:
mkdir /tmp/vhi7
cp -r ./hostintegrator/securehost /tmp/vhi7

Note: In version 7.0, the securehost subdirectory only exists if it was manually created.

  1. Note any custom web service SOAP stack configuration in the service-ctx.xml file located in the /opt/attachmate/verastream/hostintegrator/lib/container/services/ws/META-INF directory. If the file was edited (as indicated by a time/date stamp newer than other installed files), it is suggested you make a backup copy (outside the installation directory) to be used as a guide for configuring web services later in steps 11 and 13c. For more information about settings in this file, see KB 7021550.
  2. Uninstall version 7.0:
    1. Run the uninstall script from the basepath directory:
cd /opt/attachmate/verastream
sh vhi_uninstall.sh --all
    1. When prompted to confirm, enter yes.
Are you sure you want to remove the Session Server and the Management Server (in /opt/attachmate/verastream)? (yes/no) [no] _

The session server and management server are stopped, files are deleted, and the base directory is removed.

  1. Install version 7.1 or higher by expanding the downloaded .tar file (with tar xvf) and running the resulting installer file (for example, sh linux/vhisrv-7.1.221-prod-linux).

Note the following:

    • Install to the same directory that was used for version 7.0 (since the original directory paths are stored in configuration data).
    • Install the same components as you did for version 7.0 (typical vs. custom; session server, management server, connector API).
    • During installation, enter the same administrative password that was set in version 7.0.
    • On IBM platforms (Linux on System z, or AIX), IBM JDK must be installed before installing VHI. Beginning in VHI version 7.6, 64-bit Java must be installed. For earlier VHI versions, 32-bit Java must be installed. See also KB 7021532.
    • For more information on the interactive installer, command line options, or unattended install input file, refer to the Installation Guide available from https://support.microfocus.com/manuals/vhi.html.
  1. After installation completes, stop the Host Integrator services:
cd /opt/attachmate/verastream
./hostintegrator/bin/atstart -stop all
  1. Migrate the files backed up in step 5 above:
    1. Restore the configuration data from step 5a:
tar xvf /tmp/vhi7_config.tar
    1. If you backed up a certificate.pem file in step 5b, restore it:
cp /tmp/vhi7/securehost/certificate.pem /opt/attachmate/verastream/hostintegrator/securehost

(Beginning in version 7.1, the securehost subdirectory is created by the installer.)

Note: In a multi-server installation environment (with management server failover cluster), repeat steps 1 through 10 on all servers before continuing.

  1. Restore any custom web service SOAP stack configuration. Examine your backed-up service-ctx.xml file from step 6 above, and follow the appropriate procedure below, depending on which version you are upgrading to.

Upgrading to Version 7.1.1142 (Service Pack 1) or higher:

Note: Beginning in version 7.1.1142, the service-ctx.xml file is no longer used for customizing your web services configuration.

If you need to set custom (non-default) values for any of the following, see KB 7021550.

    Description
    		Property in Versions 7.0.961 through 7.1.221
    		Default
    HTTP web service port
    		hostPort
    		9680
    HTTPS web service port
    		secureHostPort
    		9681
    Session server load distribution domain
    		domainName
    		(commented out)
    Non-local management server for load distribution domain
    		serverName
    		localhost (commented out)
    HTTP basic authentication for client user authorization without WS-Security
    		authnMetadata and authnService
    		False

Note: Other properties are configured later in step 13c below.

Upgrading to Version 7.1.221:

Using the backed-up version 7.0 service-ctx.xml file from step 6 as a guide, edit your installed version 7.1.221 file located in the /opt/attachmate/verastream/hostintegrator/lib/container/services/ws/META-INF directory. Note: Do not replace the installed 7.1.221 file with the previous 7.0 file, as there are new settings available in version 7.1.221. For more information about settings in this file, see KB 7021550.

  1. Start the Host Integrator services:
cd /opt/attachmate/verastream
./hostintegrator/bin/atstart -start all

Verify the services are successfully started:

./hostintegrator/bin/atstart -status all
LogMgr Started
Server Started
HostEmul Started
MgmtServer Started

Note: If you see the message "TCP listening port required by the requested VHI service is in use" and one of the services is not started, wait 2 minutes and enter an additional command to start that service (such as atstart -start logmgr).

  1. Restore previous settings and verify successful migration:
    1. From a Windows Server Kit or Development Kit (same version as your UNIX/Linux installation), run Administrative Console. Note: For information about upgrading your Windows installation to version 7.1, see KB 7021581.
    2. Connect to the management server on UNIX and log in with the user name admin and the administrative password.
    3. If you are upgrading to version 7.1.1142 (Service Pack 1) or higher, examine your backed-up service-ctx.xml file from step 6 above. If you previously set custom values for any of the following properties, re-configure them in the Administrative Console application.
      Description
      		Property in Versions 7.0.961 through 7.1.221
      		Default
      WS-Resource and WS-Addressing
      		wsResourceEnabled *
      		true (commented out)
      ExecuteSQLStatement web method
      		executeSqlStatementEnabled
      		true (commented out)
      processString web method
      		processStringEnabled
      		true (commented out)
      Milliseconds to wait for session server to return from table procedure
      		methodTimeout **
      		60000 (commented out)
      Minutes before session server destroys suspended sessions (applicable using WS-Resource stateful web services)
      		suspendTimeout *
      		60 (commented out)
*Supported in version 7.1.221 only.
**Supported in versions 7.0.982 through 7.1.222 only.
    1. Examine the rest of your configuration to verify migration was successful.

Web Services

After upgrading to version 7.5 SP1 or higher, you may need to re-import the VHI web services WSDL in your SOAP tool, due to changes in the target namespace (as described in KB 7021323) and changed default for WS-Addressing and WS-Resource (see also KB 7021336).

Web Builder Projects

If you had previously separately installed Apache Tomcat/Axis to run a Java web application (or Java web service) project generated in Web Builder version 7.0, this is no longer necessary beginning in version 7.5, as VHI Web Server is included in UNIX Server Kit.

For information about deploying new HTML 5 web application projects to version Server Kit 7.5 on UNIX/Linux, see http://docs2.attachmate.com/verastream/vhi/7.5/en/topic/com.attachmate.vhi.webbuilder.help/html/reference/html5_deploy_apps.xhtml.

For information about deploying existing (pre-7.5 "legacy") Java projects to version Server Kit 7.5 on UNIX/Linux, see http://docs2.attachmate.com/verastream/vhi/7.5/en/topic/com.attachmate.vhi.webbuilder.help/html/reference/wb_implement_apps.xhtml.

Additional Information

Legacy KB ID

This article was originally published as Attachmate Technical Note 10122.