Subscriber Manager Integration

This module describes how to configure the DHCP Lease Query LEG on the SM and how to use the CLU.

Note This module is relevant if you are using the Subscriber Manager server on your network. You should install the DHCP Lease Query LEG on the SM server and not on the SCE device.

Information About Configuring the DHCP Lease Query LEG

The DHCP Lease Query LEG on the SM is configured using two configuration files: leaseq.cfg (general configuration) and dhcp_pkg.cfg (dynamic package association), which reside in the ~pcube/sm/server/root/config directory.

The configuration files consist of sections headed by a bracketed section title; for example, [DHCP-Lease-Query-LEG]. 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.

Configuring the DHCP Lease Query LEG

The following is a description of the configuration variables of leaseq.cfg.

Defines the number of concurrent sessions the LEG should support. This parameter limits the resources used by this module.

You must enter the IP addresses or hostnames of the DHCP servers separated by commas.

Defines the UDP port to which the DHCP servers listen and the Lease Query messages are sent. It is recommended to use 9067 when working with the DHCP Forwarder. The default value is 9067.

Defines the UDP port to which the LEG listens and the Lease Query replies are sent. It is recommended to use 9068 when working with the DHCP Forwarder. The default value is 9068.

Defines the UDP port that the LEG uses when sending Lease Query messages to the DHCP servers. It is recommended to use 8068 when working with the DHCP Forwarder. The default value is 8068.

Defines the source IP address of the lease-query packets sent to the DHCP servers. The giaddr field of the DHCP packet also uses this IP address. This parameter is useful for machines with multiple network interfaces.

Defines whether the LEG should query the DHCP servers whenever the auto-logout mechanism identifies an expired lease.

Possible values for this parameter are trueand false. The default value is false.

Defines whether the LEG utilizes the DHCP Forwarder application on the local machine.

Possible values for this parameter are trueand false. The default value is true.

Defines the number of consecutive request failures (timeouts) that triggers a fail-over. Since the queries are not answered when the server fails, these queries will time out. The consecutive timed-out queries are counted and when they reach this threshold, the second server is set as the active server. The default value is 3.

Note The session_timeout parameter affects how long it will take to detect a failed server. Only when the configured amount of queries fail will the fail-over process be triggered.

Possible values for this parameter are trueor false. The default value is true.

Possible values for this parameter are trueor false. The default value is false.

Controls log messages regarding replies that did not result in the login of a subscriber to the SM.

Possible values for this parameter are trueor false. The default value is true.

The [Subscriber ID] section defines the functionality of how the LEG handles the subscriber ID. The subscriber ID can be taken from a DHCP option, with the ability to fallback to using the allocated IP address as the subscriber ID. This section contains the following parameters:

Defines which DHCP option to use as the subscriber ID. The format of thisparameter is the option number itself; or for DHCP options that have sub-options, the format is the DHCP option and sub-option type, separated by a colon. For example: 43:123 or 61. The default value is 82:2 (Relay-Agent-Information using the Remote-ID information).

Defines the format type of the DHCP option defined by the dhcp_option parameter.

Optional values are binary, indicating a binary string converted to an ASCII hexadecimal string; or string, indicating an ASCII string. The default value is binary.

Defines whether in cases where the dhcp_option is not found in the DHCP packet, the LEG should fall back to a different way of defining the subscriber ID. The supported fallbacks are:

–

ip—Use the allocated IP address to create a subscriber ID in the format of: IP_aaa.bbb.ccc.ddd

The [DHCP-Lease-Query-Ids] section contains the message type numbers of the different Lease Query transaction message types. This is necessary, because the DHCP Lease Query definition is an IETF draft. This section contains the following parameters:

[DHCP-Lease-Query-LEG] 
start=yes 
dhcp_servers = 198.1.2.3, 198.5.6.7 
fail_over_criteria=10 
session_timeout=10 
log_timed_out_queries=true 
log_failed_queries=true 
log_all_queries=true 
log_login_failures=true 
[Subscriber ID] 
dhcp_option=44 
dhcp_option_type=binary 
[DHCP-Lease-Query-Ids] 
lease_query=13 
lease_active=16

Configuring Policy Association

The subscriber policy configuration in the DHCP Lease Query LEG can be handled in one of the following ways:

Dynamic Assignment of Policy Information

Dynamic assignment of policy information is supported when policy information is submitted in the DHCP packets. The LEG concatenates the desired options and creates a policy-name . It is possible to map, using the configuration, between the policy-names and the application policy parameters such as package IDs and Virtual-links. The DHCP Lease Query LEG can support multiple policies.

To extract the policy information data from the DHCP packet, use the dhcp_pkg.cfg configuration file to define the option types that contain the policy information and define the conversion map of the policy-names to the package IDs (or any other policy) of the Service Control Application for Broadband (SCA BB).

The LEG is able to add additional data to the login operation based on the LEG configuration. This data is added as a key-value pair. Other modules in the login chain can use this data, such as the SOAP LEG (see the Cisco SCMS SM SOAP LEG Reference Guide ). This data can be created by concatenating the data of several DHCP options and can be given a user-defined label.

Defines the DHCP options that contain the policy association information and defines the order of concatenation of the data. The DHCP header field called giaddr (Relay-Agent IP) is also supported; it requires the use of the type integer in the option_type parameter.

Defines the format type of the DHCP options and fields defined by the options_order_for_policy_nameparameter.

Possible values for this parameter are binary(a binary string that is converted to an ASCII hexadecimal string), string(an ASCII string), or integer(a 4-byte integer converted to an IP address string in dotted notation). Order the list in the same way as options_order_for_policy_name.

Defines the separator character to use between two options when concatenating them to each other to create the policy name. Any character is accepted. The default value is '_'.

Determines whether to use a default policy when no policy information can be extracted from the DHCP data, such as the configurable options are missing or no options were configured.

Possible values for this parameter are trueor false. The default value is false.

Defines the default policy ID to use if no policy information is extracted from the DHCP data. This parameter is relevant only if the use_defaultparameter is set to true.

Possible values for this parameter are any integer number. This parameter has no default value.

Defines whether to perform a login without policy information when no policy information can be extracted from the DHCP data and the use_defaultparameter is set to false.

This parameter is relevant only if the use_default parameter is set to false.

Possible values for this parameter are trueor false. The default value is true.

Defines the name of the application property that contains the policy information. This parameter has no default value.

Defines whether to write detailed user-log messages for all policy association events.

Possible values for this parameter are trueor false. The default value is false.

Defines whether to write a user-log message for every assignment of the default value (as defined by the default_policy parameter).

Possible values for this parameter are trueor false. The default value is false.

Multiple entries containing the information to convert from the policy information as it appears in the DHCP packet to the policy property value to be used by the SCA BB application.

The [Additional Data] section of the configuration file contains the following parameters:

Possible values are the option number or, in the case of DHCP options with sub-options, the option and sub-option separated by a colon. For example, 43:123 or 61.

Defines the keys that should mark the DHCP options defined by the label_options parameter.

Defines the format type of the DHCP option defined by the label_options parameter.

Possible values for this parameter are binary(a binary string that is converted to an ASCII hexadecimal string) or string(an ASCII string).

Dynamic Assignment of Policy Information Example

Suppose that the policy information appears inside option 43 (Vendor Specific Option) of the DHCP packet and that both subtypes, 102 and 101, are in use. Configure the options_order_for_policy_name parameter as follows:

Suppose that option 43 with subtype 102 contains the type of package (gold, silver, or bronze), and that option 43 with subtype 101 contains domain information (the package type has a different meaning in different domains). If the separator value is configured to the default value, configure the mapping_table entries as follows:

This configuration means that if the DHCP packet contains the value 'gold' inside option 43 with subtype 102, and the value 'domain1' inside option 43 with subtype 101, the package ID that will be associated to the subscriber in the SM will have the value 11.

The following configuration describes how to add the data of the Relay-Agent Circuit-Id option as additional data to the login operation:

[DHCP.Policy.Package] 
options_order_for_policy_name=43:102,43:101 
name_separator_value=_ 
use_default=true 
default_policy=1 
policy_property_name=packageId 
allow_login_with_no_policy=false 
log_all=false 
log_default_assignment=false 
mapping_table.gold_domain1=11 
mapping_table.gold_domain2=12 
mapping_table.silver_domain1=13 
mapping_table.silver_domain2=14 
[Additional Data] 
label_options=82:1 
label_keys=PORT_ID 
label_option_type=string

Static Assignment of Policy Information

If the installation does not require dynamic assignment of package information, the configuration file dhcp_pkg.cfg should define the default package ID and default Virtual-Link to be assigned to all the subscribers, as shown in the following example:

[DHCP.Policy.Package] 
policy_property_name=packageId 
allow_login_with_no_policy=false 
use_default=true 
default_policy=1 
[DHCP.Policy.VirtualLinkDownstream] 
policy_property_name=downVlinkId 
allow_login_with_no_policy=false 
use_default=true 
default_policy=0 
[DHCP.Policy.VirtualLinkUpstream] 
policy_property_name=upVlinkId 
allow_login_with_no_policy=false 
use_default=true 
default_policy=0

Information About the DHCP Lease Query LEG CLU

The p3leasequery utility displays the DHCP Lease Query LEG configuration, status, and statistics. The command format is p3leasequery <operation>.

Table 3-1 p3leasequery Operations
Operation	Description
`--show`	Displays all of DHCP Lease Query LEG configurations and status
`--show-statistics`	Displays counters of DHCP messages handled and number of logon operations performed
`--show-version`	Displays the version number of the DHCP Lease Query LEG
`--help`	Displays a list of available operations and arguments with a short explanation of their meanings

Viewing the DHCP Lease Query LEG Status

The following is an example using the p3leasequerycommand-line utility with the showoperation:

>p3leasequery --showDHCP Lease-Query LEG: 
===================== 
Active:    true 
DHCP Servers: 
Active:  10.1.2.3 
Standby: N/A 
Session timeout: 20 
Fail over criteria: 3 
Subscriber ID: 
Option:   82:2 
Format:   binary 
Fallback: none 
Command terminated successfully 
>

Viewing the DHCP Lease Query LEG Statistics

The following is an example of the p3leasequerycommand-line utility using the show-statisticsoperation:

>p3leasequery --show-statisticsDHCP Lease-Query LEG Statistics: 
================================ 
Lease-Queries Sent:             16 
Lease-Queries Replied:          16 
Active Lease Replies:           16 
Non-Active Lease Replies:       0 
Total timed-out sessions:       0 
Consecutive timed-out sessions: 0 
Number of fail-overs            0 
Invalid Replies:                0 
Sessions in process:            0 
Max-Concurrent sessions:        3 
Command terminated successfully 
>

Viewing the DHCP Lease Query LEG Version

The following is an example of the p3leasequerycommand-line utility using the show-versionoperation:

Table Of Contents