Cisco CNS Network Registrar User's Guide, 6.0
Configuring DHCP Scopes and Leases
Downloads: This chapterpdf (PDF - 546.0KB) The complete bookPDF (PDF - 7.06MB) | Feedback

Configuring DHCP Scopes and Leases

Table Of Contents

Configuring DHCP Scopes and Leases

Defining and Configuring Scopes

Scopes in Network Registrar

Creating Scopes

Using Multiple Scopes

Editing a Scope

Configuring an Embedded Policy for the Scope

Making a Scope a Secondary

Enabling and Disabling BOOTP for a Scope

Disabling DHCP for a Scope

De-activating a Scope

Setting a Scope to Renew-Only

Removing a Scope

Removing a Scope if Not Re-using the Addresses

Removing a Scope if Re-using the Addresses

Configuring Leases in the Scope

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 a Host Before Offering an Address

De-activating a Lease

Excluding an Address from a Range

Reserving a Lease

Reserving an Address That Is Currently Leased

Unreserving a Lease

Forcing Lease Availability

Inhibiting Lease Renewals

Handling Leases Marked as Unavailable

Setting Timeouts for Unavailable Leases, Including Upgrades

Running Address and Lease Reports

Running an Address Usage Report

Running a Lease Utilization Report

Receiving Lease Notification

Running Lease Notification Automatically in UNIX

Running Lease Notification Automatically in Windows

Specifying the Configuration File for Lease Notification

Recording IP Lease History

Enabling IP History Recording

Running the IP History Query Utility

Formatting the IP History Query Output

Trimming IP History Data

Querying Leases

Lease Query Requests

Lease Query Responses

Lease Query and Reservations


Configuring DHCP Scopes and Leases


This chapter describes how to configure primary and secondary scopes for a DHCP server and how (and when) to edit and remove them, if necessary. It also describes how to activate and de-activate leases in the scope, and make lease reservations. Finally, it describes how to run reports on addresses and leases, record the IP history of leases, and support lease queries.

Configuring scopes and leases assumes that you configured a DHCP server to manage them. See "Configuring DHCP Servers." Table 8-1 lists the topics in this chapter and their associated sections. The Network Registrar Web UI Guide explains how to accomplish these tasks using the Web-based interface.

Table 8-1 DHCP Server Scope Configuration Topics 

If you want to...
See...

Learn about the concepts behind DHCP and Network Registrar's implementation

"Dynamic Host Configuration Protocol" section

Define and configure scopes for a server

"Defining and Configuring Scopes" section

Configure leases for a scope

"Configuring Leases in the Scope" section

Run reports on addresses and leases, and receive lease notification

"Running Address and Lease Reports" section

Record a history of leases

"Recording IP Lease History" section

Support querying lease information

"Querying Leases" section


Defining and Configuring Scopes

This section describes how to define and configure scopes for the DHCP server.

Scopes in Network Registrar

A scope consists of one or more ranges of dynamic addresses in a subnet that a DHCP server manages. You must define one or more scopes before the DHCP server can provide leases to clients.


Tip Including namespace names in scopes is a feature you can use with the CLI only.


Creating Scopes

Create one or more scopes for each subnet. Each scope needs to have a:

Name

Policy that defines the lease times, grace period, and options

Network address and subnet mask

Range or ranges of addresses

Using the Web UI


Step 1 On the Primary Navigation bar, click the DHCP tab. See the Network Registrar Web UI Guide for details.

Step 2 On the Secondary Navigation bar, click the Scopes tab to open the List/Add DHCP Scopes page.

Step 3 Enter a scope name, or leave it blank to use the one defined in the scope name expression of a scope template, if any (see the Network Registrar Web UI Guide). In the latter case, select the scope template. You must always enter a subnet/mask for the scope.

Step 4 Click Add Scope. This opens the Add Scope page.

Step 5 Select a policy for the scope from the drop-down list. The policy defaults to the default policy.

Step 6 Add ranges for addresses in the scope. The ranges cannot overlap and they must belong to the defined subnet. If you enter just the host number, the range is relative to the netmask. Click Add Range to add each range.

Step 7 Add any reservations to the scope, which cannot belong to one of the assigned ranges. Add the IP address of the reserved address. Also include its MAC address, in the form 00:d0:ba:d3:bd:3b or 1,6,00:d0:ba:d3:bd:3b. Click Add Reservation to add each reservation.

Step 8 Define attributes for the scope, if necessary.

Step 9 Click Add Scope.


Using the CLI

Use the scope name create command to create a scope with its network address and mask, the scope name set policy command to set its matching policy, and the scope name addRange command to add each scope's (space-separated) range of IP addresses. Each scope must identify its network address and mask. When you create the scope, Network Registrar places it in its current namespace (as defined by the session set current-namespace command). A server reload is required.

nrcmd> scope examplescope1 create 192.168.1.0 255.255.255.0 
100 Ok 
examplescope1: 
addr = 192.168.1.0 
bootp = disabled 
deactivated = 
...
nrcmd> scope examplescope1 addRange 192.168.1.10 192.168.1.100 
100 Ok 
192.168.1.10 192.168.1.100 
nrcmd> dhcp reload 
100 Ok

You can also explicitly set the namespace by using the scope name set namespace-id command. The namespace must already exist before you can set it for the scope.

nrcmd> namespace red create 1 
100 Ok 
red: 
addr-blocks-default-selection-tags = 
addr-blocks-use-client-affinity = 
addr-blocks-use-lan-segments = 
...
nrcmd> scope examplescope1 set namespace-id=1 
100 Ok 
namespace-id=1 

You can attach individual options to a scope using the scope-policy command. You might want to do this to define just the router option for a particular scope. For a description of embedded policies for scopes, see the "Configuring an Embedded Policy for the Scope" section.

Using the GUI


Step 1 In the Server Manager window, choose the DHCP server for which you want to add a scope.

Step 2 Click Add on the toolbar.

Step 3 In the Add Scope dialog box, enter the name of the scope in the Name field. This name is not case-sensitive (scope1 is the same as Scope1).

Step 4 You can associate only one policy per scope. In the Policy field, do either of these two:

Choose an existing policy from the drop-down list. The default policy appears initially. You can also choose the system_default_policy or any policy you create at the server level in the "Configuring Server Policies" section.

Create a new policy for the scope. Click View policy to open a DHCP Server Properties dialog box that includes just the Policies tab. Proceed as in the "Configuring Server Policies" section.

Step 5 In the Network number field, enter the network number of the scope's subnet. All scopes you create in the GUI are placed in the global namespace, that is, not part of any defined namespace.

Step 6 In the Subnet mask field, enter the subnet mask. For example, a class C network uses the 255.255.255.0 subnet mask.

Step 7 Enter the address range or ranges for the scope. Enter the first address in the Start Address column and the ending address in the End Address column for each range, making sure that the ranges do not overlap.


Timesaver You can enter just the relevant octets of the start and end addresses. Entering an n value specifies the nth address in the subnet, based on the subnet mask.


Step 8 Click OK.

Step 9 Reload the server.


Using Multiple Scopes

You can configure multiple scopes (with disjoint address ranges) with the same network number and subnet mask. The DHCP server pools the available leases from all scopes on the same subnet and offers them, in a round-robin fashion, to any client that requests a lease.

You can configure a single subnet's addresses into multiple scopes to increase the speed that the GUI updates the Leases tab, or to organize the addresses in a more natural way for administration. Because each scope can have a separate reservations list, you might want to organize the leases into multiple scopes on the same subnet. Put the dynamic leases in one scope that has a policy with one set of options and lease times, and put all the reservations in another scope with different options and times.

You can also have multiple scopes with some not locally connected to your computer. In this case, configure the router (with BOOTP relay support) with the appropriate helper address.

When multiple scopes are available on a subnet through the use of secondary scopes, the DHCP server searches through all of them for a scope that satisfies an incoming DHCP client request. For example, if a subnet has three scopes, only one of which supports dynamic BOOTP, a BOOTP request for which there is no reservation is automatically served by the one supporting dynamic BOOTP. For details on secondary scopes, see the "Making a Scope a Secondary" section.

You can also configure a scope to disallow DHCP requests (the default is to allow them). By using these capabilities together, you can easily configure the addresses on a subnet so that all the DHCP requests are satisfied from one scope (and address range), all reserved BOOTP requests come from a second one, and all dynamic BOOTP requests come from a third. In this way, you can support dynamic BOOTP while minimizing the impact on the address pools that support DHCP clients.

There is no limit to the number of leases that you can configure per scope. However, if you have a scope with several thousand leases, it can take the Network Registrar GUI a while to sort them, although there is no impact on the server's operation. Hence, divide the leases among multiple scopes.

Editing a Scope

You can edit a scope's properties.

Using the Web UI


Step 1 Create a scope, as described in the "Creating Scopes" section.

Step 2 Click the name of the scope on the List/Add DHCP Scopes page to open the Edit DHCP Scope page.

Step 3 Modify the fields or attributes on this page as necessary.

Step 4 To edit the scope's embedded policy, see the "Configuring an Embedded Policy for the Scope" section.

Step 5 To list leases for the scope, see the "Viewing Leases" section.

Step 6 Click Modify Scope. See the Network Registrar Web UI Guide for details.


Using the CLI

To look at the properties for all the scopes on the server, use the scope list (or scope listnames, scope name show, or scope name get attribute command). Use the scope name set command to set or reset an attribute, or the scope name enable or scope name disable command to enable or disable it.

nrcmd> scope list 
100 Ok
examplescope1:
addr = 192.168.1.0
bootp = disabled
deactivated =
...
nrcmd> scope examplescope1 get ping-timeout 
100 Ok
ping-timeout=300
nrcmd> scope examplescope1 set ping-timeout=600 
100 Ok 
ping-timeout=600 
nrcmd> scope examplescope1 enable ping-clients 
100 Ok 
ping-clients=enabled 

You can change the subnet and mask of the scope by using the scope name change-subnet command, or you can change just the mask by using the scope name changeMask command. This changes the primary-mask attribute on any secondary scopes, iterates over all reservations and ranges, and displays reservations and ranges that now fall outside the scope.

nrcmd> scope examplescope1 change-subnet 192.168.1.0 255.255.255.0 
100 Ok
nrcmd> scope examplescope1 changeMask 255.255.254.0 
100 Ok

Note Changing a scope's subnet and mask may result in a warning that certain address ranges have values outside of the new scope definition.


Changing a mask:

Changes it on the specified scope.

Changes the primary-mask attribute on any secondary scopes to the specified scope.

Iterates over all reservations in the scope and displays any that now fall outside the scope. If reservations fall outside the scope, then the command returns "101, Ok with warnings" instead of "100 Ok."

Iterates over all ranges in the scope and displays any that have endpoints that now fall outside the scope. If range endpoints fall outside the scope, then the command returns "101, Ok with warnings" instead of "100 Ok."

If you enable the delete-orphaned-leases attribute, at the next DHCP server reload, existing leases are deleted that fall outside the acceptable ranges for this scope and are not in the acceptable ranges of any other scope.

Also, see the "Making a Scope a Secondary" section.

Using the GUI

In the Server Manager window, double-click the scope under the DHCP server. This opens the Scope Properties dialog box. Change the properties on the applicable tabs of the dialog box, then click OK.

Configuring an Embedded Policy for the Scope

When you create a scope, Network Registrar automatically creates an embedded policy for it. However, the embedded policy has no associated properties or DHCP options until you enable or add them. An embedded policy can be useful, for example, in defining the router for the scope. As the "Types of Policies" section describes, the DHCP server looks at the embedded policy of a scope before it looks at its assigned, named policy. The only way to configure an embedded policy is through the Web UI or by using the scope-policy command attributes in the CLI.


Tip The GUI does not support configuring embedded policies. In the CLI, the scope-policy command uses the same commands as the policy command, except that it takes the scope name as an argument.


Using the Web UI


Step 1 Create a scope, as described in the "Creating Scopes" section.

Step 2 Click the name of the scope on the List/Add DHCP Scopes page to open the Edit DHCP Scope page.

Step 3 Click Edit Embedded Policy to open the Edit DHCP Embedded Policy for Scope page.

Step 4 Modify the fields, options, and attributes on this page. If necessary, unset attributes.

Step 5 Click Modify Embedded Policy. See the Network Registrar Web UI Guide for details.


Using the CLI


Step 1 Determine if there are any embedded property values already set for a scope using the scope-policy scope-name show command.

nrcmd> scope-policy examplescope1 show 
100 Ok
scope-policy:examplescope1:
allow-client-a-record-update = [default=disabled]
allow-dual-zone-dns-update = [default=disabled]
allow-lease-time-override = [default=enabled]
...

Step 2 Enable or disable an attribute using the scope-policy name enable or scope-policy name disable command. Set and unset attributes using the scope-policy name set and unset commands.

nrcmd> scope-policy examplescope1 enable allow-lease-time-override 
100 Ok
allow-lease-time-override=enabled
nrcmd> scope-policy examplescope1 set server-lease-time=2880 
100 Ok
server-lease-time=48m

Step 3 You can list, get, set, and unset DHCP options. You can also list, set, and unset vendor options. See the "Supporting Vendor-Specific DHCP Options" section.

nrcmd> scope-policy examplescope1 setOption routers 192.168.1.1 
100 Ok
routers=192.168.1.1
nrcmd> scope-policy examplescope1 listOptions 
100 Ok
(3)routers: 192.168.1.1

Step 4 Set and get the policy's lease time.

nrcmd> scope-policy examplescope1 setLeaseTime 228800 
100 Ok
2d15h33m20s
nrcmd> scope-policy examplescope1 getOption dhcp-lease-time 
100 Ok
dhcp-lease-time=228800

Step 5 If you delete a scope policy, you remove all of its properties and attributes.

nrcmd> scope-policy examplescope1 delete 
100 Ok


Making a Scope a Secondary

Network Registrar supports multiple logical subnets on the same network segment, which are called secondary subnets. With several logical subnets on the same physical network, for example, 192.168.1.0 and 192.168.2.0, you might want to configure DHCP so that it offers addresses from both pools. By pooling addresses this way, you can increase the available number of leases.

To join two logical subnets, create two scopes, and elect one to be primary and the other to be a secondary. After you configure the secondary subnet, any client on this physical network gets a lease from one or the other scope on a round-robin basis, as long as the client does not have a reservation or pre-existing lease.

Using the Web UI


Step 1 Create a scope, as described in the "Creating Scopes" section, that you want to make a secondary scope.

Step 2 Click the name of the scope on the List/Add DHCP Scopes page to open the Edit DHCP Scope page.

Step 3 The first attribute under the Leases area of the page is the Primary Subnet attribute. Enter the network address of the subnet of the primary scope, thereby making this a secondary scope.

Step 4 Click Modify Scope. See the Network Registrar Web UI Guide for details.


Using the CLI

To make a newly created scope a secondary (adding ranges and policies in the process), use the scope name set primary-subnet command to assign it to a primary scope, then reload the server. To remove the secondary scope status, use the scope name unset primary-subnet command.

nrcmd> scope examplescope2 create 192.168.50.0 255.255.255.0 
100 Ok
examplescope2:
addr = 192.168.1.0
bootp = disabled
deactivated =
...
nrcmd> scope examplescope2 addRange 101 200 
100 Ok
192.168.50.101 192.168.50.200
nrcmd> scope examplescope2 set policy=examplepolicy1 
100 Ok
policy=examplepolicy1
nrcmd> scope examplescope2 set primary-subnet=192.168.1.0/24 
100 Ok
primary-subnet=192.168.1.0/24
nrcmd> dhcp reload 
100 Ok

When setting the primary-subnet property, include the number bits for the network mask, using slash notation. For example, represent the network 192.168.1.0 with mask 255.255.255.0 as 192.168.1.0/24. The mask bits are important. If you omit them, a /32 mask (single IP address) is assumed.ww

It is common practice for the primary-subnet to correspond directly to the network address of the primary scope or scopes. For example, with examplescope1 created in the 192.168.1.0/24 network, associate examplescope2 with it using primary-subnet=192.168.1.0/24. (Note that if Network Registrar finds that the defined subnet has an associated scope, it ignores the mask bit definition and uses the one from the primary scope, just in case they do not match.) However, the primary-subnet can be a subnet address that does not have a scope associated with it.

There are three other properties used in previous versions of Network Registrar that denote primary subnet affiliation: primary-addr, primary-mask, and primary-scope. These are present to provide backward compatibility, but not to be used in the current release. The primary-subnet attribute (both in the Web UI and CLI) now sets these properties.

Using the GUI


Step 1 Create a scope to become a secondary. See the "Editing a Scope" section.

Step 2 Open its properties.

Step 3 Click the Advanced tab.

Step 4 Check the Make this scope a secondary box.

Step 5 In the Primary scope field, choose the scope that you want to designate as the primary. This must be one of the other scopes on the server.

Step 6 Click OK.

Step 7 Reload the DHCP server.


Enabling and Disabling BOOTP for a Scope

The BOOTstrap Protocol (BOOTP) was originally created for loading diskless computers. It was later used to allow a host to obtain all the required TCP/IP information so that it could use the Internet. Using BOOTP, a host can broadcast a request on the network and get the data required from a BOOTP server. The BOOTP server listens for incoming requests and generates responses from a configuration database for the BOOTP clients on that network. BOOTP differs from DHCP in that it has no concept of lease or lease expiration. All addresses that a BOOTP server allocates are permanent.

You can configure the Network Registrar DHCP server to act like a BOOTP server. In addition, although BOOTP normally requires static address assignments, you can choose either to reserve addresses (and use static assignments) or have addresses dynamically allocated (known as dynamic BOOTP).

When you need to move or decommission a BOOTP client, you can re-use its lease simply by forcing lease availability. See the "Forcing Lease Availability" section.

Using the Web UI


Step 1 Create a scope, as described in the "Creating Scopes" section.

Step 2 Click the name of the scope on the List/Add DHCP Scopes page to open the Edit DHCP Scope page.

Step 3 Under the BOOTP attributes, enable the bootp attribute for BOOTP, or the dynamic-bootp attribute for dynamic BOOTP. They are disabled by default.

Step 4 Click Modify Scope. See the Network Registrar Web UI Guide for details.


Using the CLI

Use the scope name enable bootp command to enable BOOTP, and the scope name enable dynamic-bootp command to enable dynamic BOOTP. Reload the DHCP server.

nrcmd> scope examplescope1 enable bootp 
100 Ok
bootp=enabled
nrcmd> scope examplescope1 enable dynamic-bootp 
100 Ok
dynamic-bootp=enabled
nrcmd> dhcp reload 
100 Ok

Using the GUI


Step 1 Open the properties for the DHCP server containing the scope for which you want to enable BOOTP.

Step 2 On the Policies tab of the DHCP Server Properties dialog box, configure a policy to contain the information that BOOTP requires.

Step 3 Click Edit options. In the Edit Options dialog box, choose the options that you want. They are in the BOOTP Compatible category. Also, check the Send to BOOTP clients box. If you also check the Always send to DHCP clients box, the DHCP server always sends an option back in the reply packet.

Step 4 Click OK, then close the DHCP Server Properties dialog box.

Step 5 Open the properties for the scope for which you want to enable BOOTP and click the Advanced tab of the Scope Properties dialog box.

Step 6 Check the Enable BOOTP box.

Step 7 To have the server accept dynamic BOOTP requests for the scope, check the Dynamic BOOTP box. Dynamic BOOTP requests do not match a reservation, but can be satisfied from the available lease pool. If you do not want dynamic BOOTP, you must reserve the addresses. See the "Reserving a Lease" section.

Step 8 Click OK.

Step 9 Reload the DHCP server.


Disabling DHCP for a Scope

You can disable DHCP for a scope if you want to use it solely for BOOTP. See the "Enabling and Disabling BOOTP for a Scope" section. You can also temporarily de-activate a scope by disabling DHCP, but it is more often used if you are enabling BOOTP. See the "De-activating a Scope" section.

Using the Web UI


Step 1 Create a scope, as described in the "Creating Scopes" section.

Step 2 Click the name of the scope on the List/Add DHCP Scopes page to open the Edit DHCP Scope page.

Step 3 Under the BOOTP attributes, disable the dhcp attribute and enable the bootp attribute.

Step 4 Click Modify Scope. See the Network Registrar Web UI Guide for details.


Using the CLI

Use the scope name disable dhcp command to disable DHCP. You should also enable BOOTP.

nrcmd> scope examplescope1 disable dhcp 
100 Ok
dhcp=disabled
nrcmd> scope examplescope1 enable bootp 
100 Ok
bootp=enabled
nrcmd> dhcp reload 
100 Ok

Using the GUI

Open the properties of the scope for which you want to disable DHCP. On the Advanced tab of the DHCP Scope Properties dialog box, check the Disable DHCP for this scope box. If the Enable BOOTP box is unchecked, check it. Then, click OK. and reload the DHCP server.

De-activating a Scope

You may want to temporarily de-activate all the leases in a scope. To do this, you must disable both BOOTP and DHCP for the scope.

Using the Web UI


Step 1 Create a scope, as described in the "Creating Scopes" section.

Step 2 Click the name of the scope on the List/Add DHCP Scopes page to open the Edit DHCP Scope page.

Step 3 Under the Miscellaneous attributes, explicitly enable the deactivated attribute.

Step 4 Click Modify Scope. See the Network Registrar Web UI Guide for details.


Using the CLI

Use the scope name enable deactivated command to disable BOOTP and DHCP for the scope. Reload the DHCP server.

nrcmd> scope examplescope1 enable deactivated 
100 Ok
deactivated=enabled
nrcmd> dhcp reload 
100 Ok

Setting a Scope to Renew-Only

You can control whether to allow existing clients to re-acquire their leases, but not to offer any leases to new clients. A renew-only scope does not change the client associated with any of its leases, other than to allow a client currently using an available IP address to continue to use it.

Using the Web UI


Step 1 Create a scope, as described in the "Creating Scopes" section.

Step 2 Click the name of the scope on the List/Add DHCP Scopes page to open the Edit DHCP Scope page.

Step 3 Under the Miscellaneous attributes, explicitly enable the renew-only attribute.

Step 4 Click Modify Scope. See the Network Registrar Web UI Guide for details.


Using the CLI

Use the scope name enable renew-only command to set a scope to renew-only.

nrcmd> scope examplescope1 enable renew-only 
100 Ok
renew-only=enabled

Removing a Scope

You can remove scopes from the DHCP server.


Caution Although removing a scope from a DHCP server is easy to do, be careful. Doing so compromises the integrity of your network. There are several ways to remove a scope from a server, either by re-using or not re-using addresses, as described in the following sections.

DHCP, as defined by the IETF, provides an address lease to a client for a specific time (defined by the server's administrator). Until that time elapses, the client is free to use its leased address. A server cannot revoke a lease and stop a client from using an address. Thus, while you can easily remove a scope from a DHCP server, the clients that obtained leases from it can continue to do so until it expires. This is true even if the server does not respond to their renewal attempts, which happens if the scope was removed.

This does not present a problem if the addresses you remove are not re-used in some way. However, if the addresses are configured for another server before the last lease expires, the same address might be used by two clients, which can destabilize the network.

Removing a Scope if Not Re-using the Addresses

If you do not plan to re-use the addresses from the scope, you can remove the scope from the server.

Using the Web UI

If you are sure you do not plan to re-use the scope, on the List/Add DHCP Scope page, click the Delete icon () next to its name, and confirm or cancel the deletion. See the Network Registrar Web UI Guide for details.

Using the CLI

Be sure you are not immediately planning to re-use the addresses in the scope, then use the scope name delete command to delete it.

nrcmd> scope examplescope1 delete 
100 Ok

Using the GUI


Step 1 Examine the scope in the Scope Properties dialog box. If you plan not to re-use the addresses, you can remove the scope.

Step 2 Click Cancel to exit the Scope Properties dialog box.

Step 3 Choose the scope in the Server Manager window.

Step 4 Click Remove on the toolbar.

Step 5 Click Yes in the confirmation dialog box.


Removing a Scope if Re-using the Addresses

If you want to re-use the addresses after removing a scope, you have two options:

If you can afford to wait until all the leases in the scope expire—Remove the scope from the server, then wait for the longest lease time set in the policy for the scope to expire. This ensures that no clients are using any addresses from that scope. You can then safely re-use the addresses.

If you cannot afford to wait until all the leases in the scope expire—Do not remove the scope. Instead, de-activate the scope. See the "De-activating a Scope" section. Unlike a scope that was removed, this causes the server to refuse all clients' renewal requests, which forces many of them to request a new lease. This moves these clients more quickly off the de-activated lease than if the scope had been removed.

Using the GUI, you can check the state of the de-activated scope's leases on the Leases tab in the Scope Properties dialog box. After there are no more leases, remove the scope and re-use the addresses.

You can also use the ipconfig utility in Windows to cause a client to release (/release) and re-acquire (/renew) its leases, thereby moving it off a de-activated lease immediately. You can only issue this utility from the client machine, which makes it impractical for a scope with thousands of leases in use. However, it can be useful in moving the last few clients in a Windows environment off de-activated leases in a scope.

Configuring Leases in the Scope

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.

Using the Web UI


Step 1 Create a scope, as described in the "Creating Scopes" section.

Step 2 Click the name of the scope on the List/Add DHCP Scopes page to open the Edit DHCP Scope page.

Step 3 Click List Leases in the Leases area of the page. This opens the List DHCP Leases for Scope page.

Step 4 Click Return to DHCP Scope. See the Network Registrar Web UI Guide for details.


Using 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 namespace; all the leases in all the namespaces are listed. In this example, the scope was set to a namespace-id of 99, corresponding to the red namespace:

nrcmd> lease list 
100 Ok
red/192.168.1.101:
expiration = none
flags = failover-updated
start-time-of-state = none
state = available
red/192.168.1.102:
...
nrcmd> lease 192.168.1.101 show 
100 Ok
red/192.168.1.101:
address = 192.168.1.101
client-binary-client-id =
client-dns-name =
...
nrcmd> scope examplescope1 listleases 
100 Ok
red/192.168.1.101:
...

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.

nrcmd> lease 192.168.1.101 macaddr 
100 Ok
1,6,00:d0:ba:d3:bd:3b 
nrcmd> lease list -macaddr 1,6,00:d0:ba:d3:bd:3b 
100 Ok
red/192.168.1.101:
state = leased
...
nrcmd> lease list -lansegment 192.168.0.0 255.255.0.0 
100 Ok
nrcmd> lease list -subnet 192.168.1.0 255.255.255.0 
100 Ok
red/192.168.1.101:
state = leased
...

Using the GUI

Double-click the scope for which you want to view leases. This opens the Scope Properties dialog box. Then click the Leases tab. The Leases tab shows these columns of information:

Address—Leases for the scope.

State—Lease state.

R—Reserved state flag.

D—De-activated state flag.

Host Address—MAC address of the DHCP client with the currently active lease.

DNS Host Name—Host name if you are not using dynamic DNS updates, or the name entered into DNS through dynamic DNS updates.


Tip Click a column heading to sort the lease table by that column. Adjust each column horizontally by dragging the header separator lines.


Lease States

A lease can be in one of these states:

Available—Leasable.

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 a Lease" 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 to clients that 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 had there been 240 to 260 clients attempting 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.


Note 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, manual intervention is required 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.

nrcmd> policy policyCableModem create 
100 Ok
policyCableModem:
allow-client-a-record-update = disabled
allow-dual-zone-dns-update = [default=disabled]
allow-lease-time-override = enabled
...
nrcmd> policy policyCableModem setOption dhcp-lease-time 604800 
100 Ok
dhcp-lease-time=604800

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.

nrcmd> policy policyCableModem setOption dhcp-lease-time 604800 
100 Ok
dhcp-lease-time=604800

Shorter lease times require more DHCP request and response buffers. Set the request and response buffers for optimal throughput (see the "Setting Advanced DHCP Server Parameters" section for details). There should be about three times as many response buffers as request buffers.

nrcmd> dhcp set max-dhcp-requests=1000 max-dhcp-responses=3000 
100 Ok
max-dhcp-requests=1000
max-dhcp-responses=3000

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

This section explains how to import and export leases using the CLI commands.

Using the CLI

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

field-1|field-2|field-3|...|field-13 

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. Namespace name (optional; if omitted, the global namespace 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 8-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 8-1 Lease Data Export

00:60:97:40:c1:96|1|6|204.253.96.103|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|204.253.96.57|nomad|cisco.com|
00:d0:ba:d3:bd:3b|blue-namespace

00:d0:ba:d3:bd:3b|1|6|204.253.96.77|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|
204.253.96.57|NPI9F6AF8|cisco.com|blue-namespace

00:d0:ba:d3:bd:3b|1|6|204.253.96.78|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|
204.253.96.57|JTB-LOCAL|cisco.com|blue-namespace

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 a Host Before Offering an 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.


Using the Web UI


Step 1 Create a scope, as described in the "Creating Scopes" section.

Step 2 Click the name of the scope on the List/Add DHCP Scopes page to open the Edit DHCP Scope page.

Step 3 Under the Miscellaneous attributes, enable the ping-clients attribute. It is disabled by default.

Step 4 Also under the Miscellaneous attributes, set the ping-timeout attribute. It is 300 seconds by default.

Step 5 Click Modify Scope. See the Network Registrar Web UI Guide for details.


Using the CLI

Use the scope name enable ping-clients command to enable pinging before offering an address. 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.

nrcmd> scope examplescope1 enable ping-clients 
100 Ok
ping-clients=enabled
nrcmd> scope examplescope1 set ping-timeout=200 
100 Ok
ping-timeout=200

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.

nrcmd> dhcp disable ignore-icmp-errors 
100 Ok
ignore-icmp-errors=disabled

Using the GUI


Step 1 Open the properties for the scope.

Step 2 Click the Advanced tab of the DHCP Scope Properties dialog box.

Step 3 Check the Ping address before offering it box.

Step 4 Choose a time to wait before assuming that no client will answer. The default is 300 milliseconds.

Step 5 Click OK.

Step 6 Reload the DHCP server.


De-activating a Lease

The reason you would de-activate a lease is to move a client off a lease. If the lease is available, de-activating the lease prevents Network Registrar from giving the lease to a client. If the lease is active (held by a client), de-activating the lease 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.


Using the Web UI


Step 1 Click the DHCP tab on the Primary Navigation bar.

Step 2 Click the Scopes tab 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.

Step 6 On the List DHCP Leases for Scope page, the lease will now show deactivated under the Flags column.


Using the CLI

Use the lease ipaddr deactivate command to prevent a lease from being given out or renewed. To re-activate a de-activated lease, use the lease ipaddr activate command.

nrcmd> lease 192.168.1.101 deactivate 
502 Server Failure - lease 192.168.1.101 deactivate
nrcmd> lease 192.168.1.101 activate 
502 Server Failure - lease 192.168.1.101 activate

Using the GUI


Step 1 Double-click the scope to open the Scope Properties dialog box.

Step 2 Click the Leases tab.

Step 3 Choose the lease that you want to de-activate.

Step 4 Click Lease properties (or double-click the address) to open the Lease Properties dialog box.

Step 5 Look at the Lease state information. If the lease is available, de-activating it makes it unavailable; if it is active, it becomes unavailable for both initial assignment and renewal.

Step 6 Check the Deactivate lease box.

Step 7 Click OK. The Leases tab of the Scope Properties dialog box now shows the address as being de-activated, with an X in the D (De-activated) column.

To de-activate all the leases in a scope, you have to disable both BOOTP and DHCP for that scope. See the "De-activating a Scope" section.


Excluding an Address from a Range

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 a Lease" 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.

Using the Web UI


Step 1 Create a scope, as described in the "Creating Scopes" section.

Step 2 Click the name of the scope on the List/Add DHCP Scopes page to open the Edit DHCP Scope page.

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

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

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

Step 6 Click Modify Scope. See the Network Registrar Web UI Guide for details.


Using the CLI

You can remove an address from a lease range simply by removing 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 192.168.1.55 address from the range. Note that if the lease is in a scope with a defined namespace, you must explicitly define that namespace for the session, or you can include the namespace prefix in the lease command.

nrcmd> session set current-namespace=red 
100 Ok
current-namespace=red
nrcmd> scope examplescope1 listRanges 
100 Ok
192.168.1.10-192.168.1.100: start=192.168.1.10; end=192.168.1.100;
nrcmd> lease red/192.168.1.55 deactivate 
100 Ok
nrcmd> scope examplescope1 removeRange 192.168.1.55 192.168.1.55 
100 Ok
nrcmd> scope examplescope1 listRanges 
100 Ok
192.168.1.10-192.168.1.54: start=192.168.1.10; end=192.168.1.54;
192.168.1.56-192.168.1.100: start=192.168.1.56; end=192.168.1.100;
nrcmd> dhcp reload 
100 Ok

Using the GUI


Step 1 In the Scope Properties dialog box, click the Leases tab to find the address that you want to exclude.

Step 2 De-activate the lease for the address, as in the "De-activating a Lease" section.

Step 3 Click the General tab.

Step 4 In the Start Address-End Address field, find the range to which the address belongs.

Step 5 Edit the address range so that it starts just after, or ends just before, the address you want to remove.

Step 6 Add another range to the table that adds back the addresses you edited out in the previous step, but excludes the address that you want to remove.

Step 7 Specify the address range, omitting the address of the lease that you want to delete.

Step 8 Click OK to close the Scope Properties dialog box.

Step 9 Open the dialog box and click the Leases tab to confirm that the address is gone. Click Refresh list.

Step 10 Click OK.

Step 11 Reload the DHCP server.


Reserving a Lease

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 address 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.


Using the Web UI


Step 1 Create a scope, as described in the "Creating Scopes" section.

Step 2 Click the name of the scope on the List/Add DHCP Scopes page to open the Edit DHCP Scope page.

Step 3 In the Reservations area of the page, add the IP and MAC addresses of the reserved address. Ensure that it is not part of an existing range in the Ranges area of the page. The MAC address is required.

Step 4 Click Add Reservation.

Step 5 Click Modify Scope. See the Network Registrar Web UI Guide for details.


Using the CLI

Use the scope name listReservations command to list lease reservations for a scope. Use the scope name addReservation command to reserve a lease (including the IP and MAC addresses). Save the reservation, then you can 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.

nrcmd> scope examplescope1 addReservation 192.168.1.10 1,6,00:d0:ba:d3:bd:3b 
100 Ok
192.168.1.10 1,6,00:d0:ba:d3:bd:3b
nrcmd> scope examplescope1 listReservations 
100 Ok
192.168.1.10: mac=1,6,00:d0:ba:d3:bd:3b;
nrcmd> save 
nrcmd> lease 192.168.1.10 send-reservation 
100 Ok

Or:

nrcmd> dhcp reload 
100 Ok

Using the GUI

Network Registrar provides two ways to make reservations using the GUI:

On the Leases tab

On the Reservations tab

Using the GUI Leases Tab Method


Step 1 Click the Leases tab for the properties of the selected scope.

Step 2 Double-click the address of the lease you want to reserve.

Step 3 Check the Reserve lease box under Reservations.

Step 4 If the lease is available, enter the MAC address of the host in the Reserved for MAC address field. If the lease is active, the MAC address appears in the field because it needs to be defined to activate the lease. You can accept this MAC address or you can enter another one.

The hardware type and octet length of the MAC address is displayed as part of the MAC address in both the lease table and Reserved for MAC address field. The address prefix is usually 1,6, (meaning "use Ethernet and make the address six octets long"). When adding or editing a MAC address, you can include or omit this prefix (for example, 1,6,00:d0:ba:d3:bd:3b or just 00:d0:ba:d3:bd:3b), unless you want a different hardware type and address length. For details on the MAC address syntax, see the "Defining Client-Classes and Their Properties" section.

Step 5 Click OK.

Step 6 Reload the DHCP server to make the reservations take effect.


Using the GUI Reservations Tab Method


Step 1 Click the Reservations tab for the properties of the selected scope.

Step 2 Click Add.

Step 3 In the Add Reservation dialog box, enter the lease's IP address and MAC address.

You can include the hardware type and address length as part of the MAC address. The prefix is 1,6, (meaning "Ethernet and six octets long") by default, so you can omit it if the client uses Ethernet with the six-octet MAC address syntax. See the "Defining Client-Classes and Their Properties" section. An example with the prefix is 1,6,00:d0:ba:d3:bd:3b.

Step 4 Click Apply to continue adding reservations, or click OK to finish.

Step 5 Click the Leases tab and click Refresh. There should be an X in the R (Reserved) column and the MAC address displayed for each address you reserved.

Step 6 Click OK.

Step 7 Reload the DHCP server.


Reserving an Address That Is 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 192.168.1.110 1,6,00:d0:ba:d3:bd:3c 
100 Ok
192.168.1.110 1,6,00:d0:ba:d3:bd:3c
nrcmd> save 
100 Ok
nrcmd> lease 192.168.1.110 send-reservation 
100 Ok
nrcmd> lease 192.168.1.110 activate 
100 Ok
nrcmd> save 
100 Ok

Client 1,6,00:d0:ba:d3:bd:3b does a DHCPDISCOVER and gets an offer for 192.168.96.180. 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 192.168.1.110 deactivate 
100 Ok
nrcmd> scope examplescope1 removeReservation 192.168.1.110 
100 Ok
nrcmd> save 
100 Ok
nrcmd> lease 192.168.1.110 delete-reservation 
100 Ok

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 192.168.1.110 1,6,00:d0:ba:d3:bd:3d 
100 Ok
192.168.1.110 1,6,00:d0:ba:d3:bd:3d
nrcmd> save 
100 Ok
nrcmd> lease 192.168.1.110 send-reservation 
100 Ok
nrcmd> lease 192.168.1.110 activate 
100 Ok
nrcmd> save 
100 Ok

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 192.168.96.180. 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 192.168.96.180, 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 192.168.96.180.

After this, the server gives client 1,6,00:d0:ba:d3:bd:3b whatever lease is appropriate for it—some reservation other than 192.168.96.180, 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 192.168.96.180.

You could also force the availability of a lease.

nrcmd> lease 192.168.1.110 force-available 
100 Ok

However, that does not stop the original client (1,6,00:d0:ba:d3:bd:3b) from using 192.168.96.180. Also, it does not prevent the new client (1,6,02:01:02:01:02:01) from getting 192.168.96.180.

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 a Lease

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.

Using the Web UI


Step 1 Create a scope, as described in the "Creating Scopes" section.

Step 2 Click the name of the scope on the List/Add DHCP Scopes page to open the Edit DHCP Scope page.

Step 3 In the Reservations area of the page, click the Delete icon () next to the reservation you want to remove. This removes the reservation immediately, with no confirmation.

Step 4 Click Modify Scope. See the Network Registrar Web UI Guide for details.


Using the CLI

To remove the lease from the scope, 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.

nrcmd> scope examplescope1 removeReservation 192.168.1.110 
100 Ok
nrcmd> dhcp reload 
100 Ok

You can also combine removing a reservation with deleting it by using the lease ipaddr delete-reservation command. This does not require a reload.

nrcmd> lease 192.168.1.110 delete-reservation 
100 Ok

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.


Using the GUI


Step 1 Click the Reservations tab for the properties of the selected scope.

Step 2 Choose the lease's IP address.

Step 3 Click Remove.

Step 4 Click the Leases tab to confirm removing the lease reservation.

Step 5 Reload the DHCP server.


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.

Using the Web UI


Step 1 Click the DHCP tab on the Primary Navigation bar.

Step 2 Click the Scopes tab 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.


Using the CLI

Use the lease ipaddr force-available command to force making the currently held lease available.

nrcmd> lease 192.168.1.110 force-available 
100 Ok

Use the scope name clearUnavailable command to force all leases in the scope to become available.

nrcmd> scope examplescope1 clearUnavailable 
100 Ok

Using the GUI

On the Leases tab of the Scope Properties dialog box, choose the lease you want to force to become available. Double-click the address to open the Lease Properties dialog box. Then, click Force available and OK.

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.

Using the Web UI


Step 1 Create a policy, as described in the "Creating a Policy" section.

Step 2 Click the name of the policy on the List DHCP Policies page to open the Edit DHCP Policy page.

Step 3 In the attributes, enable the inhibit-all-renews or inhibit-renews-at-reboot attribute. Both are disabled by default.

Step 4 Click Modify Policy. See the Network Registrar Web UI Guide for details.


Using 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.

nrcmd> policy examplepolicy1 enable inhibit-all-renews 
100 Ok 
inhibit-all-renews=true 

nrcmd> policy examplepolicy1 enable inhibit-renews-at-reboot 
100 Ok 
inhibit-renews-at-reboot=true 

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 a Host Before Offering an Address" section.

nrcmd> scope examplescope1 enable ping-clients 
100 Ok 
ping-clients=enabled 

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.

nrcmd> scope examplescope1 enable ignore-declines 
100 Ok 
ignore-declines=enabled 

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.

nrcmd> dhcp enable ignore-requests-for-other-servers 
100 Ok
ignore-requests-for-other-servers=enabled 

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:

nrcmd> policy system_default_policy set unavailable-timeout=86400 
100 Ok 
unavailable-timeout=24h 

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:

nrcmd> dhcp set upgrade-unavailable-timeout=86400 
100 Ok 
upgrade-unavailable-timeout=24h 

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 Utilization—Displays statistics about leases in scopes.

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

Running an Address Usage Report

You can run an address usage report.

Using the Web UI

This function is currently not available in the Web UI.

Using 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.

nrcmd> report dhcp-only 
100 Ok
Network			Mask 	Cluster			Role Scope					Network			Total Static Unalloc Addrs % Free
Free Reserved Leased Dyn Leased Unavail Deactiv Other Avail Other Reserv
C0A80100			24	localhost			NONE examplescope2					192.168.1.0			100 							100%
100 			0		0		0		0		0		0		0
...
100 Ok


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 a Lease Utilization Report

Using the CLI, you can generate a static and dynamic address usage summary on one or more clusters.

Using the Web UI

See the "Viewing Leases" section.

Using 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 namespace

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 8-2.

Table 8-2 Report Values Displayed for Scope-Specific Subnets 

Report Value
Description

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.

Addresses

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.

Free

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.

Reserved

Addresses flagged as reserved in a range, unless unavailable.

Leased

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

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

De-activated

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 8-3 summarizes the address states.

Table 8-3 Categories of Address States

Category
State

deactivated

current or pending

dynamically leased

current or pending

free

current state of available minus addresses flagged reserved or deactivated

leased

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

reserved

current or pending

unavailable

current


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 8-4 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 8-4 Potential States and Flags for IP Addresses 

State
Flags
None
Reserved
Deactivated
Reserved and Deactivated

available

free

reserved

deactivated

deactivated

leased

dynamically
leased, leased

dynamically
leased, leased

deactivated,
leased

deactivated, leased

expired

dynamically
leased, leased

dynamically
leased, leased

deactivated,
leased

deactivated, leased

offered

dynamically
leased, leased

dynamically
leased, leased

deactivated,
leased

deactivated, leased

other-
available

other available

reserved

deactivated

deactivated

pending-
available

dynamically
leased, leased

dynamically
leased, leased

deactivated,
leased

deactivated, leased

unavailable

unavailable

unavailable

unavailable

unavailable


Receiving Lease Notification

Using the CLI, you can survey all scopes on the Network Registrar clusters and produce a report of all the scopes in which the available addresses equals or falls below an absolute value or percentage.

Using the Web UI

This function is currently not available in the Web UI.

Using 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 
mail-host=mailhost 
100 Ok

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 UNIX

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:

15 0,12 * * 1-5 . .profile; /opt/nwreg2/usrbin/nrcmd lease-notification available=10\% 
config=/home/jsmith/.nrconfig addresses=192.32.1.0-192.32.128.0 
recipients=jsmith,jdoe@example.com >/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 pathname on the crontab command line. You can determine the full pathname in your environment with the UNIX which nrcmd command.

Also, note that when you run the lease-notification command by means of crontab, the server ignores the user environment variables AIC_CLUSTER, AIC_NAME, and AIC_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, as shown in the following example.

AIC_CLUSTER=host1 
export AIC_CLUSTER 
AIC_NAME=admin1 
export AIC_NAME 
AIC_PASSWORD=passwd1 
export AIC_PASSWORD 

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 whitespace. 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 the Configuration File for Lease Notification" section.

Fully specified pathname 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-rw 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 into the at queue, one for each time of day at which you want to run the job.

Specifying the Configuration File 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 AIC_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.

Recording IP Lease History

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 an 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.

Enabling IP History Recording

Using the Web UI


Step 1 On the Primary Navigation bar, click the DHCP tab. See the Network Registrar Web UI Guide for details.

Step 2 On the Secondary Navigation bar, click the DHCP Server tab.

Step 3 Click the name of the server. This opens the Edit DHCP Server page.

Step 4 Under the IP History attribute category, explicitly enable IP History and set the IP History Directory value to the root of the history database directory.

Step 5 Click Modify Server.


Using 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.

nrcmd> dhcp enable ip-history 
100 Ok
ip-history=enabled

You must also specify the directory path to the root of the IP history database directory to effect enabling recording the IP history. It is best to store the history files on a different disk partition from the server's lease state database. Always use forward slashes (/) as path separators, even for Windows paths.

nrcmd> dhcp set ip-history-dir=/iphist/logs 
100 Ok
ip-history-dir=/iphist/logs

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.

Running the IP History Query 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 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 this syntax:

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

For example:

# cd /opt/nwreg2/usrbin 
# ./iphist -N user -P password 
-f "address,expiration,flags,namespace-id,stat,client-mac-addr,client-binary-client-id" 
-o output.txt all now 

The options are described in Table 8-5.

Table 8-5 iphistory Command Options 

Option
Description

-a

Shows the lease attributes.

-n namespace

Name or ID or any associated namespace, or the word all (for all namespaces) or global (for addresses without namespace). If you omit this option, Network Registrar bases the query on the global namespace only, or the current one set by the session set current-namespace command, unless you use the all value with the option.

-o file

Output to a file rather than to the screen.

-f format

Format of output lines. See the "Formatting the IP History Query Output" section.

-N username

Administrator username. This option is required.

-P password

Administrator password. This option is required.

-V visibility

Sets the visibility (1 through 5) of the lease attributes. The default is 3.


The ipaddress is the IP address of the lease in dot-quad format, or all for all addresses. This argument corresponds with the address attribute of the lease object.

The start-date is the optional date for records from which to start the query, or the word start for the earliest date in the database. This argument corresponds with the start-time-of-state attribute of the lease object.

The end-date is the optional date of records the query should end, or the word end for the latest date in the database. This argument corresponds with the expiration attribute of the lease object. If using this argument, you must also use the start-date argument.

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).

Formatting the IP History Query Output

The output from the iphist -f format command 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.

The values on each line depend on the specific lease object that the DHCP server stores. You can specify the values to include or omit using the format argument in the -f option of the 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,macaddress,start-time-of-state,
lease-expiration-time. You would specify this output using the lease object attributes:

# ./iphist -f "address,client-mac-addr,start-time-of-state,expiration" all 
username: 
password: 
[data]

Table 8-6 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 8-6 IP History Query Output Attributes 

Lease Attribute
Description

address

IP address of the lease.

client-binary-client-id

Binary form of the client's MAC address.

client-dns-name

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

client-domain-name

Domain where the client resides.

client-flags

A number of client flags.

client-host-name

Host name the client requested.

client-id

Client ID requested by or synthesized for the client.

client-last-transaction-time

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

client-mac-addr

MAC address that the client presented to the DHCP server.

client-os-type

Operating system of the leased client.

expiration

Date and time when the lease expires. This time is in GMT.

flags

Either reserved or de-activated.

lease-renewal-time

Minimal time in which the client is expected to issue a lease renewal. This time is in GMT.

namespace-id

Identifier for the namespace, if any.

relay-agent-circuit-id

Contents of the circuit-id suboption (1).

relay-agent-option

Contents of the option from the most recent client interaction.

relay-agent-remote-id

Contents of the remote-id suboption (2).

relay-agent-server-id-override

Address in the server-id-override suboption.

relay-agent-subnet-selection

Address in the subnet-selection suboption.

relay-agent-vpn-id

Contents of the vpn-id suboption.

start-time-of-state

Date and time when the lease changed its state. This time is in GMT.

state

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

vendor-class-id

Vendor class ID requested by the client.


Trimming IP 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.

Using the Web UI

This function is currently not available in the Web UI.

Using the CLI

The dhcp trimIPHistory command supplies the DHCP server with a cutoff time to apply to the history records. When you reload the server, it examines the history database and deletes any records with an expiration time older than the date-string value.

dhcp trimIPHistory date-string [-namespace name] [-logfile filename]

nrcmd> dhcp trimIPHistory "Jul 31 19:00:00 2002" 
100 Ok
nrcmd> dhcp reload 

The effect of this command is not persistent; it only affects the next reload, not all subsequent reloads. You can specify to trim data in a specific namespace only. You can also redirect output to a log file that is placed in the log file directory, mainly for debugging purposes. Enter the date-string based on the local CLI time and date, in relative or fixed format:

-numunit—Relative date in the form of a hyphen followed by a num digit, and unit as one of s (seconds), m (minutes), h (hours), d (days), or w (weeks). For example, -12d, which indicates "twelve days ago."

"[day-of-week] month day hour:minute[:second] year"—This format must be enclosed in quotes, because it includes space characters. The (optional) day of week and the (required) month are abbreviated to the first three characters; the hour is on a 24-hour clock; seconds are optional; and the year is the fully specified year or a two-digit representation in which 98 = 1998, 99 = 1999, and all other values are in 20xx. For example, "Tue Dec 31 19:00:00 02".

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 "Running the IP History Query Utility" section.

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.