Cisco H.323 Signaling Interface User Guide, Release 4.3 - Installing and Configuring Cisco HSI Software [Cisco PGW 2200 Softswitch]

Table Of Contents

Installing and Configuring Cisco HSI Software

Introduction

Installing the Operating System

Installing the Cisco HSI

Before You Start

Configuring Groups and Users

Cisco HSI Installation Information

Installing Cisco HSI

Installing Multiple Cisco HSIs in a Redundant PGW 2200 Configuration

Configuring a Redundant Deployment

HSI Software Licensing

Requesting the License File

Installing the License File

Verifying the License

Viewing License File Operations

Starting the Cisco HSI

Stopping the Cisco HSI

Configuring the Cisco HSI

Installing Cisco HSI Patches

Minimizing Dropped Calls During Patch Installation

Upgrading the Cisco HSI to a New Release

Migrating from HSI 4.1 or 4.2 to HSI 4.3

Removing the Cisco HSI

Installing and Configuring Cisco HSI Software

Revised: April, 2010, OL-11616-08

Introduction

This chapter contains instructions for installing and configuring the Cisco H.323 Signaling Interface (HSI). This chapter contains the following sections:

•Installing the Operating System

•Installing the Cisco HSI

•HSI Software Licensing

•Starting the Cisco HSI

•Stopping the Cisco HSI

•Configuring the Cisco HSI

•Upgrading the Cisco HSI to a New Release

•Removing the Cisco HSI

Installing the Operating System

The Cisco HSI Release 4.3 operates on a platform running the Sun Solaris 10 operating system.

The appropriate operating system must be installed before you install the Cisco HSI. Instructions for installing the operating system on the appropriate platform are in the Cisco Media Gateway Controller Software Release 9 Installation and Configuration Guide, located at the following URL:

http://www.cisco.com/univercd/cc/td/doc/product/access/sc/rel9/swinstl/index.htm

Note Initially, see the following document for software requirements: Release Notes for the Solaris 10 Environment Packages.

After completing the operating system installation, return to this document for Cisco HSI installation procedures.

Installing the Cisco HSI

This section provides step-by-step instructions for installing the Cisco HSI.

Before You Start

Complete the preinstallation tasks listed in Table 2-1 before installing the Cisco HSI. Use the checklist to ensure that each task is completed. Detailed instructions for completing some tasks follow the checklist.

Table 2-1 Preinstallation Tasks Checklist

Check

Preinstallation Task

Ensure that the required operating system is installed on the appropriate hardware platform.

Obtain the appropriate HSI software license required to operate the HSI software. See the"HSI Software Licensing" section.

Configure group and user names, as described in the "Configuring Groups and Users" section.

Gather the information listed in Table 2-2 and note it in the table for reference during the installation.

Have your company internal support information and Cisco support contact information readily available so you can get help with the installation if needed. If you have questions or need assistance, see the section, "Obtaining Technical Assistance" in the Preface, page 1.

Configuring Groups and Users

You must configure groups and users for the Cisco HSI on each host server. A user must be a member of the "mgcgrp" group to use certain Cisco HSI functions, such as Man-Machine Language (MML).

To configure groups and users, complete the following steps:

Step 1 Log in as root.

Step 2 At the # prompt, enter the following commands:

# mkdir -p /export/home/users/mgcusr

# mkdir /export/builds

# mkdir /export/patches

# cd /export/home/users

# groupadd -g 20000 mgcgrp

# useradd -u 20001 -g 20000 -d /export/home/users/mgcusr -s /bin/csh mgcusr

# chown mgcusr:mgcgrp mgcusr

# passwd mgcusr <type password twice>

(Enter and confirm password)

Step 3 Log out, then log in as user mgcusr, using the password you applied in Step 2.

Step 4 Verify that you are in directory /export/home/users/mgcusr by entering the following command:

% pwd

Step 5 Enter the following command:

% vi .cshrc

Step 6 Enter the vi insert mode by entering the following command:

i (enter insert mode)

Step 7 Enter the following text on the first line:

source /opt/GoldWing/currentPM/local/setup.gw.csh

Note You use the setup.gw.csh script to set up the Unix user environment variables so that the path /opt/GoldWing/currentPM/bin is added. This enables a user to execute the Cisco MML interface (the mml command) and also sets up useful Unix aliases.

Step 8 Save the file and quit vi by entering the following commands:

[Esc] (exit insert mode)

:wq (write file and quit)

Step 9 Enter the following command:

# chmod 777 .cshrc

Cisco HSI Installation Information

Gather the information listed in Table 2-2 before you begin the Cisco HSI installation. Use the Notes column in this table to record the information. Several steps in the installation procedure require you to provide this information. Refer to this table as you proceed through the Cisco HSI installation steps.

Table 2-2 Cisco HSI Installation Information

Required Information

Notes

Cisco HSI user name

Default: mgcusr

Cisco HSI group name

Default: mgcgrp

Gatekeeper IP address

This is not required if the Cisco HSI is to operate in non-gatekeeper mode (in this mode, the Cisco PGW 2200 provides the destination IP address information to the HSI instead of a gatekeeper).

Gatekeeper port

Typically, this is port 1719.

Gateway prefix

Terminal alias

Gatekeeper ID

This ID must match the entry configured in the gatekeeper.

EISUP host port

Typically 8003, but this entry must match the peer port setting of the IPLNK object in the PGW 2200 configuration.

PGW1 name (either the DNS¹ host name, if DNS is configured, or the IP address of the Cisco PGW 2200²)

The PGW1 name is the DNS host name (if DNS is configured) or the IP address of interface hme0 of the Cisco PGW 2200.

PGW1 port

This is the port number for EISUP from interface hme0 of the Cisco PGW 2200.

Typically 8003, but this entry must match the peer port setting of the IPLNK object in the PGW 2200 configuration.

¹DNS = domain name system

²PGW = PSTN Gateway

Cisco HSI Software Directory Structure

The Cisco HSI application is distributed as a tar file (with filename GoldWing-xxxx.tar in which xxxx is the version ID, for example, GoldWing-4.3.2.tar) or as a CD-ROM.

The default installation directory is /opt/GoldWing. (GoldWing is an internal Cisco identifier for the Cisco HSI product.) Cisco recommends that you use the default installation directory to enable all scripts to reference the correct location.

The software automatically installs in this default location, under a subdirectory called 4.3.x (for example, /opt/GoldWing/4.3.2).

To enable all scripts to reference the current release of software, there are two software links called /opt/GoldWing/currentPM and /opt/GoldWing/currentGW that both point to the desired software release (for example, 4.3.2).

Table 2-3 shows the subdirectories of the /opt/GoldWing/currentPM directory.

Table 2-3 CurrentPM Subdirectories

Subdirectory

Contents

./bin

All compiled executables.

./local

All scripts.

./etc

Base configuration files.

./lib

Shared libraries required by executables.

./toolkit

Toolkit files.

./var

Volatile directory that contains file locks and so on.

./var/log

Default log directory.

./var/prov

Provision system writes provisioning configuration files here.

./var/trace

Trace logs are written here.

Exported provisioning files are stored in /opt/GoldWing/export.

Installing Cisco HSI

This section provides step-by-step instructions for installing a single Cisco HSI for use with a simplex PGW 2200 configuration (a configuration with one Cisco PGW 2200 host). To install a dual Cisco HSI for use with a redundant PGW 2200 configuration (a configuration with two Cisco PGW 2200 hosts), complete the steps in this section and then proceed to the "Installing Multiple Cisco HSIs in a Redundant PGW 2200 Configuration" section.

As part of the installation procedure, the Cisco HSI software prompts for some configuration values (for example, the IP address of the Cisco PGW 2200). This information is used to create a quick base configuration. When the software is installed, it operates using the base configuration. You can perform additional configuration later using the Cisco HSI MML user interface.

During the installation procedure, enter the correct values as presented in the prerequisites instead of dummy values, except for the gatekeeper IP address. As part of the quick base configuration, the Cisco HSI always assumes that it is to operate with a gatekeeper.

To operate the HSI in non-gatekeeper mode, you must enter an MML command later to change the operation mode. If you wish to operate the Cisco HSI in non-gatekeeper mode, you can enter a dummy value during the installation procedure for the gatekeeper IP address (for example, 10.20.30.40).

Note In the following installation procedure, the package name is OTTgw000 and the version of the software is 4.3.2; the /export/builds directory is used to install the system software.

To install the Cisco HSI, complete the following steps:

Step 1 Verify that a Unix group and user have been created (see the section, "Configuring Groups and Users").

Step 2 Log in as root.

Step 3 Issue the command: cd /export/builds

Step 4 The initial step for downloading the HSI software depends upon the media from which you obtain the software:

•If you download the software from a server, it will be in a tar file. Issue the following command:

# tar xvf GoldWing-4.3.2.tar

This command displays the following text:

x ./4.3.2/APPLICATIONS, 0 bytes, 0 tape blocks
x ./4.3.2/APPLICATIONS/OTTgw000.pkg, 38954496 bytes, 76083 tape blocks
x ./4.3.2/install.sh, 5223 bytes, 11 tape blocks
x ./4.3.2/uninstall.sh, 3053 bytes, 6 tape blocks

Note The byte and block counts for your installation might be different from those provided in the preceding example.

•If you download the software from a CD-ROM, insert the Cisco HSI 4.3.2 CD-ROM into the drive and issue the following commands:

# mkdir builds/4.3.2
# cp -r /cdrom/hsi_4.3.2/* /export/builds/4.3.2

Step 5 At the # prompt, enter the following commands:

# cd /export/builds/4.3.2
# ./install.sh

Note Be sure to type correct and valid entries when executing this installation script. The entries become part of the base configuration of the HSI (see the command description restart-softw, page A-23). If, at a later date, a new and incorrect configuration is entered, the HSI reverts to the base configuration when it is restarted.

The following text displays:
Processing package instance <OTTgw000> from 
</export/builds/4.3.2/APPLICATIONS/OTTgw000.pkg>
Cisco HSI (GoldWing) H323 Adjunct Processor V4.3(2)
(sparc) 4.3.2
Copyright (c) 2007 Cisco Systems, Ltd.
All Rights Reserved
This product is protected by copyright and distributed under 
licenses restricting copying, distribution and decompilation.
Enter GoldWing base directory path (default /opt/GoldWing) [?,q] 
Step 6 Press Enter to select the default GoldWing base directory path. The following text displays:
Enter SNMP base directory path (default /opt/GoldWing/currentPM/bin) [?,q] 
Step 7 Press Enter to select the default SNMP base directory path.

The following text displays:
Enter base directory path (default /opt/GoldWing/4.3.2) [?,q]
Caution We strongly recommend that you select the default base directory path. Operational issues might arise if other directories are used.

Step 8 Press Enter to select the default base directory path. The following text displays:
Enter GoldWing user name
Step 9 Type the Cisco HSI user name mgcusr and press Enter (the default user name is cisco). The following text displays:
Enter GoldWing group name 
Step 10 Type the Cisco HSI group name mgcgrp and press Enter (the default user group name is sysadmin). The following text displays:
Enter GateKeeper IP Address 
Step 11 If you are using a gatekeeper with the Cisco HSI, you must enter a valid gatekeeper IP address. If you intend to run the Cisco HSI in non-gatekeeper mode, you can enter an invalid IP address (for example, 10.20.30.40). You must modify the configuration later to operate the Cisco HSI in non-gatekeeper mode by entering an MML command.

Type the gatekeeper IP address (see Table 2-2) and press Enter. The following text displays:
Enter GateKeeper Port
Step 12 Type the gatekeeper port (see Table 2-2) and press Enter (the default port is 1719). The following text displays:
Enter GateWay Prefix
Step 13 Type the gateway prefix (see Table 2-2) and press Enter.

Note The gateway prefix is any E.164 numeric value (for example, 9 or 044). The Cisco HSI uses the prefix to register to the gatekeeper. (For operating the HSI in non-gatekeeper mode, the gateway prefix can be any value.)

When a call is made from the H.323 network (that is, an H.323 endpoint or gateway) with this prefix, the gatekeeper directs the call to the Cisco HSI, which automatically forwards the call to the Cisco PGW. After the HSI is installed, you can add more prefix entries to the configuration by entering MML configuration commands.

The following text displays:
Enter Terminal Alias
Note The terminal alias can be a text string (for example, hsi1@OuterLondonDomain.com, which used to identify the HSI).
Step 14 Type the terminal alias (see Table 2-2) and press Enter. The following text displays:
Enter GateKeeper Id
Step 15 Type the gatekeeper ID (see Table 2-2) and press Enter.

Note Typically, the gatekeeper ID (or gatekeeper name) is a text string assigned to the gatekeeper. The gatekeeper ID value that you enter must match exactly the gatekeeper configuration. The value is case-sensitive. For Cisco gatekeepers, use the IOS command zone local to define the gatekeeper ID.

The following text displays:
Enter EISUP Host Port
Step 16 Type the EISUP host port (see Table 2-2) and press Enter.

Note The EISUP host port is typically 8003, but it must match the peer port setting of the IPLNK object in the PGW 2200 configuration.

The following text displays:
Enter PGW1 Name
Step 17 Type the PGW1 name and press Enter.

Note The PGWI name is either the DNS host name (if DNS is configured) or the IP address of the PGW 2200.

The following text displays:
Enter PGW1 Port
Step 18 Type the PGW1 port number (see Table 2-2) and press Enter.

Note The PGW1 port is typically 8003, but it must match the port setting of the IPLNK object in the PGW 2200 configuration.

The following text displays:
Enter Installation NodeId
Step 19 Type the installation node ID (see Table 2-2) and press Enter.

Note The installation node ID is a text field typically used by network designers for identification purposes. Entering a value in this field does not affect functionality.

The following text displays:
Enter Hardware Platform
Step 20 Type the hardware platform name (see Table 2-2) and press Enter (typically, accept the default platform name). The following text displays:
Enter Installation Location 
Step 21 Type the installation location (see Table 2-2) and press Enter.

Note The installation location field is a text field typically used by network designers for identification purposes. Entering a value in this field does not affect functionality.

The following is an example of the screen that displays:
## Executing checkinstall script.
Modified Environment is:
-------------------------
BASEDIR=/opt/GoldWing/4.3.2
GWHOME=/opt/GoldWing
GWUSR=mgcusr
GWGRP=mgcgrp
GWCONF_IP="10.70.54.53"
GWCONF_PORT="1719"
GWCONF_PREFIX="0208"
GWCONF_ALIAS="cisco@OuterLondonDomain.com"
GWCONF_GKID="OuterLondon"
GWCONF_HOST_PORT=8003
GWCONF_VSC1_NAME=goliath
GWCONF_VSC1_PORT=8003
GWCONF_NODEID="H323-GW1"
GWCONF_HARDWARE="Sun Netra T1"
GWCONF_LOCATION="H323 - GW1"
-------------------------
The selected base directory </opt/GoldWing/4.3.2> must exist before installation is 
attempted.
Do you want this directory created now [y,n,?,q] 
Step 22 Type y to create the version directory. The following text displays:
Using </opt/GoldWing/4.3.2> as the package base directory.
## Processing package information.
## Processing system information.
## Verifying disk space requirements.
## Checking for conflicts with packages already installed.
## Checking for setuid/setgid programs.
This package contains scripts which will be executed with super-user
permission during the process of installing this package.
Do you want to continue with the installation of <OTTgw000> [y,n,?] 
Step 23 Review the output before you continue the installation. Type y to continue. The files are installed. The following text displays:
Installing Cisco HSI (GoldWing) H323 Adjunct Processor V4.3(2) as <OTTgw000>
    ## Installing part 1 of 1.
    /etc/init.d/CiscoGW
    /opt/GoldWing/4.3.2/bin/GWmain
    /opt/GoldWing/4.3.2/bin/PMmain
    /opt/GoldWing/4.3.2/bin/mml
    /opt/GoldWing/4.3.2/bin/msg.conf
    /opt/GoldWing/4.3.2/bin/parse
    /opt/GoldWing/4.3.2/etc/GWmain.base.conf
    /opt/GoldWing/4.3.2/etc/GWmain.default.conf
    /opt/GoldWing/4.3.2/etc/GWmain.static.conf
    /opt/GoldWing/4.3.2/etc/H323SkeletonFileSimple.dat
    /opt/GoldWing/4.3.2/etc/parse.exclude.list
    /opt/GoldWing/4.3.2/etc/parse.list
    /opt/GoldWing/4.3.2/lib/libgwMib_shlib.so
    /opt/GoldWing/4.3.2/var/prov/active_config <symbolic link>
    [ verifying class <none> ]
    [ verifying class <script> ]
    ## Executing postinstall script.
    Installed package instance is: OTTgw000
    Installation of <OTTgw000> was successful.
    Installed package instance environment variables are:
    -----------------------------------------------------
    PKGINST=OTTgw000
    VERSION=4.3.2
    BASEDIR=/opt/GoldWing/4.3.2
    GWHOME=/opt/GoldWing
    MGCUSR=mgcusr
    MGCGRP=mgcgrp
    -----------------------------------------------------
    Setting link /opt/GoldWing/currentPM.
    Setting link /opt/GoldWing/currentGW.
Installation of the Cisco HSI is now complete. The directory /opt/GoldWing now displays as follows:
drwxr-xr-x   7 cisco    sysadmin     512 Jan  9 18:31 4.3.2
lrwxrwxrwx   1 cisco    sysadmin      19 Jan  9 18:31 currentGW -> /opt/GoldWing/4.3.2
lrwxrwxrwx   1 cisco    sysadmin      19 Jan  9 18:31 currentPM -> /opt/GoldWing/4.3.2
-rwxrwxr-x   1 root     other       3053 Jan  9 18:31 uninstall.sh
Note The HSI might generate checksum errors at the completion of the installation. It is safe to ignore these errors, which are normal because the installation process modifies some of the installation files (for example, IP addresses and gatekeeper IDs). The UNIX pkgchk function detects such changes to the installation files.

Note The links currentPM and currentGW point to the currently active version of the Cisco HSI. The uninstall script has been copied here for convenience, but it can be run only by root user.

To check the Cisco HSI installation, enter pkgchk OTTgw000.

Note The package name is OTTgw000. If more than one instance of the package is installed, the package name has a suffix (for example, OTTgw000.2, OTTgw000.3, and so on).

Outside of the /opt/GoldWing directory, the start/stop script CiscoGW is copied to the /etc/init.d directory.

When the installation is complete, a file named PKINST is written to the base directory on the installed software.

Caution Do not modify the PKINST file. It contains information derived from the installation, and the uninstall script uses the PKINST file in the version directory to determine which package name to remove if more than one instance of the package is installed.

Installing Multiple Cisco HSIs in a Redundant PGW 2200 Configuration

Typically, the Cisco PGW 2200 is deployed as a two-box solution, in an Active-Standby configuration (the two boxes are referred to as a PGW node).

The Cisco HSI operates permanently in an Active configuration. You can deploy additional HSIs for N+1 redundancy. All the HSIs are active permanently, and the PGW load balances calls across the HSIs. If one HSI is goes offline, the PGW continues to load balance the calls across the remaining HSIs.

Note The Cisco HSI operates in a load balancing mode. Therefore, you should deploy at least two HSIs in a network. This enables the Cisco PGW 2200 to load balance calls between the HSIs. Each HSI communicates by using H.323 through network interface hme0 only.

Figure 2-1 illustrates a typical PGW/HSI solution.

Figure 2-1 Dual Cisco HSI with a Redundant PGW 2200 Configuration

During the HSI installation procedure, one EISUP link is configured. You can configure an additional EISUP link for communications from the HSI interface hme1 to the Cisco PGW interface hme1 by issuing MML command line interface commands.

You can configure two more EISUP links to enable the HSI to communicate (by way of the interfaces hme0 and hme1) to the standby PGW, in case the standby PGW becomes active.

Figure 2-1 shows an Active-Standby PGW node, and a single Cisco HSI (in practice, another HSI should be used for load balancing). In the illustration, the red network has address 194.182.147.226/28 (the subnet mask is 255.255.255.240) and the blue network has address 192.182.147.240/28.

The IP addresses and desired EISUP port numbers are:

•pgw1 interface0 194.182.147.226 port 8003

•pgw1 interface1 194.182.147.242 port 8003

•pgw2 interface0 194.182.147.227 port 8003

•pgw2 interface1 194.182.147.243 port 8003

•hsi interface0 194.182.147.228 port 8003

•hsi interface1 194.182.147.244 port 8003

After the HSI install.sh script runs, the following parameters are configured (VSCA refers to PGW1):

•sys_config_static HOST_PORT_NUMBER1 = 8003

•sys_config_static HOST_PORT_NUMBER2 = 0

•sys_config_static VSCA_IPADDR1 = 194.182.147.226

•sys_config_static VSCA_IPADDR2 = 194.182.147.226

•sys_config_static VSCA_PORT_NUMBER1 = 8003

•sys_config_static VSCA_PORT_NUMBER2 = 8003

Configuring a Redundant Deployment

The following steps show the MML commands one can use to configure the deployment illustrated in Figure 2-1.

Step 1 Login as root user.

Step 2 Start up the Cisco HSI by entering the command:
/etc/init.d/CiscoGW start
Step 3 Log out of root user, and log in as user mgcusr.

Step 4 Start the Cisco MML command line interface by entering the command:
mml
Step 5 Copy the initial configuration to "base_conf" so that you can refer to it later if necessary. (The configuration file name "base_conf" is a suggestion. It can be replaced with any text.)
prov-sta: srcver=active, dstver=base_conf
prov-cpy
Step 6 Start another configuration based on the active configuration:
prov-sta: srcver=active, dstver=fig2.2
Step 7 Configure the HSI to use the two local interfaces hme0 and hme1:
prov-ed: name=sys_config_static, HOST_PORT_NUMBER2 = 8003
prov-add: name=sys_config_static, HOST_IPADDR1 = 194.182.147.228
prov-add: name=sys_config_static, HOST_IPADDR2 = 194.182.147.244
Step 8 Configure the second IP address of PGW1:
prov-ed:name=sys_config_static, VSCA_IPADDR2 = 194.182.147.242
Step 9 Configure details for PGW2 (referred to as VSCB):
prov-add: name=sys_config_static, VSCB_IPADDR1 = 194.182.147.227
prov-add: name= sys_config_static, VSCB_IPADDR2 = 194.182.147.243
prov-add: name= sys_config_static, VSCB_PORT_NUMBER1 = 8003
prov-add: name= sys_config_static, VSCB_PORT_NUMBER2 = 8003
Step 10 Copy the newly configured parameters to the configuration file:
prov-cpy
Step 11 Restart the software:
restart-softw
MML Command Examples

The MML commands presented in the preceding configuration example are described in detail in Appendix A: "MML User Interface and Command Reference". These commands are described briefly in the following list:

•prov-sta: srcver=active, dstver=xxx—This command starts a provisioning session. The word "active" is a key word; but, it can be replaced with the name of an existing configuration. The new configuration "xxx" is stored in /opt/GoldWing/currentPM/var/prov/xxx.

•prov-ed: name=mml_type, mml_item=xxx—In this command, mml_type is usually set to sys_config_static, sys_config_dynamic, ras, q931 or h245. The value specified for mml_type depends on the mml_item that is being edited. The term mml_item is the name of the parameter that is being edited. The value of xxx is a numeric or text value, depending on the parameter. (If xxx is specified as a text value, optionally you can enclose it in quotes "".)

•prov-add: name=mml_type, mml_item=xxx—This command is used to add additional parameters that are not already part of the configuration.

•prov-cpy—This command stores and deploys the active configuration. However, some parameters require a restart, which can be achieved by stopping and starting the HSI using /etc/init.d/CiscoGW [stop | start] or by issuing the MML command restart-softw.

•restart-softw [:xxx]—In this command, the optional xxx value can be set to restart the HSI using an alternate configuration. For example, the command restart-softw:base_conf would restart the HSI using the configuration stored at /opt/GoldWing/currentPM/var/base_conf.

HSI Software Licensing

After you install the Cisco HSI software, you must install a license file before you can operate the HSI.

Caution Proper interoperation of the Cisco HSI 4.3 with the Cisco PGW 2200 Softswitch requires that the Cisco PGW 2200 Softswitch is running release 9.7(3) or later.

Requesting the License File

Contact the Cisco TAC (http://www.cisco.com) for a demonstration license or to request a license when a Cisco PGW 2200 is obtained. The Cisco TAC might require the machine identifier in order to generate a license. You can get the machine identifier by issuing the Unix command hostid.

Example
telnet hsi-1
Last login: Sat May 27 20:27:14 from cisco.com
hsi-1:~> hostid
8311c97b
The Cisco HSI 4.3 release requires Cisco PGW 9.7(3) or later to operate. For backward compatibility, HSI 4.3 will operate for a short period (30 days) with older releases of the PGW (new features such as Annex M.1 support will not work until the PGW is upgraded). During the 30 days, you must upgrade the PGW to release 9.7(3) or later.

Installing the License File

After you receive the license file by email, you must install it on the Cisco HSI. Copy the license file into the directory /opt/GoldWing/license directory. Restart the Cisco HSI to enable the license file to take effect.

Verifying the License

Issue the following MML command to ensure that the license file is installed correctly:
gw mml> rtrv-lics
   H323 Signalling Gateway   Sat Dec 30 22:41:00 2006
M  SUCC
HSI licensing current operation status:
        License check not in progress
Current status (Node license):
        Node license feature passed ok, successful
Current status (PGW interworking license):
        HSI is is licensed to interwork with 9.6 PGW or later
New license check invoked.
The preceding example indicates that the Cisco HSI recognized that the HSI node (or machine identifier) successfully matches the license file, that the Cisco HSI is correctly licensed to run, and that the HSI can run on PGW 9.6 or later (the 30 days has not expired).

If you issue the rtrv-lics command immediately after the HSI is restarted, the license file may not have been read yet. In this case, the Cisco HSI assumes that the license is valid and continues to function. The rtrv-lics command output would appear as follows:
gw mml> rtrv-lics
   H323 Signalling Gateway   Sat Dec 30 22:50:24 2006
M  SUCC
HSI licensing current operation status:
        License not read yet, results below assume a valid license for now
Current status (Node license):
        Node license feature passed ok, successful
Current status (PGW interworking license):
        HSI is licensed to interwork with 9.6 PGW or later
Please re-enter 'rtrv-lics' in a while. 
If the HSI cannot find the license file, or if the license file is invalid, the rtrv-lics command output would appear as follows:
gw mml> rtrv-lics
   H323 Signalling Gateway   Sat Dec 30 22:50:33 2006
M  SUCC
HSI licensing current operation status:
        License check not in progress
Current status (Node license):
        Node license feature failed! Please contact Cisco TAC www.cisco.com/tac
Current status (PGW interworking license):
        HSI is not licensed to interwork with 9.6 PGW, only 9.7 or later
New license check invoked.
In this case, if you contact the Cisco TAC or your Cisco representative and provide the output from the Unix hostid command, Cisco will issue a new license file.

Caution Each Cisco HSI requires a license file. If you move the HSI software to different hardware, request a new license file from the Cisco TAC.

Viewing License File Operations

The Cisco HSI can deposit detailed information in the log file. When you initially set up the HSI, or if the Cisco TAC requires additional information, the log file can provide useful information.

To enable the debug, enter the following MML command:
set-log:eisup:level=0x0008
This command sets the minimal log level for license file operations to be deposited in the HSI log file.

Caution Do not execute the set-log command on a live network, unless the Cisco TAC requests you to do so.

To obtain greater detail, you can set the log level to 0x1509 or 0xffff.

Caution Do not set the log level to 0x1509 or 0xffff on a live network.

Starting the Cisco HSI

To start the Cisco HSI, execute the start script as the root user and enter the following command:

# /etc/init.d/CiscoGW start

Note The Cisco HSI can be started and stopped only by the root user.

Stopping the Cisco HSI

To stop the Cisco HSI, log in as root user and enter the following command:

# /etc/init.d/CiscoGW stop

Configuring the Cisco HSI

To configure the Cisco HSI, use the MML command line interface. If the /opt/GoldWing/currentPM/local/setup.gw.csh file is sourced, the MML is in the user path.

(See Chapter 3, "Provisioning the Cisco HSI" and Appendix A, "MML User Interface and Command Reference" for more information).

The following example shows a typical user interaction with the MML interface.
hsi-1:~> mml
Connecting to port 10129 on host hsi-1
Welcome to the GoldWing H323 Signalling Gateway.
gw mml> 
gw mml> rtrv-ne
   H323 Signalling Gateway   Sat Dec 30 23:15:16 2006
M  RTRV
Type           : H323 Signalling Gateway
Hardware       : Sun Fire V210
Vendor         : Cisco Systems, Inc.
Location       : H323-GW1
Primary IP Addr: 10.52.70.151
Version        : 4.3.2
Platform Status:
        Signalling gateway: Running
        Call processing: Active
gw mml> prov-rtrv: list
   H323 Signalling Gateway   Sat Dec 30 23:15:30 2006
M  RTRV
No provisioning session is active.
The following provisioning sessions are available:
fig2.2 *     base_conf           old_conf         
gw mml>
In this example, the user entered the rtrv-ne command, which retrieves general network element details. The prov-rtrv:list command lists all the configurations that have been stored. The active configuration is marked with an asterisk (*).

Caution Do not modify configuration files directly. Modify files by using the Cisco MML interface.

Installing Cisco HSI Patches

Over time, you can access Cisco HSI 4.3 patches online (http://www.cisco.com), or through your contact at Cisco. A patch is supplied as a single file (for example, hsi-4_3_2_p1.tar.Z) along with a readme file, which is a text file.

Always refer to the readme file for the exact patch install instructions and for any additional information about requirements.

Typically, a patch incorporates the contents of all preceding patches. Therefore, you need to install only the latest patch. When a new patch is released, you uninstall the current patch. Patch uninstall and installation is typically a 5 minute process. Detailed instructions are provided in the readme file.

If more than one version of the Cisco HSI is available, you can perform the patch installation procedure without downtime. In this case, you upgrade one HSI while the other HSIs continue to run. After you upgrade the initial HSI and it is restored to operation, you upgrade the next HSI, and so on.

Minimizing Dropped Calls During Patch Installation

The following procedure provides a method to minimize the number of H.323 calls that are dropped when you install an HSI patch.

Step 1 Initiate an MML session by issuing the mml command.

Step 2 Issue the stp-callproc command to enable active H.323 calls to remain connected and to stop all new calls through the HSI.
stp-callproc: timeout=600
If configured to do so, the Cisco PGW 2200 reattempts blocked calls through the other HSIs. After 600 seconds (10 minutes) the Cisco HSI drops any calls that are still active (that is, if the users have not gone on-hook after 10 minutes).

Step 3 Wait 10 minutes and then issue the rtrv-ne command.

The rtrv-ne command should return a message that indicates that the call processing state is idle.

Step 4 Issue the quit command to exit the MML session.

Step 5 As root user, stop the Cisco HSI by issuing the following command:
/etc/init.d/CiscoGW stop
Step 6 Install the HSI patch.

Step 7 Restart the HSI.

Upgrading the Cisco HSI to a New Release

Before removing an old version of the Cisco HSI, install the new version of the software. You can export a provisioning session to a flat file in a format that can be used as input to another provisioning session (see prov-exp in Appendix A, "MML User Interface and Command Reference," for more information).

Note To upgrade to Cisco HSI 4.3.2, if you have not partitioned disks according to the information provided in the partitioning tables presented in the Cisco Media Gateway Controller Software Release 9 Installation and Configuration Guide, you must repartition the disks and reinstall the operating system.

Also, see the document: Release Notes for the Cisco Media Gateway Controller Software Release 9.7(3).

When you upgrade the Cisco HSI version, the following conditions apply:

•The Cisco HSI must be stopped first before installation is allowed to proceed.

•The installation of the new software does not overwrite the existing installed version.

•The installation of a new version creates a new version directory in the /opt/GoldWing parent directory. The links currentPM and currentGW are updated to point to this new version.

•The system should be restarted to enable the re-initialization of the SNMP processes. The craftsperson needs to change the user to root and issue the following Unix command:
shutdown -i 6 -g 0 -y
Note To revert to a previous version of the software, manually modify the currentPM and currentGW links in the/opt/GoldWing parent directory to point to the previous version.

The uninstall.sh script uses the PKINST file in the version directory to determine which package name to remove.

Caution When upgrading the Cisco HSI, you must install the security package CSC0h013 before you remove (uninstall) the preceding version of the HSI software. If you do not, the CSC0h013 security package will not operate. This step is not required if you are performing a fresh installation of the Cisco HSI.

Migrating from HSI 4.1 or 4.2 to HSI 4.3

If you are upgrading from HSI 4.2 and plan to use the same configuration (including IP addresses) and wish to migrate the configuration from the old HSI machine to the new HSI machine, complete the following steps.

Step 1 On the HSI running Release 4.2, issue the following commands:
mml>
    prov-sta:srcver-active, dstver=dummy1
    prov-exp:all:dirname=my42
    proc-stp::confirm
quit
cd /opt/GoldWing/export/my42
copy the config.mml file to a safe place
Step 2 On the new HSI 4.3 machine, after the Solaris 10 operating system and HSI 4.3 are installed, copy the config.mml file to a location on the new machine (for example, the home directory).

Step 3 If you are installing the Cisco HSI on the Netra 210 or V210, go to step 4.

If you are installing the Cisco HSI on the high performance platform, Netra 240, enter the following:
/opt/GoldWing/currentPM/bin/migrate config.mml
This generates a file named 43_migrated.mml.

Note The /opt/GoldWing/currentPM/bin/migrate function configures higher overload thresholds, which are required for the high performance platform

Step 4 Copy the license file to the directory /opt/GoldWing/license.

Step 5 Start the HSI.

Step 6 If you are installing the Cisco HSI on the Netra 210 or V210, configure the HSI by logging in as mgusr and issuing the command:
% mml> -b config.mml
If you are installing the Cisco HSI on the high performance platform (Netra 240), configure the HSI by logging in as mgusr and issuing the command:
% mml> -b 43_migrated.mml
Step 7 Restart the HSI by issuing one of the following commands:
/etc/init.d/CiscoGW [stop|start] 
mml>
restart-softw
Removing the Cisco HSI

To remove the Cisco HSI, complete the following steps:

Step 1 Log in as root.

Step 2 Enter the following command to stop the Cisco HSI:

# /etc/init.d/CiscoGW stop

Step 3 Enter the following commands:

# cd /opt/GoldWing

# ls -l

The following is an example of the screen that displays:
drwxr-xr-x   7 cisco    sysadmin     512 Jan  9 18:31 4.3.2
lrwxrwxrwx   1 cisco    sysadmin      19 Jan  9 18:31 currentGW -> /opt/GoldWing/4.3.2
lrwxrwxrwx   1 cisco    sysadmin      19 Jan  9 18:31 currentPM -> /opt/GoldWing/4.3.2
-rwxrwxr-x   1 root     other       3053 Jan  9 18:31 uninstall.sh
Step 4 Enter the uninstall command and specify the version of the software that you want to uninstall, for example:

# ./uninstall.sh 4.3.2

The following text displays:
Warning: This script will remove the package OTTgw000
Do you wish to proceed? [n] [y,n,?,q] 
Step 5 Type y and press Enter. The following text displays:
Deleting generated files in /opt/GoldWing/4.3.2
The following package is currently installed:
OTTgw000        GoldWing H323 Adjunct Processor V0.1.6
(sparc) 4.3.2
Do you want to remove this package?
Step 6 Type y and press Enter. The following text displays:
## Removing installed package instance <OTTgw000>
This package contains scripts which will be executed with super-user
permission during the process of removing this package.
Do you want to continue with the removal of this package [y,n,?,q] 
Step 7 Type y and press Enter. The following text displays:
## Verifying package dependencies.
## Processing package information.
## Executing preremove script.
## Removing pathnames in class <script>
/opt/GoldWing/4.3.2/local/setup.gw
/opt/GoldWing/4.3.2/local/pmStart.sh
/opt/GoldWing/4.3.2/local/gwhalt
/opt/GoldWing/4.3.2/local/CiscoGW
## Removing pathnames in class <none>
/opt/GoldWing/4.3.2/local
/opt/GoldWing/4.3.2/lib/libgwMib_shlib.so
/opt/GoldWing/4.3.2/lib
/opt/GoldWing/4.3.2/etc/parse.list
/opt/GoldWing/4.3.2/etc/parse.exclude.list
/opt/GoldWing/4.3.2/etc/H323SkeletonFileSimple.dat
/opt/GoldWing/4.3.2/etc/GWmain.static.conf
/opt/GoldWing/4.3.2/etc/GWmain.request.conf
/opt/GoldWing/4.3.2/etc/GWmain.default.conf
/opt/GoldWing/4.3.2/etc/GWmain.conf
/opt/GoldWing/4.3.2/etc/GWmain.base.conf
/opt/GoldWing/4.3.2/etc
/opt/GoldWing/4.3.2/bin/parse
/opt/GoldWing/4.3.2/bin/msg.conf
/opt/GoldWing/4.3.2/bin/mml
/opt/GoldWing/4.3.2/bin/PMmain
/opt/GoldWing/4.3.2/bin/GWmain
/opt/GoldWing/4.3.2/bin
/opt/GoldWing/4.3.2/PKGINST
/etc/init.d/CiscoGW
/etc/init.d <shared pathname not removed>
/etc <shared pathname not removed>
## Executing postremove script.
## Updating system information.
Removal of <OTTgw000> was successful.