Cisco CNS Network Registrar User's Guide, 6.1
Managing Leases
Downloads: This chapterpdf (PDF - 369.0 KB) The complete bookPDF (PDF - 6.99 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

Import Prerequisites

Import and Export Commands

Lease Times in Import Files

Pinging Hosts Before Offering Address

De-activating Leases

Excluding Addresses from Ranges

Reserving Leases

Reserving Addresses That Are Currently Leased

Unreserving Leases

Forcing Lease Availability

Inhibiting Lease Renewals

Handling Leases Marked as Unavailable

Setting Timeouts for Unavailable Leases, Including Upgrades

Running Address and Lease Reports

Running Address Usage Reports

Running Lease Histories

Enabling Lease History Recording on the Local Cluster

Collecting Lease History Using the Web UI

Querying Lease History Using the iphist Utility

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

Lease Query Requests

Lease Query Responses

Lease Query and Reservations

Managing Leases

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

This chapter describes how to manage leases in a network.

Configuring Leases in Scopes

After setting the address ranges for a scope, you can monitor and adjust the leases that result from DHCP assignments. While there is no limit to the number of leases that you can configure per scope, if you have one with several thousand leases, it can take Network Registrar awhile to sort them.

Viewing Leases

You can view the current state of leases for the scope address ranges.

In the local cluster Web UI, create a scope, as described in the "Defining and Configuring Scopes" section. You can view the leases in two ways:

Click the View icon () in the Leases column for the scope on the List/Add DHCP Scopes page.

Click the name of the scope on the List/Add DHCP Scopes page to open the Edit DHCP Scope page. Click List Leases in the Leases area of the page.

Both of these actions opens the List DHCP Leases for Scope page, where you can click each lease to manage it.

In the CLI, use the lease list command to list all the leases in the cluster, or the lease name show command to show the properties of a particular lease. Use the scope name listLeases command to show all the leases for a scope. The output is nearly identical for all the commands. Note that you cannot list leases in a particular virtual private network (VPN); all the leases in all the VPNs are listed.

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 leased out. The lease addr list -macaddr command lists the lease data only if the IP address for that MAC address was actually leased out (and not reserved). You can also list leases by LAN segment and subnet.

Lease States

A lease can be in one of these states:


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

Leased—Held by a client.

Offered—Offered to the client.

Expired—Available when the lease grace period expires.

De-activated—Not renewable or leasable after the lease expires. See the "De-activating Leases" section.

Pending available—Failover-related. See "Configuring DHCP Failover."

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 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 addresses or the leases to expire at the DHCP server. Consequently, the addresses may return to the free-address pool for re-use. If many changes occur on your network, Cisco recommends a lease time between four and ten days. Assigning such a lease time more quickly re-assigns addresses as clients leave the subnet.

Another important factor is the ratio of available addresses to connected computers. For example, the demand for re-using 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, as clients will be renewing their leases more frequently. The DHCP failover functionality can help guarantee such levels of availability.

Create policies that have permanent leases carefully. There is a certain amount of turnover among clients 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 address. It would be better to create a long lease, such as six months, which ensures 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 your 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 for details). There should be about three times as many response buffers as request buffers.

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 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 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, so enable this option using the policy name enable permanent-leases command, as necessary.

Import and Export Commands

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


There are no spaces between the vertical line (|) delimiter and the field values. You must include at least the first four required fields. If including more, so 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. Host name (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-day-time-year format (such as Mon Apr 10 16:35:48 2000).

When you use the export leases command, you can choose between writing the state of all current and expired leases, or just the current leases, to the output file. Example 12-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 12-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

The client is given the lesser of these lease times:

In the import file.

What the client would receive if it were to acquire a lease using the existing configuration of the DHCP server.

For example, it is 2:00 p.m. and 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.

Caution 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 host name, then the server uses the host name when updating DNS, unless the host name was overridden by a host name specification in a client or client-class entry.

The only way to indicate to the DHCP server that the client's host name should be in a zone other than the default associated with the scope is to specify that zone in a client or client-class entry.

Pinging Hosts Before Offering Address

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 address before assigning it. This 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.

Tip The ping timeout period is important. Because pinging helps to ensure that no client is using a particular 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's ability to detect another client using the address.

In the local cluster Web UI:

Step 1 On the Edit DHCP Scope page, under the Miscellaneous attributes, enable the ping-clients attribute. It is disabled by default.

Step 2 Under the Miscellaneous attributes, set the ping-timeout attribute. It is 300 seconds by default.

Step 3 Click Modify Scope.

In the CLI, use the scope name enable ping-clients command. The default time interval to wait before assuming that no client will answer is 300 milliseconds. To change this, use the scope name set ping-timeout command. See the preceding Tip.

The server will make unavailable any address for which it receives a successful ECHO reply. You can control this by using the dhcp enable ignore-icmp-errors command, which is the default. If disabled, the DHCP server also treats ICMP DEST_UNREACHABLE and TTL_EXPIRED error messages that it receives after sending ICMP ECHO requests as grounds for making an address unavailable.

De-activating Leases

The reason you would de-activate a lease is to move a client off it. If the lease is available, de-activating it prevents Network Registrar from giving it to a client. If the lease is active (held by a client), de-activating it prevents the client from renewing it and it being given to another client. You can only de-activate a lease if the server is running. Network Registrar de-activates the lease immediately; you do not need to reload the DHCP server.

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

In the local cluster Web UI:

Step 1 Click DHCP on the Primary Navigation bar.

Step 2 Click Scopes on the Secondary Navigation bar.

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

Step 4 Click the name of the lease on the List DHCP Leases for Scope page.

Step 5 On the Manage DHCP Lease page, click Deactivate. On the List DHCP Leases for Scope page, the lease will now show deactivated under the Flags column.

In the CLI, use the lease ipaddr deactivate command. To re-activate a de-activated lease, use the lease ipaddr activate command.

Excluding Addresses from Ranges

Addresses ranges, by definition, must be contiguous, without any holes in the range. Therefore, to exclude an address from an existing range, you must divide the range into two smaller ranges. The new ranges then consist of the addresses between the original starting and ending range addresses and the address which you want to exclude.

However, if the address being excluded currently has an active lease, you should first follow the steps in the "De-activating Leases" section. You will get a warning message otherwise.

Caution Deleting an active lease can cause a duplicate address on the network if the deleted address is re-assigned. Information about that lease will no longer exist after you reload the server.

In the local cluster Web UI:

Step 1 On the Edit DHCP Scope page, in the Ranges area, click the Delete icon () next to the address range you want to remove.

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

Step 3 Click Add Range.

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

Step 5 Click Add Range.

Step 6 Click Modify Scope.

In the CLI, simply remove the range of just that address. The resulting ranges are then split appropriately. De-activate the lease first. Use the scope name listRanges, lease ipaddr deactivate, and scope name removeRange commands, then reload the server. 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-namespace=red 
nrcmd> scope examplescope1 listRanges 
nrcmd> lease red/ deactivate 
nrcmd> scope examplescope1 removeRange 
nrcmd> scope examplescope1 listRanges 
nrcmd> dhcp reload 

Reserving Leases

To ensure that a client always gets the same lease, you can create a lease reservation. You must reserve leases for DHCP clients whose addresses must remain constant.

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

A lease reservation consists of an IP and MAC address pairing. You can choose any valid address on the network. It does not necessarily have to be in one of the scope's ranges. In fact, you can use the addresses in the scope's range for dynamic leases and the others not in the range for reserved leases.

Note Even though a reserved address may not be in the scope's range, the policy associated with the scope still applies to the address.

In the local cluster Web UI:

Step 1 On the Edit DHCP Scope page, in the Reservations area, add the IP and MAC addresses of the reserved address. Ensure that the reservation is part of an existing range in the Ranges area of the page. The MAC address is required.

Step 2 Click Add Reservation.

Step 3 Click Modify Scope.

In the CLI:

To list lease reservations for a scope, use the scope name listReservations command.

To reserve a lease (including the IP and MAC addresses), use the scope name addReservation command. Save the reservation, then send the reservation using the lease ipaddr send-reservation command. This does not require a server reload. Instead of saving and sending, you can also just reload the server.

Reserving Addresses That Are Currently Leased

It is possible to delete a reservation for one client and re-use the reservation for a second client, even though the first client still has the lease. The following example describes how Network Registrar behaves in this situation. Assume that you have this reservation and lease:

nrcmd> scope examplescope1 addReservation 1,6,00:d0:ba:d3:bd:3c 
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's lease expiration time, you terminate the reservation:

nrcmd> lease deactivate 
nrcmd> scope examplescope1 removeReservation 
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> scope examplescope1 addReservation 1,6,00:d0:ba:d3:bd:3d 
nrcmd> save 
nrcmd> lease send-reservation 
nrcmd> lease activate 
nrcmd> save 

Now you have 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 prior to the original client (1,6,00:d0:ba:d3:bd:3b) doing a DHCPDISCOVER, it does not get Instead, it receives a random IP address from the dynamic pool.

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

After this, the server 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 does a DHCPDISCOVER, it gets

You could also force the availability of a lease, using the lease ipaddr force-available command. However, that 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 it if some other client already has it. Instead, it gets some other 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.

In the local cluster Web UI, on the Edit DHCP Scope page, in the Reservations area, click the Delete icon () next to the reservation you want to remove. This removes the reservation immediately, with no confirmation. Then, click Modify Scope.

In the CLI, use the scope name removeReservation command, indicating the client's MAC or IP address (note that if you omit it, this removes all lease reservations). Removing the reservation requires a server reload. You can also combine removing a reservation with deleting it by using the lease ipaddr delete-reservation command. This does not require a reload. However, when using this command:

Ensure that the reservation was already removed from the nrcmd internal database.

If you use failover on the scope in which the reservation resides:

a. Use the lease ipaddr delete-reservation command on the backup server.

b. Use the lease ipaddr delete-reservation command on the main server.

c. Use the scope name removeReservation command on both systems.

Tip Save the results of this operation to ensure that it is preserved across server reload, because issuing the lease ipaddr delete-reservation command alone affects only the server's internal memory.

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.

In the local cluster Web UI:

Step 1 Click DHCP on the Primary Navigation bar.

Step 2 Click Scopes on the Secondary Navigation bar.

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

Step 4 Click the name of the lease on the List DHCP Leases for Scope page.

Step 5 On the Manage DHCP Lease page, click Force Available.

Step 6 On the List DHCP Leases for Scope page, the lease will now show an empty value in the Flags column.

In the CLI, use the lease ipaddr force-available command. Use the scope name clearUnavailable command 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 and it is a feature that is usually desirable. However, for some customers, such as ISPs, clients with long-lived lease associations may be undesirable, as these client 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 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 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 lease reservation, it can continue to use the reserved address, whether or not renewal inhibition is configured.

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

In the local cluster Web UI, create a policy, on the Edit DHCP Policy page, enable the inhibit-all-renews or inhibit-renews-at-reboot attribute. Both are disabled by default. Then, click Modify Policy.

In the CLI, 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 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.

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 and are:

The DHCP server is configured for a ping before an offer, and the ICMP echo message is returned successfully—This indicates that there is a currently active client using that address, causing the DHCP server to marks 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 Address" section.

The server receives a DHCPDECLINE message from a client to which it leased what it considered to be a good address—The client does an address resolution (ARP) request for the 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 address does not appear in the server-id option, but the IP 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 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 in the Web UI or CLI.

Inconsistent lease data—This is extremely rare and occurs only during server startup. Inconsistent lease data happens while configuring a lease, when the server reads the lease data from disk during a refresh of the internal cache. The lease state shows as leased, but there is incomplete data to construct a client for that lease. For example, it might not yet have a client-id option value. The server considers the data to be inconsistent and marks the address unavailable. The lease address force-available command should clear up this problem.

Setting Timeouts for Unavailable Leases, Including Upgrades

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 not having this timeout feature, a special upgrade timeout attribute is included at the server level, upgrade-unavailable-timeout, which also defaults to one day.

The upgrade-unavailable-timeout value is the timeout given to leases set to unavailable before the Network Registrar 6.0 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 of the unavailable leases that were present at the last reload will time out. If the server is reloaded in less than a day, the entire process restarts with the next reload. Note that this process only occurs for leases that were set unavailable before the upgrade to Network Registrar 6.0. Leases that become unavailable after the upgrade receive the unavailable-timeout value from the policy, as previously described.

If a Network Registrar 6.0 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 Network Registrar 6.0 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 that are addressed in the following sections:

Address Usage—Displays the IP addresses used by a DHCP server.

Lease History—Provides a history of the leases in a network.

Lease Utilization—Displays statistics about leases in scopes.

Lease Notification—Receive notification if available addresses in a scope fall below a certain level.

Running Address Usage Reports

In the local cluster Web UI, on the Edit DHCP Scope page, in the Leases area, click List Leases to open the List DHCP Leases for Scope page (see Figure 12-1).

Figure 12-1 List DHCP Leases for Scope Page

To manage a specific lease, click its name on the page. This opens the Manage DHCP Lease page (see Figure 12-2).

Figure 12-2 Manage DHCP Lease Page

On this page, you can force a lease to be available, and you can de-activate a lease:

To force a lease to become available, click Force Available.

To de-activate an active lease, click Deactivate.

To cancel the page, click Cancel.

Each action returns to the List DHCP Leases page.

In the CLI, use the report command to display the IP address usage for specified servers. See the CLI Reference Guide for additional options you can set.

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

Running Lease Histories

You can extract 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.

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

Note When the state of an existing lease changes, such as when it is configured as a reserved address or it is de-activated, the change does not appear as a lease history change at the regional cluster. A lease history change appears only when the lease expires or is assigned to another client.

Enabling Lease History Recording on the Local Cluster

You must explicitly enable lease history recording for the local cluster DHCP server. You can do this in the local Web UI and the CLI.

In the local cluster Web UI:

Step 1 On the Primary Navigation bar, click DHCP, then click DHCP Server on the Secondary Navigation bar.

Step 2 On the Manage DHCP Server page, click the Local DHCP Server link.

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

IP History (lease-history)—Be sure this is set to enabled.

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 Reload the DHCP server.

In the CLI, you must explicitly enable recording IP (lease) history for addresses. Do so using the dhcp enable ip-history command. If enabling history recording, it is best to leave it enabled.

The DHCP server logs IP history recording errors in the usual DHCP log files. It also stops recording the history if the available free disk space drops below a certain point.

Collecting Lease History Using the Web UI

You collect lease history by first having leases by setting up the scopes, address ranges, and collection criteria on the local cluster. You then set up the local cluster containing the DHCP server as part of the regional cluster, and enable polling the lease history data from the regional cluster. These steps are described in the "Enabling Lease History Collection" section.

You can set polling criteria globally on the CCM server and can overwrite it for each cluster or failover pair.

The two DHCP server attributes to set to enable polling this data are:

ip-history—Explicitly set this to enabled.

ip-history-max-age—Limit on the age of the history records (set to 4w by default).

Set the polling criteria for the cluster in the regional cluster Web UI using these attributes:

poll-lease-hist-interval—Polling interval; be sure that this is set to a reasonable time interval greater than 0.

poll-lease-hist-retry—Retry count in case of a polling failure; by default, this is set to one retry.

poll-lease-hist-offset—Fixed time when polling occurs. For example, setting the offset to 1h (for 1:00 P.M.) and the interval to 2h means that polling occurs every two hours, including 1:00 P.M. each day.

On the regional cluster, you must also set the selection criteria for querying the lease history data.

Step 1 On the Primary Navigation bar, click Address Space.

Step 2 On the Secondary Navigation bar, click Lease History. This opens the Query Lease History page (see Figure 12-3). Using this functionality requires DHCP rights locally and address space rights on the regional cluster.

Figure 12-3 Query Lease History Page

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

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

Time range for the query—Select 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 select this value, also select 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. 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—Select 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—Select all the leases by no particular criteria.

Step 4 After entering or selecting these values, click Query Lease History to open the List Lease History Records page.

Tip At the top 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).

Querying Lease History Using the iphist Utility

You can query the IP history database and direct the results to standard output or to 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 of the utility is:

On Windows—\Program Files\Network Registrar\bin

On Solaris and Linux—/opt/nwreg2/usrbin

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

iphist [options] {ipaddress | 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 universal time (GMT) by default, unless you use the -l option to specify local time. For example, on Solaris:

# cd /opt/nwreg2/usrbin 
# ./iphist -N user -P password 
-f "address,client-mac-addr,binding-start-time,binding-end-time" 
-o output.txt 
-l all 

These and the other command options are described in Table 12-1.

Table 12-1 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.


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 addresses without a VPN). If omitted, the query is based on the global VPN, or the current one set by the session set current-namespace 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 (quotes are required if space characters are included):

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

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

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

The 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 2003 Dec 31 2003 

for the following leases:

Lease 1 Begin Jan 01 2003 End Jun 30 2003
Lease 2 Begin Mar 10 2003 End Sep 01 2003
Lease 3 Begin Jun 01 2003 End Sep 30 2003
Lease 4 Begin Jan 01 2004 End Mar 10 2004

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 quote-enclosed and comma-separated list of lease attribute names 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 quotes. Within quotes, literal backslash (\) or quote (") characters are escaped with a single backslash (\). New lines in attributes are printed as \n.

Table 12-2 lists the lease object attributes you can include in the output. Also, see the lease command in the Network Registrar CLI Reference Guide for details.

Table 12-2 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's MAC address.


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


Domain where the client resides.


A number of client flags.


Host name 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 de-activated.


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


Identifier for the namespace, if any.


Contents of the circuit-id suboption (1).


Contents of the option from the most recent client interaction.


Contents of the remote-id suboption (2).


Address in the server-id-override suboption.


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.

Trimming Lease History Data

If you enabled IP history trimming, you should regularly trim IP history database so that you can reclaim disk space. Each history record has an expiration time.

The CCM server performs background trimming on the regional cluster, which trims off the lease history data older than a certain age at regular intervals. The trimming intervals are set by default to one week, and the ages (how far back to go in time before trimming) to 24 weeks.

In the regional cluster Web UI, you must be a central configuration administrator to adjust the lease history trimming values:

Step 1 Click Administration on the Primary Navigation, then Servers on the Secondary Navigation bar. This opens the Manage Servers page.

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

Step 3 Under the Lease History Settings, set the following attributes:

trim-lease-hist-interval—How often to trim the old lease history data automatically, the default being not to trim the data. You must set this to a nonzero value to trigger any background trimming. The bounded values are 0 to one year, and you can use units in seconds (s), minutes (m), hours (h), days (d), weeks (w), months (m), and years (y).

trim-lease-hist-age—How far back in time to trim the old lease history data automatically, the default being 24 weeks. (However, the trim-lease-hist-interval value must be set to other than 0 for trimming to be in effect at all.) The bounded values are 24 hours to one year, and you can use units in seconds (s), minutes (m), hours (h), days (d), weeks (w), months (m), and years (y).

Step 4 You can also 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 among the controls at the bottom of the page.

You can also control trimming that the DHCP server itself performs by setting these trimming attributes for the server:

ip-history (Lease History in the Web UI)—This is disabled by default.

ip-history-max-age—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 default value is four weeks.

You can get a true confirmation of the history data trimmed by running the iphist utility again and verifying the results, as described in the "Querying Lease History Using the iphist Utility" section.

Running Lease Utilization Reports

Using the CLI, you can generate a static and dynamic address usage summary on one or more clusters. In the Web UI, see the "Viewing Leases" section.

In the CLI, the report command displays a row of information for each subnet specified by a scope or deduced from DNS static address assignments outside of scopes. It displays subtotal rows when more than one scope shares a common subnet, and when addresses share a common subnet, as specified by their address and mask. The report command assumes that there is no overlap between static addresses and scope ranges.

For each scope or subnet, the report command displays this information:

Network number, in hexadecimal, based on the session's current VPN

Number of bits in the subnet mask

Network number in canonical dotted-octet format

For each scope-specified subnet, the report command also displays the values described in Table 12-3.

Table 12-3 Report Values Displayed for Scope-Specific Subnets 

Report Value

Cluster name

Name of the cluster.

Scope role

Indicates if using safe failover on a main or backup server.

Scope name

Name of the scope.


Total number of addresses in the scope ranges. The addresses equal the free plus dynamically leased plus reserved plus unavailable plus de-activated plus other available.


Addresses in a range and in the available state, and not flagged reserved or de-activated.

% free

Free addresses as a percentage of all addresses in scope ranges.


Addresses flagged as reserved in a range, unless unavailable.


Leased addresses in a range and in the leased, offered expired, or released state, even if flagged reserved or de-activated.

Dynamically leased

Dynamically leased addresses in a range and in the leased, offered, or expired state, unless flagged reserved or de-activated.


Unavailable addresses in a range and marked as unavailable by the server, regardless of flags.


De-activated addresses in a range and flagged de-activated, unless unavailable

Other available

Leases set aside for the safe failover partner to lease when communication is interrupted.

Other reservations

Addresses marked reserved which are not in a scope range.

Addresses have both a current state and a pending state after their lease expires. The categories leased and unavailable represent current states. The categories dynamically leased, reserved, and de-activated may represent current or pending states. The category free represents the current state available minus addresses that are flagged as reserved or de-activated. Note that the leased category overlaps other categories and is not incorporated in the scope total. Table 12-4 summarizes the address states.

Table 12-4 Categories of Address States 



current or pending

dynamically leased

current or pending


current state of available minus addresses flagged reserved or deactivated


current (The leased category overlaps other categories and is not incorporated in the scope total.)


current or pending



For each subtotal row, the report command provides summaries of any scope values in the subnet, and additionally, displays these values:

Total—All addresses in the subnet.

Static—Addresses statically assigned.

Unallocated—Addresses unallocated to DHCP scope ranges, otherwise reserved or statically assigned, and therefore available for static assignment or allocation to a scope range.

Grand total—At the end of the report summarizes all the data in the subnets.

At the end of the report, a grand total summarizes all the data in the subnets.

The comma-delimited text format is well suited for import into a database, spreadsheet or a similar tool. You can easily create customized reports. Specify this format using the column-separator keyword with the report command.

The rows and columns in Table 12-5 represent potential states and flags that an address within a DHCP scope can possess. The cells within the table indicate the category into which Network Registrar places addresses with a given state and flag. When setting multiple flags, deactivated takes priority over reserved, and reserved takes priority over any remaining flags for reporting purposes.

Table 12-5 Potential States and Flags for IP Addresses 

Reserved and Deactivated







leased, leased

leased, leased


deactivated, leased


leased, leased

leased, leased


deactivated, leased


leased, leased

leased, leased


deactivated, leased


other available





leased, leased

leased, leased


deactivated, leased






Receiving Lease Notification

You can survey all scopes on the Network Registrar clusters and produce a report of all the leases. This is available in the Web UI as a lease view, and in the regional cluster as a lease history report. In the CLI, you have the additional feature of sending notifications if the number of available addresses equals or falls below a certain threshold.

In the local cluster Web UI:

Step 1 On the Primary Navigation bar, click DHCP.

Step 2 On the Secondary Navigation bar, click Scopes.

Step 3 Select the scope on the List/Add DHCP Scopes page for editing.

Step 4 On the Edit DHCP Scope page, click List Leases in the Leases section of the page. This opens the List DHCP Leases for Scope page, where you can see the list of leases.

In the regional cluster, you can also generate a lease history report, as described in the "Running Lease Histories" section.

In the CLI, 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 details on the command syntax, see the lease-notification command in the Network Registrar CLI Reference.

Running Lease Notification Automatically in Solaris and Linux

You can run the lease-notification command periodically by means of the cron(1) command by supplying crontab(1) with the command to run. This example, specified to crontab, runs the lease-notification command 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 CLI command's full path on the crontab command line. You can determine the full path in your environment with the UNIX which nrcmd command.

Also, note that 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.

You should 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 white space. For notification on a different cluster, or clusters, than the one on which nrcmd is running, specify this information:

Clusters to check in a config file, as described in the "Specifying Configuration Files for Lease Notification" section.

Fully specified path as in 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, the lease-notification command 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 white space from each line and ignores blank lines.

Querying Leases

Part of the implementation of the Cisco uBR access concentrator's relay agent is to capture and glean information from DHCP lease requests and responses. It does this so that it can:

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 can be compromised by malicious clients.

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 the uBR device's 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. The DHCPLEASEQUERY message's number in the dhcp-message-type option (53) is 13. The uBR device's relay agent sends a DHCPLEASEQUERY request to the DHCP server. The request always yields either a DHCPACK or DHCPNAK response from the server. A DHCP server that does not support this type of message is likely to drop the DHCPLEASEQUERY packet.

Lease Query Requests

In a DHCPLEASEQUERY request, the gateway IP address (giaddr) field must have the IP address of the requesting relay agent. The giaddr field is independent of the client address (ciaddr) searched and is simply the return address for any responses from the server. The relay agent can send one of these types of DHCPLEASEQUERY requests:

By IP address—The request packet includes an IP address in the client address (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 the client-id option. This is generally the most efficient and should be the most widely used query method.

By MAC address—The request packet includes a MAC address in the hardware type (htype), address length (hlen), and client hardware address (chaddr) fields, and no value in the client address (ciaddr) field. The DHCP server returns all the IP addresses and most recent lease data for this MAC address in the associated-ip option of the DHCPLEASEQUERY packet. See the "Lease Query Responses" section.

By 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 does not also include a MAC address, the server returns all addresses and their data for the requested dhcp-client-identifier. 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 client address (ciaddr) field or associated-ip option (161).

Lease Query Responses

The parameter-request-list option (55) in a DHCPACK response from the server should contain data pertinent to the requestor, such as dhcp-lease-time (51) and relay-agent-info (82) option values:

The dhcp-lease-time (51) value is for the remaining time until the lease expires.

The relay-agent-info (82) value is from the most recent DHCPDISCOVER or DHCPREQUEST message from the client to the server.

Network Registrar provides these options for responding to DHCPLEASEQUERY messages:

cisco-client-last-transaction (163)—Contains the most recent time a server accessed the client.

cisco-client-requested-host-name (162)—Contains the host name that the client requested in the host-name option (12) or client-fqdn option (81).

cisco-associated-ip (161)—Contains data on all the IP addresses associated with the client.

Lease Query and Reservations

The DHCP server includes lease reservation data in DHCPLEASEQUERY responses. In previous releases of Network Registrar, the DHCPLEASEQUERY responses were possible only for leased or previously leased clients for which the MAC address was stored. Cisco uBR relay agents, for example, discard DHCPLEASEQUERY datagrams not having a MAC address and lease time (dhcp-lease-time option).

Network Registrar returns a default lease time of one year (31536000 seconds) for reserved leases in a DHCPLEASEQUERY response. If the address is actually leased, Network Registrar returns its remaining lease time.