Cisco Billing and Measurements Server User's Guide, Release 3.30

Introduction to Cisco BAMS

The Cisco Billing and Measurements Server (BAMS) collects, formats, and stores billing and measurements data derived from CDR files, which BAMS polls from a Cisco PGW 2200 operating in signaling mode or call-control mode. (see Figure 1-1). BAMS-formatted data can then be processed by a billing system and other measurement collection and reporting systems. BAMS also reports error information using the bamstrap utility. This error information is collected and displayed by the Cisco MGC Node Management System.

Figure 1-1 Cisco PGW 2200 PSTN Gateway Components

Collecting Data

Cisco BAMS collects data from the Cisco MGC through File Transfer Protocol (FTP) or Secure File Transfer Protocol (SFTP). BAMS is configured with a login ID and password for the Cisco MGC hosts. BAMS can collect data from the Cisco MGC in simplex or redundant mode of operation.

Data Collection

Cisco BAMS can collect data from up to eight MGC nodes with BAMS software Release 3.0 and above. Data collected from the first MGC node is stored in the /opt/CiscoBAMS/data/s01 directory, data collected from the second MGC pair is stored in the /opt/CiscoBAMS/data/s02 directory, and so forth. Cisco BAMS collects data from the Cisco MGC through the File Transfer Protocol (FTP) or SFTP.

Each BAMS node can collect from a single MGC node. The polling function of each BAMS node is configured with a login ID and password for the Cisco MGC hosts. BAMS can collect data from the Cisco MGC in simplex or redundant mode of operation. In a simplex mode of operation, the single BAMS unit performs the data collection across all eight nodes. In redundant mode, for each node, one BAMS unit actively collects from the MGC while the other unit is in standby mode. The active/standby polling status is independent for each BAMS node. On a single BAMS unit in a redundant system, some nodes may be in the active collection state, while other nodes are in the standby state. The corresponding nodes on the other BAMS unit will have the opposite polling status.

For each node, the data collection can be manually rotated from the active to the standby BAMS unit. Such a rotation is referred to as a data switchover and can be carried out routinely for preventive maintenance purposes. The fail-safe mode of operation invokes an automatic rotation from the active BAMS unit to the standby unit in the event of a system failure on the active unit.

Cisco BAMS Terminology

Cisco has changed some of the names for its products. Not all of these name changes have yet been made within the Cisco BAMS software. Note the following terms used in the Cisco BAMS software and configurations and their more recent Cisco MGC software equivalent.

Formatting Data

The raw data collected from the Cisco MGC units is in the form of binary files. This data must be converted into a format that the billing system can recognize. In addition to formatting the data files, BAMS also augments the billing data, adding data required by the billing system but not automatically provided by the Cisco MGC. BAMS validates the records and flags exceptions.

Finally, BAMS provides the data in a uniform format to the billing system, which permits record comparisons. Because the records are normalized, they are in a format suitable for statistical analysis. In addition to standardized billing data, BAMS generates measurements data. Measurements can be taken in a specified time interval and for a variety of data objects. This data is suitable for traffic studies on network usage.

Note Depending on the error flagged during validation, the record can be written to an error file and dropped, or it can flow through the system with default values. In either case, alarms are generated and written to the system log file (syslog). In general, structure or record-format errors result in the record being dropped. Lookup errors result in the record acquiring default values.

Storing Data

BAMS stores the formatted data on disk in a data directory where it can be collected or polled by the billing system. In addition to billing data, BAMS stores exception and measurements data, and writes system messages to a log file. The data collected by the billing system is renamed and is deleted from BAMS after archival, if desired, by the Mass Storage Control (MSC) task.

Files collected by BAMS from the Cisco MGC are time-stamped and sequence-numbered. Successfully formatted files are renamed with special prefix and suffix symbols. The MSC task must be set up with this file pattern information. The MSC can also be configured to generate alarms when specified data thresholds are passed. Alarm notification can also be set up for aged files. Alarms flag polling problems and prevent available disk space from filling up completely and halting or otherwise impeding system operation.

Note Billing files contain Bellcore AMA (Automatic Message Accounting) Format (BAF) records. BAF records do not contain an indexing field, such as a record count or sequence number. The billing file name, however, can be traced back to the original input file from the Cisco MGC.

Trapping Errors

Each BAMS software task generates its own set of error messages. A Simple Network Management Protocol (SNMP) task, bamstrap, is used to manage the trap messages. All messages are written to the system log by the Alarm task (ALM), converted into traps by bamstrap, and forwarded to the Cisco MGC Node Manager for response. The operator can then determine appropriate action based on the reported alarm or event.

System Backup and Recovery

Backup of data on BAMS can be accomplished in one of the following ways:

•For BAMS Release 3.20 and later: By using the BAMS utility, bamsbackup, to back up the configuration and data files to a file or device. For more information, see the "Backing up and Restoring BAMS.".

•For BAMS Release 3.14 and earlier: By backing up the data from the Sun Netra to a mass storage device, in which case the storage device must be supported by the Sun Netra platform

•For BAMS Release 3.14 and earlier: By collecting the data from BAMS over a TCP/IP network connection when backup is required and storing it on a backup server

The procedures for backing up and restoring data on Sun Solaris client/server systems are well established and documented, and several related tools are available to the UNIX system administrator. In addition to Sun Solaris documentation, third-party vendor documentation (for example, by Veritas) and general reference information are provided by UNIX software publishers, including O'Reilly and Wiley.

The best backup strategy depends on the user's network configuration and available resources. In general, users should collect files in an FTP session as often as necessary and store them as required. Each file recommended for backup is indicated in Table 1-5 by an asterisk following the description.

See the Sun Netra j20 (or later) Answerbook (Administrator's Guide) for system backup instructions.

BAMS features built-in recovery processes for system interrupt or crash. If the unit crashes in the middle of a provisioning session, restart the session using the dstver that the system crashed with as your srcver, and use a new dstver (see "prov-sta—Provision Start" section for details).

Note Contact the Cisco Technical Assistance Center for assistance with performing a BAMS system backup or restoring BAMS from a previous backup.

Installing the Sun Solaris 10 Operating System

Note The BAMS software package by itself does not contain any operating-system-dependent code and, therefore, will run on Solaris 10. The BAMS software license libraries do contain some operating-system-dependent calls that are not available in Solaris versions prior to 5.8. The only BAMS task that links to the software licensing libraries is MGR. The MGR task is built on Solaris version 5.8. BAMS 3.30 is compatible with Solaris 5.8 through 5.10.

Cisco BAMS 3.30 is compatible with the Sun Solaris 10 operating system. In addition, Cisco BAMS requires that you follow specific guidelines in the partitioning of the BAMS hard disks.

Before you install Cisco BAMS Release 3.30 software, you must ensure that Sun Solaris 10 is installed and that the Cisco BAMS server disks are properly partitioned. For information on installing Solaris 10 installation and disk partitioning, see the Cisco Media Gateway Controller Software Release 9 Installation and Configuration Guide.

BAMS 3.30 Modifications Overview

The Cisco Billing and Measurements Server (BAMS), for Release 3.30 software is modified to provide the following:

•Support for all the feeds and capabilities that are available in BAMS 3.20 release.

•Support for any new fields/CDRs that are supported in the Cisco Media Gateway Controller software, Releases 9.6(2) and 9.7(3), which runs on the Cisco PGW 2200.

•Support for any fields/CDRs that were changed after the release of Cisco BAMS 3.20.

•Support for the following Trunk Group measurements. Traps must be supported that notify when a configured threshold is crossed.

–Total seizures on a trunk group during a measured period—BAMS counts the call attempts (seizures) on a trunk group (IAM/SETUP in TAG 4003), over a defined period of time. The measured period must be configurable (1 hour is the default duration).

–Total answered calls on a trunk group during a measurement period—BAMS counts the receipt of ANM/ANSWER messages (TAG 4005) on a trunk group, over a defined period of time. The measured period must be configurable (1 hour is the default duration).

–Answer Seizure Ration (ASR) value during a measurement period—Information is derived using the measurements in A and B above (B ÷ A). The measured period must be configurable (1 hour is the default duration). The measurement threshold on ASR is crossed when the value drops below a specified value.

–Peak Traffic carried by each trunk group in Erlangs—A measurement is required for each trunk group to determine the Busy Hour (calls that reach the answer state) during a 24-hour period.

BAMS 3.30 Features and Formats

BAMS 3.30 supports all of the features and output formats that were supported in prior versions of BAMS. The BAMS 3.30 package supports all of the BAMS 3.20 features and output formats. The following new features and output formats are provided in BAMS 3.30:

•Support for Solaris 10 operating system

•Support for new fields/CDR in MGC Release 9.6 and 9.7

•Length change in existing CDE tags

•New CDE fields for extended ASCII output and Binary 1110 Output

•Support for trunk group measurements such as total seizures on a trunk group during a measured period and total answered calls on a trunk group during a measurement period; answer seizure ration (ASR) value during a measurement period; and peak traffic carried by each trunk group in Erlangs.

•New Measurements reported in the Daily file, based on current and new stored values, requiring new captured data and non-integer measurements

•Support for BAMS software licensing

•New alarms related to license failures

•Support for new QoS feed

•Support for the mode PGW Dynamic Update = True only

•SFTP File Transfer Support

•Generic Error Handling

Solaris 10 Support

The BAMS software package runs on the Solaris 10 operating system. The BAMS software licensing libraries do contain some operating-system-dependent calls that are not available in Solaris versions prior to 5.8. The BAMS MGR task is the only task that links to the license libraries. The MGR task is built on Solaris version  8. BAMS 3.30 is compatible with Solaris 5.8 through 5.10.

Continued Support for BAMS 3.20 Features and Formats

BAMS 3.30 supports all of the features and output formats that were supported in prior versions of BAMS. The BAMS 3.30 package is based on the source code of BAMS 3.20. The BAMS 3.30 new features and output formats are added to the existing functionality.

CDE Tag Length Changes

Table 1-1 lists the CDE tags for which the maximum length is changed. The internal structure of BAMS 3.30 is adjusted to accommodate the maximum length for the listed tags.

New CDE fields

Table 1-2 lists new CDEs in BAMS 3.30 that were not present in BAMS 3.20. FMT converts these fields into the internal BAMS format. The COR task merges the new fields.

New CDE Fields for Extended ASCII Output

For Cisco BAMS 3.30, new fields are added to the BAMS 3.20 Extended ASCII Output. The Field Index is a reference to the field in the comma-separated billing-output record.

See Chapter 7 "Configuring BAMS for ASCII Output and Measurements"

Note CDE 4234 and 4235 were present in BAMS 3.20 but are only used in CDB 1071. Therefore, they will not be generated on any billing outputs.

New CDE Fields for Binary 1110 Output

New fields 97-132 are added to the BAMS Binary1110 Output. The Field Index is for reference only and is not related to position in output.

See Chapter 10 "Configuring BAMS for 1110 Binary Output"

New Measurements

See Chapter 12 "Obtaining Measurements"

Support for BAMS Software Licensing

See the section "Cisco BAMS Software License" section.

Support for New QoS Feed

See Chapter 11 "Configuring BAMS for QoS Output"

Support for the Mode PGW Dynamic Update = True

The feature PGW Dynamic Update Mod was introduced in the BAMS 3.20 software release. All of the code necessary to support PGW Dynamic Update Mode already exists in the code base. The code base also supports operation when the PGW Dynamic Update Mode is set to False. The Mode of operation is determined by an environment variable (PGW_DYNAMIC_MODE). A utility provided in BAMS 3.20 was used to set this variable and make the necessary table modification when the value was changed.

The code that controls the operation of BAMS based on the value of the PGW_DYNAMIC_MODE is spread across almost all processes. To minimize the possibility of introducing errors into the system, the tasks have not been modified to change the way they handle the PGW_DYNAMIC_MODE variable. Instead, the set_pgw_mode utility is modified to enable setting the value to TRUE only. The utility changes the table structure to the PGW_DYNAMIC_MODE=TRUE structure.

The utility is required for users that wish to upgrade to BAMS 3.30; but, who currently are operating BAMS in the mode PGW_DYNAMIC_MODE = False. For such cases, the utility backs up the current configuration and then restructures the TRUNKGRP table. This action retains the customer's current trunk configuration and creates a TRUNKGRP table that is compatible with the PGW_DYNAMIC_MODE=TRUE mode. The default value for new installations is set to TRUE and an empty TRUNKGRP table with the correct structure for PGW_DYNAMIC_MODE=TRUE is installed. No utility is provided to change the PGW_DYNAMIC_MODE to FALSE. The MML command set-pgw-mode not available in Cisco BAMS 3.30. The MML command rtrv-ne will not report the PGW_DYNAMIC_MODE state.

SFTP File Transfer Support

Cisco BAMS 3.20 uses FTP to collect files from the Cisco PGW 2200 and to pass files between redundant BAMS units. In BAMS 3.30, operators can use FTP or the more secure SFTP as the file transfer protocol. The PGW2200 polling protocol is controlled by the poll.CTL file on a node by node basis. By default, the file transfer protocol is set to FTP for new installations. For upgraded installations, the current poll.CTL file is changed to the BAMS 3.30 structure and the polling protocol is set to FTP. In BAMS 3.30, file transfer protocol for BAMS-to-redundant-BAMS connections can be SFTP or FTP; but, for security purposes, Cisco recommends SFTP.

The FTP protocol is integrated into the BAMS software. Instead, BAMS invokes the command-line FTP utility supplied with the operating system. In BAMS 3.30, the polling task invokes either the command-line FTP or SFTP. SFTP is somewhat more complicated because the password cannot be supplied in the polling script as it is with FTP. In addition, SFTP attempts to read commands from a terminal. SFTP is invoked with the -b switch to redirect the command input to a file. In place of the password, the systems use a public key with a plaintext key file as the authentication method. Although this is not the most secure unattended authentication method, it does not require users to manually configure an ssh agent after each reboot. The use of public keys require the user to generate pairs of keys for each PGW 2200 that will be configured for SFTP using the ssh-keygen utility. The ssh-keygen utility must be used for new installations and for systems that are upgraded to BAMS 3.30. The setbamunit utility is used to identify a redundant BAMS system and the user name. A password is no longer required and can be left blank. There is no data-structure change and no migration is required.

Generic Error Handling

Background

The Generic Error Handling feature supports changes in CDE lengths without causing BAMS to stop processing data or shutting down. In prior releases, BAMS did not check the length of each CDE. The BAMS software ran with the assumption that the CDE length would match the expected length. When the FMT task encountered a CDE that exceeded the expected length, it used the length supplied in the CDE and copied it to the BAMS internal data structure. This caused memory to be overwritten and could cause a core dump and the task would shutdown. The MGR restarted the FMT task but the problem repeated until an operator intervened manually.

Implementation

Initially, all CDRs are processed by the FMT task and converted from Cisco raw format into BAMS internal format. As the FMT task processes each CDE, it checks it against an expected length. If the length is correct, it converts the CDE into internal format. If the CDE exceeds the expected length, FMT transfers only the expected number of bytes into the BAMS internal format. Any extra bytes are discarded. A minor alarm is raised and the system logs the discrepancy in the syslog.

Alarm

Whenever a CDE exceeds the expected length, an alarm is raised and a record of the alarm is entered into the syslog. Table 1-3 identifies a new alarm that supports generic error handling.

Cisco BAMS Software License

Cisco BAMS, Release 3.30 introduces software licensing. The BAMS software license enables running the BAMS application software on a specified Sun platform. The license is assigned per BAMS system. The license file is node locked on the hostID of the BAMS machine. For BAMS systems configured in an active-standby context, both BAMS nodes require an individual license file.

Host ID Mechanism

All Sun Microsystems machines have a unique hostID, which is a 32-bit integer. For BAMS software licensing, the hostID is used for node locking. For example, on Sun systems running the Solaris operating system, entering the hostid command obtains the 32-bit hostID in hexadecimal format.

The hostID is associated with the main board of the machine. If the main board is replaced or if a user wants to move the software to a new machine, the user must contact Cisco for a new license.

BAMS License Validation

BAMS 3.30 checks the base license with the start_system script first. Then BAMS continues to perform license validation. If there is no valid base license, the start_system script stops running and the user is informed that no valid base license exists.

Periodic License Validation

The BAMS software periodically checks (every 5 minutes) to ensure that the base license remains valid.

•If the base license expired, BAMS generates the "License Expired" alarm and shuts down the BAMS software. A user can read the log file to learn why BAMS shutdown.

•If there is a valid base license but it is due to expire in a week or less, BAMS generates the
"License to Expire at MM/DD/YYYY" alarm. However, the BAMS application software continues to run.

Base License Management During Switchover

BAMS checks for the existence of a base license during startup, and periodically thereafter, on both active and standby BAMS systems. A switchover does not affect base license management.

Exception Management

If the BAMS start_system script stops because there is no valid base license, the user first checks to verify that a valid base license exists and that the license is located in the directory /opt/CiscoBAMS/license on the associated machine.

If a valid base license exists but the license file is located in the wrong directory, the user must place the license file in the directory /opt/CiscoBAMS/license on the associated machine.

If no valid base license exists or an existing license has expired, the user must contact Cisco to obtain a license.

If BAMS generates a license-related alarm, the user should respond appropriately to address the problem identified in the alarm or contact the Cisco TAC.

If the BAMS software shuts down, the user should read the log file to see whether the shutdown occurred because the license expired. If the license expired, the user must contact the Cisco account team.

BAMS Software License Operations

Cisco BAMS Release 3.30 provides a check_license script that displays the current license information.

To install a new license file, a user copies the file to the directory /opt/CiscoBAMS/license.

License-Related Alarms

The BAMS Release 3.30 software includes the following alarms that it can generate if a license file does not exist:

•License Expired—This is a critical alarm. BAMS shuts down immediately following this alarm.

•License to Expire at MM/DD/YYYY—This is a major alarm. This alarm is cleared when a new license is installed. The alarm is generated when there are 7 days or fewer remaining for the license. This alarm is generated every 24 hours until a new license file is installed.

BAMS License File Types

Cisco BAMS Release offers five distinct license types.

•General license—A general (base) license does not expire.

•Temporary license—A temporary license is intended to be used by a customer whose application has gone down and must be reactivated quickly but cannot get a license through the appropriate channel.

•Demo license—"Evaluation" orders for BAMS include a demo license that expires after 60 days. After 60 days, BAMS will not operate until a new product authorization key (PAK) is registered.

•External Lab License—An external lab license enables a Cisco partner to run BAMS in its lab to validate interoperability of its systems with BAMS. This license is similar to a Demo License, but expires after 180 days.

•Internal Lab License—A lab license for running BAMS in Cisco labs. This license expires after one year.

Table 1-4 provides additional information about the BAMS license types.

Note Cisco BAMS 3.30 provides the command check_license that you can enter to check the status of a BAMS software license.

Installing BAMS with the Licensing Mechanism

To support BAMS licensing, the BAMS 3.30 software includes the new directory /opt/CiscoBAMS/license, which is provided to contain license files. Also, a new license management utility named lmutil is included in the directory /opt/install/bin.

Note If BAMS is uninstalled, existing license files remain on the system so that they are present in case the user re-installs BAMS.

To install BAMS 3.30 to include the licensing mechanism on an active-standby system, complete the following steps:

Step 1 Install BAMS on the active platform and configure it as BAMS unit 0.

Step 2 Obtain the hostID of the BAMS system by establishing a Telnet session and issuing the hostid command as shown in the following example:

bash-3.00$ telnet <BAMS_IP_address>

Trying <BAMS_IP_address>...

Connected to <BAMS_IP_address>.

Escape character is '^]'.

login: bams

Password: 

Last login: Wed Mar 12 21:56:30 from <BAMS_hostname>

Sun Microsystems Inc.   SunOS 5.10      Generic January 2005

$ hostid  

8459d5de 

Step 3 Go to the Cisco Systems web site and use the hostID of BAMS unit 0 with the PAK that is provided with the BAMS software CD to apply the license file.

Note Cisco emails the appropriate license file to each BAMS customer.

Step 4 Copy the license file to the directory /opt/CiscoBAMS/license. If an older license file is present in this directory, delete it.

The active BAMS is now ready for operation.

Step 5 Login as bams user and enter the command start_system.

Step 6 Install BAMS on the standby platform and configure it as BAMS unit 1.

Step 7 Go to the Cisco Systems website and use the hostID of BAMS unit 1with the PAK that is provided with the BAMS software CD to apply the license file.

Step 8 Copy the license file to the directory /opt/CiscoBAMS/license. If an older license file is present in this directory, delete it.

Step 9 Login as bams user on BAMS unit 1 and enter the command start_system

Note The preceding steps are all that are required to install BAMS 3.30 (with the licensing mechanism) on a BAMS active-standby system. For a single, standalone BAMS system, only the first four steps are required.

License Upgrade Procedure

To upgrade BAMS to include the licensing mechanism on an active-standby system, complete the following steps:

Step 1 Stop BAMS on BAMS unit 0.

Step 2 Remove the preceding release of the BAMS software.

Step 3 Install BAMS 3.30.

Step 4 Go to the Cisco Systems web site and use the hostID of BAMS unit 0 with the PAK that is provided with the BAMS software CD to apply the license file.

Step 5 Install the license file on BAMS unit 0.

Step 6 Login as bams user on BAMS unit 0 and run start_system.

Step 7 Stop BAMS on BAMS unit 1.

Step 8 Remove the preceding release of the BAMS software.

Step 9 Install BAMS 3.30.

Step 10 Go to the Cisco Systems website and use the hostID of BAMS unit 1 with the PAK that is provided with the BAMS software CD to apply the license file.

Step 11 Install the license file on BAMS unit 1.

Step 12 Login as bams user on BAMS unit 1 and run start_system.

Note The preceding steps are all that are required to upgrade to BAMS 3.30 (with the licensing mechanism) on a BAMS active-standby system. For a single, standalone BAMS system, only the first four steps are required.

Upgrading from a Temporary to a Base License

If you operate BAMS initially with a demo or temporary license and subsequently wish to upgrade to a base BAMS license, complete the following steps.

Step 1 Obtain the appropriate license file via email from Cisco.

Step 2 Copy the new license file onto the license server and into the directory /opt/CiscoBAMS/license on the BAMS system.

Step 3 Delete the demo or temporary license file from the license server and from the BAMS system.

Migration

See the section "Upgrading to BAMS Release 3.30"

Creating Directory Structures

Data directories are created for you during BAMS installation. Table 1-5 describes the Cisco BAMS directories.

1. Indicates files recommended for backup.