Cisco Service Control Management Suite Collection Manager User Guide, Rel 3.1
Installing the Collection Manager

Table Of Contents

Installing the Collection Manager

System Requirements

Checking System Prerequisites

Solaris Requirements

Red Hat Linux Requirements

Distribution Content

Default Configuration Settings

How to Install the Collection Manager

Ports Used by the Collection Manager Software

Installing the Sybase Database

Installing the Collection Manager Software

How to Uninstall the Sybase Database and the Service Control Software

Uninstalling Sybase

Uninstalling the Service Control Software

Upgrading the CM to Version 3.1


Installing the Collection Manager


This module describes the procedures for installing the Collection Manager and its database, and explains how to run the Collection Manager.

System Requirements 

How to Install the Collection Manager 

How to Uninstall the Sybase Database and the Service Control Software 

Upgrading the CM to Version 3.1 

System Requirements

The CM and its database are software components that run on a Server Platform. They can be installed on either of the following configurations:

Sun SPARC machine running Solaris 9 or Solaris 10. (See Solaris Requirements )

IA32 machine running Red Hat Enterprise Linux 3.0 or Red Hat Enterprise Linux 4.0. (See Red Hat Linux Requirements )

Checking System Prerequisites 

Solaris Requirements 

Red Hat Linux Requirements 

Distribution Content 

Default Configuration Settings 

Checking System Prerequisites

The CM distribution contains a script, check_prerequisites.sh , located in the install_scripts directory, that helps to determine whether a system meets the requirements for installing a CM or the bundled Sybase database.

The script checks overall readiness of the system for a CM or Sybase installation. The main prerequisites checked are:

CPU speed

Amount of RAM

Operating System version (Solaris 9 or 10, Red Hat Enterprise Linux 3.0 or 4.0)

Additional required and optional packages

Python installed and executable in path

Free space for CM and Sybase homes

Names for all NICs

Sybase kernel parameters

Locale and time zone formats

check_prerequisites.sh[ --sybhome=SYBHOME] [ --cmhome=CMHOME] [ --datadir=DATADIR]

Table 3-1 check_prerequisites.sh Script Options

--sybhome=SYBHOME

Intended home directory for Sybase installation

--datadir=DATADIR

Intended data directory for Sybase data files (for the Datadir installation method)

--cmhome=CMHOME

Intended home directory for CM installation


Solaris Requirements

Collection Manager 3.1.0 or later can be installed on any Sun SPARC Machine running Solaris that conforms to the requirements listed in the following sections.

Hardware 

Software and Environment 

Setting the Locale and Time Zone 

Hardware

Minimum 500 MHz CPU

Minimum 1 GB RAM per CPU

Hard disk:

One hard disk, at least 18 GB

(Recommended for bundled installations) A second hard disk (at least 18 GB), to store Sybase data

100BASE-T network interface

Software and Environment

Solaris 5.9 64-bit build 04/01 or later (currently only Solaris 5.9 and 5.10 are supported).

Solaris Core Installation.

The following additional packages should be installed:

system

SUNWbash

GNU Bourne-Again shell (bash)

system

SUNWgzip

The GNU Zip (gzip) compression utility

system

SUNWzip

The Info-Zip (zip) compression utility

system

SUNWlibC

Sun Workshop Compilers Bundled libC

system

SUNWlibCx

Sun WorkShop Bundled 64-bit libC


If you are installing the CM in bundled mode with the Sybase database, the following package should also be installed:

system

SUNWipc

Interprocess Communication


(Optional) The following packages may be installed (for sysadmin applications such as sys-unconfig):

system

SUNWadmap

System administration applications

system

SUNWadmc

System administration core libraries


To use the Python scripts, a Python interpreter version 2.2.1 or later must be present on the system. One way to get such an interpreter is to install the following package:

application

SMCpythn (Solaris 9)

SMCpython (Solaris 10)

Python


The Python package requires the installation of two additional packages:

application

SMClibgcc

libgcc

application

SMCncurs

ncurses


These packages can be downloaded from http://sunfreeware.com/

The root (/) partition must have at least 104 MB of free space to install these packages.

The latest recommended patches from Sun should be applied:

For Solaris 9, go to http://sunsolve.sun.com/pub-cgi/show.pl?target=patches/xos-9&nav=pub-patches

For Solaris 10, go to http://sunsolve.sun.com/pub-cgi/show.pl?target=patches/xos-10&nav=pub-patches

For Java, go to http://sunsolve.sun.com/pub-cgi/show.pl?target=patches/J2SE

If you are using Sybase, current Solaris patches recommended by Sybase should be installed:

Go to http://my.sybase.com/detail?id=1016173

At least 8 GB free on the partition where the CM is to be installed. (This is used for CSV storage and persistent buffers.)

(For installations with bundled Sybase) At least 3 GB free on one partition for the Sybase home directory.

(For installations with bundled Sybase) Free space on a single partition to hold the desired size of the Sybase data and logs (these sizes are configurable at install time).

(Optional, and only for installations with bundled Sybase) Install the sudo package (from, for example, http://sunfreeware.com), and configure the following line in the sudoers file:

scmscm ALL= NOPASSWD: XXX/scripts/dbconf.sh

where XXX is the intended home directory for scmscm.

If you choose not to install sudo: in the rare event of a Sybase crash, the CM will not be able to revive the database by itself.

(For installations with bundled Sybase where the legacy (pre-3.0) Cisco Service Control Application Suite (SCAS) Reporter is to be used) An FTP server should be listening on port 21 so that the SCA Reporter can authenticate against it.

(For installations with bundled Sybase) Verify before installation that all IP addresses that are configured for the machine NICs have host names associated with them in /etc/hosts or in another active naming service. (This is a limitation of Sybase Adaptive Server Enterprise.)

(For installations with bundled Sybase) The kernel should be configured with at least:

512000000 bytes in shmmax

Additionally, the IPC module should be loaded at startup. This is achieved by putting the following lines in the file /etc/system :

forceload: sys/semsys
forceload: sys/shmsys

If you are using database periodic delete, the scmscm user should be able to schedule and run cron jobs.

Setting the Locale and Time Zone

For correct CM and Sybase operation, US English locale must be used.

The easiest way to set the locale is by putting the following line in the /etc/TIMEZONE configuration file (changes in this file need a restart to take effect):

LANG=en_US

Solaris also needs to have this locale installed. Verify that the locale is installed by checking that the directory /usr/lib/locale/en_US exists. If the directory does not exist, install the locale files from the Solaris CDs.

Setting the OS time zone as an offset from GMT in POSIX format is not recommended, and may lead to problems. Best is to set the time zone in the /etc/TIMEZONE configuration file by (supported) country name, as in the following example.

TZ=Japan

Verify that the country name is supported as a time zone setting by checking that it is listed in the directory /usr/share/lib/zoneinfo.

If GMT offset must be used, use the zoneinfo format by prepending an :Etc/ prefix, as in the following example:

TZ=:Etc/GMT+5

Red Hat Linux Requirements

Collection Manager 3.1.0 or later can be installed on any i386 running Red Hat Linux that conforms to the requirements listed in the following sections.

Hardware 

Software and Environment 

Setting the Locale and Time Zone 

Hardware

Minimum 800 MHz CPU

Minimum 1 GB RAM per CPU

Hard disk:

One hard disk, at least 18 GB

(Recommended for bundled installations) A second hard disk (at least 18 GB), to store Sybase data

100BASE-T network interface

Software and Environment

Red Hat Linux 3.0 or 4.0.

Red Hat Enterprise "Base" Installation.

(For installations with bundled Sybase) The following additional package should be installed:

compat-libstdc++

This package is available on the Red Hat installation CD.

Latest recommended patches from Red Hat should be applied.

(For installations with bundled Sybase) Current patches recommended by Sybase should be installed.

At least 8 GB free on the partition where the CM is to be installed. (This is used for CSV storage and persistent buffers.)

(For installations with bundled Sybase) At least 1 GB free on some partition for the Sybase home directory.Optional, and only for installation with a bundled database) Install the sudo package and configure the following line in the sudoers file:

scmscm ALL= NOPASSWD: XXX/scripts/dbconf.sh

where XXX is the intended home directory for scmscm.

If you choose not to install sudo, in the rare event of a Sybase crash, the CM will not be able to revive the database by itself.

(For installations with bundled Sybase where the legacy (pre-3.0) Cisco Service Control Application Suite (SCAS) Reporter is to be used) An FTP server should be listening on port 21 so that the SCA Reporter can authenticate against it.

(For installations with bundled Sybase) Verify before installation that all IP addresses that are configured for the machine NICs have host names associated with them in /etc/hosts or in another active naming service. (This is a limitation of Sybase Adaptive Server Enterprise.)

(For installations with bundled Sybase) The kernel should be configured with at least:

512000000 bytes in shmmax

If you are using database periodic delete, the scmscm user should be able to schedule and run cron jobs.

Setting the Locale and Time Zone

For correct CM and Sybase operation, US English locale ( en_US ) must be used.

Distribution Content

The Collection Manager installation kit contains installation scripts for installing the CM and the Sybase database.

It also contains:

Scripts to support file gathering

Scripts for periodic Sybase maintenance

Default Configuration Settings

Settings for the CM are configured during installation. These settings include which adapters should be enabled and their locations, Priority Queue parameters, the target adapters for each type of RDR (by RDR tag value), and various logging policies. Only qualified personnel should change these settings.

How to Install the Collection Manager

This section describes how to install CM version 3.1.0 or later and the Sybase database on a computer running Solaris or Red Hat Linux.

Ports Used by the Collection Manager Software 

Installing the Sybase Database 

Installing the Collection Manager Software 

Ports Used by the Collection Manager Software

The following table describes the TCP/UDP ports on which the CM software and associated components (such as the Sybase database) listen. This table may help the network administrator understand the behavior of the software and its adherence to the security policy.

The ports listed are those on which the device listens constantly. You should allow access on these port numbers; otherwise, certain operations may fail.

Some operations (such as file transfer) cause a device to temporarily open ports other than those listed; however, these ports close automatically when the operation ends.

Table 3-2 Ports that the CM Listens on Constantly

Port Number

Description

33000

Used by the SCE devices to send RDRs for data collection.

21

Used by the legacy (pre-3.0) SCAS Reporter to authenticate against the CM user on the CM machine.

33001

Internal Collection Manager.

Note Access is required only from the local machine; external access can be blocked.

9092

HTTP technician interface.

4100

(For installations with bundled Sybase) Sybase database connectivity through ODBC/JDBC. Required for access to the database.

1099—1120

RMI. Used as the management interface between the data collector and the Service Control management server.

22000

FTP server of the CM.

Note FTP transactions may listen on other ports (22001 to 22100) for data transfer, as negotiated by the protocol.

7787

Internal logging of the management user log.

Note Access is required only from the local machine; external access can be blocked.

14375

Used by the Cisco Service Control Application Suite for Broadband (SCAS BB) Console to send symbol definitions ( values.ini ) to the CM.


Installing the Sybase Database

If you do not want to install Sybase (for example, when working in unbundled mode), Installing the Collection Manager Software.


Note If at any point during the installation you want to reverse the Sybase installation actions (for example, in the rare case that an installation is interrupted because of a power failure), do the following:


1. Log on as the root user.

2. Kill any Sybase processes by typing pkill -u sybase.

3. Remove the Sybase user and home directory by typing userdel -r sybase.

4. Restart the Sybase installation process from the beginning.

Actions Performed by installsyb.sh

The installsyb.sh script installs the Sybase database. The script performs the following actions:

Verifies the shmem setting for Sybase in /etc/system. If the setting is not there, the script inserts it and reboots (after prompting the user).

Adds a user sybase and group sybase.

Runs the Sybase installer for your platform.

Builds a Sybase server including Sybase users and passwords.

Starts Sybase.

Runs SQL scripts to create the Collection Manager database structure. This is a lengthy process that involves restarting Sybase several times.

Prerequisites

Log on as the root user and make the distribution kit contents available on your system or local network.

SUMMARY STEPS

1. Change directory to sybase in the distribution kit root.

2. Run the script installsyb.sh

DETAILED STEPS


Step 1 Change directory to sybase in the distribution kit root.

Step 2 Run the script installsyb.sh

The script usage is as follows:

installsyb.sh --sybhome=SYBHOME{ --datadir=DATADIR}

SYBHOME is the home directory of the Sybase user (and should have 1 GB free)

Select one of the following data location options:

Specify --datadir=DATADIR , where DATADIR is a directory in which all Sybase data is to be stored.

This location should be in a partition where at least 15 GB is free.

If you specify a DATADIR , all Sybase data is stored as normal files in that directory, with default sizes of 10 GB for data, 3 GB for logs, and 3 GB for Sybase temporary storage. The ownership of the directory is changed to the Sybase user during installation.


Installing the Collection Manager Software


Note If at any point during the installation you want to reverse the Sybase installation actions (for example, in the rare case that an installation is interrupted because of a power failure), do the following:


1. Log on as the root user.

2. Kill any Sybase processes by typing pkill -u sybase.

3. Remove the Sybase user and home directory by typing userdel -r sybase.

4. Restart the Sybase installation process from the beginning.

Information About the install-cm.sh Script

The install-cm.sh script is used to install the Collection Manager Server.

install-cm.sh Options

The usage message for the install-cm.sh script is:

Usage: install-cm.sh [-h] (-d CMDIR | -o) 
Options: -d CMDIR   select directory for ~scmscm 
(must not exist and must be on 8 GB free partition) 
-o   upgrade the existing installation 
while preserving the current configuration 
(can't be used with -d) 
-h   print this help and exit

Description of the options:

-d CMDIR 
Used to designate the directory of the newly created 
scmscm user's home. Should be the name of a 
non-existing directory, whose parent resides on a 
partition where at least 8 GB is free. 
As an alternate to this option, you can specify -o : 
-o 
Use this option when you wish to upgrade the existing 
installation while preserving the current configuration. 
(can't be used with  -d)

Actions Performed by install-cm.sh

The install-cm.sh script performs the following actions:

If needed, creates an scmscm user and an scmscm group

Optionally, creates the home for this user

Populates the home of scmscm with CM files and scripts

Installs the following extra component:

private JRE in ~scmscm/cm/lib

Creates boot script symbolic links for the sybase and scmscm users in /etc/init.d and /etc/rcX.d

SUMMARY STEPS

1. Change directory to install-scripts under the distribution kit root

2. Run the install-cm.sh script

3. After the script completes, set a password for the scmscm user

4. Increase the amount of memory allocated to the Topper/Aggregator Adapter

5. Open the file ~scmscm/cm/config/cm.conf.

6. Locate the setting containing TAAdapter in the [adapter_mem] section.

7. Change the default value (512 MB) to a larger value.

8. Save and close the file.

9. Increase the amount of memory allocated to the Real-Time Aggregating Adapter

10. Open the file ~scmscm/cm/config/cm.conf.

11. Locate the setting containing RAGAdapter in the [adapter_mem] section.

12. Change the default value (512 MB) to a larger value.

13. Save and close the file.

14. For each adapter that your application will use, configure the adapter to point to the application

15. Install and activate the periodic delete procedures for the database tables.

16. Install the periodic delete procedures

17. Activate the automatic invocation of the periodic delete procedures

18. Set the Service Control Engine (SCE) device time zone

19. Start the CM

DETAILED STEPS


Step 1 Change directory to install-scripts under the distribution kit root

Step 2 Run the install-cm.sh script

For more information about the install-cm.sh script options, see install-cm.sh Options.

For additional information about the script, see Actions Performed by install-cm.sh.

Step 3 After the script completes, set a password for the scmscm user

Run the following command to set the password for the scmscm user:

passwd scmscm

Be sure to record the passwork that you choose.

Step 4 Increase the amount of memory allocated to the Topper/Aggregator Adapter

If you are going to run an application that uses the Topper/Aggregator (TA) Adapter, you may need to increase the amount of memory allocated to this adapter. This depends on the number of subscribers to be handled by the CM. To increase the memory allocation:

a. Open the file ~scmscm/cm/config/cm.conf.

b. Locate the setting containing TAAdapter in the [adapter_mem] section.

c. Change the default value (512 MB) to a larger value.

For example, to allocate 1024 MB of memory, set the value to -Xmx1024M.

d. Save and close the file.

Step 5 Increase the amount of memory allocated to the Real-Time Aggregating Adapter

If you are going to run an application that uses the Real-Time Aggregating (RAG) Adapter, you may need to increase the amount of memory allocated to this adapter. This depends on the number of subscribers to be handled by the CM and on your RAG Adapter configuration. To change the setting:

a. Open the file ~scmscm/cm/config/cm.conf.

b. Locate the setting containing RAGAdapter in the [adapter_mem] section.

c. Change the default value (512 MB) to a larger value.

For example, to allocate 1024 MB of memory, set the value to -Xmx1024M.

d. Save and close the file.


Note To use an external database, you must also configure a dbpack to enable the CM to connect to the database. See Managing Databases and the CSV Repository, page 5-1 for details of how to do this.


Step 6 For each adapter that your application will use, configure the adapter to point to the application

JDBC Adapter— Edit the file ~scmscm/cm/config/jdbcadapter.conf , and, in the [app] section, change the value of app_conf_dir to point to your desired application.

By default, it is set to apps/scasbb/3.1.0.

TA Adapter— Edit the file ~scmscm/cm/config/taadapter.conf , and, in the [app] section, change the value of app_conf_dir to point to your desired application. By default, it is set to apps/scasbb/3.1.0.

Step 7 Install and activate the periodic delete procedures for the database tables.

(For more information about configuring the behaviour of periodic delete, see Managing the Periodic Deletion of Old Records, page 5-2.)


Note If reports are sent to the database and you do not install and activate the periodic delete procedures, the second disk may overflow.


a. Install the periodic delete procedures

Log on as the scmscm user, start the CM, wait 1-2 minutes for the database tables to be created, and then run the script:

~scmscm/db_maint/create_periodic_del_procs.sh.

b. Activate the automatic invocation of the periodic delete procedures

Run the following command:

~scmscm/scripts/dbperiodic.py --load

Step 8 Set the Service Control Engine (SCE) device time zone

Use the following command to set the time zone:

~scmscm/cm/bin/jselect-sce-tz.sh --offset=offset-in-minutes from GMT

For example, if the SCE device is located in GMT+2, use:

~scmscm/cm/bin/jselect-sce-tz.sh --offset=120

If the SCE is located in GMT-10, use:

~scmscm/cm/bin/jselect-sce-tz.sh --offset=-600

Note This script should be run on every occasion that the time zone of the SCE is updated; for example, when updating the time zone when moving to daylight savings time.


Step 9 Start the CM

Start the CM by running the following command:

~scmscm/cm/bin/cm start

How to Uninstall the Sybase Database and the Service Control Software

Uninstalling Sybase 

Uninstalling the Service Control Software 

Uninstalling Sybase

SUMMARY STEPS

1. Log in as the root user

2. Uninstall Sybase

3. Edit /etc/system and remove the Sybase shmem setting

DETAILED STEPS


Step 1 Log in as the root user

Step 2 Uninstall Sybase

Run the following commands to uninstall Sybase:

pkill -u sybase userdel -r sybase rm /etc/rc*.d/[SK]*sybase

Step 3 Edit /etc/system and remove the Sybase shmem setting


Uninstalling the Service Control Software

SUMMARY STEPS

1. Log in as the root user.

2. Uninstall the Service Control software

DETAILED STEPS


Step 1 Log in as the root user.

Step 2 Uninstall the Service Control software

Run the following commands to uninstall the Service Control software:

pkill -u scmscm userdel -r scmscm rm /etc/rc*.d/[SK]*scmscm

Upgrading the CM to Version 3.1

SUMMARY STEPS

1. Stop the CM

2. Install the new CM using the install-cm.sh script.

DETAILED STEPS


Step 1 Stop the CM

Step 2 Install the new CM using the install-cm.sh script.

When upgrading, use the -ooption to preserve the existing configuration.

The current scmscm user is used.

The database tables that are new in 3.1 will be created automatically when the CM comes up for the first time after the upgrade.


Note The upgrade to version 3.1 can be done only from version 3.x.