Introduction to Cisco BAMS
Available Languages
Table Of Contents
Installing the Sun Solaris 10 Operating System
BAMS 3.30 Modifications Overview
BAMS 3.30 Features and Formats
Continued Support for BAMS 3.20 Features and Formats
New CDE Fields for Extended ASCII Output
New CDE Fields for Binary 1110 Output
Support for BAMS Software Licensing
Support for the Mode PGW Dynamic Update = True
Base License Management During Switchover
BAMS Software License Operations
Installing BAMS with the Licensing Mechanism
Upgrading from a Temporary to a Base License
Introduction to Cisco BAMS
Revised: April, 2010, OL-11618-16The 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
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:
•
•
•
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 on page 4-16 for details).
Note
Installing the Sun Solaris 10 Operating System
Note
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:
•
•
•
•
–
–
–
–
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:
•
•
•
•
•
•
•
•
•
•
•
•
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, "Extendable ASCII Output"
Note
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, "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.
•
•
"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:
•
•
BAMS License File Types
Cisco BAMS Release offers five distinct license types.
•
•
•
•
•
Table 1-4 provides additional information about the BAMS license types.
Table 1-4 BAMS License Types
General
none
Temporary
72 hours
Demo
60 days
Internal lab
1 year
External lab
180 days
Note
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
To install BAMS 3.30 to include the licensing mechanism on an active-standby system, complete the following steps:
Step 1
Step 2
bash-3.00$ telnet <BAMS_IP_address>Trying <BAMS_IP_address>...Connected to <BAMS_IP_address>.Escape character is '^]'.login: bamsPassword:Last login: Wed Mar 12 21:56:30 from <BAMS_hostname>Sun Microsystems Inc. SunOS 5.10 Generic January 2005$ hostid8459d5deStep 3
Note
Step 4
The active BAMS is now ready for operation.
Step 5
Step 6
Step 7
Step 8
Step 9
Note
License Upgrade Procedure
To upgrade BAMS to include the licensing mechanism on an active-standby system, complete the following steps:
Step 1
Step 2
Step 3
Step 4
Step 5
Step 6
Step 7
Step 8
Step 9
Step 10
Step 11
Step 12
Note
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
Step 2
Step 3
Migration
See the section Appendix B, "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.
Feedback