User Guide for Cisco Network Registrar, 7.0
Managing Leases
Downloads: This chapterpdf (PDF - 485.0 KB) The complete bookPDF (PDF - 18.25 MB) | Feedback

Managing Leases

Table Of Contents

Managing Leases

Configuring Leases in Scopes

Viewing Leases

Lease States

Guidelines for Lease Times

Importing and Exporting Lease Data

Pinging Hosts Before Offering Addresses

Deactivating Leases

Excluding Leases from Ranges

Searching Server-Wide for Leases

Creating Lease Reservations

Setting Advanced Lease and Reservation Properties

Reserving Currently Leased Addresses

Unreserving Leases

Extending Reservations to Non-MAC Addresses

Forcing Lease Availability

Inhibiting Lease Renewals

Handling Leases Marked as Unavailable

Setting Timeouts for Unavailable Leases

Running Address and Lease Reports

Running Address Usage Reports

Running IP Lease Histories

Enabling Lease History Recording at the Local Cluster

Querying IP Lease History

Trimming Lease History Data

Running Lease Utilization Reports

Receiving Lease Notification

Running Lease Notification Automatically in Solaris and Linux

Running Lease Notification Automatically in Windows

Specifying Configuration Files for Lease Notification

Querying Leases

Leasequery Implementations

Pre-RFC Leasequery for DHCPv4

RFC 4388 Leasequery for DHCPv4

Leasequery for DHCPv6

Leasequery Statistics

Leasequery Example

Managing Leases

Leases are at the center of the Dynamic Host Configuration Protocol (DHCP). They are the IP addresses allocated to individual clients for a certain time period. The DHCP server automatically allocates these leases with properly configured scopes that include valid IP address ranges. No two clients can have the same leased address. Reservations are leases that always get the same IP address.

This chapter describes how to manage leases and reservations in a network.

See Also

Configuring Leases in Scopes
Searching Server-Wide for Leases
Creating Lease Reservations
Setting Advanced Lease and Reservation Properties
Running Address and Lease Reports
Querying Leases

Configuring Leases in Scopes

After setting the IP address ranges for a scope, you can monitor and adjust the leases that result from DHCP assignments.

See Also

Viewing Leases
Lease States
Guidelines for Lease Times
Importing and Exporting Lease Data
Pinging Hosts Before Offering Addresses
Deactivating Leases
Excluding Leases from Ranges

Viewing Leases

To view leases, you must first create a range of IP addresses for them in a scope, as described in the "Set Up DHCP" chapter of the Quick Start Guide to Cisco Network Registrar or the "Defining and Configuring Scopes" section on page 20-3, then wait for the DHCP server to generate leases based on these addresses.

Local Basic Web UI

To view leases, click DHCP, then Scopes to open the Manage Scopes page, then click the View icon () in the Leases column for the scope. This opens the List Leases for Scope page, where you can click each lease to manage it (see Figure 22-1).

Figure 22-1 List Leases for Scope Page (Local Basic)

See the "Lease States" section for a description of the values in the State column. For guidelines as to the lease expiration time, see the "Guidelines for Lease Times" section.

When you click the lease IP address, you open the Manage DHCP Lease page (see Figure 22-2).

Figure 22-2 Manage DHCP Lease Page (Local Basic)

Local Advanced Web UI

Click DHCP, then Scopes to open the List/Add DHCP Scopes page. You can then click the View icon () in the Leases column for the scope; or you can click the name of the scope to open the Edit DHCP Scope page, then click List Leases in the Leases area of the page. Both actions open the List DHCP Leases for Scope page, where you can manage the leases as in Basic mode.

CLI Commands

Use lease ipaddr show to show the properties of a particular lease based on its IP address. Use scope name listLeases to show all the leases for a named scope. The output is nearly identical for both commands. Note that you cannot list leases in a particular virtual private network (VPN); all the leases in all the VPNs appear in the list.

You can show the most recent MAC address associated with a lease or what lease is associated with a MAC address. The lease addr macaddr command shows the MAC address of the lease, whether or not that lease is reserved or active. The lease addr list -macaddr command lists the lease data only if the IP address for that MAC address was actively leased (and not reserved). You can also list leases by LAN segment and subnet by using lease addr list -subnet network netaddr netmask.

Lease States

A lease can be in one of the states described in Table 22-1.

Table 22-1 Lease States 



IP address available to be leased.


Not leasable. See the "Handling Leases Marked as Unavailable" section for ways the DHCP server might set a lease to unavailable.


Held by a client.


Offered to the client.


Available when the lease grace period expires.


Not renewable or leasable after the lease expires. See the "Deactivating Leases" section.

Pending available

Failover-related. See Chapter 27, "Configuring DHCP Failover."

Note The DHCP server logs the lease state only if you enable the ip-history-detail attribute for the server.

When the state of an existing lease changes (such as when it becomes reserved or deactivated), the DHCP server does not report the change as an IP lease history change to the regional servers. The DHCP server reports a lease history change only when the lease expires or the DHCP server leases the IP address to another client. (See the "Running IP Lease Histories" section.)

Guidelines for Lease Times

To define appropriate values for lease times, consider these events on your network:

Frequency of changes to DHCP options and default values.

Number of available IP addresses compared to clients requesting them.

Number of network interface failures.

Frequency at which computers are added to and removed from the network.

Frequency of subnet changes by users.

All these events can cause clients to release IP addresses or the leases to expire at the DHCP server. Consequently, the addresses may return to the free-address pool for reuse. If many changes occur on your network, Cisco recommends a lease time between one and three days for active networks, and between four and ten days for inactive networks. Assigning such a lease time reassigns IP addresses more quickly as clients leave the subnet.

Another important factor is the ratio of available addresses to connected computers. For example, the demand for reusing addresses is low in a class C network having 254 available addresses, of which only 40 are used. A long lease time, such as two months, might be appropriate in such a situation. The demand would be much higher if there were 240 to 260 clients trying to connect at one time. In this situation, you should try to configure more address space. Until you do, keep the DHCP lease time to under a hour.

Tip Short lease periods increase the demand that the DHCP server be continuously available, because clients will be renewing their leases more frequently. The DHCP failover functionality can help guarantee such levels of availability.

Be careful when creating policies that have permanent leases. A certain amount of turnover among clients occurs, even in a stable environment. Portable hosts might be added and removed, desktop hosts moved, and network adapter cards replaced. If you remove a client with a permanent lease, it requires manual intervention in the server configuration to reclaim the IP address. It would be better to create a long lease, such as six months, to ensure that addresses are ultimately recovered without administrator intervention.

Recommendations for lease durations include:

Set cable modem lease times to seven days (604800 seconds). The leases should come from private address space, and the cable modems should seldom move around.

Leases for customer premises equipment (CPE) or laptops should come from public address space and should match the habits of the user population, with as long a lease as possible to reduce load on the server.

Shorter lease times require more DHCP request and response buffers. Set the request and response buffers for optimal throughput (see the "Setting DHCP Request and Response Packet Buffers" section on page 27-18).

Allow the server to determine the lease period, by ensuring that the allow-lease-time-override policy attribute is disabled, which is its normal default. Even if enabled, clients can only request lease times that are shorter than you configure for the server. Some clients always request a fixed lease time (such as an hour) or the same one they had previously. These kinds of requests can cause problems in that the client never gets the full lease time, thereby generating more traffic for the server.

Defer any lease extensions for clients trying to renew leases before the halfway mark in the lease. For details, see the "Deferring Lease Extensions" section on page 23-6.

Importing and Exporting Lease Data

You can use the CLI to import lease data to, and export from, text files.

Import Prerequisites

Before you can import leases, you must perform several configuration steps:

1. Configure a scope or scopes in the DHCP server for the leases that you plan to import.

2. If you want the hostnames for the leases dynamically entered into DNS as part of the import, configure zones in the DNS server to allow dynamic updates from the DHCP server.

3. Set the DHCP server to import mode so that it does not respond to other lease requests during the lease importing.

4. For all the time fields, use either the number of seconds since midnight GMT January 1, 1970, or a day, month, date, time, year format (Mon Apr 15 16:35:48 2002).

5. After you import the leases, take the DHCP server out of import mode so that it can respond to other lease requests.

Note Importing permanent leases will fail if you disable the permanent leases option. Enable this option using policy name enable permanent-leases, as necessary.

Import and Export Commands

The import leases and export leases commands use a special file format. Each record, or line, in the file represents one DHCP client:


Do not use spaces between the vertical line (|) delimiter and the field values. You must include at least the first four required fields. If you include more, you must delimit all the remaining null fields with the vertical line (|) so that there are 13 fields. The fields are, in order:

1. MAC address in aa:bb:cc:dd:ee:ff format (required)

2. MAC address type (required)

3. MAC address length (required)

4. IP address in dotted decimal format, a.b.c.d (required)

5. Start of lease time (Greenwich Mean Time, GMT) (optional)

6. Lease expiration time (GMT) (optional)

7. Allowable extension time (GMT) (optional)

8. Last transaction time (GMT) (optional)

9. IP address of the DHCP server (optional)

10. Hostname (without domain) (optional)

11. Domain name (optional)

12. Client ID (optional)

13. VPN name (optional; if omitted, the global VPN is used)

For all the time fields, use either the number of seconds since 1970, or the day-month-date-time-year format (such as Mon Apr 9 16:35:48 2007).

When importing leases, the DHCP server might not accept a lease, or a communication failure might drop the lease packet. In the latter case, the server retries the import several times, and after about a minute, reports a failure. If the import fails, check the DHCP server log file to find the lease that caused the error. Then go back to the import file, delete all lease entries up to and including the offending one, and repeat the lease import.

When you use export leases, you can choose between writing the state of all current and expired leases, or just the current leases, to the output file. Example 22-1 shows part of a lease data export from a Network Registrar DHCP server. The blank lines between records appear in the example for clarity; they are not in the actual output.

Example 22-1 Lease Data Export

00:60:97:40:c1:96|1|6||Wed Aug 30 08:36:57 2000|Fri Sep 01 13:34:05 2000|
Wed Aug 30 08:36:57 2000|Fri Sep 01 09:34:05 2000||nomad||

00:d0:ba:d3:bd:3b|1|6||Thu Aug 17 13:10:11 2000|Fri Sep 01 14:24:46 2000|
Thu Aug 17 13:10:11 2000|Fri Sep 01 10:09:46 2000||NPI9F6AF8||blue-vpn

00:d0:ba:d3:bd:3b|1|6||Fri Jun 23 15:02:18 2000|Fri Sep 01 14:11:40 2000|
Fri Jun 23 15:02:18 2000|Fri Sep 01 09:56:40 2000||JTB-LOCAL||blue-vpn

Lease Times in Import Files

During an import, the DHCP server gives the client the lesser of these lease times:

The time specified in the import file.

The time that the client receives if it were to acquire a lease using the existing configuration of the DHCP server.

For example, at 2:00 P.M. your scope is configured for a one-hour lease. According to the file that you import, the lease time does not expire until 5:00 P.M. After you import the file, the lease expires at 3:00 P.M. and not at 5:00 P.M.

Note If your import file specifies a DNS zone name, the server does not use the zone name when it updates DNS. If the file specifies a hostname, then the server uses the hostname when updating DNS, unless hostname specification in a client or client-class entry overrides the hostname.

The only way to indicate to the DHCP server that the client hostname should be in a zone other than the zone associated with the DNS update configuration object used for the DNS update is to specify that zone in a client or client-class entry.

Pinging Hosts Before Offering Addresses

You can have the DHCP server use the Internet Control Message Protocol (ICMP) echo message capability (also known as ping) to see if anyone responds to an IP address before assigning it. This test allows the DHCP server to check that an address is not in use before assigning it. Using ping can help prevent two clients from using the same address. If a client responds to the ping, the DHCP server marks that address as unavailable and offers a different address. This test works only for powered-up clients; it is possible for clients to have a lease and be powered down.

Tip The ping timeout period is important. Because pinging helps to ensure that no client is using a particular IP address, each ping must wait the entire timeout period. This ping timeout period comes before an offer, so the time specified has a considerable effect on server performance. If you set this time too long, it slows down the lease offering process. If you set this time too short, it reduces the effectiveness of the ping packet to detect another client using the IP address.

To implement pinging hosts before offering IP addresses, modify the scope by:

Enabling the ping-clients attribute. It is disabled by default.

Setting the ping-timeout attribute. It is 300 milliseconds by default.

The server makes unavailable any IP address for which it receives a successful ECHO reply. You can control this action by enabling the DHCP server attribute ignore-icmp-errors (the preset value). If disabled, the DHCP server also uses ICMP DEST_UNREACHABLE and TTL_EXPIRED error messages that it receives after sending ICMP ECHO requests as reasons for making an IP address unavailable.

Deactivating Leases

Deactivating a lease moves a client off of it. If the lease is available, deactivating it prevents the DHCP server from giving it to a client. If the lease is active (held by a client), deactivating it prevents the client from renewing it and the server from giving the lease to another client. You can deactivate a lease only if the server is running. The DHCP server deactivates the lease immediately.

Tip If you did not set synchronous scope edit mode, you must reload the DHCP server.

To force a Windows client to release its lease, run ipconfig /release on the client machine.

Local Basic Web UI

To deactivate a lease, click the address of the lease on the List Leases for Scope page (see the "Viewing Leases" section). On the Manage DHCP Lease page, click Deactivate. The lease now shows as deactivated. To reactivate the lease, click Activate.

Local Advanced Web UI

To deactivate a lease, the same operations exist as in Basic mode, except that you click the address of the lease on the List DHCP Leases for Scope page, which opens the Manage DHCP Lease page.

CLI Commands

To deactivate a lease, use lease ipaddr deactivate. To reactivate a lease, use lease ipaddr activate.

Excluding Leases from Ranges

IP address ranges, by definition, must be contiguous. To exclude a lease from an existing range, you must divide the range into two smaller ones. The new ranges consist of the addresses between the original starting and ending range addresses and the address that you want to exclude.

Caution If the excluded address currently has an active lease, you should first follow the steps in the "Deactivating Leases" section, otherwise you will get a warning message. Deleting an active lease can result in a duplicate IP address if the deleted address is subsequently reconfigured and then reassigned. Information about that lease will no longer exist after you reload the server.

Local Basic Web UI

To exclude a lease from a scope address range:

Step 1 Click DHCP, then Scopes to open the Manage Scopes (Address Pools) page.

Step 2 Click the name of the scope to open the Edit DHCP Scope (Address Pool) page.

Step 3 In the Ranges area, click the Delete icon () next to the IP address range you want to remove.

Step 4 Add a range that ends just before the excluded IP address.

Step 5 Add another range that begins just after the excluded IP address.

Step 6 Modify the scope. If you set staged scope edit mode, you must also reload the DHCP server.

Local Advanced Web UI

To exclude a lease from a scope address range, the same operations exist as in Basic mode, except that you click the name of the scope on the List/Add DHCP Scopes page, which opens the Edit DHCP Scope page.

CLI Commands

To exclude a lease from a scope address range, discover the lease range (scope name listRanges), deactivate the lease (lease ipaddr deactivate), then remove the range of just that IP address (scope name removeRange). The resulting ranges are then split appropriately.

The following example removes the address from the range. Note that if the lease is in a scope with a defined VPN, you must explicitly define that VPN for the session, or you can include the VPN prefix in the lease command:

nrcmd> session set current-vpn=red 
nrcmd> scope examplescope1 listRanges 
nrcmd> lease red/ deactivate 
nrcmd> scope examplescope1 removeRange 
nrcmd> scope examplescope1 listRanges 

If you set staged edit mode for the scope, reload the server.

Searching Server-Wide for Leases

Network Registrar 7.0 provides a new function with which you can search for leases server-wide. The search is a filter mechanism whereby you can specify a combination of lease attributes to target one or more leases configured for the network. The search function is available at the local cluster only and is provided separately for DHCPv4 and DHCPv6 leases.

Local Advanced Web UI

Step 1 Click DHCP, then Search to open the DHCP Search page (see Figure 22-3 for the DHCPv4 version of this page).

Step 2 If necessary, choose a specific VPN (the [none] VPN is the current one) or search in all VPNs.

Step 3 Choose a Filter Attribute from the drop-down list, such as client-id. DHCPv4 and DHCPv6 have separate lists of filter attributes. Attributes in the list are greyed out once they are selected as an element.

Figure 22-3 DHCPv4 Lease Search Page (Local Advanced)

Step 4 Choose a filter Type from the drop-down list. You can choose at least Binary or Regular Expression, but the list can contain one or more of the following, depending on the Filter Attribute selected:

Binary—Value is in binary notation.

Date Range—Range of date values, From a date and time To a date and time.

Integer—Value is an integer.

Integer Range—Integer From value to an integer To value.

IP Address—Value is an IP address.

IP Range—IP address From value to an IP address To value.

IP Subnet—Value is an IP subnet.

Regular Expression—Value is a Regular Expression in regex syntax. (For common regex usage, see Table 5-4 on page 5-22).

Step 5 Enter a Value, based on the Type selected. To clear the filter, click Clear Filter.

Step 6 Click Add Element to add the search element to the Filter Elements list. You can delete the element by expanding the filter display, then clicking the Delete icon () next to the element.

Step 7 Once you assemble a list of elements, you can search on them, so that the elements are ANDed together for the result. Click Search.

Step 8 Check the table of resulting leases from the search, which shows for each an address, state, MAC address, hostname, flags, and expiration date. If necessary, change the page size to see more entries. The leases are ordered by IP address.

Tip The filter elements are ANDed together for the search. If you find that the search results do not yield what you expect, look at the Filter Elements list again and delete elements that can obstruct the results.

CLI Commands

Use lease list -macaddr mac-addr [-vpn=vpn-name] to find leases in the DHCPv4 space. Specify the MAC address of the lease. If you omit the VPN designation, you base the search on the current VPN.

For leases in the DHCPv6 space, use the following lease6 list syntax:

nrcmd> lease6 list 
[-lookup-key=key] [-blob | -string]] 

The -macaddr and -cm-macddr options are to search for leases identified by the CableLabs DOCSIS vendor-opts option (DHCPv6 option 17). For example, for these two commands:

nrcmd> lease6 -macaddr=01:02:03:04:05:06 
nrcmd> lease6 -cm-macaddr=01:02:03:04:05:06 

The -macaddr line lists leases where the option 17 device-id suboption (36) contains the requested MAC address. The -cm-macddr line lists leases where the option 17 cm-mac-address suboption (1026) matches the requested MAC address. (See Table C-4 on page C-7 for details on these suboptions.)

Creating Lease Reservations

To ensure that a client always gets the same lease, you can create a lease reservation. Managing lease reservations is available only to administrators having the dhcp-admin role at the local cluster, or the central-cfg-admin role with the dhcp-management subrole at the regional cluster.

Tip Try to limit the use of reservations. Because they are stored for scopes and not leases, using them adds to the administrative burden and complication in the case of failover. Limit reservations to less than one thousand per scope. To configure extended leases, it is often better to set long grace periods instead of reservations.

Caution If multiple DHCP servers distribute IP addresses on the same subnet, the client reservations must be identical. If not, a client for whom a lease reservation exists can receive offers of different IP addresses from different servers.

A lease reservation pairs an IP address with a MAC address or lookup key. You can choose any valid IP address on the network; it does not necessarily have to be in one of the scope ranges. You can use the IP addresses in the scope range for dynamic leases and the ones outside the range for reserved leases. However, even though a reserved IP address may not be in the scope range, the policy associated with the scope still applies to the address.

Local Basic Web UI

To view lease reservations, click DHCP, then Scopes to open the Manage Scopes (Address Pools) page, then click the View icon () in the Reservations column to open the List/Add DHCP Reservations for Scope page (see Figure 22-4).

To create a reservation on this page, enter the IP address of the lease you want to reserve, and either enter its MAC address in the MAC Address field or a lookup key in the Lookup Key field. If you enter a lookup key other than a MAC address in the Lookup Key field, also click the string or binary radio button, as appropriate for the entry. Click Add Reservation, then Modify Scope.

Figure 22-4 List/Add DHCP Reservations for Scope Page (Local Basic)

Viewing Reservations for Scopes in Local Advanced Web UI

To view lease reservations, click DHCP, then Scopes to open the List/Add DHCP Scopes page, then click the View icon () in the Reservations column to open the List/Add DHCP Reservations for Scope page. Proceed as for the Basic web UI.

Configuring Reservations Directly in Local Advanced Web UI

Advanced mode also provides a mechanism to create reservations independent of scopes. Click DHCP, then Reservations to open the List Reservations page (see Figure 22-5).

Figure 22-5 List Reservations Page (Local Advanced)

For reservations that could be in one of several scopes, this method requires that you enter client-class selection and other advanced attributes so that you can associate the reservation with the correct scope. On this page, click Add Reservation to open the Add Reservation page (see Figure 22-6 that shows the Advanced attributes expanded).

Figure 22-6 Add Reservation Page (Local Advanced)

Enter the IP address of the reservation in the IP Address field, then enter either its MAC address or a string or binary lookup key (do not enter both a MAC address and lookup key).

Further down the page, you can set advanced attributes such as include-tags, relay-info, device-name, or a description (see the "Setting Reservation Attributes" section). (Choose either a client-class or enter an include-tags value, but not both.) Click Add Reservation when you are done.

Note In Expert mode, you can synchronize reservations on the CCM server from the DHCP server, and synchronize reservations on the DHCP server from the CCM server, on the List Reservations page. Click Sync CCM Server from DHCP Server to open the Sync Reservations on CCM Server from DHCP Server page. Click Sync DHCP Server from CCM Server to open the Sync Reservations on DHCP Server from CCM Server page. Click Return on both pages.

CLI Commands

To list the reservations for a scope, use scope name listReservations. To list all the available reservations, use reservation list [[vpn/]ipaddr | -mac | -key]. Using the -mac or -key option shows a value for the MAC address or lookup key for each reservation.

To add a reservation to a particular scope, use scope name addReservation ipaddr {macaddr | lookupkey}. To add a reservation just for the IP address, use reservation [vpn/]ipaddr create {macaddr | lookupkey}. If you use a lookupkey other than the MAC address, you must add the -blob or -string option to the command. The DHCP server assigns the reservation to the scope that encompasses its IP address. You can set attribute values for the reservation such as the client-class, include-tags, relay-info, device-name, or a description. (See the "Setting Reservation Attributes" section.) If you set the scope edit mode to staged, you must save (save), then send the reservation (lease [vpn/]ipaddr send-reservation).

Setting Reservation Attributes

You can set certain attributes for lease reservations other than the VPN, IPv4 or IPv6 address, MAC address, or lookup key (see Table 22-2). In the CLI, you use reservation [vpn/]ipaddr set attribute=value.

Table 22-2 Reservation Attributes



Optional description of the device that this reservation represents.


Optional name of the device that this reservation represents.


Scope selection criteria for this reservation. Do not set this value if you are setting a client-class.


Relay agent information option (82) value required for Leasequery purposes (see the "Querying Leases" section).

Setting Advanced Lease and Reservation Properties

Setting advanced lease and reservation properties can include:

Reserving currently leased IP addresses—See the "Reserving Currently Leased Addresses" section.

Unreserving leases—See the "Unreserving Leases" section.

Extending leases to non-MAC addresses—See the "Extending Reservations to Non-MAC Addresses" section.

Forcing lease availability—See the "Forcing Lease Availability" section.

Inhibiting lease renewals—See the "Inhibiting Lease Renewals" section.

Handling leases marked as unavailable—See the "Handling Leases Marked as Unavailable" section.

Setting timeouts for unavailable leases—See the "Setting Timeouts for Unavailable Leases" section.

Reserving Currently Leased Addresses

You can delete a reservation for one client while reusing it for another one, even though the first client still has the lease.

Local Advanced Web UI

To reserve an existing lease:

Step 1 Click DHCP, then Scopes, then the name of the scope to open the Edit DHCP Scope page.

Step 2 Click the View icon () under the Leases column.

Step 3 Click the IP address of the lease on the List DHCP Leases for Scope page.

Step 4 On the Manage DHCP Lease page, if the IP address is not leased (in available state), enter the lookup key or MAC address for the reservation.

Step 5 Click Make Reservation. On the List DHCP Leases for Scope page, the lease will appear as reserved.

Step 6 Modify the scope.

Step 7 To remove the reservation, click Remove Reservation on the Manage DHCP Lease page, then modify the scope. The lease no longer appears as reserved.

Example of Reserving an Existing Lease

This CLI command example creates a reservation from an existing lease:

nrcmd> reservation create 1,6,00:d0:ba:d3:bd:3b 
nrcmd> save 
nrcmd> lease send-reservation 
nrcmd> lease activate 
nrcmd> save 

Client 1,6,00:d0:ba:d3:bd:3b does a DHCPDISCOVER and gets an offer for The client then does a DHCPREQUEST and gets an ACK message for the same IP address.

As time passes, client 1,6,00:d0:ba:d3:bd:3b does several DHCPREQUESTs that are renewals, which the server acknowledges. Then, at some time before the client lease expiration time, you terminate the reservation:

nrcmd> lease deactivate 
nrcmd> reservation delete 
nrcmd> save 
nrcmd> lease delete-reservation 

You then add a reservation for a different client for that IP address, even though the address is still leased to the first client:

nrcmd> reservation create 1,6,02:01:02:01:02:01 
nrcmd> save 
nrcmd> lease send-reservation 
nrcmd> lease activate 
nrcmd> save 

This action results in an IP address that is leased to one client, but reserved for another. If the new client (1,6,02:01:02:01:02:01) does a DHCPDISCOVER before the original client (1,6,00:d0:ba:d3:bd:3b) does, the new client does not get, but gets a random IP address from the dynamic pool.

When the original client (1,6,00:d0:ba:d3:bd:3b) sends its next DHCPREQUEST/RENEW for the lease on, it gets a NAK message. Generally, upon receipt of the not-acknowledged message, the client immediately sends a DHCPDISCOVER. On receiving that DHCPDISCOVER, the server cancels the remaining lease time for

The server then gives client 1,6,00:d0:ba:d3:bd:3b whatever lease is appropriate for it—some reservation other than, some dynamic lease (if one is available), or nothing (if no dynamic leases are available). When the new client (1,6,02:01:02:01:02:01) tries to renew the random IP address it received, the server sends it a NAK, because it wants to give it the reserved address. When the new client then does a DHCPDISCOVER, it gets the reserved address.

You could also force availability of a lease (see "Forcing Lease Availability" section). However, doing so does not stop the original client (1,6,00:d0:ba:d3:bd:3b) from using Also, it does not prevent the new client (1,6,02:01:02:01:02:01) from getting In other words, this means that making a reservation for a client is independent of the lease state (and actual lease client) of the IP address for which the reservation is made.

Thus, making a reservation for one client does not cause another client to lose that lease right away, although that client receives a NAK response the next time it contacts the DHCP server (which could be seconds or days). Additionally, the client that reserved the IP address does not get that address if some other client already has it. Instead, it gets another IP address until the:

IP address it is supposed to receive is free.

Client sends a DHCPREQUEST as a renewal and receives a NAK response.

Client sends a DHCPDISCOVER.

Unreserving Leases

You can remove lease reservations at any time. However, if the lease is still active, the client continues to use the lease until it expires. If you try to reserve the lease for a different client, you will get a warning.

Local Advanced Web UI

To unreserve a lease, click DHCP, then Reservations to open the List Reservations page, then click the Delete icon () next to the reservation you want to remove. This removes the reservation immediately, with no confirmation.

CLI Commands

To unreserve a lease, use reservation [vpn/]ipaddr delete or scope name removeReservation {ipaddr | macaddr | lookupkey} [-mac | -blob | -string].

You can also completely delete a reservation by using lease ipaddr delete-reservation. However:

Ensure that the reservation is gone from the nrcmd internal database.

If you use failover on the scope containing the reservation:

1. Use reservation [vpn/]ipaddr delete, or scope name removeReservation, on both servers.

2. On the backup server, if you are in staged scope edit mode, use lease [vpn/]ipaddr delete-reservation.

3. Use the same command on the main server.

Save the result of this operation to preserve it across server reloads, because issuing lease ipaddr delete-reservation alone affects only the server internal memory.

Extending Reservations to Non-MAC Addresses

You might need to create lease reservations based on something other than the MAC address from the incoming client packet. Often, DHCP client devices attached to a switch port need to get the same IP address, regardless of the MAC address. This approach helps when you replace factory floor devices with identical devices (with different MAC addresses), but want to maintain the same IP address.

Overriding Client IDs

You can set an expression in a client-class override-client-id attribute that extracts the MAC address and port of a switch from the relay-agent-info option (82) and creates a client identity from it. Regardless of the client-id in the incoming packet, the identity that allocates an IP address is the same for any device coming in through the same switch port. The expression you use for the attribute depends on the option 82 format. The DHCP server calculates the expression when it assigns the packet to the client-class. The override-client-id value becomes the identity of the client from that point onward.

However, when you enable the use-client-id-for-reservations attribute in a policy, the server turns the client-id of that request into a string of the form nn:nn:nn ... nn:nn, and uses that string to look up the reservation.

The add-to-environment-dictionary attribute for a client or client-class also serves to send attribute values to the DHCP extension environment dictionary (see Chapter 29, "Using Extension Points"), specified as name-value pairs. You can configure an add-to-environment-dictionary attribute on either a client or a client-class. If you choose to configure this attribute on both a client and client-class, you should ensure that the name-value pairs that you configure on the client have different names than the name-value pairs that you configure on the client-class, because they are all going to be put into the same environment dictionary (which can have only one value for a particular name). Generally, it is best to configure this attribute on a client or a client-class only, but not on both.

Local Advanced Web UI

You can find the override-client-id attribute on the Add DHCP Client-Class page (click DHCP, then Client-Class, then Add Client-Class) or Edit DHCP Client-Class page (click DHCP, then Client-Class, then the name of the client-class).

You also need to configure a client-class lookup ID for the DHCP server, to put every packet into a particular client-class where you configure the override-client-id expression. Click DHCP, then DHCP Server, then the Local DHCP Server link to open the Edit DHCP Server page. In the Client Class attributes, enter a client-class-lookup-id expression.

To use the client ID for the reservation, configure the policy to enable the use-client-id-for-reservations attribute on the Add DHCP Policy page (click DHCP, then Policy, then Add Policy) or Edit DHCP Policy page (click DHCP, then Policies, then the name of the policy).

CLI Commands

The syntax for setting the override-client-id attribute is client-class name set override-client-id="expression". The syntax for setting the client-class-lookup-id attribute is dhcp set client-class-lookup-id="expression". The syntax for setting the use-client-id-for-reservations attribute is policy name enable use-client-id-for-reservations.

Reservation Override Example

The following example shows how to override a client ID for a reservation:

Step 1 Create a scope for the reservation:

a. Enter a subnet address.

b. If you want dynamic reservations, add an IP address range.

Step 2 Add the reservation for the scope:

a. Include a value for the lookup key.

b. Specify the lookup key type as binary.

Step 3 Create a policy for the purpose, enabling the use-client-id-reservations attribute.

Step 4 Create a client-class for the purpose:

a. Specify the policy created in the previous step.

b. Include an expression for the override-client-id attribute that returns a blob value with the client ID you want, based on the contents of the packet.

Step 5 Get a lease for a client with the MAC address. This client will then get the override ID.

Forcing Lease Availability

You can force a current lease to become available. You should request that the user release the lease, or do so yourself, before forcing its availability. Forcing lease availability does not require a server reload.

Note After a lease is forced to be available, the client continues to use it until the client contacts the DHCP server.

Local Advanced Web UI

To force lease availability:

Step 1 Click DHCP, then Scopes to open the List/Add DHCP Scopes page.

Step 2 Click the View icon () under the Lease column for the scope that has leases.

Step 3 Click the IP address of the lease on the List DHCP Leases for Scope page.

Step 4 On the Manage DHCP Lease page, click Force Available. On the List DHCP Leases for Scope page, the lease will now show an empty value in the Flags column.

CLI Commands

To force lease availability, use lease [vpn/]ipaddr force-available. Use scope name clearUnavailable to force all leases in the scope to become available.

Inhibiting Lease Renewals

Normally, the Network Registrar DHCP server retains the association between a client and its leased IP address. The DHCP protocol explicitly recommends this association and it is a usually desirable feature. However, for some customers, such as ISPs, clients with long-lived lease associations may be undesirable, because these clients should change their IP addresses periodically. Network Registrar includes a feature that allows customers to force lease associations to change when DHCP clients attempt to renew their leases or reboot.

A server can never force a client to change its lease, but can compel the client to do so based on a DHCPRENEW or DHCPDISCOVER request. Network Registrar offers configuration options to allow customers to choose which interactions to use to force a client to change its IP address:

Inhibiting all lease renewals—While a client is using a leased address, it periodically tries to extend its lease. At each renewal attempt, the server can reject the lease, forcing the client to stop using the IP address. The client might have active connections that are terminated when the lease terminates, so that renewal inhibition at this point in the DHCP interaction is likely to be user-visible.

Inhibiting renewals at reboot—When a DHCP client reboots, it might have recorded a valid lease binding that did not expire, or it might not have a valid lease. If it does not have a lease, you can prevent the server from granting the last held lease. If the client has a valid lease, the server rejects it, forcing the client to obtain a new one. In either case, no active connections can use the leased address, so that the inhibition does not have a visible impact.

Effect on reservations—Reservations take precedence over renewal inhibition. If a client has a reservation, it can continue to use the reserved IP address, whether or not renewal inhibition is configured.

Effect on client-classes—Client-class testing takes place after renewal inhibition testing. If a client is forced to change IP addresses by renewal inhibition, then client-class processing might influence which address the server offers to the client.

You can enable or disable lease renewal inhibition for a policy, which you can set system wide, for a scope or on a client-by-client basis. The inhibit-all-renews attribute causes the server to reject all renewal requests, forcing the client to obtain a new IP address any time it contacts the DHCP server. The inhibit-renews-at-reboot attribute permits clients to renew their leases, but the server forces them to obtain new addresses each time they reboot.

The DHCP server needs to distinguish between a client message that it should reject (such as a renewal request) and one that represents a retransmission. When the server processes a message, it records the time the packet arrived. It also records the time at which it made a lease binding to a client, and the last time it processed a message from the client about that binding. It then compares the packet arrival time with the lease binding time (the start-time-of-state) and processes packets from the client within a certain time interval from the start time of the binding. By default, this time interval is one minute.

Local Advanced Web UI

To inhibit lease renewals, create a policy on the Edit DHCP Policy page (click DHCP, then Policies, then the name of the policy), then enable the inhibit-all-renews or inhibit-renews-at-reboot attribute. (Both attributes are preset to disabled). Then, modify the policy.

Handling Leases Marked as Unavailable

One of the aspects of effective lease maintenance is determining the number of unavailable leases in a scope. This number is sometimes higher than expected. Each unavailable lease is probably an indication of a serious problem. Possible causes for an unavailable lease are:

The DHCP server is configured for a ping before an offer, and the ICMP echo message is returned successfully—A currently active client is using that IP address, causing the DHCP server to mark it as unavailable. To prevent the server from doing so, disable pinging an address before offering it to a client. See the "Pinging Hosts Before Offering Addresses" section.

The server receives a DHCPDECLINE message from a client to which it leased what it considered to be a good IP address—The client does an address resolution (ARP) request for the IP address on its local LAN segment, and another client responds to it. The client then returns the address to the server with a DHCPDECLINE packet and sends another DHCPDISCOVER packet to get a new address. The server marks as unavailable the address that the client returns. To prevent the server from reacting to DHCPDECLINE messages, you can set a scope attribute, ignore-declines.

The server receives "other server" requests from the client—Because all DHCPREQUEST messages that follow DHCPOFFER messages are broadcast, the server can see messages directed to other DHCP servers. A server knows that a message is directed to it by the value of the server-id option in the packet. If the Network Registrar server recognizes a message directed at another server, in that its own IP address does not appear in the server-id option, but the address leased in the message is one that the server controls, it believes that two servers must be trying to manage the address simultaneously. It then marks the local address as unavailable. This behavior does not apply in a DHCP failover configuration. Either the two servers are configured with some or all of the same IP addresses, or (in rare cases) the DHCP client placed a wrong server-id option value in the packet.

If you have reason to believe that the client is sending bad server-id options (rather than packets actually directed to other servers), Network Registrar has a server attribute you can enable that turns this behavior off, the ignore-requests-for-other-servers attribute.

Inconsistent lease data—Extremely rare and occurring only during server startup when, while configuring a lease, the server reads the lease data from disk during a refresh of the internal cache. The lease state appears as leased, but there is incomplete data to construct a client for that lease, such as that the lease might not yet have a client-id option value. The server considers the data to be inconsistent and marks the IP address as unavailable. Forcing the lease to be available (such as by using the lease ipaddr force-available command in the CLI) should clear up this problem.

Setting Timeouts for Unavailable Leases

During the times when leases become unavailable, as described in the "Handling Leases Marked as Unavailable" section, all unavailable leases remain in that state for a configured time only, after which time they again become available. A policy attribute, unavailable-timeout, controls this time. The system_default_policy policy sets this value to one day by default.

To handle upgrades from previous releases of Network Registrar that do not have this timeout feature, a special upgrade timeout attribute, upgrade-unavailable-timeout (which is preset to one day) is included at the server level. The upgrade-unavailable-timeout value is the timeout given to leases set to unavailable before the Network Registrar upgrade. This setting affects the running server only and does not rewrite the database. If the server stays up for one day without reloading, all the unavailable leases that were present at the last reload will time out. If the server reloads in less than a day, the entire process restarts with the next reload. Note that this process occurs only for leases that were set unavailable before the upgrade. Leases that become unavailable after the upgrade receive the unavailable-timeout value from the policy, as previously described.

If a Network Registrar failover server receives an update from a Network Registrar DHCP server running prior to Network Registrar 6.0, the unavailable leases do not have a timeout value. In this case, the upgraded Network Registrar server uses the unavailable-timeout value configured in the scope policy or system_default_policy policy as the timeout for the unavailable lease. When the lease times out, the policy causes the lease to transition to available in both failover partners.

Running Address and Lease Reports

You can run these reports on IP addresses and leases:

Address Usage—See the "Running Address Usage Reports" section.

Lease History—See the "Running IP Lease Histories" section.

Current Utilization—See the "Running Lease Utilization Reports" section.

Lease Notification—See the "Receiving Lease Notification" section.

Running Address Usage Reports

The address usage reports show the IP addresses that are assigned leases.

Local Advanced Web UI

To view the leases for IP addresses, on the Edit DHCP Scope page, in the Leases area, click List Leases to open the List DHCP Leases for Scope page. To manage a specific lease, click its IP address on the page. This opens the Manage DHCP Lease page.

CLI Commands

To view the IP address usage for specified servers, use report.

Tip If you are not already using lease-notification in an automated way, try lease-notification available=100% for a concise scope-by-scope summary of the state of the servers.

Running IP Lease Histories

You can extract IP lease history data from a special database so that you can determine past allocation information for a given IP address. You can get a historical view of when a client was issued a lease, for how long, when the client or server released the lease before it expired, and if and when the server renewed the lease and for how long.

Network Registrar provides a client to control querying IP history data. Through this client, you can:

Get the MAC addresses associated with a given IP address over a given time.

See the entire IP history database as a comma-separated file.

View the attributes of the lease history (the lease history detail report)—See the "Querying IP Lease History" section.

You must use additional administrative functions to trim the IP history database of records, to keep the size of the database from growing without bounds.

Note When the state of an existing lease changes (for example, when it is configured as a reserved IP address or it is deactivated), the change does not appear as a lease history change at the regional cluster, unless you enable the ip-history-detail attribute. With detail collection disabled, a lease history change appears only when the lease transitions from leased to not leased or is assigned to another client.

See Also

Enabling Lease History Recording at the Local Cluster
Querying IP Lease History
Trimming Lease History Data

Enabling Lease History Recording at the Local Cluster

You must explicitly enable lease history recording for the local cluster DHCP server. The DHCP server logs IP history recording errors in the usual DHCP log files.

Local Advanced Web UI

To enable lease history recording:

Step 1 Click DHCP, then DHCP Server to open the Manage DHCP Server page.

Step 2 Click the Local DHCP Server link.

Step 3 On the Edit DHCP Server page, look for the Lease History attributes:

Lease History (ip-history)—Be sure this is set to enabled.

ip-history-detail—Enable this to get detailed lease history data.

ip-history-max-age—Maximum age of the lease history to collect. With lease history enabled, the DHCP server periodically examines the lease history records and deletes any records with lease history bindings older than this age threshold.

Step 4 Click Modify Server at the bottom of the page.

Step 5 If you set staged edit mode for the scope, reload the server.

CLI Commands

To enable lease history recording, you must explicitly enable recording IP (lease) history for IP addresses by using dhcp enable ip-history.

Querying IP Lease History

Once you have leases, you can query for their history. You set up the local cluster containing the DHCP server as part of the regional cluster, and enable polling for the lease history data from the regional cluster (see the "Enabling Lease History Collection" section on page 6-12).

You can adjust the polling criteria for the cluster in the regional cluster web UI by using the attributes described in the "Polling Subnet Utilization and Lease History Data" section on page 6-9.

You must also set the selection criteria for querying the lease history data, as described in the following sections.

Regional Web UI

To query IP lease history:

Step 1 Click Address Space, then Lease History to open the Query Lease History page. Using this functionality requires DHCP rights locally and address space rights at the regional cluster.

Step 2 You can query lease history based on the following criteria:

Virtual private network (VPN) for the addresses to be polled for lease data—A VPN choice is available only if at least one was defined or pulled to the regional cluster (see the "Managing Virtual Private Networks" section on page 6-16). By default, the query is based on no specific VPN unless you choose it from the VPN drop-down list on the page. You can also query based on all VPNs.

Time range for the query—Choose from one of the following time ranges for the lease history data:

last 10 days

last 30 days

last 60 days

last 90 days

from/to (limited to 90 days)

If you choose the time range value, also choose the Start Date and End Date month, day, and year from the drop-down lists. The result depends on the value of the poll-lease-hist-interval attribute. Note that if the time range is set back one month, but you set the polling interval to greater than a month, no data will appear.

Criteria—Choose the criteria on which you want to base the query (per VPN and time range):

By IP Address—Enter the IP address in the adjacent field.

By MAC Address—Enter the MAC address in the adjacent field.

By IP Range—Enter the IP address range in the adjacent field, the start of range in the left field and end of range in the right field.

All—Choose all the leases by no particular criteria.

Current Lease by IP—Show the current lease for an IP address (entered in the adjacent field).

Note The regional CCM server references the DHCP server to obtain the most recent lease data for the IP address. Therefore, the regional address space must include the matching subnet from the local cluster, and the particular DHCP server must be running.

Step 3 Click Query Lease History.

Tip At the upper-left corner of the List Lease History Records page is either the Log icon () for the Netscape browser that you can click to view a text version of the report, or the Save icon () for the Internet Explorer browser so that you can save the report to a file (.txt by default). The List Lease History page also has a View Detail column with the View icon () if you set the CCM server with the ip-history-detail attribute enabled. Click this icon to open the View Lease History Detail page. This page shows the changeset for each history record.

iphist Utility

You can query the IP history database at the local cluster and direct the results to standard output or a file by using the iphist utility. You must run this utility on the same machine as the DHCP server, and you must have superuser/root privileges to read and modify the database file. The default location is:

Windows—\Program Files\Network Registrar\bin

Solaris and Linux—/opt/nwreg2/usrbin

From the command prompt, change to the location and run the utility using the syntax:

iphist [options] {ipaddr | all} [start-date | start [end-date | end]]

The IP address is a single address or the keyword all, the start date is in local time or the keyword start for the earliest date in the database, and the end date is in local time or the keyword end for the last date in the database. However, the output is in Greenwich Mean Time (GMT) by default, unless you use the -l option to specify local time.

The full list of command options appears in Table 22-3.

Table 22-3 iphist Command Options 


-N username

Administrator username. If omitted, you are prompted for the username.

-P password

Administrator password. If omitted, you are prompted for the password.

-C cluster[:port]

Destination server and optional SCP port.


Shows the lease attributes, visibility 5 and 3.


Displays the local and backup server failover leases.

-f "format"

Format of the output lines. The default format is: "address,client-mac-addr,binding-start-time,binding-end-time"


Displays output in local time rather than the default GMT.


Displays the local and main server failover leases.

-n vpn

Name or ID of an associated VPN, or the word all (for all VPNs) or global (for IP addresses without a VPN). If omitted, the query is based on the global VPN, or the current one set by the session set current-vpn command, unless you use the all value with the option.

-o file

Sends output to a file.


Displays the database version.

-V visibility

Sets the visibility level of the output attributes. The visibility is 3 by default.

-z debug-args

Sets the debug output levels.

Dates can use this syntax (quotation marks are required if space characters are included):

month/day/year@hour:min:sec (for example, 8/28/2007@10:01:15), with the time optional

month/day/year hour:min:sec (for example, "8/28/2007 10:01:15"), with the time optional

month day year hour:min:sec (for example, "Aug 28 2007 10:01:15"), with the time optional

Keywords start, end, or now (for the current time)

The date filtering is intended to limit the output to leases that were active during that time. This means that they can begin before the specified start date, as long as they do not end before the start date. They can also not begin after the specified end date. For example, invoking the command:

# ./iphist -N user -P password all Aug 28 2008 Dec 31 2008 

for the following leases:

Lease 1


Jan 01 2008


Jun 30 2008

Lease 2


Mar 10 2008


Sep 01 2008

Lease 3


Jun 01 2008


Sep 30 2008

Lease 4


Jan 01 2009


Mar 10 2009

would return just Lease 2 and Lease 3, because they both end after the specified start date of the query, even though they both begin before that date. The other two are out of range, because they either end before the specified start date or begin after the specified end date of the query.

The values on each line depend on the specific lease object that the DHCP server stores. You can specify the values to include using the iphist -f format command. The format argument is a list of lease attribute names, enclosed in quotation marks with the names separated by commas, that provides the template for the output lines. The default output is ipaddress,client-mac-addr,binding-start-time, binding-end-time.

For example:

# ./iphist -f "address,client-mac-addr,binding-start-time,binding-end-time" all 

The output is a sequence of lines terminated with a newline sequence appropriate to the operating system (\n on UNIX or \r\n on Windows). Each line contains data on a single lease record. The format of the lines is generally comma-separated values enclosed in quotation marks. To use a literal backslash (\) or quotation mark (") inside quotation marks, precede each with a single backslash (\). New lines in attributes are printed as \n.

Table 22-4 lists some of the common lease object attributes you can include in the output. Also, see the help for the lease command. To get a full list, use iphist -a.

Table 22-4 IP History Query Output Attributes 

Lease Attribute


IP address of the lease.


Start time of the lease binding.


End time of the lease binding.


Binary form of the client MAC address.


Latest DNS name of the client known by the DHCP server.


Domain where the client resides.


A number of client flags.


Hostname that the client requested.


Client ID requested by or synthesized for the client.


Date and time when the client most recently contacted the server.


MAC address that the client presented to the DHCP server.


Operating system of the leased client.


Date and time when the lease expires.


Either reserved or deactivated.


Minimal time that the client is expected to issue a lease renewal.


Contents of the circuit-id suboption (1).


Contents of the option from the most recent client interaction.


Contents of the remote-id suboption (2).


IP address in the server-id-override suboption.


IP address in the subnet-selection suboption.


Contents of the vpn-id suboption.


Date and time when the lease changed its state.


One of available, expired, leased, offered, or unavailable.


Vendor class ID requested by the client.


Identifier for the VPN, if any.

Trimming Lease History Data

If you enabled IP history trimming at the regional cluster, the IP history database is automatically trimmed so that you can reclaim disk space. Each history record has an expiration time. Trimming is necessary for the DHCP server itself, as well as for the CCM regional server that polls the DHCP server for history data.

The CCM server performs background trimming at the regional cluster, which trims off the lease history data older than a certain age at regular intervals. The trimming interval is set by default to 24 hours, and the age (how far back to go in time before trimming) to 24 weeks. The DHCP server at the local cluster performs daily automatic trimming (at 3:00 A.M. local time), and stores four weeks of data by default.

Regional Web UI

To trim lease history data, you must be a central configuration administrator:

Step 1 Click Servers to open the Manage Servers page.

Step 2 Click the Local CCM Server link to open the Edit CCM Server page.

Step 3 Under Lease History Settings, set the following attributes (you can use the s, m, h, d, w, m, or y suffix with values you enter):

trim-lease-hist-interval—How often to trim the old lease history data automatically, the default being daily. If set to 0, no automatic lease trimming occurs, which is not recommended due to the increasing disk space used. The bounded values are 0 to one year.

trim-lease-hist-age—Provided that the trim-lease-hist-interval is not set to 0, how far back in time to trim the old lease history data automatically, the default being 24 weeks. The bounded values are one day to one year.

Step 4 To force immediate trimming, at the bottom of the page find the Trim/Compact Inputs section (compacting is available only for subnet utilization data). Set the Trim/Compact age to a desired value. This age is how far in time to go back to trim the lease history data. There are no bounds to this value. However, if you set a very small value (such as 1m), it trims or compacts very recent data, which can be undesirable. In fact, if you set it to zero, you lose all of the collected data. Setting the value too high (such as 10y) may end up not trimming or compacting any data.

Step 5 If you are trimming immediately, click Trim All Lease History.

You can adjust the trimming that the DHCP server itself performs by setting the ip-history-max-age attribute. If ip-history is enabled, the DHCP server accumulates database records over time as lease bindings change. This parameter establishes a limit on the age of the history records kept in the database. The server periodically examines the lease history records, establishes an age threshold based on this parameter, and deletes any records that represent bindings that ended before the threshold. The preset value is four weeks.

Running Lease Utilization Reports

Lease utilization reports show the current utilization of address blocks, subnets, and scopes. For both user interfaces, see the "Generating Subnet Utilization History Reports" section on page 9-14.

Local Advanced Web UI

View the current utilization for address blocks, subnets, and scopes from pages in the Address Space function.

CLI Commands

To view lease utilization reports, use report.

Receiving Lease Notification

The CLI provides the feature of sending notifications if the number of available IP addresses equals or falls below a certain threshold. The lease-notification command specifies, through an available attribute, when the notification should occur if the number of available leases reaches or falls below a certain threshold. You can e-mail the report to a user. Although you can use the command interactively, its primary use is in an automated procedure such as a UNIX cron task or Windows Scheduled Task.

The following example sets up lease notification for examplescope for when its free addresses fall to 10%. It sends the report to recipients billy, joe, and jane, on a specific Windows mail host:

nrcmd> lease-notification available=10% scopes=examplescope recipients=billy,joe,jane 

The output consists of an explanatory header, a table containing a row for each scope in which the number of free addresses is equal to or less than the threshold, and possible warnings related to the scopes and clusters requested.

Network Registrar uses the default cluster and the .nrconfig file by default, unless you specify otherwise. For the command syntax, see the help for the lease-notification command.

See Also

Running Lease Notification Automatically in Solaris and Linux
Running Lease Notification Automatically in Windows
Specifying Configuration Files for Lease Notification

Running Lease Notification Automatically in Solaris and Linux

You can run lease-notification periodically by means of the cron(1) command by supplying crontab(1) with the command to run. This example, specified to crontab, runs lease-notification at 00:15 and 12:15 (15 minutes after midnight and noon), Monday through Friday (note that this encompasses a single command line):

15 0,12 * * 1-5 . .profile; /opt/nwreg2/usrbin/nrcmd lease-notification available=10\% 
config=/home/jsmith/.nrconfig addresses= 
recipients=jsmith, >/dev/null 2>&1 

You can perform crontab editing by running the UNIX crontab -e command. Set your EDITOR environment variable before running the command, unless you want to use ed(1). See the crontab(1) man page for additional details.

Note that you must supply the full path of the CLI command on the crontab command line. You can determine the full path in your environment with the UNIX which nrcmd command.

Also, when you run the lease-notification command by means of crontab, the nrcmd command ignores the user environment variables CNR_CLUSTER, CNR_NAME, and CNR_PASSWORD. Because other viewers can view the command being run, do not provide the password through the -P option on the command line, for security reasons.

Supply the cluster name, user, and password information for the cluster you want the nrcmd command to run from in a .profile or other file in the home directory of the user running crontab -e. For example:

export CNR_NAME 

The . .profile specification in the crontab entry explicitly reads the file. The first dot (.) is the shell command that reads the file and you must follow it with at least one space character. For notification on a different cluster (or clusters) than where nrcmd is running, specify this information:

Clusters to check in a config file (see the "Specifying Configuration Files for Lease Notification" section).

Fully specified path as in the sample crontab entry at the beginning of this section.

You can prevent others from examining or changing the contents of the .profile and the configuration file that you create by changing its permissions with the chmod go-rwx config-file UNIX command.

Running Lease Notification Automatically in Windows

Use the Scheduled Tasks service available in Windows Explorer under My Computer to schedule the lease-notification command. If you do not find a Scheduled Tasks folder under My Computer, you need to add this optional component from Microsoft Internet Explorer 4.0 or later, or use some third-party task scheduler. You can also use the at command to schedule the nrcmd lease-notification command. Put multiple entries in the at queue, one for each time of day at which you want to run the job.

Specifying Configuration Files for Lease Notification

If you omit a configuration file, lease-notification looks for a default .nrconfig file in your current directory, then in your home directory, and finally in the CNR_INSTALL_PATH/conf directory. Network Registrar uses the first file it encounters. Each line of the file must either begin with the character # (comment), a section header enclosed in square brackets, or a parameter/value pair or its continuation. Network Registrar strips leading space characters from each line and ignores blank lines.

Querying Leases

Network Registrar can work together with Cisco routers to provide enhanced provisioning capabilities. This function is described in the DHCP Leasequery specification (RFC 4388), with which Network Registrar conforms. Part of the implementation of the Cisco uBR access concentrator relay agent is to capture and glean information from DHCP lease requests and responses. It uses this information to:

Associate subscriber cable modem and client MAC addresses with server-assigned IP addresses.

Verify source IP addresses in upstream datagrams.

Encrypt unicast downstream traffic through the DOCSIS Baseline Privacy protocol.

Avoid broadcasting downstream Address Resolution Protocol (ARP) requests, which can burden the the uBR as well as the subscriber hosts, and which malicious clients can compromise.

The uBR device does not capture all DHCP state information through gleaning. The uBR device cannot glean from unicast messages (particularly renewals and releases) because capturing them requires special processing that would degrade its forwarding performance. Also, this data does not persist across uBR reboots or replacements. Therefore, the only reliable source of DHCP state information for the uBR device is the DHCP server itself.

For this reason the DHCP server supports the DHCPLEASEQUERY message, which is similar to a DHCPINFORM message. Access concentrators and relay agents can thereby obtain client location data directly from the DHCP server, for DHCPv4 and DHCPv6 addresses.

See Also

Leasequery Implementations
Pre-RFC Leasequery for DHCPv4
RFC 4388 Leasequery for DHCPv4
Leasequery for DHCPv6
Leasequery Statistics
Leasequery Example

Leasequery Implementations

Network Registrar provides three Leasequery implementations:

DHCPv4 Cisco-proprietary for pre-RFC 4388—See the "Pre-RFC Leasequery for DHCPv4" section.

DHCPv4 compliant with RFC 4388—See the "RFC 4388 Leasequery for DHCPv4" section.

DHCPv6—See the "Leasequery for DHCPv6" section.

The Cisco-proprietary and the more recent RFC-compliant implementations for DHCPv4 differ in only minor ways and will coexist. The DHCP server accepts Leasequery requests at the same port and returns the specified data for both implementations. The DHCPv6 implementation, new to Network Registrar 7.0, conforms with an IETF draft that is soon to be approved as a DHCPv6 Leasequery RFC.

The DHCP server can include lease reservation data in Leasequery responses for DHCPv4. Network Registrar returns a default lease time of one year (31536000 seconds) for reserved DHCPv4 leases in a response. If the IP address is actually leased, Network Registrar returns its remaining lease time.

Leasequery is preset to be enabled for all the implementations. To disable it, disable an Expert mode attribute, leasequery.

Pre-RFC Leasequery for DHCPv4

Leasequery messages usually contain request fields and options. To illustrate, suppose that after a relay agent reboot or replacement, the relay agent receives a request to forward a datagram downstream to the public broadband access network. Because the relay agent no longer has the downstream location data, it sends a LEASEQUERY message to the DHCP server that includes the gateway IP address (giaddr) of the relay agent and the MAC address or dhcp-client-identifier (option 61) of the target client. If the DHCP server finds the client, it returns the client IP address in the client address (ciaddr) field in the response to the leasequery. If the server cannot find the client address, it returns a DHCPNACK.

In the pre-RFC implementation for DHCPv4, the requestor can query by IP address, client ID option (61), or MAC address, and receives from the server a DHCPACK (with the returned data) or a DHCPNACK message, or the server drops the packet. If the request includes multiple query types, the DHCP server responds to the first one it can find. The giaddr value from the requestor is independent of the ciaddr searched and is simply the return IP address for any responses from the server. The three possible query types are:

IP address (ciaddr)—The request packet includes an IP address in the ciaddr field. The DHCP server returns data for the most recent client to use that address. A packet that includes a ciaddr value must be a request by IP address, despite the values in the MAC address fields (htype, hlen, and chaddr) or dhcp-client-identifier option. Querying by IP address is the most efficient method and the one most widely used, in that the other two methods can put more load on the DHCP server.

dhcp-client-identifier option (61)—The request packet includes a dhcp-client-identifier option value. The DHCP server returns a DHCPACK packet containing the IP address data for the most recently accessed client. If the request omits a MAC address, the server returns all IP addresses and their data for the requested client ID in the cisco-leased-ip (also called the associated-ip) option. If the request includes the MAC address, the server matches the dhcp-client-identifier and MAC address with the client data for the IP address and returns that data in the ciaddr field or cisco-leased-ip (also called the associated-ip) option.

MAC address—The request packet includes a MAC address in the hardware type (htype), address length (hlen), and client hardware address (chaddr) fields, and a blank ciaddr field. The server returns all the IP addresses and most recent lease data for the MAC address in the cisco-leased-ip (also called the associated-ip) option of the reply packet.

The DHCPLEASEQUERY message number in the dhcp-message-type option (53) for the pre-RFC implementation is 13. A server that does not support this type of message is likely to drop the packet. The DHCPACK message reply always contains the physical address of the lease owner in the htype, hlen, and chaddr fields. If the request contains the ciaddr, the data returned is always based on the ciaddr and never the client ID or MAC address.

The requestor can include the parameter-request-list option (55) to request specific options about an address. The reply often contains the dhcp-lease-time option (51) and the original content of the relay-agent-info option (82) that the client sent. If the server does not detect a valid lease for a client, it does not return option 51, and the requestor needs to determine if there is a valid lease.

A DHCPACK from the server can also contain the following Leasequery options:

cisco-leased-ip (161)—Data on all the IP addresses associated with the client; also known as (and later renamed) the associated-ip option.

cisco-client-requested-host-name (162)—Hostname that the client requested in the host-name option (12) or client-fqdn option (81). The requested hostname was dropped in the RFC 4388 implementation.

cisco-client-last-transaction-time (163)—Most recent time duration that a DHCP server contacted the client.

RFC 4388 Leasequery for DHCPv4

Leasequery became an official RFC 4388 for DHCPv4 in February 2006. Network Registrar provides the RFC 4388 implementation alongside the pre-RFC one (see the "Pre-RFC Leasequery for DHCPv4" section) and there are no conflicts between them. However, the RFC 4388 implementation includes a few notable changes:

The DHCPLEASEQUERY message type contained in the dhcp-message-type option (53) changed its message ID to 10 (the ID 13 was given to the DHCPLEASEACTIVE message), and the reply messages were changed from just DHCPACK and DHCPNACK to be more specific:

DHCPLEASEQUERY (10) for queries

DHCPLEASEUNASSIGNED (11) for replies of unassigned addresses

DHCPLEASEUNKNOWN (12) for replies of unknown addresses

DHCPLEASEACTIVE (13) for replies of active addresses

The reply option names and IDs changed, and the cisco-client-requested-host-name option was dropped so that there are only two reply options:

client-last-transaction-time (91)—Most recent time duration that a DHCP server contacted the client.

associated-ip (92)—Data on all the IP addresses associated with the client.

If querying by client ID or MAC address, the request can contain only the dhcp-client-identifier option (61) or MAC address; if the packet contains both, the server drops it.

Leasequery for DHCPv6

The Network Registrar Leasequery for DHCPv6 available in Release 7.0 (based on RFC 5007) is designed to:

Support the source-verify capability of DHCPv6-aware cable modem termination systems (CMTSs).

Provide data to additional processes that need real-time information about DHCP lease and client activity (such as Cisco Broadband Access Center).

Implement a pending RFC for DHCPv6 Leasequery.

The message types for DHCPv6 Leasequery are:



A query can be by:



A DHCPv6 LEASEQUERY_REPLY message can contain one or more of the following options:

lq-query (44)—Query being performed. The option, used in a request only, includes the query type, link-address (or 0::0), and options to provide data needed for the query.

client-data (45)—Encapsulates the data for a single client on a single link. The client data can include any number of these or other requested options.

clt-time (46)—Client last transaction time encapsulated in a client-data option (45); identifies how long ago (in seconds) the server last communicated with the client.

lq-relay-data (47)—Relay agent data used when the client last communicated with the server. Fields are the peer-address and the relay-message. This option can include further options.

lq-client-link (48)—Links on which the client has any bindings. Used in reply to a client query when the link-address is omitted and the client is found to be on more than one link.

DHCPv6 uses the Option Reply option (oro) to request a list of options in the Leasequery reply.

Leasequery Statistics

As of Network Registrar 7.0, lease queries provide statistics attributes, in the web UI, on the DHCP Server Statistics page (see the "Displaying Statistics" section on page 7-11), and in the CLI by using dhcp getStats. The Leasequery statistics are:

lease-queries—Number of RFC 4388 message ID 10 (or pre-RFC message ID 13) DHCPv4 Leasequery packets received in the given time interval.

lease-queries-active—Number of RFC 4388 DHCPLEASEACTIVE packets.

lease-queries-unassigned—Number of RFC 4388 DHCPLEASEUNASSIGNED packets.

lease-queries-unknown—Number of RFC 4388 DHCPLEASEUNKNOWN packets.

leasequeries—Number of DHCPv6 Leasequery packets received.

lease-query-replies—Number of responses to DHCPv6 Leasequery packets that might or might not be successful.

Leasequery Example

Example 22-2 shows a packet trace of a DHCPv6 query by client ID without a link-address, but with addresses on more than one link. The first part of the output shows the query message and the second part shows the reply data. The lq-query option identifies the type of query. Note the list of requested options via the Option Request option (oro) in the request, and the two addresses returned in the lq-client-links option in the reply.

Example 22-2 Packet Trace of Sample Lease Query

>> +- Start of RELAY-FORW message
> > |  msg-type = RELAY-FORW     xid = 0x0       hop-count = 0
> > |  link-address = 1:2:5::
> > |  peer-address = fe80::d02:3ff:fe04:50d
> > |  options: 
> > |    relay-message = 
> > |      +- Start of LEASEQUERY message
> > |      |  msg-type = LEASEQUERY      xid = 0x10
> > |      |  options: 
> > |      |    lq-query = 2 query-by-clientid|::|options: 
> > |      |      client-id = duid-ll|1|0f:02:03:04:05:0d
> > |      |      oro = client-id,server-id,ia-na,ia-ta,iaaddr,domain-list,lq-relay-data
> > |      |    client-id = duid-ll|1|01:03:05:07:09:11
> > |      +-  End of LEASEQUERY message
> > |    remote-id = 4491|01:02:03
> > |    relay-agent-subscriber-id = 03:04:05
> > |    interface-id = 05:06:07
> > +-  End of RELAY-FORW message
> < +- Start of RELAY-REPL message
> < |  msg-type = RELAY-REPL     xid = 0x0       hop-count = 0
> < |  link-address = 1:2:5::
> < |  peer-address = fe80::d02:3ff:fe04:50d < |  options:
> < |    interface-id = 05:06:07
> < |    relay-message = 
> < |      +- Start of LEASEQUERY_REPLY message
> < |      |  msg-type = LEASEQUERY_REPLY        xid = 0x10
> < |      |  options: 
> < |      |    server-id = duid-llt|1|5/4/07 12:42 PM|00:0a:e4:3b:42:4c
> < |      |    lq-client-links = 1:2:5:0:955f:926e:b9d3:ca8e,1:2:7:0:9494:8f2a:a9c2:fad1
> < |      +-  End of LEASEQUERY_REPLY message
> < +-  End of RELAY-REPL message