Toolpack Installation v2.2:Windows XP

From TBwiki
Revision as of 16:10, 28 December 2009 by Allyntree (Talk | contribs)
Jump to: navigation, search

Contents

Prerequisites

The prerequisites in this section list the requirements of a basic development host computer on which Toolpack will run. In addition, the required support applications and services that need to be present on the host machine before installing the Tmedia Toolpack packages are listed in this section with the various locations from which the support software may be retrieved. 1.1 Base Development Package The minimum requirements of the computer running Toolpack are listed as follows:


  • Intel or AMD-based system at 2Ghz or more with 1GB of memory
  • Windows 2000 Professional/Server with Service Pack 3 or later, or Windows XP with Service Pack 2 or later. The Toolpack software packages has not been tested with other versions of Windows.
  • WinZip, WinRar, 7Zip, or an equivalent extraction software
  • HyperTerminal or equivalent serial access application
  • One 1Gbps Ethernet adapter (two for network redundancy). TelcoBridges recommends 1Gbps in all conditions.


Note: It is mandatory to disable the anti-virus software’s on access scan on the MYSQL database directory (generally C:\Program Files\MySQL\MySQL Server 5.0\data), as this will prevent database backup operation to complete properly upon Toolpack System Update.


Note: The Windows firewall may prevent Toolpack to work properly. We recommend disabling the firewall, or enabling all UDP and TCP ports on the local network.


Toolpack System

The software listed below is required by the host machines:


  1. LibIConv 1.9.2 or later (It is a dependency of LibXml2). Located at:
  2. LibXml2 2.6.30 or later. Located at:
  3. Zlib 1.2.3 or later. Located at:


Toolpack Stream Server

The Tmedia Toolpack Stream Server requires WinPCAP 4.0 or later. It can be downloaded from the following location:

Toolpack System Database

The Toolpack system database is used by the main host and requires mySQL database server version 5.0 or later. It can be downloaded from the following location:



Toolpack System Web Portal

The Toolpack System Web Portal is required in order to host the Toolpack Web Portal. It requires the following software:


  1. Ruby 1.8.6 or later. Located at:
  2. Mongrel web server


Installing the Prerequisite Software

The following software is required in order to run Toolpack.


LiblConv, LiblXml2, and zlib

  • Download the packages from the location listed in Section 1.2 “Toolpack System” on page 2 and

copy the DLL file to C:\Windows\System32, or elsewhere in the PATH environment variable.


WinPCAP 4.0

  • Download from the location listed in Section 1.3 “Toolpack Stream Server” on page 2.
  • Use the default installation parameters.


MySQL Database server

  • Download from the location listed in Section 1.4 “Toolpack System Database” on page 2.
  • Choose complete installation
  • Run MySQL Server Instance Configuration Wizard. (You should be prompted to do so after

selecting complete installation.)

  • Choose standard configuration
  • Install as a Windows service and check, Launch Automatically.
  • Choose Include Bin Directory in Windows PATH.
  • Enter a User Name and Password, and note them down on paper as you will need them later in

the installation process.

  • Enable access from remote machines if you plan to run Tmedia Toolpack on more than one host

machine.


Ruby

  • Download from the location listed in Section 1.5 “Toolpack System Web Portal” on page 2.
  • Use the default installation parameters.


Mongrel

Install Mongrel using the following commands:

  • gem install mongrel --include-dependencies


Update the windows firewall

Make sure that the firewall enables the following services and ports. Failure to open those ports will render socket communication between the distributed software elements unavailable:

  • Service: http (80/tcp)
  • Service: https (443/tcp)
  • Port: All ports (tcp/udp) enabled for local networks


Note: Make certain that all of the installed DLLs for the applications are accessible through the PATH environment variable. These DLLS must be available through the path:

  • libxml2.dll, iconv.dll, zlib1.dll, and libmysql.dll


Toolpack Software Installation

Note: The instructions listed in this section require that all prerequisite procedures be followed as listed in the Prerequisites section.


Note: The instructions listed in this section assume the installation of package version 2.2.0. When installing another version (e.g. 2.3.4), replace the following references:

  • All references to “2.2.0” replaced by “2.3.4”
  • All references to “2_2_0” replaced by “2_3_4”
  • All references to “2_2” replaced by “2_3”


Installing Toolpack

Follow the instructions listed below, in order to install Toolpack:

  1. Download the Toolpack installer named “TBToolPack-2.2.0-Setup.exe”, and double-click on it.
  2. Follow on-screen instructions.You will be asked to provide an IP address, user name and password for the database to use with this Toolpack system. You will also be asked to provide a license (or a zip

file that contains multiple licenses) for the TMP6400 boards to use with this installation.

  1. You may optionally change some parameters in the following file:
    • C:\TelcoBridges\toolpack\setup\2.2\toolpack.ini
      • TBX_GW_PORT: The default value is 12358. However, you need to change it to another unique value if you are installing another Toolpack System on the same local subnet, otherwise applications from the two system will see each other and interact in an unpredictible manner. Don’t change that value after the Toolpack system has been launched once!
      • TBX_GW_ADDRESS_0: Uses the local IP address of the host which is on same subnet as

the first Ethernet interface of the TMP6400 boards. Recommended if the host has more than one IP address.

      • TBX_GW_ADDRESS_1: Uses the local IP address of the host which is on same subnet as the second Ethernet interface of the TMP6400 boards.Recommended if the host has more than one IP addresses. Otherwise, use “NONE”.
      • TBDB_UID and TBDB_PWD: Can be changed to match the user name and password you defined earlier for the MYSQL database.
  2. Configure default parameters that will be used while creating the initial configuration in the

database. It will be possible to modify these parameters later through the Web Portal, once the Toolpack System is running. To set these parameters, edit the following file:

    • C:\TelcoBridges\toolpack\setup\2.2\toolpack.yml


Install licenses

This section presents how to manually install license files required for each TMP6400 board installed, in case they were not provided to the installer during Toolpack installation. Get the appropriate license files:

  1. Identify the serial number of the TMP6400 boards that will be used by this Toolpack System.
  2. Contact TelcoBridges support department, and ask for licenses for the current package (2.2.0) for the appropriate TMP6400 boards.
  3. Copy all licenses provided by TelcoBridges into the following directory:
    • C:\TelcoBridges\toolpack\setup\2.2\licenses


Starting and stopping Toolpack

This section presents how to start and stop the Toolpack service, which in turn will launch or shutdown all applications required by the Toolpack System.


Manually starting or stopping Toolpack:

  1. Make sure that the Windows integrated firewall must have been properly configured (or completely disabled) for the Toolpack applications to access to the local network on any UDP or TCP port.
  2. To launch Toolpack, double-click on the following application:
    • C:\TelcoBridges\toolpack\service\tbtoolpack_service.exe
  3. To stop Toolpack, close the tbtoolpack_service.exe window.


Starting Toolpack as a Windows Service:

Open a DOS shell and run:

  • tbtoolpack start


Note that this service will not automatically restart when Windows is rebooted. You can enable automatic start of Toolpack at statup by editing the Toolpack service configuration in:

  • Start->Program->Administrative Tools->Services


Stopping the Toolpack Windows Service:

Open a DOS shell and run:

  • tbtoolpack stop


Note: It can take from few seconds to few minutes before the system is fully running. During that period, the Web Portal may not yet be available. It may longer the first time the system is started, as a default configuration needs to be created in the database.


Using the Toolpack Web Portal to view system status

In order to view the Toolpack system status and validate that it’s properly running, you will need to connect to the Toolpack Web Portal:

  1. Using a web browser, type:
  2. Enter your user name and password. You will be presented the global status page of the Toolpack system. On this page, you can switch from one Tab to the other to view the status of various components of the system.


Using the Toolpack Web Portal to Configure the Tmedia System

Configuring the Toolpack system is done through the Web Portal. Connect to the Web Portal as explained above, then visit the different sections on the left of the page to configure the various components of the system.

For further information on how to use the Toolpack Web Portal to configure your system, refer to Tmedia Web Portal System Configuration Tutorial Guide, 9020-00047-A2, Issue 1.


Configure Streamserver for file playback and recording

By default, the Streamserver application is not launched within the Toolpack System. It’s installed in "maintenance mode", because it requires some manual configuration that depend on the host hardware capacities. The StreamServer is required on installations that are required to play files and record audio on active calls (to implement features such as ring back tone, IVR, voice mail, etc). This section explains how to configure and start the Streamserver application:

  1. Click on the section “Applications -> Configurations” (always visible on the left of the screen).
  2. Click “Edit” on the Stream server application.
  3. Adjust parameters. It is important to configure these parameters with care according to the host capacities, and to the system play and record requirements. Pay particular attention to “RAM limit” and “Database chunk size” parameters, which highly depend on the hardware configuration. For information on how to configure the Streamserver application, please refer to the tbstreamserver hardware guide.
  4. Click “Save”.
  5. Click on the section “Applications -> Instances” (always visible on the left of the screen).
  6. Switch to “Status” tab.
  7. Click on the Stream server application name.
  8. Change the “Oam Target State” to “Run”.
  9. Click “Apply states”.


The Streamserver application should now be running and connected to other application. It is now possible, rom the Gateway application or other custom-built application, to play and record files. In order to play, audio files must be stored on the server. When play or record commands are issued, a file path is provided. That file path can be abolute, or relative. When relative, the current directory is the following directory:

  • C:\TelcoBridges\toolpack\setup\2.2\apps\tbstreamserver


It is now up to the user to store appropriate files on the server, in the directory of choice. Files should be in WAV format, with the following characteristics:

  1. Encodings:
    • aLaw / uLaw
    • PCM 8 bits / 16 bits
    • ADPCM (G721 32Kbps, G723 24Kbps or G726 16Kbps, Dialogic VOX)
  2. Channels:
    • Mono / Stereo
  3. Sample rate:
    • 8Khz, 11.025Khz, 16Khz, 22.05Khz, 44.1Khz or 48Khz


Note: The following file extensions are also supported: .alaw, .ulaw, .pcm, .pcm8, .g721, .g723, .g726, .vox, .vox6


Connect to applications shell, and view various status

The tbx_cli_tools_remote.exe tool enables you to remotely attach to Telcobridges applications running in service mode. This will allow you to have access to their text-based interface and to verify log files as well as applications status:

  1. Open a shell prompt, type the following command (replace port 12358 by the actual value of TBX_GW_PORT value set earlier):
    • cd c:\TelcoBridges\toolpack\pkg\2.2.0\bin\release\i586-win32
    • tbx_cli_tools_remote.exe -gw 12358
  2. Select the application to remotely control from the displayed list. You should see the following applications:
    • tboam_app: This is the main Toolpack application that launches and monitors all other applications in the

system. It’s command-line interface present multiple pages that show information about configuration loading or validation status, launched applications status, and system update status.

    • web_server: This application is a wrapper that launches the actual web server. There is not much information to see in that window (the actual web server’s log is not displayed there).
    • toolpack_sys_manager: This application is responsible for applying active configuration on the TMP6400 boards, and activating toolpack_engine to enable call control.
    • toolpack_engine: This application is responsible for allocating all resources (signaling and data path) required to establish calls.
    • gateway: This application is implementing actual call flow, and routing. It controls the engine, telling when to accept, answer calls, play or record files, enable tone detection, etc. This gateway application provides basic routing from incoming calls to outgoing calls, but it can be replaced by customer own call control application to implement different call flows.


Toolpack Redundant Host Installation

Note: The instructions listed in this section assume the installation of the package version 2.2.0. When installing another version (e.g. 2.3.4), replace the following references:

  • All references to “2.2.0” replaced by “2.3.4”
  • All references to “2_2_0” replaced by “2_3_4”
  • All references to “2_2” replaced by “2_3”


Installing Toolpack

Note: The following instructions need to be done only once on the redundant host, in order to install an initial Toolpack package. Once Toolpack is running on that host, it will automatically update itself to any other package installed and activated on the main host of this Toolpack system:

  1. Download the Toolpack installer named “TBToolPack-2.2.0-Setup.exe”, and double-click on it.
  2. Follow on-screen instructions.You will be asked to provide IP address, user name and password for the Database to use with this Toolpack system. You can skip the installation of the license.
    • Note: Make sure that you provide the IP address of the same MySQL server that was used on the primary Toolpack host.
  3. You may optionally change some parameters in the following file:
    • C:\TelcoBridges\toolpack\setup\2.2\toolpack.ini
      • TBX_GW_PORT: The default value is 12358. However, you need to change it to another unique value if you are installing another Toolpack System on the same local subnet, otherwise applications from the two system will see each other and interact in an unpredictible manner. Don’t change that value after the Toolpack system has been launched once. Make sure that this value is the same as the one used on the primary host of this Toolpack system.
      • TBX_GW_ADDRESS_0: By using the local IP address of the host which is on same subnet as the first Ethernet interface of the TMP6400 boards. Recommended if the host has more than one IP addresses.
      • TBX_GW_ADDRESS_1: By using the local IP address of the host which is on same subnet as the second Ethernet interface of the TMP6400 boards. Recommended if the host has more than one IP addresses. Otherwise, use “NONE”.
      • TBDB_UID and TBDB_PWD: Can be changed to match current user name and password you defined earlier for the MYSQL database.


Create the redundant host configuration in the Web Portal

Before starting Toolpack on the redundant host, it is mandatory to create the configuration for that host in the Web Portal. Toolpack will refuse to start on the redundant host if it can’t find it’s configuration:

  1. Go to the main host of this Toolpack system (not this redundant host yet). Using a web browser, type:
  2. Enter user name and password to login.
  3. Click on the “Hosts” section on the left of the screen.
  4. Click on “Create New Host Configuration”.
  5. Enter the required information:
    • Enter the host name (this must exactly match the name of the redundant host).
    • Select one or multiple functions that this host should fullfill. This should generally be "Management", "Call", and in some cases, "Streamserver" and "Faxserver".
    • Click "Create".
  6. Click on the “Systems” section on the left of the screen.
  7. Click “Edit” on the current system.
  8. Click on the button “Build application list”.
  9. Go back to the “Hosts” section on the left of the screen. You should see something like this:


Starting Toolpack on the redundant host

To start or stop Toolpack on the redundant host, follow the instructions provided earlier in this document in Section 2.3 “Starting and stopping Toolpack” on page 8.


Using the Toolpack Web Portal to view system status

In order to view the status of Toolpack on the secondary host, click on the "Status" section on the left of the page, then select the "Hosts" tab. You can also see the status of individual applications on the redundant host under the "Applications" tab.


Updating package version on the redundant host

There is nothing to do on the redundant host to install a new package version. Once the package is installed on the primary Toolpack host, it will automatically be replicated on any redundant host.


Connect to applications shell, and view various statuses

The "tbx_cli_tools_remote.exe" tool enables you to remotely attach to Telcobridges applications, including those running on the redundant host. This allows reading log files, and looking at more detailed applications status on both hosts of the Toolpack system. Open a shell prompt, type the following command (replace port 12358 by the actual value of TBX_GW_PORT set earlier):

  • cd c:\TelcoBridges\toolpack\pkg\2.2.0\bin\release\i586-win32
  • tbx_cli_tools_remote.exe -gw 12358


Toolpack Minor Software Update

Note: The instructions listed in this section require that Toolpack has been previously installed using installation procedure was found in Section 2 “Toolpack Software Installation” on page 5. Current procedure is used to update Toolpack to another version from the same major branch (from version 2.2.3 to 2.2.5 for example). Instructions to follow with updating to another major version (from 2.2.X to 2.3.X for example) are found in Section 4 “Toolpack Major Software Update” on page 27.


Note: This procedure can be done while the system is already running under the previous version. It will be possible, at any time, to switch back and forth between the newly installed version and the other versions already present.


The minor software update of the Toolpack applications consists of the following:

  • Running the installer for the new version to install.
  • Instructing the running system to switch to the new package


Note: The instructions listed in this section assume the update is done to the package version 2.2.3. When installing another version (e.g. 2.3.5), replace the following references:

  • All references to “2.2.3” replaced by “2.3.5”
  • All references to “2_2_3” replaced by “2_3_5”
  • All references to “2_2” replaced by “2_3”


Run the Toolpack installer

Follow the following instruction in order to run the Toolpack installer:

  1. Download the Toolpack installer named “TBToolPack-2.2.0-Setup.exe”, and double-click on it.
  2. Follow on-screen instructions.You will be asked to provide IP address, user name and password for the Database to use with this Toolpack system. You will also be asked to provide a license (or a zip file that contains multiple licenses) for the TMP6400 boards to use with this installation. This will install the new version on a separate directory. It does not override any previous installations.


Activate the newly installed package

After being installed, a new Toolpack version is not automatically activated, and requires to use the Web Portal interface to active it whenever the system is ready for an update (for example, during low traffic periods). Once activated, the Toolpack System will automatically update itself to the new package with minimal service interruption. The automatic update will do the following operations:

  • Update the database, if appropriate, with newly added tables or parameters.
  • Shut down, and re-launch each application from new package, one at the time, including the web server.
  • Install the new package on each TMP6400 board
    • Note: Some active and transient calls will be lost during the update. A TMP6400 board cannot handle calls when being updated. Calls need to be handled by the other TMP6400 boards of the system, if the system configuration allows that. Define the new package in the Web Portal
  • Connect to the Web Portal, then click on the section "Packages" (always visible on the left of the screen)
  • Click "Create New Package"
  • Set the package name to "2.2.3", the package path to "2.2.3", and click "Save". Activate the new package
  • On the Web Portal, click on the section "Systems" (always visible on the left of the screen)
  • Click the "Edit" button of the current system
  • Scroll-down to the "Activate package" section, choose the package "2.2.3" from the pop-up menu, then click "Activate".
  • Click again on the section "Systems" to see the current status. The update will be complete when "2.2.3" is moved from "Target Package" to "Active Package". You will have to manually refresh your Web Browser page to see that change.


Note: The update process will take up to 5 minutes per TMP6400 board in the system.


Toolpack Major Software Update

Note: The instructions in this section refer to updating Toolpack sofware from one major branch to another (from 2.2.X to 2.3.X, for example). Instructions to switch from two versions from the same major branch (from 2.2.3 to 2.2.5 for example) are found in Section 4 “Toolpack Minor Software Update” on page 27.


Note: This procedure must be done while the Toolpack system is NOT running.


The major software update of the Toolpack applications consists of the following:

  • Stopping the Toolpack system.
  • Running the installer for the new version to install.
  • Changing the Toolpack system working directory in configuration file
  • Starting Toolpack system again.


Note: The instructions listed in this section assume the update is done to the package version 2.3.0. When installing another version (e.g. 2.4.5), replace the following references:

  • All references to “2.3.0” replaced by “2.4.5”
  • All references to “2_3_0” replaced by “2_4_5”
  • All references to “2_3” replaced by “2_4”


Stop the Toolpack system

Stop the Toolpack system by following procedure described in Section 2.3 “Starting and stopping Toolpack” on page 8.


Run the Toolpack installer

  1. Download the Toolpack installer named “TBToolPack-2.3.0-Setup.exe”, and double-click on it.
  2. Follow on-screen instructions.You will be asked to provide IP address, user name and password for the Database to use with this Toolpack system. You will also be asked to provide a license (or a zip file that contains multiple licenses) for the TMP6400 boards to use with this installation.
  3. You must change some parameters in the following file:
    • C:\TelcoBridges\toolpack\setup\2.3\toolpack.ini
      • Make sure to use the same parameters in this file as the previous version’s file (C:\TelcoBridges\toolpack\setup\2.2\toolpack.ini)
    • TBX_GW_PORT: The default value is 12358. However, you need to change it to another unique value if you are installing another Toolpack System on the same local subnet, otherwise applications from the two system will see each other and interact in an unpredictible manner. Don’t change that value after the Toolpack system has been launched once. Make sure that this value is the same as the one used on the primary host of this Toolpack system.
    • TBX_GW_ADDRESS_0: By using the local IP address of the host which is on same subnet as the first Ethernet interface of the TMP6400 boards. Recommended if the host has more than one IP addresses.
    • TBX_GW_ADDRESS_1: By using the local IP address of the host which is on same subnet as the second Ethernet interface of the TMP6400 boards. Recommended if the host has more than one IP addresses. Otherwise, use “NONE”.
    • TBDB_UID and TBDB_PWD: Can be changed to match current user name and password you defined earlier for the MYSQL database.


Note: This will install the new version on a separate directory. It does not override any previous installations.


Change the Toolpack working directory

Edit the following configuration file:

  • C:\TelcoBridges\toolpack\service\config.txt


Replace any reference to “2.2” for “2.3”. For instance:

  • application= C:/TelcoBridges/toolpack/setup/2.2/apps/tboamapp/tboamapp_wd_cfg.ini

becomes: application= C:/TelcoBridges/toolpack/setup/2.3/apps/tboamapp/tboamapp_wd_cfg.ini


Start the Toolpack system

Start the Toolpack system by following procedure described in Section 2.3 “Starting and stopping Toolpack” on page 8.


Note: Once started, the Toolpack system will update the version of any TMP6400 board in the system. This operation can take up to 5 minutes per TMP6400 board.


Roll back to previous version

To roll back to previous version, run the reverse procedure above (except running the installer):

  • Stop the Toolpack system
  • Revert any reference to “2.3” for “2.2” in the file C:\TelcoBridges\toolpack\service\config.txt
  • Start the Toolpack system


Toolpack Software Uninstall

There is no automatic tool to uninstall the Toolpack Software. However, it’s very easy to uninstall.


Note: The instructions listed in this section assume that the package to uninstall is version 2.2.3. When uninstalling another version (e.g. 2.3.5), replace all references to “2.2.3” with “2.3.5”.


Uninstall a minor Toolpack Software version

To uninstall a minor Toolpack Software version (2.2.3, for example, but not the other 2.2.x), the procedure is the following:

  • Make sure the package to uninstall (2.2.3) is not active, by connecting to the Web Portal, in section “Systems” (the “Active package” must not be “2.2.3”). If appropriate, switch the system to another package, and wait until the switch has completed.
  • Erase the appropriate folder on the server:
    • C:\TelcoBridges\toolpack\pkg\2.2.3


Uninstall the entire Toolpack Software

To uninstall the complete Toolpack Software, the procedure is the following:

  • Make sure the Toolpack system is not running, by entering the following DOS command:
    • tbtoolpack stop
  • Erase the entire toolpack home directory:
    • C:\TelcoBridges\toolpack
  • If no more required by non-Toolpack software, also uninstall the Mysql database by through the appropriate Windows control panel (“Add or Remove programs”).
Retrieved from "https://docs.telcobridges.com/mediawiki/index.php?title=Toolpack_Installation_v2.2:Windows_XP&oldid=5101"
Personal tools