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

Setup and Installation

Overview

This chapter provides information on how to configure the Cisco Media Gateway Controller (MGC) for using the Billing and Measurements Server (BAMS), how to uninstall previous BAMS software versions, and how to install and configure new versions of BAMS.

Upgrading from BAMS Release 2.68 to Release 3.x

If this is a first-time BAMS installation, follow the installation procedure in this chapter. If you are currently operating BAMS Release 2.68 software, you need to follow a migration procedure to install Release 3.x. Proceed to "Upgrading from BAMS Release 2.68 to BAMS Release 3.10."

Configuring the Cisco MGC for Using BAMS

You must edit your dmprSink.dat file to set the interval to dump the call detail records (CDRs) to the spool directory every 5 minutes. To do so, use this procedure:

Step 1 cd /opt/CiscoMGC/var

Step 2 mkdir bam

Step 3 chmod 777 bam

Step 4 Open a vi session:
vi /opt/CiscoMGC/etc/dmprSink.dat

Step 5 Edit it as follows:
1 "callDetail" bin "cdr" "../var/log" "../var/bam" 8000 0 5

Step 6 Open another vi session on the XECfgParm.dat:
vi /opt/CiscoMGC/etc/XECfgParm.dat

Step 7 Verify the correct CDB settings:

a. engine.CDRtimeStamp = M

b. engine.CDRmessageTypes = "1010,1020,1030,1040,1050,1060,1070,1080"

Note The time stamp must be in milliseconds (M) and the message types must be from 1010 through 1080, except 1110 is not supported when you are using BAMS in its normal configuration. However, BAMS can be configured to output Cisco MGC End of Call records (see "Configuring BAMS for BAF Output," for details).

Step 8 Edit the diskmonitor parameter in XECfgParm.dat to indicate whether the CDR files are to be kept after collection. You can use the same parameter to indicate how long the files are to be kept. If the value is 0, the .finished files are removed immediately. A value of 1 means that the .finished files are deleted after 1 day, 2 for 2 days, and so on. In the following example, the files are removed after 1 day, as reflected in diskmonitor.CdrRmFinished = 1.

#----------------------------------

# Disk Monitor Parameters

#----------------------------------

diskmonitor.Limit = 7 # MIGRATED

diskmonitor.Threshold = 80 # MIGRATED

diskmonitor.SoftLimit = false # MIGRATED

diskmonitor.CdrRmFinished = 1 # (remove "finished" cdrs after X days (0 = immediate))

diskmonitor.OptFileSys = # (list of optional file systems to monitor (no trimming))

Step 9 Open another vi session:

vi /opt/CiscoMGC/etc/CONFIG_LIB/new/XECfgParm.dat 

Step 10 Repeat Step 4 through Step 8 in the active_link directory, the prov_link directory, and in the new directory.

Caution The Cisco MGC file-closing interval must be set to a value less than the BAMS measurement interval. For example, if the BAMS measurement interval is set to 5 minutes, the dumper file interval must be set to 4 minutes or less. If the Cisco MGC file interval is greater than or equal to the BAMS measurement interval, more than one measurement interval could be crossed in a single input file. If this happens, a COR206 major alarm is asserted. The end result is the loss of measurement data. This loss of data causes the ACC task to generate an ACC222 minor alarm.

Step 11 Stop the Cisco MGC

/etc/init.d/CiscoMGC stop 

Step 12 Start the Cisco MGC for the file changes to take effect:

/etc/init.d/CiscoMGC start

Uninstalling BAMS

If a previous BAMS release is already installed, you must uninstall it to start a new system. This procedure removes all BAMS software; however, you can save the data and archive directories during the uninstall procedure. The uninstall procedure also asks you if you want to save the current active BAMS configuration to a restorable provisioning batch file.

Note The uninstallation process removes the contents of the /opt/CiscoBAMS directory except the /opt/CiscoBAMS/CDR and /opt/CiscoBAMS/data folders.

Caution Do not remove the /opt/CiscoBAMS/CDR and /opt/CiscoBAMS/data directories manually. They are disk partition mount points.

To uninstall BAMS, use this procedure:

Step 1 Log in as the BAMS user.

Step 2 Stop the application by entering the following commands:
$ cd /opt/CiscoBAMS/bin
$ mml
mml:sys> stp-softw::confirm
mml:sys> quit

Note The default UNIX prompt ($ or #) might vary with the shell program being used.

Step 3 Log out. Make sure that all BAMS logins have exited. This account is removed during the uninstallation.

Step 4 Log in as the root user by entering the following command:
:root
:<password>

Step 5 Uninstall the application software:
$ cd /opt/install

Step 6 Run the uninstall script:
$ bams uninstall

Step 7 Follow the prompts from the uninstallation script. (The uninstall script automatically copies the BAMS configuration files from /opt/CiscoBAMS/files to /usr/tmp/bamsconfig).

Step 8 Uninstall the application software:
$ cd /opt
$ pkgrm CSCOcaBAM

This completes the uninstallation procedure.

Installing Cisco BAMS

Note Cisco BAMS Release 3.x requires the Sun Solaris 8 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.x software, you must make sure that Sun Solaris 8 is installed and that the Cisco BAMS server disks are properly partitioned. For information on installing Solaris 8 installation and disk partitioning, see the Cisco Media Gateway Controller Software Release 9 Installation and Configuration Guide located at:

http://www.cisco.com/univercd/cc/td/doc/product/access/sc/rel9/swinstl/index.htm

Step 1 Insert the CD labeled "Cisco Billing and Measurements Server (BAMS)" (Release 3.12 or higher) in a CD-ROM drive.

Step 2 For each machine on which BAMS is to be installed, obtain the following information from your system administrator:

a. Platform host name.

b. Platform IP address.

c. Platform user name.

d. Platform user password.

e. Home directory for the BAMS account (default: /opt/CiscoBAMS/local).

f. Where to put the /opt/CiscoBAMS/data directory for all data files created by the application. This is usually a separate disk or file system (default: /opt/CiscoBAMS).

Note The system prompts are displayed in the UNIX Korn shell. Refer to user documentation such as UNIX Complete by SYBEX for more information on the Korn shell. You must be familiar with the Korn shell and use of the UNIX vi text editor in order to properly set up and configure BAMS.

Step 3 Log in as the root user by entering the following command:
:root
:<password>

Step 4 Install the CSCOcaBAM package (from the solaris_patches directory) by entering the following commands:
$ cd /cdrom/cdrom0
$ pkgadd -d CSCOcaBAM.pkg

Step 5 Follow the prompts.

Caution Do not install the following Solaris 8 Patch:

CSCOh005: It creates two unnecessary file systems on BAMS.

Step 6 Run the BAMS install script by entering the following commands:
$ cd /opt/install
$ ./bams install

Step 7 Follow the prompts.

When the installation is complete, the system displays the following message: Installation of <CiscoBAMS> was successful.

Step 8 After the installation has successfully completed, reboot the system.

Note For upgrade installations: An option to restore the BAMS configuration files is given during the installation:

Do you wish to restore BAMS configuration files from the previous installation? [y,n]

Answering y to this prompt restores the provisioning tables from the previous installation. After you install BAMS Release 3.x with the restore option, on each BAMS unit run the change_mode command. As well, start an mml session and set each node with the set-node command. Set the sequence numbers for that node and the next file to be polled from the Cisco MGC VSC pair with the MML chgno command.

Refer to the "Configuring BAMS" section for further details about these commands.

Step 9 Go to the Cisco website and download the latest patch for BAMS Release 3.x.

Step 10 Install the patch.

Configuring BAMS to Forward SNMP Traps

To configure BAMS to forward SNMP traps to a management application, perform the following steps:

Step 1 Log in as the root user by entering the following command:
:root
:password

Step 2 Open a vi session:

vi /etc/srconf/agt/snmpd.cnf

Step 3 Make sure the following lines exist under the snmpNotifyEntry section (if they are not there, add them):
snmpNotifyEntry 31 Console trap nonVolatile
snmpNotifyEntry 32 TrapSink trap nonVolatile

Note Number 31 must be unique in that section. Each entry number must be unique.

Step 4 Make sure the following lines exist under the snmpTargetAddrEntry section (if they are not there, add them):
snmpTargetAddrEntry 33 snmpUDPDomain 127.0.0.1:0 100 3 Console \
v1ExampleParams nonVolatile 255.255.255.255:0 2048
snmpTargetAddrEntry 34 snmpUDPDomain 127.0.0.1:0 100 3 Console \
v2cExampleParams nonVolatile 255.255.255.255:0 2048

Note Number 33 must be unique in that section. Each entry number must be unique.

Step 5 To forward a V1 trap to the IP address of the network management platform (A.B.C.D in the lines below), add the following line:
snmpTargetAddrEntry 35 snmpUDPDomain A.B.C.D:0 100 3 TrapSink \
v1ExampleParams nonVolatile 255.255.255.255:0 2048

Step 6 To forward a V2c trap to destination A.B.C.D, add the following line:
snmpTargetAddrEntry 36 snmpUDPDomain A.B.C.D:0 100 3 TrapSink \
v2cExampleParams nonVolatile 255.255.255.255:0 2048

Step 7 Restart the snmpdm process:
kill -9 pid

Note The value of pid is the process ID for snmpdm, and snmpdm restarts itself after termination.

Configuring BAMS

To configure BAMS, perform the following steps:

Step 1 Log in as the root user by entering the following command:
:root
:password

Step 2 Define the network node names and IP addresses of the Cisco MGC and the BAMS units in the file /etc/hosts. You must edit and save the host file with the information obtained from your system administrator, using the UNIX vi text editor to enter the following commands:
$ cd /etc/inet
$ chmod 744 hosts
$ vi hosts

Step 3 Log out as the root user.

Caution All of the dual Ethernet connections and host names should be set up and defined for each BAMS and Cisco MGC unit. The redundant Ethernet connection should have a suffix of _b; for example: MGC1 hostname=ciscomgc1, MGC1 redundant connection hostname=ciscomgc1_b.

Step 4 Log in as the BAMS user.

Step 5 Set up the basic BAMS configuration. Define the following options:

a. Simplex versus redundant BAMS units

b. Cisco MGC setup: normal versus Cisco SC2200

c. Measurements reporting interval (bucket size)

Note To change the system settings for simplex versus redundant mode, run change_mode and follow the instructions. The following change_mode example shows user input for setting up BAMS in simplex mode:

$ cd /opt/CiscoBAMS/bin
$ change_mode

System must be re-started manually for changes to take effect.
Do you want to continue (y/n)? y

Enter mode of operation:
1. Simplex BAMs mode
2. Redundant BAMs mode

Enter mode [1-2] : 1

To set up the BAMS unit for SC2200 applications and check the measurements reporting interval, start an MML provisioning session, modify the configuration of the Node Parameters table using the NODEPARMS tag ID, and deploy any changes you make.

Refer to the "Configuring Node Parameters" section.

Step 6 Set the unit designation.

Note For a redundant configuration, this step must be performed on both units:

a. Modify the UNITNO environment variable definitions to define the unit number in the file /opt/CiscoBAMS/bin/sym_defs. (The primary BAMS unit should be 0, and the secondary BAMS unit should be 1.)

Note You can designate the Cisco MGC units 1 and 2. You must confirm the unit designations with your system administrator. Do not modify the BAMS 0 and 1 unit numbers to match the Cisco MGC numbers 1 and 2, or the system will not work as intended.

b. After unit designation is complete, reset the system environment variables by entering the following commands:
$ cd /opt/CiscoBAMS/bin
$ . sym_defs

Note Only valid users with appropriate permissions can access the Cisco MGC. They must be set up with permissions in the Cisco MGC group for Cisco MGC software Release 7.4 and later releases, and in the TransPath group for releases before software Release 7.4.

c. From within the /opt/CiscoBAMS/bin directory, enter the command setbamunit to configure the host name, login ID, and password parameters for both BAMS units.

All parameters should be defined. The parameters bam_name0 and bam_name1 should correspond to the node names of the BAMS units defined in the file /etc/hosts. See the following example:

$ cd /opt/CiscoBAMS/bin
$ setbamunit
New value for `bam-name0' [ ]: bams0
New value for `login0' [bams]: bams
Enter new password for `passwod0': xxxxxxxx
Re-enter password: xxxxxxxx
New value for `bam-name1' [ ] : bams1
New value for `login1' [bams] : bams
Enter new password for `passwd1': yyyyyyyy
Re-enter password: yyyyyyyy
$

Step 7 Configure the Cisco MGC polling parameters for the first node by using the Man-Machine Language (MML) program to set the first node. This creates the initial polling control file for node 1 (opt/CiscoBAMS/files/s01/poll.CTL).
$ cd /opt/CiscoBAMS/bin
$ mml

You can also change the MML environment by just entering the node identifier:
mml:sys> set-node:1:

To start an MML editing session, enter the following command:
mml:1> prov-sta::srcver=active,dstver=test1
Billing and Measurements Server - BAMS-00 2002-01-09 15:20:30
B COMPLD
;

To set the node name "boston" for the first node, enter the following command:
mml:sys> set-nodename:1:name="boston"

To display the polling record for this node, enter the following command:
mml:1> prov-rtrv:poll:
Billing and Measurements Server - BAMS-00 2002-01-09 15:30:02
B RTRV
;

Initially, this file is empty.
To display the configuration parameters, enter the following command:
mml:1> prov-rtrv:poll:?
Billing and Measurements Server - BAMS-00 2002-01-09 15:21:49
B COMPLD
host-name1 (string)
rem-dir1 (string)
file-prefix1 (string)
file-suffix1 (string)
host-name2 (string)
rem-dir2 (string)
file-prefix2 (string)
file-suffix2 (string)
action (string)
interval (numeric)
maxtries (numeric)
;

When you add a polling record to the Poll table, you must specify the file prefix (for example, "cdr*") and suffix (for example, ".bin") for the CDR files on each host. The CDR files produced on the Cisco MGC switch use the following naming convention:

<prefix>_yyyymmddhhMMss_nnnnnn.bin

where:

<prefix> is defined in the Cisco MGC switch configuration (for example, "cdr")

yyyymmddhhMMss is the timestamp. BAMS ignores the timestamp when polling; it uses the file sequence number instead.)

nnnnnn is the file sequence number. You specify this number with the chgno command in Step 9.

.bin is the suffix

To add a polling record (all required fields and values must be specified), enter the following command:

mml:1> prov-add:poll:host-name1="MGCtest1",rem-dir1="/opt/CiscoMGC/var/bam",
file-prefix1="cdr*",file-suffix1=".bin",host-name1="MGCtest2",file-prefix2="cdr*",file-suffix2=".bin",action="R",interval=5,timeout=2,maxtries=2
Billing and Measurements Server - BAMS-00 2002-01-09 16:28:02
B COMPLD
"POLL"
;

In the example above, the file-prefix1 and file-suffix1 parameters must correspond to the file generated on the Cisco MGC switch 1 (host-name1 parameter), and the file-prefix2 and file-suffix2 parameters must correspond to the file generated on the Cisco MGC switch 2 (host-name2 parameter).

To edit the polling configuration information for this node, use the following command:
mml:1> prov-ed:poll:maxtries=3

Refer to the "POLL Tag ID" section for details on the Poll table's required fields and values.

Step 8 To deploy the changes, use the following command:
mml:1> prov-dply::

If the remote unit is online, the files are synchronized and the following messages display on the screen:

/* Synchronizing remote BAMS ... */
/* Transferring file /opt/CiscoBAMS/files/s01/zoneinfo.CTL ... */
/* Transferring file /opt/CiscoBAMS/files/s01/TrunkGroup.CTL ... */
/* Transferring file /opt/CiscoBAMS/files/s01/alm_parms.CTL ... */
/* Transferring file /opt/CiscoBAMS/files/s01/country.CTL ... */
/* Transferring file /opt/CiscoBAMS/files/s01/maptype.CTL ... */
/* Transferring file /opt/CiscoBAMS/files/s01/nodeParm.CTL ... */
/* Transferring file /opt/CiscoBAMS/files/s01/NpaNxx.CTL ... */
/* Transferring file /opt/CiscoBAMS/files/s01/poll.CTL ... */
/* Transferring file /opt/CiscoBAMS/files/s01/RatingType.CTL ... */
/* Transferring file /opt/CiscoBAMS/files/s01/RatingException.CTL ... */
/* Transferring file /opt/CiscoBAMS/files/s01/NailedConn.CTL ... */
/* Transferring file /opt/CiscoBAMS/files/s01/skipcdb.CTL ... */
/* Transferring file /opt/CiscoBAMS/files/s01/skipcde.CTL ... */
/* Transferring file /opt/CiscoBAMS/files/s01/thresholds.CTL ... */
/* Transferring file /opt/CiscoBAMS/files/s01/tollfree.CTL ... */
;

Note You must be in an active provisioning session (prov-sta command) to edit any parameters; use the prov-dply command to implement the changes.

Step 9 Identify the sequence number of the first file to be polled from each Cisco MGC switch. You modify the polling file sequence number by using the MML chgno command. This file sequence number must correspond to the sequence number of the files generated by the Cisco MGC switches. Refer to Step 7 for the filename format. You can change one or both file sequence numbers with this command.

mml:1> chgno::[seqno1=#,][seqno2=#]

seqno1 is the file sequence number of the first polled unit, and seqno2 is the file sequence number of the second polled unit. For example:

chgno::seqno1=0001,seqno2=0002

The system should be stopped when you execute the chgno command. If the system is running, be sure it is not polling, or else a "Load record failed error" message could be generated. If chgno fails, you receive the message "Polling control record #1 in use by POL program — try again later."

Step 10 Quit the MML session by entering the following command:
mml:1> quit

Step 11 For security reasons, the login information for the Cisco MGCs is not entered through the MML interface. The BAMS user must execute the program /opt/CiscoBAMS/bin/setpollpwd to define the login IDs and passwords for the redundant Cisco MGC units.

$ cd /opt/CiscoBAMS/bin
$ setpollpwd -sx (Where x represents the node identifier: 1 to 8)
New value for `userid1' [ ]: mgcuser1
Enter new password for `password1': xxxxxxxx
Re-enter password: xxxxxxxx
New value for `userid2' [ ]: mgcuser2
Enter new password for `password2': yyyyyyyy
Re-enter password: yyyyyyyy
$

Step 12 Repeat Step 7 through Step 11 to set up each additional node (2 through 8).

Step 13 Configure the MSC module to monitor the disk usage levels.

Note The MSC threshold levels have been set at default values, but you can modify them by entering the following commands:

$ cd /opt/CiscoBAMS/bin
$ mml
mml:sys> sta-softw

To display threshold values, enter the following command:

mml:sys> prov-rtrv:msc-thres:

To display file parameters, enter the following command:

mml:sys> prov-rtrv:msc-parms:

Note If BAMS Release 1.x has been uninstalled and is being replaced by BAMS Release 3.x, log in as a user and enter the following commands:

$ cd /opt/CiscoBAMS/data/output
$ mv /tmp/incomplete_cdr.cor.out incomplete_cdr.cor

Reconfigure the provisioning tables using the MML command.

Step 14 Start the system by entering the following commands:
$ cd /opt/CiscoBAMS/bin
$ mml
mml:sys> sta-softw

This completes the installation process.

Note You can also start or stop the system from the UNIX prompt by using start_system or stop_system.

Configuring Node Parameters

Use the NODEPARMS tag ID to set node parameters such as record-type outputs (for example, ASCII, BAF, NICS, P01) and measurements.

To display the node parameters, you need to first set a node. Enter the following commands:

$ cd/opt/CiscoBAMS/bin 
$ mml 
mml:sys> set-node:1:

Billing and Measurements Server - BAMS-00 2002-01-22 10:36:39 
mml:1:boston> prov-rtrv:NODEPARMS:

Billing and Measurements Server - BAMS-00 2002-04-29 15:51:52

B  RTRV

   
"NODEPARMS:activate=1,statoutput=1,bafoutput=0,asciibafoutput=0,asciioutput=2,lookupinfo=1
,bafinfo=1,dynamicaccumes=0,sup-zero-counts=0,interval-minutes=15,nailed-cfg=1,p01output=0
,p01prefix="p01_",enable-h323=0,extasciioutput=0,nicsoutput=0"

   ;

Caution The Cisco MGC file-closing interval must be set to a value less than the measurement interval. For example, if the measurement interval is set to 5 minutes, the dumper file interval must be set to 4 minutes or less. If the Cisco MGC file interval is greater than or equal to the BAMS measurement interval, the possibility exists that more than one measurement interval can be crossed in a single input file. If this happens, a COR206 major alarm is asserted. The end result is the loss of measurement data. This loss of data causes the ACC task to generate an ACC222 minor alarm.

Note Refer to the "NODEPARMS Tag ID" section for details on the available node parameters and acceptable values.

Host Configuration Setup for Downstream Polling

You can collect files in the opt/CiscoBAMS/data directories (ASCII, BAF, measurements, NICS, and so forth) through an appropriate FTP session. This is referred to as FTP polling of BAMS by the downstream billing system. In an automated FTP session, data collected from BAMS is stored in appropriate directories on the downstream billing system. After a successful poll of a data file, the data file in the BAMS /data subdirectory should be renamed with a *.finished suffix. In a redundant configuration, the duplicate file on the redundant BAMS unit should also be renamed. This allows the BAMS MSC task to delete these polled files, freeing up disk space.

The billing system host must be set up to support such polling. Data files should be collected through FTP in binary transfer mode so that data file corruption is avoided. For automated storage, report creation and generation, and analysis, a number of solutions are available.

Setting Up Disk Monitoring Thresholds

The Mass Storage Control (MSC) task maintains disk space on the BAMS units according to percentage-based disk-space usage thresholds. Use the MSC-THRES tag ID at the system level to configure the MSC thresholds. Refer to "Using BAMS Tag IDs," for the MSC-THRES field names and values.

In the following example, the MSC task is set up to run at 15-minute intervals:

prov-ed:msc-thres:interval=15,iut=50000,put=60,plt=40,uut=80,mil=75 

Note the following in this example:

•The inode upper threshold has been set at 50,000 inodes.

•The polling upper threshold is set at 60 percent of the available disk space, and the lower threshold is set at 40 percent of the disk space.

•The unpolled upper threshold has been set at 80 percent of the available disk space.

•A minor alarm level has been set at 75 percent.

The MSC task uses the directory name and a user-defined file pattern to distinguish polled files from unpolled files. The actual values depend on disk usage and fill factors that vary between BAMS locations. The system administrator must determine the appropriate values for a given location.

Calculating Disk Space Usage

When you establish the MSC task interval, you must make disk space usage estimates. The following examples are provided to help you estimate data processing and archive partitioning based on average calls per second (CPS). You can use the estimates listed to:

•Calculate how long data files will remain in the data directories before deletion by the MSC task

•Determine a backup procedure if the BAMS data is not being forwarded to another device

•Customize the MSC disk usage parameters

The estimates listed in Table 2-1 are based on an 18-GB disk partition and an output configuration for BAF, measurements, and ASCII. The estimates in Table 2-2 are based on an 18-GB disk partition and an output configuration for BAF and measurements. The estimates in Table 2-3 are based on a 12-GB disk partition.

Defining Conditions for MSC Alarms

Use the MSC-PARMS tag ID to define conditions that generate alarms or events, based on parameters such as file size, file type, and file age. Refer to "Using BAMS Tag IDs," for a detailed description of the tag ID field names and values.

In the following example, the MSC task looks for polled files with a baf* prefix to determine whether or not to set off a minor alarm:

prov-ed:msc-parms:type=baf*,polled=1

Setting a File-Age Condition

You can set a file-age condition by setting an age value (in days) in the MSC-PARMS tag ID's agealarm field. In the following example, an alarm will occur once BAF files are 40 days old:

prov-ed:msc-parms:type="baf*",agealarm=40

Setting a File-Type Condition

You can add file-type conditions for files that the MSC task should monitor. To do so, use the prov-add command. Configure the MSC task to clean up unneeded files and to conserve disk space. A file already polled by the downstream billing system is an example of an unneeded file. A BAMS file-naming convention is used to indicate the file processing state and whether files have been polled or not. Thus file naming serves to indicate to the control task which files must be saved and which files are unneeded.

In the following example, the MSC task looks for files with a *.polled suffix.

prov-add:msc-parms:type="*.polled"

Setting Disk Usage Thresholds

You can add disk usage thresholds to be monitored by the MSC task. To do so, use the prov-add command. In the example below, the MSC task looks for unpolled files with the baf* prefix and generates a minor alarm if a file is older than 10 days. After 30 days, the MSC task deletes that file and sets a critical alarm.

prov-add:msc-parms:type="baf*",polled=2,agealarm=10,agelevel=2,delage=30,delalarm=0