Cisco SCMS SM DHCP Lease Query LEG Reference Guide

The following diagram represents the operation of the DHCP Lease Query LEG:

Figure 1.1. DHCP Lease Query LEG Operation

The subscriber's traffic (1) triggers a pull-request from the SCE (2). The SM receives the request for processing. If the SM does not find a subscriber with a matching IP address in the subscriber database, it passes the pull-request to the DHCP Lease Query LEG (3). The LEG queries the DHCP server. If the server finds a match for the IP address in its database, the server replies with the subscriber information (4). The LEG performs a login operation (5). This operation updates the subscriber database based on the received information and logs the subscriber into the SCE (6), which triggered the pull-request.

If desired, install the DHCP Lease Query LEG directly on the SCE device to integrate the SCE with DHCP servers without the use of an SM server. The following diagram represents the operation of the LEG when installed on the SCE device:

Figure 1.2. DHCP Lease Query LEG Operation installed on an SCE device

The subscriber's traffic (1) triggers a pull-request from the SCE (2). The Lease Query LEG receives the request and queries the DHCP server. If the server finds a match for the IP address in its database, the server replies with the subscriber information (3). Based on the received information, the LEG responds to the SCE with a pull-response, which includes the subscriber ID and the IP address lease-time returned from the DHCP server (4).

The following terms and concepts are necessary to understand the DHCP Lease Query LEG and SM configuration and operation. Additional information can be found in the Cisco SCMS Subscriber Manager User Guide.

The LEG processes DHCP Lease-Query transactions to the DHCP server using the IP address indicated in the pull-request from the SCE. The DHCP server replies whether there is an active lease (DHCPLEASEACTIVE message) for this IP address and provides information about the subscriber associated with this IP address according to a list of options requested by the LEG. By default, the LEG requests the lease time and the modem MAC and adds package association related options if needed.

The DHCP Lease Query LEG supports up to two redundant DHCP servers. The LEG identifies a server failure by counting the consecutive requests that time out. After a configurable threshold of timed-out requests, the LEG starts to send the requests to the recently activated server, which was previously in standby. The LEG does not return to the failed server until the activated server fails.

When installing the LEG on the SM server, it runs with the privileges assigned to the user pcube on this machine. On UNIX platforms, because only the super-user (root) can open ports under 1024, the LEG cannot open the DHCP ports. To solve this problem, a simple application is supplied with the LEG, which forwards the DHCP packets between the LEG and the DHCP servers. This application is the DHCP Forwarder, which is described in Appendix A of this document.

When installing the LEG on the SCE device, there is no need to use the DHCP Forwarder application.

The DHCP Lease Query transaction is a DHCP transaction where the client (LEG) sends a DHCPLEASEQUERY message to the server, indicating the information it wants to query about. The LEG only queries about IP address. The server can reply with several types of messages, for example, DHCPLEASEACTIVE, which means that an active lease was found and the request information is supplied, or DHCPLEASEUNASSIGNED, which means this IP currently is not assigned to any subscriber.

The following is a detailed description of the attributes extracted from the DHCP Lease Query transaction:

After extracting the above information, the LEG logs the subscriber into the SM/SCE.

The SCMS SM LEG distribution file contains the DHCP Lease Query LEG distribution, which is located in the Lease_Query_LEG directory. Cisco supplies a DHCP Lease Query LEG distribution package. The following table describes the package contents:

The DHCP Lease Query LEG must be upgraded as part of the SM upgrade process, because previous versions of the DHCP Lease Query LEG are incompatible with the SM 3.0 version. The upgrade for the DHCP Lease Query LEG should be performed together with the upgrade process of the SM.

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

The [DHCP-Lease-Query-LEG] section contains the following parameters:

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:

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:

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

[Package Names]
gold_domain1=11
gold_domain2=12
silver_domain1=13
silver_domain2=14
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:
[Additional Data]
label_options=82:1
label_keys=PORT_ID
label_option_type=string
The following is an example of the entire configuration file:
[Package Association]
options_order_for_package_name=43:102,43:101
name_separator_value=_
use_default=true
default_package=1
package_property_name=packageId

[Package Names]
gold_domain1=11
gold_domain2=12
silver_domain1=13
silver_domain2=14

[Additional Data]
label_options=82:1
label_keys=PORT_ID
label_option_type=string

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

The following table lists the p3leasequery operations.

Use the Command-Line Interface (CLI) to configure the general LEG settings of the DHCP Lease Query LEG, and a configuration file for package association.

To enable the LEG:

SCE(config)# no subscriber LEG dhcp-lease-query

SCE(config)# subscriber LEG dhcp-lease-query servers STRING STRING

SCE(config)# no subscriber LEG dhcp-lease-query servers

SCE(config)# subscriber LEG dhcp-lease-query session-timeout DECIMAL

SCE(config)# default subscriber LEG dhcp-lease-query session_timeout

SCE(config)# subscriber LEG dhcp-lease-query failover-criteria DECIMAL

SCE(config)# default subscriber LEG dhcp-lease-query failover-criteria

SCE(config)# subscriber LEG dhcp-lease-query sub-id-option STRING <binary|string> [ip-fallback]

SCE(config)# default subscriber LEG dhcp-lease-query sub-id-option

SCE(config)# subscriber LEG dhcp-lease-query package-association-file STRING

SCE(config)# default subscriber LEG dhcp-lease-query package-association-file

SCE(config)# default subscriber LEG dhcp-lease-query

To view the general configuration of the LEG, enter the following command:

SCE# show subscriber LEG dhcp-lease-query

To view the statistics counters of the LEG:

SCE# show subscriber LEG dhcp-lease-query counters

To reset the statistics counters of the LEG:

SCE# clear subscriber LEG dhcp-lease-query counters