This document describes the concept of a RADIUS Listener Login Event Generator (LEG), and explains how to install and configure the RADIUS Listener LEG on the Service Control Management Suite Subscriber Manager (SCMS SM) platform.
|
Cisco Service Center Release |
Part Number |
Publication Date |
|---|---|---|
|
Release 3.0.5 |
OL-7202-04 |
November, 2006 |
Description of Changes
Added new section describing mapping the RADIUS attribute to the subscriber IP address. See Mapping of RADIUS Attribute to Subscriber IP Address.
Various other small changes to text.
|
Cisco Service Center Release |
Part Number |
Publication Date |
|---|---|---|
|
Release 3.0.3 |
OL-7202-03 |
May, 2006 |
Description of Changes
Added new section describing how to configure the stripping of an attribute value. See Configuring Stripping of the Attribute Value.
Various other small changes to text.
|
Release 3.0 |
OL-7202-02 |
December, 2005 |
This document is intended for system administrators and system integrators who are familiar with the RADIUS extensions concept and with Cisco Service Control Subscriber Management and Subscriber Integration concepts.
This guide contains the following topics:
|
Chapter |
Title |
Description |
|---|---|---|
|
Chapter 1 |
Describes the Subscriber Manager RADIUS Listener LEG software module and the terms and concepts used in this guide. | |
|
Chapter 2 |
Details the procedures for installing the software on the Subscriber Manager. It also describes uninstalling the software and upgrading procedures. | |
|
Chapter 3 |
Describes the configuration procedure for the RADIUS Listener LEG. | |
|
Chapter 4 |
Provides a description of the command-line utility commands when the software is installed on the Subscriber Manager. | |
|
Appendix A |
Describes the algorithm used for deciding the subscriber domain to which a subscriber should be logged on. |
The following publications are available for the Cisco SCMS SM RADIUS Listener LEG Reference Guide:
Cisco SCMS Subscriber Manager User Guide
This document uses the following conventions:
|
Convention |
Description |
|---|---|
|
boldface font |
Commands and keywords are in boldface. |
|
italic font |
Arguments for which you supply values are in italics. |
|
[ ] |
Elements in square brackets are optional. |
|
{x | y | z} |
Alternative keywords are grouped in braces and separated by vertical bars. |
|
[x | y | z] |
Optional alternative keywords are grouped in brackets and separated by vertical bars. |
|
string |
A nonquoted set of characters. Do not use quotation marks around the string, or the string will include the quotation marks. |
|
|
Terminal sessions and information that the system displays are in |
|
|
Information you must enter is in |
|
|
Arguments for which you supply values are in |
|
< > |
Nonprinting characters, such as passwords, are in angle brackets. |
|
[ ] |
Default responses to system prompts are in square brackets. |
|
!, # |
An exclamation point (!) or a pound sign (#) at the beginning of a line of code indicates a comment line. |
Note
Means reader take note. Notes contain helpful suggestions or references to materials not covered in this manual.
Caution
Means reader be careful. In this situation, you might do something that could result in loss of data.
The following sections provide sources for obtaining documentation from Cisco Systems.
You can access the most current Cisco documentation on the World Wide Web at the following sites:
Cisco documentation and additional literature are available in a CD-ROM package that ships with your product. The Documentation CD-ROM is updated monthly and may be more current than printed documentation. The CD-ROM package is available as a single unit or as an annual subscription.
Cisco documentation is available in the following ways:
Registered Cisco Direct Customers can order Cisco Product documentation from the networking Products MarketPlace:
Registered Cisco.com users can order the Documentation CD-ROM through the online Subscription Store:
Nonregistered Cisco.com users can order documentation through a local account representative by calling Cisco corporate headquarters (California, USA) at 408 526-7208 or, in North America, by calling 800 553-NETS(6387).
If you are reading Cisco product documentation on the World Wide Web, you can submit technical comments electronically. Click Feedback in the toolbar and select Documentation. After you complete the form, click Submit to send it to Cisco.
You can e-mail your comments to bug-doc@cisco.com.
To submit your comments by mail, use the response card behind the front cover of your document, or write to the following address:
Attn Document Resource Connection Cisco Systems, Inc. 170 West Tasman Drive San Jose, CA 95134-9883
We appreciate your comments.
Cisco provides Cisco.com as a starting point for all technical assistance. Customers and partners can obtain documentation, troubleshooting tips, and sample configurations from online tools. For Cisco.com registered users, additional troubleshooting tools are available from the TAC website.
Cisco.com is the foundation of a suite of interactive, networked services that provides immediate, open access to Cisco information and resources at any time, from anywhere in the world. This highly integrated Internet application is a powerful, easy-to-use tool for doing business with Cisco.
Cisco.com provides a broad range of features and services to help customers and partners streamline business processes and improve productivity. Through Cisco.com, you can find information about Cisco and our networking solutions, services, and programs. In addition, you can resolve technical issues with online technical support, download and test software packages, and order Cisco learning materials and merchandise. Valuable online skill assessment, training, and certification programs are also available.
Customers and partners can self-register on Cisco.com to obtain additional personalized information and services. Registered users can order products, check on the status of an order, access technical support, and view benefits specific to their relationships with Cisco.
To access Cisco.com, go to http://www.cisco.com.
The Cisco Technical Assistance Center (TAC) website is available to all customers who need technical assistance with a Cisco product or technology that is under warranty or covered by a maintenance contract.
If you have a priority level 3 (P3) or priority level 4 (P4) problem, contact TAC by going to the TAC website http://www.cisco.com/tac.
P3 and P4 level problems are defined as follows:
P3—Your network is degraded. Network functionality is noticeably impaired, but most business operations continue.
P4—You need information or assistance on Cisco product capabilities, product installation, or basic product configuration.
In each of the above cases, use the Cisco TAC website to quickly find answers to your questions.
To register for Cisco.com, go to http://tools.cisco.com/RPF/register/register.do.
If you cannot resolve your technical issue by using the TAC online resources, Cisco.com registered users can open a case online by using the TAC Case Open tool at http://www.cisco.com/tac/caseopen.
If you have a priority level 1 (P1) or priority level 2 (P2) problem, contact TAC by telephone and immediately open a case. To obtain a directory of toll-free numbers for your country, go to http://www.cisco.com/warp/public/687/Directory/DirTAC.shtml.
P1 and P2 level problems are defined as follows:
P1—Your production network is down, causing a critical impact to business operations if service is not restored quickly. No workaround is available.
P2—Your production network is severely degraded, affecting significant aspects of your business operations. No workaround is available.
The RADIUS Listener LEG is a software module that receives RADIUS Accounting messages, and according to their content, invokes logon operations to the Subscriber Manager (SM). The RADIUS Listener LEG is an extension to the SM software and runs concurrently with the SM.
When the RADIUS Listener LEG receives an Accounting-Start message, it extracts the subscriber ID, the subscriber IP-address, and optionally, the subscriber package index from the message attributes, and triggers a login operation to the SM. In the same manner, Accounting-Interim-Update triggers a login operation, and the Accounting-Stop message triggers a logout operation.
The RADIUS Listener LEG was carefully developed and thoroughly tested with several RADIUS AAA servers and NAS devices.
The following is a list of some terms and concepts that are necessary to understand the RADIUS Listener and SM configuration and operation. Additional information regarding the various issues can be found in the Cisco SCMS Subscriber Manager User Guide.
A network device that serves as an access point for a remote user. It initiates RADIUS transactions to the RADIUS server to authenticate a remote user.
The RADIUS Listener LEG refers to all of its RADIUS clients as NAS devices, even though they might be RADIUS servers acting as a proxy or forwarding messages.
The RADIUS Accounting messages must hold an attribute called Acct-Status-Type. This attribute can receive the value of start, interim-update, stop, or other RADIUS Accounting messages. An Accounting-Start message contains the Acct-Status-Type with the value start.
For additional information, see the relevant RADIUS RFC documentation.
The SCE platform requires mappings between the network IDs (IP addresses) of the flows it encounters and the subscriber IDs. The SM database contains the network IDs that map to the subscriber IDs. The SCE network-ID-to-subscriber mappings are constantly updated from the SM database.
The main function of the RADIUS Listener LEG is to provide the SM with network-ID-to-subscriber mappings in real time.
For information about the SCE platforms, see the SCE 1000 and SCE 2000 User Guides.
The SM provides the option of partitioning SCE platforms and subscribers into subscriber domains. A subscriber domain is a group of SCE platforms that share a group of subscribers. Subscriber domains can be configured using the SM configuration file and can be viewed using the SM CLU.
For additional information about domains and domain aliases, see Appendix A of the Cisco SCMS Subscriber Manager User Guide.
A subscriber policy package usually defines the policy enforced by Cisco SCMS solutions on each subscriber. The RADIUS Listener LEG can handle the package ID in any of the following ways:
Set the package ID according to a value of a RADIUS attribute
Set the package ID using a constant default value
Leave the package ID unset
For additional information, see Mapping of RADIUS Attribute to Subscriber Package, and the Cisco Service Control Application for Broadband (SCA BB) User Guide.
The following diagram illustrates a topology in which a RADIUS server/proxy forwards or proxies the RADIUS Accounting messages to the RADIUS Listener LEG.
The following diagram illustrates a topology in which the NAS performs authentication with the RADIUS server, and sends RADIUS Accounting messages to the RADIUS Listener LEG and, optionally, to the RADIUS server.
Figure 1.2. Example of NAS Sending Radius Accounting Messages to both the Radius Listener LEG and the Radius Server
This section describes the procedures for installing the RADIUS Listener LEG. It also describes the uninstall procedure.
The RADIUS Listener LEG is part of the SM installation package. The installation package also includes configuration files and the Command-Line Utility of the LEG.
To install the RADIUS Listener LEG:
Edit the RADIUS Listener LEG configuration file. To run the RADIUS Listener LEG at SM startup, set the
startparameter toyes. See Configuring the General Settings.Load the configuration file using the
p3smcommand-line utility. Run thep3smcommand-line utility from the SM CLU sm-inst-dir/sm/server/bin (sm-inst-dirrefers to the SM installation directory):> p3sm --load-configConfigure the NAS devices that are sending RADIUS Accounting messages to the RADIUS Listener LEG. The NAS devices may be RADIUS servers acting as RADIUS clients that proxy or forward RADIUS accounting messages to the RADIUS Listener.
These RADIUS clients must be configured according to the RADIUS Listener configuration, as performed in Step 1 above. There are many different RADIUS client devices, each of which is configured in a different manner. See Configuring the NAS Devices for instructions on configuring the RADIUS clients on NAS devices.
To uninstall the RADIUS Listener LEG:
Edit the SM configuration file and set the RADIUS Listener
startparameter tono. See Configuring the General Settings.Note
Setting the
startparameter tonodoes not remove the RADIUS Listener LEG from the SM installation. You can reinstall the software again by setting the start parameter toyes.Run the
p3smcommand line utility:> p3sm --load-config
The RADIUS Listener LEG is configured using the SM configuration file p3sm.cfg, which resides in the sm-inst-dir/sm/server/root/config directory (sm-inst-dir refers to the SM installation directory).
The configuration file consists of sections headed by a bracketed section title; for example, [Radius.Subscriber ID]. Each section consists of several parameters having the format parameter=value. The number sign (“#”) at the beginning of a line signifies that it is a remark.
The General RADIUS Listener LEG configuration settings reside in the [Radius Listener] section. All additional RADIUS Listener LEG sections start with the prefix Radius., such as [Radius.NAS.nas1], and they are defined initially as remark lines.
The [Radius Listener] section in the SM configuration file contains the following parameters:
startDefines whether the SM should run the RADIUS Listener at startup.
Possible values for this parameter are
yesandno. The default value isno.accounting_portDefines the RADIUS Listener accounting port number.
The default value is
1813.ipThe IP address to which the RADIUS listener should bind. Use this parameter only in cases where the IP address used for RADIUS transactions is not the main IP address of the SM machine. (For example in an SM cluster)
Possible values are any IP address in dotted notation. The default value is
not set.packet_typesDefines the RADIUS protocol packet types to analyze.
Possible values are
accounting-start,accounting-interim,accounting-stopseparated by a comma.The default value is
accounting-start,accounting-interim,accounting-stop.
The following example is a portion of a configuration file illustrating the [Radius.Listener] section:
[Radius Listener]
# The following parameter defines whether the SM should
# run the RADIUS Listener at startup.
# Receives the values: yes, no. (default no)
start=no
# accounting port number (default 1813)
accounting_port=1813
# RADIUS packet types
packet_types=accounting-start,account-interim,accounting-stopThe RADIUS Listener LEG must be configured with the RADIUS clients/NAS devices that transmit RADIUS messages to the LEG, to accept RADIUS messages.
Each [Radius.NAS.XXX] section specifies a single Network Access System (NAS), where XXX represents the NAS name.
To configure a new NAS device:
Copy the example Radius.NAS.XXX section that exists in the configuration file, and remove the remarks from the parameters and section header.
Configure a section name from the format
[Radius.NAS.my_name_for_the_NAS].Configure the following parameters:
domainSet the domain parameter with a valid subscriber domain name.
IP_addressSet the IP_address parameter with the NAS IP address with which the RADIUS messages arrive. IP address should be in dotted notation (xxx.xxx.xxx.xxx).
NAS_identifierSet the NAS_identifier parameter with a NAS-ID attribute with which the RADIUS messages are sent.
secretSet the secret parameter with the secret key defined in the NAS for this connection.
For more information about the domain, IP_address, and NAS_identifier parameters usage, see Appendix A - Domain Association Algorithm.
The following example is a portion of a configuration file illustrating how to configure the NAS:
[Radius.NAS.Access134]
# Cisco's subscriber domain name
domain = subscribers
# IP address in dotted notation
IP_address = 202.156.24.100
# name of the NAS that exists in the NAS-ID attribute
NAS_identifier =ACCESS134
# secret string
secret = secret123Note
The configuration described in this section is optional.
The subscriber ID is usually put in the User-Name RADIUS attribute. However, in certain installations, it is possible to use a different RADIUS attribute. For example, in wireless environments, it is possible to use the 3GPP-IMSI or the 3GPP2-IMSI attributes. The default is to use the User-Name attribute.
To define which attribute to use for the subscriber ID, configure the [Radius.Subscriber ID] section. To define the attribute to be used, configure the following parameters:
radius_attributeConfigure the radius_attribute parameter with the RADIUS attribute number. Enter the value of 26 for Vendor Specific Attributes (VSA).
radius_attribute_typeConfigure radius_attribute_type parameter according to the RADIUS attribute format. Possible values for this parameter are
integerandstring. The default value isinteger.
The following is an example configuration file illustrating how to configure the subscriber ID assignment option. In this example, the User-Name attribute is assigned to the subscriber ID:
[Radius.Subscriber ID]
# RADIUS protocol attribute number
radius_attribute=1
# the type of the attribute (type "integer" or "string")
radius_attribute_type = string
The following is an example configuration file illustrating how to configure the subscriber ID assignment option. In this example, the 3GPP_IMSI vendor-specific attribute is assigned to the subscriber ID:
[Radius.Subscriber ID]
# in case of a vendor specific attribute (VSA)
# when the 'radius_attribute' is set to 26
# configuration for 3GPP_IMSI
radius_attribute = 26
radius_attribute_vendor_id=10415
radius_sub_attribute=1
# the type of the attribute (type "integer" or "string")
radius_attribute_type = stringIt is possible to configure the RADIUS listener to strip a RADIUS attribute based on a selected character. This provides a convenient method for obtaining the subscriber ID from a prefix or a suffix of an attribute value.
For example, you can obtain the subscriber ID from the USERNAME attribute value of subscriber@domain-name by stripping the characters after the “at” sign (@) to produce the subscriber.
The following is an example configuration file illustrating how to configure the stripping of an attribute value.
[Radius.Subscriber ID]
# RADIUS protocol attribute number
radius_attribute=1
# the type of the attribute (type "integer" or "string")
radius_attribute_type = string
strip_char=@
strip_type=remove_suffixNote
The configuration described in this section is optional.
Subscriber package configuration in the RADIUS Listener can be handled in any of the following ways:
Extract the data from a RADIUS attribute
Set a default value for all subscribers that log on via the RADIUS Listener
Do not set any package to the subscriber
The attribute configuration is performed in the same manner as described in Mapping of RADIUS Attribute to Subscriber ID.
Additionally, configure the following parameters:
use_defaultDefines whether to use a default value if the attribute was not found.
Possible values for this parameter are
trueandfalse.The default value is
true.defaultDefines the default value to use if the attribute was not found.
There is no default value.
Note
This parameter must be set if the use_default parameter is set to true.
mapping_tableDefines a conversion table between the result of the attribute manipulation (e.g. after stripping), and the property value. The conversion is mandatory if the radius_attribute_type is string. The format of the mapping_table is <attribute-value>=<property-value>
There is no default value.
The following example is a portion of a configuration file illustrating how to configure the subscriber package assignment option. In this example, a VSA is assigned to the subscriber package. It is stripped from its prefix and converted to integer type using a mapping table.
[Radius.Property.Package]
# the following is the configuration for using Vendor Specific Attributes (VSA)
radius_attribute = 26
radius_sub_attribute = 1
radius_attribute_vendor_ID = 5655
# the type of the attribute (type "integer" or "string")
radius_attribute type = integer
# strip the prefix
strip_type=remove_prefix
strip_character=@
# this flag indicates whether to use default value
# if the attribute was not found (when not mandatory)
use_default = true
# default property value
default = 0
# definition of mapping table
mapping_table.gold=1
mapping_table.silver=2
mapping_table.bronze=3Do not configure the radius attribute parameters. However, set the use_default parameter to true and set the value of the default parameter as needed.
The subscriber IP address is normally based on the Framed-IP-Address attribute; however, it can also be based on a different RADIUS attribute. The default is to use the Framed-IP-Address attribute.
The following algorithm is applied to handle IP addresses in this LEG:
If the user configured an attribute from which to extract the IP, the LEG will look for that attribute in the packet. If the attribute exists, the LEG will use the attribute as the subscriber IP address.
If the attribute does not exist or is not configured, the LEG will look for the Framed-Route attributes; several Framed-Route attributes may exist. If any Framed-Route attributes exist, the LEG will use these attributes as the subscriber IP addresses.
If there are no Framed-Route attributes, the LEG will look for a Framed-IP-Address attribute and a Framed-IP-Netmask attribute. If a Framed-IP-Address attribute exists, the LEG will use this attribute as the subscriber IP address. If both the Framed-IP-Address and the Framed-IP-Netmask attributes exist, the operation is performed with the IP range represented by the IP address and the IP netmask.
Otherwise, the LEG will perform a login without the IP address.
Note
The configured attribute can be a regular RADIUS attribute or a VSA. It is possible to encode the attribute as an integer in which case it will be a single IP address. It can also be encoded as a string and will therefore be an IP-Address/IP-Range value: the value must be formatted as A.B.C.D/E or A.B.C.D.
Note
The supported format of the Framed-Route attribute is as described in RFC-2865. It must start with a string that starts with the route itself in the format A.B.C.D/E followed by a space. Other values follow the space, but the LEG ignores these other values.
To define which attribute to use for the subscriber IP address, configure the [Radius.Subscriber IP Address] section. To define the attribute to use, configure the following parameters:
radius_attributeConfigure the radius_attribute parameter with the RADIUS attribute number. Enter the value 26 for Vendor Specific Attributes (VSA).
radius_attribute_vendor_idThis parameter is only relevant if radius_attribute is configured to 26 (Vendor-Specific attribute).
The parameter defines the vendor ID number for the subscriber ID classification.
This parameter has no default value.
radius_sub_attributeThis parameter is only relevant if radius_attribute is configured to 26 (Vendor-Specific attribute).
The parameter defines the sub attribute within the vendor specific attribute that is used for subscriber ID classification.
This parameter has no default value.
radius_attribute_typeConfigure radius_attribute_type parameter according to the RADIUS attribute format. Possible values for this parameter are
integerandstring. If the type isstring, you must supply a mapping table.The default value is
integer.
The RADIUS clients are needed to send RADIUS messages to the RADIUS Listener and must be configured to do so.
To configure a RADIUS client:
Configure the SM machine as the destination of accounting messages.
You must configure the following parameters:
The SM IP address
The UDP ports to which the RADIUS Listener listens
The shared secret configured for this client in the SM configuration file
Verify that the Accounting-Start message is sent with the following attributes:
The attribute configured in the subscriber ID attribute mapping in the SM configuration file. See Mapping of RADIUS Attribute to Subscriber ID
The attribute configured in the subscriber IP address attribute mapping in the SM configuration file, the Framed-Route or the Framed-IP-Address. See Mapping of RADIUS Attribute to Subscriber IP Address
(Optional) The attribute configured in the Subscriber package attribute mapping in the SM configuration file. See Mapping of RADIUS Attribute to Subscriber Package
Verify that the Accounting-Stop message is sent with the following attributes:
The attribute configured in the subscriber ID attribute mapping in the SM configuration file. See Mapping of RADIUS Attribute to Subscriber ID
The attribute configured in the subscriber IP address attribute mapping in the SM configuration file, the Framed-Route or the Framed-IP-Address. See Mapping of RADIUS Attribute to Subscriber IP Address
Note
It is recommended that you configure the RADIUS client to not send Authentication and Accounting-Intermediate messages to the SM to reduce the load of packet handling.
The p3radius utility displays the RADIUS Listener configurations, status, and statistics. The RADIUS Listener configuration includes all configured NAS devices and general RADIUS Listener parameters.
The p3radius command format is p3radius <operation>.
The following table lists the p3radius operations.
Table 4.1. p3radius Operations
|
Operation |
Description |
|---|---|
|
--show |
Displays all of the NAS and RADIUS configurations and other general information (status of ports, etc.) |
|
--show-statistics |
Displays counters of RADIUS messages handled and number of logon operations performed |
The following is an example using the p3radius command-line utility with the show operation:
> p3radius --show
Radius Listener information
===========================
running: true
listen-only: true
accounting port: 1813
packet types: accounting-start, accounting-interim, accounting-stop
NASs:
====
name: Access134
nasId: ACCESS134
ip: 202.156.24.100
secret: secret123
domain: subscribers
auth-servers: none
acct-servers: none
login on: accounting-start
Subscriber ID
=============
radius attribute: 1
radius attribute type: string
Properties
==========
radius attribute: 26
radius_vendor_id: 5655
radius_sub_attribute: 1
radius attribute type: string
property name: packageId
Command terminated successfully
>The following is an example of the p3radius command-line utility with the showstatistics operation:
> p3radius --show-statistics
Statistics:
===========
Packets Received: 0
Packets Transmitted: 0
Accounting Request: 0
Accounting Start: 0
Accounting Interim: 0
Accounting Stop: 0
Accounting Response: 0
Dropped: 0
Successful logins: 0
Failed logins: 0
Successful logouts: 0
Failed logouts: 0
Command terminated successfully
>This section describes the algorithm used for deciding the subscriber domain to which a subscriber should be logged on. The Radius Listener decides to which domain the subscriber should be logged on, according to the NAS that sent the Accounting-Start message.
However, if the only NAS the Radius Listener is configured with is the proxy device (as illustrated in the following diagram), which is the device from where the RADIUS Listener receives messages, the RADIUS listener cannot distinguish between NAS1 and NAS2 subscribers and cannot map them to different subscriber domains.
Figure A.1. Example of when the only NAS that the Radius Listener is configured with is the Proxy Device
To solve the problem of distinguishing between two NAS devices, the following algorithm is used:
If a NAS-Identifier attribute exists in the Accounting-Start message and a NAS device is configured with that identifier, this NAS subscriber domain configuration is used.
If the NAS-Identifier attribute does not exist, the same test will be performed on the NAS-IP-Address attribute. If the NAS-IP-Address attribute exists in the Accounting-Start message the NAS device was configured, this NAS domain configuration is used.
Otherwise, the domain configured for the NAS identified by the Accounting-Start packet source IP address is used.
Using the Radius attributes provides the ability to distinguish between the two NAS devices.
Note
If none of the three NAS identification characteristics (packet source IP, NAS-Identifier, or NAS-IP-Address) matches the Radius message, the message is dropped because of Radius packet processing reasons. The domain selection stage will not be performed.