Cisco Service Control Management Suite Subscriber Manager User Guide

Service providers of any access technology (DSL, cable, mobile, and so on) targeting residential and business consumers must find new ways to get maximum leverage from their existing infrastructure, while differentiating their offerings with enhanced IP services.

The Cisco Service Control Application for Broadband adds a new layer of service intelligence and control to existing networks that can:

Cisco provides complete network FCAPS (Fault, Configuration, Accounting, Performance, Security) Management.

Two interfaces are provided for network management:

Where the SCA BB enforces different policies on different subscribers and to track usage on an individual subscriber basis, the Cisco Service Control Management Suite (SCMS) Subscriber Manager (SM) may be used as middleware software for bridging between the OSS and the SCE platforms. Subscriber information is stored in the SM database and can be distributed between multiple platforms according to actual subscriber placement.

The SM provides subscriber awareness by mapping network IDs to subscriber IDs. It can obtain subscriber information using dedicated integration modules that integrate with AAA devices, such as Radius or DHCP servers.

Subscriber information may be obtained in one of two ways:

The Cisco Service Control solution generates usage data and statistics from the SCE platform and forwards them as Raw Data Records (RDRs), using a simple TCP-based protocol (RDR-Protocol). The Cisco Service Control Management Suite (SCMS) Collection Manager (CM) software implements the collection system, listening in on RDRs from one or more SCE platforms and processing them on the local machine. The data is then stored for analysis and reporting functions, and for the collection and presentation of data to additional OSS systems such as billing.

The following figure shows the flow of subscriber information through the SM.

Figure 2.1. SM General Architecture

The flow takes place as follows:

The SM may be configured with more than one SCE platform. These SCE platforms may be grouped into domains. Each domain represents a group of SCE platforms that serve the same group of subscribers.

The subscribers of the service provider may be divided into the following logical types (at any given moment):

In addition, the total number of subscribers is all the subscribers whose IP traffic might be traversing through the SCE platforms in a specific deployment.

There are four general scenarios for a network system using the SCE platforms:

For specific scenarios using the SM with multiple servers and/or SCE platforms, see System Configuration Examples.

The SM uses a commercial relational database from TimesTen, optimized for high performance and with a background persistency scheme. The In-Memory Database efficiently stores and retrieves subscriber records.

A subscriber record stored in the SM Database (SM-DB) consists of the following components:

You can access the subscribers using one of two indexes:

Note that in cluster redundancy topology, the active machine database replicates the subscriber data to the standby machine database. For additional information, see the Subscriber Manager (SM) Fail-Over section.

The Subscriber ID is a string representing a subscriber that is a unique identifier for each subscriber from the customer perspective. For example, it may represent a subscriber name or a CM MAC address. This section lists the formatting rules of a subscriber ID.

It may contain up to 64 characters. The following characters may be used:

For example:

Use the SM API for:

The SM API is provided in C, C++, and Java. It serves as the bottom-most layer of every LEG.

SM API programmer references are provided in the Cisco SCMS SM C/C++ API and the Cisco SCMS SM Java API Programmer Guides.

The SM Login Event Generators (LEGs) are software components that use the SM API to generate subscriber-record update messages (such as login/logout) and send them to the SM. LEGs are usually installed with AAA/OSS platforms, or with provisioning systems. They translate events generated by these systems to Cisco Service Control subscriber update events.

The unique functionality of each LEG depends on the specific software package with which it interacts. For example, RADIUS LEGs, DHCP LEGs, or some provisioning third party system LEGs may be implemented. LEGs can set up subscribers or alter any of the fields of an existent subscriber record.

You can connect multiple LEGs to a single SM. Conversely, a single LEG can generate events for multiple domains.

As illustrated in the figure in Flow of Subscriber Information, the SM introduces subscriber data to the SCE platforms. This operation functions in one of two modes:

Push or Pull mode is configured for the entire SM system.

For information detailing the configuration of the subscriber integration modes, see the SM General Section.

The SM provides the option of partitioning SCE platforms and subscribers into subscriber domains.

The motivation for the domains concept is for enabling a single SM to handle several separate network sections, and for better control of subscriber introduction to the SCEs.

A subscriber domain is a group of SCE platforms that share a group of subscribers. The subscriber traffic can pass through any SCE platform in the domain. A subscriber can belong to only a single domain. Usually a single SCE platform serves a subscriber at any given time.

Domains are managed differently in the Push and Pull modes:

The system is configured with one default subscriber domain called “subscribers”. When adding an SCE platform to the SM, it is automatically added to this default domain, unless otherwise specified. Subscribers are also associated with this default subscriber domain, unless otherwise specified. To associate a subscriber with a different domain, first define this domain in the configuration file, and then explicitly specify it when adding the subscriber to the SM. To associate an SCE platform with a non-default subscriber domain, edit and reload the configuration file. For more information, see Chapter 4, Configuration and Management.

A communication failure may occur either on the LEG-SM communication link or on the SMSCE communication link. A communication failure may occur due to a network failure or because the SCE, SM, or LEG has failed. High availability and recovery from an SM failure are discussed in SM Cluster.

When configuring the system, you should consider three issues related to communication failures:

The SM supports high availability using the Veritas Cluster Server (VCS) technology. In a high availability topology, the SM software runs on two machines, designated as the active machine and the standby machine. Subscriber data is continuously replicated from the active to the standby machine, ensuring there is minimal data loss in case of active SM failure. When the active machine fails, the standby machine discovers the failure and becomes active. For additional information, see the Subscriber Manager Fail-Over section.

The fail-over scheme that is implemented in the SM is based on the Veritas cluster technology. The cluster includes two machines, each of them running SM TimesTen and Veritas software. The Veritas Cluster Server (VCS) software consolidates the SMs and exposes a single entity by providing a single virtual IP address for the entire cluster.

The cluster software distinguishes an active and a standby machine: the active machine “owns” the virtual IP address and all network connections, while the standby machine is passive until a fail-over occurs. At fail-over, the IP address is passed from the failing server to the backup server, which becomes activated and re-establishes all network connections.

When a fail-over occurs, the LEGs lose their connection with the failed SM, and reconnect to the activated (backup) SM and retransmit their uncommitted messages. The activated SM connects to the SCE platforms and performs an SCE resynchronization.

The TimesTen database replication agent constantly replicates the SM database from the active node to the standby node. This enables a fast fail-over from one SM to another, since the subscriber data in the activated machine is always valid. The two SM nodes do not communicate except for passing the subscriber data.

The VCS uses software components called “cluster agents” to monitor and control the state of resources such as Network Interface Cards (NICs), disks, IP addresses, and processes. Cisco supplies cluster agents to monitor the SM and the TimesTen database daemon and replication agent.

As part of the cluster operation, the TimesTen database daemon and replication agents are up and running regardless of the fail-over state. The SM Veritas agent monitors the daemon and the replication agent process. In case one of them fails, a fail-over takes place.

The following sections describe these concepts in further detail.

The two SM nodes operate in hot-standby mode, where at any given time one node (the active node) receives and processes all the SM events, while the other node (the standby node) waits and is ready to go into operation on fail-over. For enabling seamless fail-over and for minimizing the fail-over time, the two SM nodes operate without an external storage device.

During the normal operation of the cluster, the active node (selected by the cluster):

On the standby node, both the SM and the TimesTen software are running:

The following figure depicts an SM cluster configuration in a topology with a redundant AAA server and two SCE 2000 platforms that are cascaded for redundancy.

Figure 2.2. SM Cluster Configuration for Fail-Over Topology

As already mentioned, an SM fail-over topology includes two SM nodes connected in a cluster scheme.

Two dedicated (private) redundant networks interconnect the two nodes:

The two nodes should be located in the same site, where the heartbeat network is implemented using back-to-back connectivity between the two nodes or via redundant switches. Each node in the cluster has redundant network paths (NICs) connecting it to all of the external entities with which the SM communicates (AAA, LEG, SCE).

Each node in the cluster has a minimum of six Ethernet NICs, where

The cluster has a virtual IP (VIP) address used for communication with the external entities. Each node in the cluster has also an IP address for administration of the node/cluster, as well as an IP address for replication use.

Upon failure of the primary NIC of the public network, there is a fail-over to the secondary NIC on the same node, keeping the same IP addresses (VIP1), with no fail-over of the cluster. Upon failure of the primary NIC of the replication or heartbeat networks, there is fail-over to the secondary NIC on the same node, keeping the same IP addresses (VIP2 and VIP3), with no fail-over of the cluster.

The following diagram illustrates the usage of the regular and virtual IP addresses used in cluster configuration:

Figure 2.3. Regular and Virtual IPs in Cluster Configuration

For further information about replication IP configuration, see Appendix E, Veritas Cluster Server Requirements and Configuration.

Before you can install the SM, you must first load and extract the distribution files on the installed machine or in a directory that is mounted to the installed machine.

After the installation script has completed successfully, set the password for the pcube user by running the following command:

# passwd pcube

Reboot the computer to complete the installation.

Depending on the integration type, you might need to install the SCA BB package on the SM or install Login Event Generator (LEG) modules.

To perform the installation, use the p3inst command-line utility. For example:

> p3inst -–install –file=eng30.pqi

For additional information, see Installing an Application.

It is necessary to add a user for PRPC authentication because the SCA BB application requires a username and password when connecting to the SM.

To add a user for PRPC authentication, use the p3rpc command-line utility. For example:

> p3rpc -–set-user --username=<username> --password=<password>

The installation of an SM cluster is very similar to installing the SM on two machines.

The following table lists the command options.

The script performs the following steps:

Example:

The following example installs the SM and CLU to a directory named /usr/local/pcube, using the default data storage directory definition.

# install-sm.sh –d /usr/local/pcube

The installation distribution file contains a set of customized Veritas Cluster Agents for supporting monitoring and controlling of SM-related resources in cluster topology. You must install the cluster agents under the VCS bin directory.

The following table lists the command options.

The script performs the following steps:

Script messages are logged into the system log in the following manner:

During installation, a user named pcube is created (unless it already exists) with its own group. This user owns all installed SM and CLU files. The user home directory is the installation directory selected during installation. For security purposes, the user is initially created with a locked password. You must assign a new password.

The SM is started on boot to run level 2, and is stopped when leaving this run level (for example, when the machine is shut down).

The installer installs the following files for startup and shutdown:

The TimesTen installer creates similar startup and shutdown scripts.

Subscriber Manager version 3.0.3 provides an upgrade script that implements an upgrade from previous versions. The upgrade procedure script preserves the subscriber database and the entire SM configuration, including network elements, domains, and application-specific components.

For additional information, see the following sections:

The following table lists the command options.

The script performs the following steps:

Example:

The following example upgrades the SM, keeps the current database, and does not pause the upgrade for PQI installation.

# upgrade-sm.sh

The following example upgrades the SM and removes the current database.

# upgrade-sm.sh –d

The data duplication procedure enables the user to duplicate or copy the entire database from one machine to the other, and then keep the databases synchronized by running the replication agent at the end. Some of the upgrade procedures described in the following sections use this procedure.

For details of the procedure, see Database Duplication Recovery.

To upgrade from a non-cluster setup to a non-cluster setup, follow the instructions described in Upgrade Procedure.

This section describes the basic procedure for upgrading from a non-cluster setup to a cluster setup, from version 2.2 and up.

In the following procedure, suppose that SM-A is the original SM machine running SM version 2.2 and later, and SM-B is the new SM machine being added for redundancy.

This section describes the basic procedure for upgrading from a cluster setup to a cluster setup, from SM version 3.0 and up.

In the following procedure, SM-A is the active SM machine and SM-B is the standby SM machine.

This section describes the basic procedure for upgrading from a cluster setup to a cluster setup, from SM versions 2.x.

To upgrade from a cluster setup, follow the instructions described in Upgrade Procedure. Each step should be applied on both machines.

The following table lists the command options:

The script performs the following steps:

The SM uses a configuration file, p3sm.cfg, located in ~pcube/sm/server/root/config/p3sm.cfg. For a detailed description of the configuration file parameters, see Appendix A, Configuration File Options.

The configuration file, together with the Command-Line Utilities, is used for configuring all the parameters that define the behavior of the SM application.

The configuration file contains the following types of parameters:

Usually, the parameters in the configuration file are specified once when setting up the system, and are valid throughout the system lifetime. To modify the configuration file parameters, edit the file using any text editor and reload it using the CLU (see Reloading the SM Configuration (p3sm)). The configuration file can be loaded on starting or restarting the SM and by explicitly running the CLU command.

The configuration file is designed so that the same configuration file can be used in multiple SM applications of a high availability setup. This enables the user to replicate the configuration by simply copying the file from one machine to another.

The SM provides a set of Command-Line Utilities (CLU), which you use, together with the configuration file, to configure the parameters that might change during the operation of the SM.

The CLU enables the user to configure the SM using shells installed on the machine. CLU commands are executable only when the user is logged in to the machine using the pcube user account, which is always installed (see Chapter 3, Installation and Upgrading). The CLU is used mainly for viewing and for subscriber management.

In high availability setups, you cannot use the CLU to perform subscriber management operations on the standby SM. Moreover, the standby SM refreshes the database before performing subscriber display operations, so the operation takes longer (than for the active SM). Therefore, it is recommended to perform all subscriber operations on the active SM.

This chapter explains how to perform various tasks using the appropriate CLU, but it does not describe the CLU in detail. For a complete, detailed description of the CLU, see Appendix B, Command-Line Utilities.

Before configuring any of the components in your subscriber management solution, verify that all the items on the following checklist have been successfully completed:

This configuration procedure applies to a single group, consisting of the following:

Every subscriber management solution can be divided into such groups, and this procedure can be applied to each of these groups.

This procedure consists of the following steps:

System Configuration Examples

This section presents and explains common subscriber management scenarios, including the correct configuration parameters for these scenarios. The following scenarios are described:

• Automatic introduction of subscribers, with Push mode and fail-over of SCE platforms

• Manual introduction of subscribers with Pull mode

• SM fail-over scenario

Example 1: Automatic Introduction of Subscribers, with Push Mode and Fail-Over of SCE Platforms

This scenario assumes the following:

• Automatic introduction of subscribers, that is, a provisioning system of an AAA system introduces the subscribers. This example assumes that integration with a DHCP server allows automatic introduction of subscribers to the SM.

• The SM is operating in Push mode.

• The application that is used includes states that should be preserved such as volume quotas states in the Service Control Application for Broadband (SCA BB).

Figure 4.1. Cable Topology with Automatic Integration with a DHCP Server, Push Mode, and Fail-Over of SCE Platforms

Note

Ensure that everything is properly installed before proceeding with configuring the SM.

To configure the SM using this scenario:

1. Edit the SM configuration file (p3sm.cfg) to add the SCE devices to the SCE device repository and group the SCE devices to domains, as depicted in the above figure.

2. Edit the SM configuration file, as displayed in the table below.

3. Reload the SM configuration file using the p3sm CLU.

4. Import the cable modems to the SM database using the p3cable CLU.

This scenario does not need an SCE platform configuration.

Table 4.1. Configuration File Parameters for Automatic Integration with Push Mode in a Cable Environment

Section and Parameter	Value and Description
SM General
introduction_mode	push
High Availability Setup
topology	standalone The value should be set to standalone because the described scenario has just one SM.
Subscriber State Persistency
save_subscriber_state	true The value must be set to true if working with an application that requires preserving the state. In any case, however, it is advisable to set the value to true.
SCE_subscriber_persistency	false The value should be set to false due to limited space on the SCE platform that probably will not suffice in an automatic integration scenario. Moreover, setting this value to true causes performance degradation.
SM-LEG Failure Handling
timeout	300 seconds (more tolerance may be advisable for SM-LEG failures in actual configurations)
clear_all_mappings	true The value should be set to true because under the scenario conditions (automatic integration in cable environment), subscribers are likely to change their state or to logout from the SCE during an SM-LEG connection failure. You would therefore like to clean their mappings when the SM and LEG are connected again.
LEG-Domain Association
<LEG name>	Define associations between LEGs and domains LEG-Domain associations should be defined in order that all subscriber mappings will be cleared on SM-LEG disconnection. If no association is defined, subscriber mappings will not be cleared (the clear_all_mappings value will be ignored).
Default Domains Configuration
property	None Configure the policy here if all domains in the system have the same policy.
Domain.XXX
aliases	Define aliases, to facilitate working in cable environment Define aliases if working with LEGs that are not aware of system domains. Alternatively, you can define domains with names that match values produced by LEGs.
property	None Configure the policy here only if you want it to be applied to all subscribers in the domain.
allow_dynamic_CM	no The value should be set to no in order to prevent uninstalled CMs from using the network.
Auto Logout
auto_logout_interval	60 minutes Auto-logout should be activated assuming that the AAA system cannot provide logout events, which is true in cable environments. The value defined here should be smaller than the CPE lease time in this cable environment.
grace_period	10 seconds You should define a relatively high value to eliminate mistakes because of management network delays.
max_rate	100 logouts per second You should define a value similar to the max-login rate to the SM.

Example 2: Manual Introduction of Subscribers with Pull Mode

This scenario assumes the following:

• Manual introduction of subscribers

• Pull mode

• Application that does not require preserving state

Note

Ensure everything is properly installed before proceeding with configuring the SM.

Figure 4.2. Topology with Manual Introduction of Subscribers and Pull Mode

To configure the SM using this scenario:

1. Edit the SM configuration file (p3sm.cfg) to add the SCE devices to the SCE device repository and group them to domains, as depicted in the above figure.

2. Further edit the SM configuration file, as shown in the table below.

3. Reload the SM configuration file using the p3sm CLU.

4. Import the subscribers using the p3subsdb CLU (required for manual integration; there is no other way to bring subscribers into the SM).

5. Use the SCE platform CLI to configure the system for Pull mode:

   • Subscriber templates—In accordance with application

   • Anonymous groups—In accordance with your network and subscribers

   • Introduced subscriber aging—In accordance with your network and IP address allocation scheme

Table 4.2. Configuration File Parameters for Manual Integration with Pull Mode

Section and Parameter	Value
SM General
introduction_mode	pull
High Availability Setup
Topology	standalone The value should be set to standalone because this scenario involves just one SM.
Subscriber State Persistency
save_subscriber_state	false
SCE_subscriber_persistency	false Defines whether the SCE stores subscriber information in persistent memory. Use this option only when there are just a few subscribers, which rarely change, in the system.
SM-LEG Failure Handling
Timeout	Not applicable—No LEGs are involved in the scenario (use default—60 seconds)
clear_all_mappings	Not applicable—No LEGs are involved in the scenario (use default—no action)
LEG-Domain Association
<LEG name>	Not applicable—No LEGs are involved in the scenario (Use default—no mappings)
Default Domains Configuration
Default policy (property.XXX)	None Configure the policy here only if all domains in the system have the same policy.
Domain.XXX
Aliases	Not applicable (use default—none)
property.XXX	None Configure the policy here only if you want to apply it to all subscribers in the domain.
allow_dynamic_CM	Not applicable—valid for cable environment only (use default – no)
Auto Logout
auto_logout_interval	Not applicable (use default—0)
grace_period	Not applicable (use default—10)
max_rate	Not applicable (use default—50)

Example 3: SM Fail-over Configuration (General)

When using a set-up with SM fail-over (based on two SM nodes connected in a cluster), the configuration is identical to the regular configuration, with one exception:

• The topology parameter in the SM High Availability Setup Section should be set to cluster for both SM machines.

Other than that, SM fail-over configuration is performed normally via the p3sm.cfg configuration file. Manually copy the configuration file from the active SM to the standby SM.

For additional information of how to configure the VCS, see Appendix E, Veritas Cluster Server Requirements and Configuration.

All CLU commands support the following operations for informative output:

Place in quotation marks a command operation or option containing any of the following characters:

A command operation or option that contains any of the following characters must have that character preceded by an escape character:

Following are several examples of the above rules:

One-letter abbreviations are available for some of the operations and options. For example, “-d” is an abbreviation for “--domain”. Note that only one hyphen (-), not two, precedes the letter for an abbreviation, and that if the operation or option takes a parameter, there is a space and not an equal sign before the parameter.

The abbreviations are useful if you want to specify an expression to be expanded by the UNIX shell, for example:

Use the p3sm utility to configure the SM by reloading the SM configuration file p3sm.cfg. Use any standard text editor to edit the configuration file.

Use the p3sm utility to manage the SM on an ongoing basis. The p3sm utility enables you to start, stop, and resynchronize the SM.

The following table lists the p3sm operations relevant to managing the SM.

Example 1:

The following example shows how to stop the server operation and then restart it.

Example 2:

The following example shows how to resynchronize an SCE whose logical name is SCE_1000A.

p3sm -–resync --ne-name=SCE_1000A

Example 3:

The following example shows how to extract the SM support information to a file named support.zip.

p3sm –-extract-support-file --output=support.zip

Use the p3subs utility to manage subscribers. You can add or remove subscribers. You can also manage subscriber properties and mappings with this utility.

The subscriber on whom the operation is to be performed is specified by using the format --subscriber=subscriber-name. A mapping (IP address, VLAN, or MPLS/VPN specification), property, or domain, if specified, uses the format displayed.

This section describes the following:

p3subs --add --subscriber=jerry --ip=96.128.128.42 --overwrite

Use the p3subsdb utility to manage the SM database. You can import subscriber information for a group of subscribers from a CSV file into the SM database. You can also export subscriber information from the SM database to a CSV file.

The following table lists the p3subsdb operations.

Example 1:

The following example shows how to list all subscribers in a specified domain.

Example 2:

The following example shows how to import subscribers from the specified CSV file.

p3subsdb --import --file=goldSubscriberFile.csv 

Example 3:

The following example shows how to export subscribers with filtering options to a specified CSV file.

p3subsdb --export --prefix=a -–output=silverSubscriberFile.csv

Use the p3net utility for viewing the connection status of network elements and trying to reconnect disconnected elements.

The following tables list p3net operations and options.

Example:

The following example shows how to display a network element's connection status.

Use the p3domains utility for viewing the subscriber domains. As explained in Introducing the Subscriber Manager, subscriber domains are groups of SCE devices that serve the same subscribers.

The following tables list p3domains operations and options.

In the cable environment, the SM supports two modes of operation: CM as Subscriber and CPE as Subscriber, as described in CPE as Subscriber in Cable Environment.

This section only discusses the support of the CPE as Subscriber mode. In this mode, the CPE is modeled as the subscriber, and it inherits its policy and domain from the cable modem (CM) through which it connects to the network. Each cable modem is linked with one or more CPEs. (For background information about special characteristics of the CPE as Subscriber mode in the cable environment, see CPE as Subscriber in Cable Environment.)

Use the p3cable utility commands to import cable modem information from a CSV file to the SM, and to export the cable modem information from the SM to a CSV file. You can also use this utility to clear the repository of all cable modems, and to show whether to allow or deny the login of CPEs that belong to unfamiliar cable modems; i.e., cable modems that do not exist in the SM database. However, for specifying whether to allow or deny such a login, use the Cable Adapter section of the p3sm.cfg configuration file.

The following table lists the p3cable operations.

Example 1:

The following example shows how to import cable modems from a CSV file.

Example 2:

The following example shows how to clear the repository of all cable modems:

p3cable --clear-all-cm

Example 3:

The following example shows how to display login status (allow/deny) of CPEs that belong to cable modems that do not exist in the SM database:

p3cable --show-dynamic-mode

Use the p3inst utility to install or uninstall an application (pqi file). You can install an application on the SM to customize the components. You can also upgrade an existing application to a new version, or uninstall a previously installed application.

The following table lists the p3inst operations.

Example 1:

The following example shows how to install the specified installation file.

Example 2:

The following example shows how to uninstall the specified installation file.

p3inst --uninstall –-file=oldInstallation.pqi

Cisco provides a proprietary RPC (Remote Procedure Call) interface to the SM. Use the p3rpc utility to view the configuration and statistics of the PRPC server.

The following table lists the p3rpc operations.

Example:

The following example displays the statistics of the PRPC server.

Use the p3cluster utility to view the redundancy state of the SM and its components. This utility also supports operations that alter the redundancy state of the SM. These operations are used by the SM Cluster Agent and for administrative tasks.

The following table lists the p3cluster operations.

Example:

The following example displays the redundancy status of the SM and it components.

Use the p3log utility to configure and manage the user log. All user-related events and errors are directed to the SM user log. You can extract the contents of the user log to a specified file in order to read and save its contents. You can also clear the user log.

Use the p3radius utility to view the statistics of the RADIUS Listener LEG. For information about this CLU, see the Cisco SCMS SM RADIUS Listener LEG Reference Guide.

This section describes the following:

p3batch --file=mainBatchFile.txt --skip-errors