Installing Evolve IMSWorkX IMS Suite¶

Pre-Installation Checklist¶

• A 64-bit operating system on each virtual machine (VM).

• The Application Manager installed on the primary Network Interface Unit (NIU).

• The Evolve IMSWorkX Application Server version 4.5 or later installed on all VMs.

The following is the recommended order of installation for the applications:

1. I-CSCF

2. S-CSCF

3. E-CSCF

4. SCC AS

5. IP-SM-GW

6. IMS Suite Web-based User Interface (VSUI)

Installing an Application¶

1. Access the Customer Portal.

2. Log in with your Username and Password.

3. Click Software Downloads on the portal’s main menu.

4. Locate the application package in the software list, and click the link to download the file.

The following is a list of each application package file where yrmo is the year and month of release and x.x-x is the version that will be installed:

• imsworkx-icscf*yrmo*-installer-x.x-x.noarch.rpm

• imsworkx-scscf*yrmo*-installer-x.x-x.noarch.rpm

• imsworkx-ecscf*yrmo*-installer-x.x-x.noarch.rpm

• imsworkx-sccas*yrmo*-installer-x.x-x.noarch.rpm

• imsworkx-ipsm*yrmo*-installer-x.x-x.noarch.rpm

• imsworkx-vsui*yrmo*-installer-x.x-x.noarch.rpm

5. Log in as root on the primary NIU.

6. Copy the downloaded file to the primary NIU.

7. Run the yum install <filename> command where <filename> is the name of the downloaded application package file.

8. Run the application install command.

The following is a list of the install commands for each application where x.x-x is the version that will be installed:

• xpressworkx_app_manager install icscf x.x-x

• xpressworkx_app_manager install scscf x.x-x

• xpressworkx_app_manager install ecscf x.x-x

• xpressworkx_app_manager install sccas x.x-x

• xpressworkx_app_manager install ipsm x.x-x

• xpressworkx_app_manager install vsui x.x-x

There will be output showing on the screen, and any errors will be clearly indicated.

Installing an Application with no Internet Access¶

The Ansible tasks will try to go out to the Internet to find and install the necessary RPM dependencies and Python dependencies. The Python dependencies needs to be installed using PIP.

1. Log in as root on the primary NIU.

2. Copy the downloaded RPM to the primary NIU.

3. Since application installation procedures run over SSH, configure the SSH daemon with the required PIP environment variables. To do this, run the following commands on each machine in the cluster.

echo AcceptEnv PIP_FIND_LINKS >> /etc/ssh/sshd_config
echo AcceptEnv PIP_NO_INDEX >> /etc/ssh/sshd_config
service sshd restart

4. Configure Ansible to install dependencies from the disk instead of the Internet using environment variables. To do this, run the following commands on each machine in the cluster.

export PIP_FIND_LINKS=/root/python_dependencies
export PIP_NO_INDEX=true
export ANSIBLE_SSH_ARGS="-C -o ControlMaster=auto -o ControlPersist=60s -o SendEnv=PIP_FIND_LINKS -o SendEnv=PIP_NO_INDEX"
source ~/.bashrc

5. Optional. This step will change the overall behavior of Python and may help improve the speed of the installation. Add the following to /etc/hosts on each machine in the cluster in order to block (with immediate errors) unreachable repositories:

127.0.1.1   yum.postgresql.org pypi.python.org

6. Optional. This step will change the overall behavior of Python and may help improve the speed of the installation. Add the disabled repository setting to /etc/yum.conf on each machine in the cluster:

[postgres]
enabled=0

7. Ensure all dependencies are installed on each NIU and AS. See the Knowledge Base for the full list of dependencies.

8. Python dependencies can be downloaded from the Python Package Index. When downloading the dependencies, be sure to download the exact version specified if a version is provided. Otherwise, download the latest version supporting Python 2.7 for CentOS/RHEL 7 machines. To easily gather the dependencies, create a text file with a list of the following Python dependencies and name it requirements.txt.

   • MarkupSafe

   • Jinja2

   • psycopg2

   • importlib

   • Django==1.6

   • WebOb

   • chardet

9. Place all of the downloaded Python dependencies in the following directory on the primary NIU using the requirements.txt file that you created.

`/root/python_dependencies`
pip download -r requirements.txt

10. Run the yum install <filename> command where <filename> is the name of the downloaded application package file.

11. Run the application install command.

The following is a list of the install commands for each application where x.x-x is the version that will be installed:

• xpressworkx_app_manager install icscf x.x-x

• xpressworkx_app_manager install scscf x.x-x

• xpressworkx_app_manager install ecscf x.x-x

• xpressworkx_app_manager install sccas x.x-x

• xpressworkx_app_manager install ipsm x.x-x

• xpressworkx_app_manager install vsui x.x-x

There will be output showing on the screen, and any errors will be clearly indicated.

Network Interface Unit (NIU) Configuration¶

Upon installation, the following jobs are added to the crontab:

• xpressworkx-cdr-partition vsui

• xpressworkx-cdr-synchronize vsui

• xpressworkx-cdr-cleanup-database vsui

• restworkx-vsui clean

• vsui-clear-expired-jobs

Web Services

The following configuration needs to be added to the ps_init section of ps_master_config in order to run Web Services. Additional steps are necessary if using HTTPS.

<process name="xpressworkx_web_services"
        run-offline="1"
        stop-script="/usr/sipxpress/bin/stop_web_services" />

Data Services

The following configuration needs to be added to the ps_init section of ps_master_config in order to run Data Services.

<process name="xpressworkx_data_services"
        run-offline="1"
        run-as="postgres"
        wait-to-start="120"
        stop-script="/usr/sipxpress/bin/stop_data_services"
        offline-script="/usr/sipxpress/bin/offline_data_services"
        online-script="/usr/sipxpress/bin/online_data_services"
        notify-cluster-changes="1" />

CDR

The cdr_synchronization_config.yml file is used to set the retention values for Call Detail Records (CDR), and the size of the files that will be copied over during synchronization.

Typically, only the maximum_backup_age is edited. This value sets the number of days that CDRs are kept in the database.

Refer to the comments in the cdr_synchronization_config.yml file for more information on the other values:

• use_app_manager_config: True

• maximum_backup_age: 7

• page_size: 1000

• thread_count: 3

• synchronization_throttle: 0

• application_servers:

  • host: 127.0.0.1

  • user: root

  • password: pass

For more information, see CDR Service.

Automatic Database Maintenance Task

There are a number of automatic database maintenance tasks that run on the NIU. These tasks are installed as cron jobs in the root user’s crontab.

Evolve recommends that the schedule for these tasks remain unmodified unless otherwise directed by Evolve support.

Log Rotation

The following log files are written to on the NIU by the IMS Suite applications. Each file should be rotated using your method of choice. Common options are cron jobs, rsyslog/syslog configuration, and logrotated.

• /var/log/xpress.log

• /var/log/xpressworkx/app-manager/web/access_log

• /var/log/xpressworkx/app-manager/web/error_log

• /var/opt/xpressworkx/app-manager/vsui/logs/vsui-apache.log

• /var/opt/xpressworkx/app-manager/vsui/logs/vsui-apache-ssl.log

• /var/opt/xpressworkx/app-manager/vsui/logs/vsui-django.log

• /var/opt/xpressworkx/app-manager/vsui/logs/vsui.log

Application Processing Server (AS) Configuration¶

CDR Synchronization

The following configuration needs to be added to the ps_init section of ps_master_config if not already present.

<process name="xpressworkx_cdr_services"
        control-queue="xpressworkx_cdr_services" />

Java Classpath

The following configuration needs to be added to the JVM server classpath section of ps_master_config for each installed [application]-interface.jar file in /usr/sipxpress/jars/

<ps-jvm>
    <ps-jvm
        class-path="/usr/sipxpress/jars/pt-mutables.jar:/usr/sipxpress/jars/icscf-interface.jar:/usr/sipxpress/jars/scscf-interface.jar:..."
        jvm-start-size="-Xms16m"
        jvm-max-size="-Xmx32m"
        num-threads="9" />
</ps-jvm>

Routing Rules

Routing Rules tell the AS which events should be processed by an application. For more information about routing rules, see the Application Server User’s Guide.

Each element in the IMS Suite can process a number of events that can be configured in the routing rules. For a full list of these events, see Event Names.

Configuring SSL¶

These steps are required to use secure communications via the web UI and/or API with the application. Our SSL implementation uses TLS with certificate exchange.

1. Add the private key to the configuration on both NIUs. Edit the /root/xpressworkx-ssl-vars and add the following:

CERTIFICATE_FILE=/root/easy-rsa/pki/issued/<hostname>.crt
KEY_FILE=/root/easy-rsa/pki/private/<hostname>.key
CA_FILE=/root/easy-rsa/pki/ca.crt
HOSTNAME=<hostname>

2. Run the configure-ssl command on both NIUs.

Running this command will stop and restart the HTTP server (httpd), which will briefly affect any system traffic. Also, this command will start a test process (test-httpd) which will check that the configured certificates are working at a basic level.

After running this command, further modifications to HTTP configuration should be made only if instructed to do so by Customer Support.

Starting an Application¶

To launch IMS Suite applications automatically on startup, add the following to the <ps-appexec> section of the ps_master_config on each AS:

<ps-appexec>
        <application sessions="nnn" iterations="0">icscf.xml</application>
</ps-appexec>
<ps-appexec>
        <application sessions="nnn" iterations="0">scscf.xml</application>
</ps-appexec>
<ps-appexec>
        <application sessions="nnn" iterations="0">ecscf.xml</application>
</ps-appexec>
<ps-appexec>
        <application sessions="nnn" iterations="0">sccas.xml</application>
</ps-appexec>
<ps-appexec>
        <application sessions="nnn" iterations="0">ipsm.xml</application>
</ps-appexec>
<ps-appexec>
        <application sessions="nnn" iterations="0">vsui.xml</application>
</ps-appexec>

Where nnn is the number of simultaneous sessions of the specified application to launch.

If IMS Suite applications are not configured to automatically launch on startup, follow these steps to launch IMS Suite applications using the Console:

1. Launch Console.

2. Add Platform Services Host.

3. Right-click Applications in the Object panel.

4. Select Start Application from the menu.

5. Select the required application from the Application Name list.

6. Enter the number of sessions that you want to run.

7. Click OK.

For more information, see the Console User’s Guide.

Uninstalling an Application¶

When uninstalling an IMS Suite application, you can either maintain or purge the database.

To uninstall and maintain the database:

1. Log in as root on the primary NIU.

2. Run the application uninstall command.

The following is a list of the uninstall commands for each application:

• xpressworkx_app_manager uninstall icscf

• xpressworkx_app_manager uninstall scscf

• xpressworkx_app_manager uninstall ecscf

• xpressworkx_app_manager uninstall sccas

• xpressworkx_app_manager uninstall ipsm

• xpressworkx_app_manager uninstall vsui

To uninstall and purge the database:

1. Log in as root on the primary NIU.

2. Run the application purge command.

The following is a list of the purge commands for each application:

• xpressworkx_app_manager purge icscf

• xpressworkx_app_manager purge scscf

• xpressworkx_app_manager purge ecscf

• xpressworkx_app_manager purge sccas

• xpressworkx_app_manager purge ipsm

• xpressworkx_app_manager purge vsui

Updating an Application¶

Updating an IMS Suite application is as simple as installing the application with the new version. This update should be performed at a time when call traffic is minimal or during a maintenance window.

Restarting an Application¶

To gracefully restart an IMS Suite application on an AS, complete the following steps:

Stop an Application

1. In Console, right-click the application in the Object panel and select Stop.

2. Select the Stop Application Gracefully check box to allow each running session to complete its current iteration.

3. Click Yes.

Start an Application

1. Right-click Applications in the Object panel.

2. Select Start Application from the menu.

3. Select the required application from the Application Name list.

4. Enter the number of sessions that you want to run.

5. If you want to generate a trace file, select the associated check box. The trace file is logged to the /usr/sipxpress/logs directory.

6. In the Stopping Instructions section, specify whether the application should run until it is manually stopped or for a specified number of iterations.

7. Click OK.

For more information on starting and stopping an application through the Console, see Working with Applications.