Table of Contents

Using the Nrcmd Commands

Using the Nrcmd Commands

The Network Registrar nrcmd program is a command-line based configuration tool. It allows you to set all Network Registrar configurable options as well as to start and stop the servers.

This chapter contains an alphabetic listing of all the commands and their properties.

Admin

The admin command allows you to configure administrators for the cluster. You can choose any string for the name. Network Registrar uses the password to authenticate the name. If you create an administrator without a password, Network Registrar cannot authenticate the name, and thus will deny that user access to the cluster.

Because the password is sensitive information, Network Registrar prints its value as'********'.

The syntax is:

Examples

To create the administrator bob with the password xyz, enter:

nrcmd> adminbob create password=xyz

 

To delete the administrator bob, enter:

nrcmd> adminbob delete

Admin Properties

Use the set, get, and show commands to assign and retrieve values from the admin's properties.

The syntax is:

To enter a password and not have Network Registrar display the password on your screen, create an administrator and do not supply a password. Then use the enterPassword command to enter a password and prevent Network Registrar from echoing it on the screen. Network Registrar prompts you to verify the password before it accepts it.

Client

The client and client-class commands let you create and manipulate clients and groups of clients for the purpose of determining what type of IP address and/or policy to assign to requesting hosts.

Using the client command you can assign properties to a specific client entry, based on the client's MAC address or the literal string default, which matches any client that does not have a specific client configuration. The properties you can assign include such things as a class of client, a policy, an action, and the inclusion or exclusion of scope selection tags. The DHCP server looks up these properties to determine how it should process the host's request for an IP address.

You can configure common client properties, such as selection criteria, in one client-class configuration, and can have multiple client configurations use it.

The DHCP server reads the client configuration information each time it receives a request for an IP address, so you do not have to reload the server after modifying these client configurations. If you modify the default client configuration however, you must reload the server for the change to take effect.

The way that you specify the client is to use the MAC address in the format of hardware-type,hardware-length,hardware address or the word default. Note that the commas are required.

A sample Ethernet MAC address might be 1,6,06:44:40:26:f5:0f.

• Hardware type—usually either 1 or 6 (1 indicates Ethernet and 6 token ring), but it could be any number between 1 and 255.
  
  
• Hardware length—a number between 1 and 16 that represents the length of the MAC address in octets.
  
  
• Hardware address—a number of two-character hex values: one for each octet of the hardware address. Note that although case is not significant, each octet must have exactly two characters and be separated by colons.
  
  

Note   Network Registrar stores the client name in lowercase regardless of the case you use to specify the client.

The syntax is:

Examples

To create a client that is a member of the external client-class, enter:

nrcmd> client 1,6,02:02:02:02:02:02 create client-class-name=external

 

To delete client 1,6,02:02:02:02:02:02:, enter:

nrcmd> client 1,6,02:02:02:02:02:02 delete

 

To list all the clients, enter:

nrcmd> client list

Client Properties

The property list contains the name and values in the following format: prop=value{,value}.

For the host-name and domain-name strings to have any effect, you must have enabled dynamic DNS update in the scope from which the IP address was allocated.

Use the set and get commands to set and display their values.

The syntax is:

Table 2-1 lists the client command properties.

Action Strings

The action string is made up of one or more comma-delimited tokens. Valid tokens are the following:

• exclude—Causes the server to ignore all communication from this client. If you specify the exclude action in the default client entry, then any client not specifically registered through the use of the client command will not be allowed to communicate with the server.
  
• Ignore—Causes the server to ignore any client or client-class object, including default clients and default client-classes.
  
• one-shot—Causes the server to fail to renew or re-offer any lease made to a client that has specified this action string (either directly or in a client-class entry).
  

One-Shot Action

Use the one-shot action to allocate provisional addresses, which are useful when you want an unknown client to have an address for only a short period of time.

To use the one-shot action in this way, configure it as the action for the default client (or in the client-class specified by the default client). This configuration causes the server to give a lease to an unknown client, but when the lease expires, the server will not respond to that client for the duration of the grace period. After the grace period expires, the server will not respond to that client until the now available lease is re-allocated to another client. This final period may be short or long, depending on the number of leases in the scope, and the number of clients using them. Newly available leases go on the end of a queue, and are allocated from the beginning of a queue, so that it might be quite some time before this lease is re-allocated to another client.

It is possible to allow the client a relatively short lease time, such as one day, and then specify a long grace period, such as two weeks. In this manner, you can offer an incentive to the client to register with some authority and become a known client, while preventing the lease from being reallocated to another client.

After the lease expires, the client is unable to get another address for the extent of the two-week grace period. Note that you can configure the lease and grace period differently for each scope, so that the non-provisional leases can have different lease and grace periods.

After the lease is reallocated to another client, all record of the first client's use is lost, and the first client could get another lease as an unknown client and have another opportunity to register.

Using provisional addresses would be less restrictive if you use multiple DHCP servers, because each one operates its one-shot capabilities independently. Thus, with the above approach and two DHCP servers, an unregistered client could get two days of provisional address use every two weeks.

Authenticate-Until

The authenticate-until property provides a mechanism for limiting the authentication of a client entry. By default, client entries are authenticated forever, but by using the authenticate-until property it is possible to specify an expiration time for the authentication.

When the authentication for a client entry is no longer authenticated, the DHCP server uses the value of the unauthenticated-client-class property for the name of the client-class entry to use in answering this DHCP request. If the unauthenticated-client-class property is not set or if there is no client-class entry in the unauthenticated-client-class property, the DHCP server ignores the DHCP request; that is, the server will not provide the client an IP address.

The following are valid authentication values:

• +num unit—Expire the authentication num unit of time in the future. The num is a decimal number, and unit is one of s, m, h, d, w, in which s is seconds, m is minutes, h is hours, d is days and w is weeks. For example +3w for three weeks.
  
  
• date—Specify the date as month, day, hour (24 hour) year (4 or last 2 digits). For example, Jun 30 20:00:00 1998.
  
  

If you specify 98 or 99, Network Registrar assumes 1998 or 1999. If you specify a lower number, such as 05 or 10, Network Registrar assumes 2005 or 2010.

• forever—Do not expire the authentication for this client.
  
  

Note   Wherever you specify a date using the nrcmd command, you should enter the time that is local to the nrcmd process. This means that if the server is running in another time zone than your nrcmd process, you should disregard the time zone where the server is running and use local time instead.

Host Name Strings

The value you specify in the host-name property can be one of two general forms.

The first form is a string that does not start with a "@." This form of host-name value is used to override the DHCP client-request host name. When you enter a valid name, you cause the DHCP server to ignore any host name specified by this client, and instead use this client-entry property. The actual value of the host-name option in the client's DHCP packet is ignored.

• hostname—Causes the server to use this host name to override the DHCP client request host name. This name can be any valid DNS name. Note you cannot use underscores.
  
  

The second form is a string that starts with the special token "@." Network Registrar uses this form of host-name value to signal the following special handling.

• @host-name-option—Causes the server to use whatever host-name option the client sent. This is the default behavior if there is no entry for host-name in either the client or client-class.
  
  
• @no-host-name-option—Causes the server to drop the host-name option that the client sent, and not replace it. If you have disabled DNS name synthesis, then the client will have no name placed into DNS.
  
  
• @use-macaddress—Causes the server to synthesize a host name for the client that is derived from its MAC address, and is thus unique. This token is used to ensure that a client has a valid, unique, and predictable name in DNS.
  
  

Client-Class

The client-class command allows you to apply a set of properties to a group or class of clients.

Client-Class Creation and Deletion

The syntax is:

Examples

To create the client-class internal, enter:

nrcmd> client-class internal create

 

To delete the client-class internal, enter:

nrcmd> client-class internal delete

 

To list all the client-classes, enter:

nrcmd> client-class list

Note   Client-class names are case sensitive. When referencing a client-class, you need to enter the name just as it was created.

Client-Class Properties

The client-class command allows you to configure and display common properties for DHCP client configurations using the set, unset, get and show commands.

Note   You can use the same properties as the client command, except for the following two properties: client-class-name and unauthenticated-client-class-name. These two properties provide names of client-class configurations that the DHCP server can use to initialize property values for a specific client configuration.

Unlike most client configurations, the DHCP server reads the client-class configurations at server start-up time, and thus you must reload the server for changes to take affect.

The syntax is:

For descriptions of the properties, see the "Client Properties" section.

Client and Client-Class Hierarchy

The server processes client and client-class property values in the following way:

• Network Registrar looks for the scope selection tag in the client-entry. If the tag appears in the client-entry, then Network Registrar uses it. If the tag is blank, then Network Registrar looks for the tag in the client-class. If the tag is specified as none in the client, Network Registrar does not look in the client-class.
  
  
• The policy property is processed a bit differently. If you specify a policy in the client, it is placed first on the search list of policies. A policy specified in the client-class is placed next. The policy specified in the scope is placed next, and the system-default policy is placed last. When looking for information from a policy (frequently a DHCP option) to return to a DHCP client, the policies in the list are searched in order. Network Registrar uses the first information it finds.
  
  

Note   If you delete the dhcp-lease-time option from client or client-class policies, Network Registrar uses the system-default policy whose dhcp-lease-time option cannot be deleted.

Client-Class-Policy

The client-class-policy command allows you to configure DHCP embedded policies for client classes. A client-class-policy is a policy object embedded within (and limited to) a client-class object. Each client-class may contain option data within its embedded policy, and may refer to a named policy with more option data, such as a router IP address.

Embedded client-class-policies are implicitly created and deleted when you create or delete the corresponding client-classes. You manipulate the client-class-policy using the name of the client-class to which the embedded policy is attached.

Client-Class-Policy Features

You can enable, disable, unset, and show client-class-policy features. The syntax is:

The delete command re-initializes all properties and features of the client class policy.

Table 2-2 lists and describes the client-class-policy command features. For more information about lease time, see "Lease Times" section.

Client-Class-Policy Properties

Use the set and get commands to assign and retrieve values from the client-class-policy command properties.

The syntax is:

Table 2-3 lists and describes the client-class-policy properties.

Example

To set the grace period to three days for client-class-policy 168.1-net, enter:

nrcmd> client-class-policy 168.1-net set grace-period=3d

Client-Class-Policy Reply Options

When the server is getting ready to return option data to a client, it examines up to seven policies: the client's embedded policy, the client's policy, the client's client-class's embedded policy, the client's client-class's policy, the client's lease's scope's embedded policy, the client's lease's scope's policy, and the system default policy, in that order. The server looks through these policies for option data that the client has asked for.

Then the server looks through the policies for a reply-options list. It looks for bootp- or dhcp-reply-options depending on the client. The server uses the first list it finds. For each option in the list, the server looks through all of the policies, in order, and returns the data from the first policy that has a matching option. There is no requirement that the data that the server returns must come from the same policy that the reply-options list came from. If the server finds a reply-options list, it looks for each option in the list individually, and searches all of the related policies if necessary.

There is also no requirement that the options mentioned in a reply-options list be present in the client-class-policy that contains the list. The nrcmd program allows you to enter a string, and that string can name any option. The Network Registrar GUI, however, presents a special dialog box for adding a reply-options property to a client-class-policy that restricts you to the options already configured in the client-class-policy. This is a GUI-only restriction; the server does not impose this restriction.

Client-Class-Policy Option Method Commands

You can set individual option values with the setOption command, unset option values with the unsetOption command, and view option values with the getOption and listOptions commands. When you set an option value, the DHCP server replaces any existing value or creates a new one, as needed, for the given option name.

Note   For a list of all the DHCP options that you can configure, enter the nrcmd program help dhcp-option command or refer to Appendix D "DHCP Extension Dictionary Entries."

The syntax is:

Table 2-4 lists and describes the client-class-policy command options.

Table 2-5 describes the properties of the client-class-policy option method commands.

Examples

To specify the lease time in a client-class-policy, enter:

nrcmd> client-class-policy 168.1-net setOption dhcp-lease-time 608400

 

To list the options in a client-class-policy, enter:

nrcmd> client-class-policy 168.1-net listOptions

Client-Class-Policy Lease Time Method Commands

The setLeaseTime command allows you to set the values of lease times and the getLeaseTime command to display the value of a lease time.

The syntax is:

The lease time is the value of the dhcp-lease-time DHCP option. You should specify the time in seconds.

Lease Times

A client-class-policy contains two lease times: the client lease time and the server lease time.

• You set the client-class-policy lease time through the setLeaseTime method. This lease time determines how long the client-class-policy believes its lease is valid.
  
  
• You set the server lease time through the server-lease-time property. This lease time determines how long the server considers the lease valid. Note that the server lease time is independent of the lease's grace period; that is, the server will not allocate the lease to another client until after the server's lease period has expired and the grace period has expired.
  
  

You might want to establish these two different lease times if you want to retain information about clients' DNS names and yet have them renew their leases frequently. When you use a single lease time and it expires, the server no longer keeps that client's DNS name. If, however, you use a short client lease time and a longer server lease time, the client information is retained even after the client's lease has expired.

Caution Although Network Registrar supports the use of two lease times for special situations, it is generally recommended that you not use the server-lease-time property.

Client-Policy

The client-policy command allows you to configure DHCP embedded policies for clients. A client-policy is a policy object embedded within (and limited to) a client object. Each client may contain option data within its embedded policy, and may refer to a named policy with more option data, such as a router IP address.

Embedded client-policies are implicitly created and deleted when you create or delete the corresponding client. You manipulate the client-policy using the name (which, in this case, is the MAC address) of the client to which the embedded policy is attached.

Client-Policy Features

You can enable, disable, unset, and show the client-policy features. The syntax is:

The value of client-name must be either the MAC address of a client that has already been defined or else the literal string "default."

The delete command re-initializes all features and properties of the client policy.

Table 2-6 lists and describes the client-policy command features. For more information about lease time, see "Lease Times" section.

Client-Policy Properties

Use the set and get commands to assign and retrieve values from the client-policy's properties.

The syntax is:

Table 2-7 lists and describes the client-policy command properties.

Example

To set the grace period to three days for client-policy 1,6,02:02:02:02:02:02, enter:

nrcmd> client-policy 1,6,02:02:02:02:02:02 set grace-period=3d

Client-Policy Reply Options

When the server is getting ready to return option data to a client, it examines up to seven policies: the client's embedded policy, the client's policy, the client's client-class's embedded policy, the client's client-class's policy, the client's lease's scope's embedded policy, the client's lease's scope's policy, and the system default policy, in that order.

Then the server looks through the policies for a reply-options list. It looks for bootp- or dhcp-reply-options depending on the client. The server uses the first list it finds. For each option in the list, the server looks through all of the policies, in order, and returns the data from the first policy that has a matching option. There is no requirement that the data that the server returns must come from the same policy that the reply-options list came from. If the server finds a reply-options list, it looks for each option in the list individually, and searches all of the related policies if necessary.

There is also no requirement that the options mentioned in a reply-options list be present in the client-policy that contains the list. The nrcmd program allows you to type in a string and that string can name any option. The Network Registrar GUI, however, presents a special dialog box for adding a reply-options property to a client-policy. This dialog box restricts you to the options already configured in the client-policy. This is a GUI-only restriction; the server does not impose this restriction.

Client-Policy Option Method Commands

You can set individual option values with the setOption command, unset option values with the unsetOption command, and view option values with the getOption and listOptions commands. When you set an option value the DHCP server replaces any existing value or creates a new one, as needed, for the given option name.

Note   For a list of all the DHCP options that you can configure, type the nrcmd program help dhcp-option command.

The syntax is:

Table 2-8 lists and describes the client-policy command option methods.

Table 2-9 describes the properties of the client-policy option method properties.

Examples

To specify the lease time for a client, enter:

nrcmd> client-policy 168.1-net setOption dhcp-lease-time 608400

 

To list the options in a client-policy, enter:

nrcmd> client-policy 168.1-net listOptions

Client-Policy Lease Time Method Commands

The setLeaseTime command allows you to set the values of lease times and the getLeaseTime command to display the value of a lease time.

The syntax is:

The lease time is the value of the dhcp-lease-time DHCP option. You should specify the time in seconds.

Lease Times

A client policy contains two lease times: the client lease time and the server lease time.

• You set the client policy lease time through the setLeaseTime method. This lease time determines how long the client policy believes its lease is valid.
  
  
• You set the server lease time through server-lease-time property. This lease time determines how long the server considers the lease valid. Note that the server lease time is independent of the lease's grace period; that is, the server will not allocate the lease to another client until after the server's lease period has expired and the grace period has expired.
  
  

You might want to establish these two different lease times if you want to retain information about clients' DNS names and yet have them renew their leases frequently. When you use a single lease time and it expires, the server no longer keeps that client's DNS name. If, however, you use a short client lease time and a longer server lease time, the client information is retained even after the client's lease has expired.

Custom-Option

The custom-option command allows you to create, list, or delete a custom DHCP option.

You can also use the custom-option command to redefine any predefined DHCP options. The newly defined option's definition will override the original option. If you delete this option, its definition returns to its original value.

The syntax is:

Table 2-10 lists and describes the custom-option command properties.

Option Data Types

Table 2-11 lists the option data types supported by the nrcmd program.

Examples

To create a custom option called red, mapped to number 100, of type IPADDR, enter:

nrcmd> custom-option red create 100 IPADDR

 

To create a custom option called blue, mapped to number 101, that is an array of bytes, enter:

nrcmd> custom-option blue create 101 BYTE_ARRAY

 

To give custom-option blue a description, enter:

nrcmd> custom-option blue set desc="this is another option called blue." 
 

To create a custom-option that overlays pre-defined option 2 (time-offset), enter:

nrcmd> custom-option green create 2 INT desc="Option green overlays time-offset." 

 

Note   We recommend that you do not create case-sensitive option names; for example, if you create a custom-option named BLUE, then reference it as blue in another command, the option will not work. It is better to name your options consistently with lowercase letters.

To list the custom-options you have created, enter:

nrcmd> custom-option list 

 

To cause option 2 to revert to its original definition, enter:

nrcmd> custom-option green delete 
 

To redefine the time-offset option to change its name, enter:

nrcmd> custom-option TimeOffset create 2 INT 

 

To display the option's new definition, enter:

nrcmd> custom-option TimeOffset show 

 

Do not map numbers to custom options that are already used by DHCP or BOOTP options. For a complete list of pre-assigned numbers, see the "Import Leases" section in this guide.

Dhcp

The dhcp command allows you to configure the DHCP server in the cluster. Because there is only one DHCP server per cluster, you do not need to reference the server by name.

The syntax is:

Table 2-12 lists and describes the dhcp features.

Defer-lease-extensions

You might want to use the defer-lease-extensions feature to reduce the number of writes to the Network Registrar database. These writes can occur because the Network Registrar DHCP server commits fresh information to the database any time it changes the duration of a client's lease. Because the DHCP server renews leases for the full lease interval every time the client contacts the server, these database writes may have a performance impact if the server is on a busy network.

Some database writes can be eliminated if the data being written is redundant, that is, the same as the old data. Instead of granting the full lease duration, the server can re-grant the lease with a new duration equal to the remaining time on the old lease. Because the absolute expiration time does not change, no database write is needed.

There are three cases of lease extensions to consider:

• Extensions due to client retries—When the server gets behind, it is possible for a client to retransmit requests. The DHCP server does not maintain enough information to recognize these as retransmissions, and processes each to completion, regranting a full lease duration and updating the database. When the server is already behind, doing extra work just makes the situation worse. To prevent this, the DHCP server will not extend leases that are less than 30 seconds old, regardless of the state of the defer-lease-extensions feature.
  
  
• Extensions due to client reboots—The effective renew time for a client's lease is really the minimum of the configured renew time and the time between client reboots. In many installations this may mean that clients are getting fresh leases one (in a typical enterprise) or two (in a typical cable network) times per day, even if the renew time is set for many days. Setting the defer-lease-extensions feature can prevent these early renews from causing database traffic.
  
• Extensions due to artificially short renewal times—Because there is no way for a DHCP server to proactively contact a DHCP client with regard to a lease, you might configure fairly short client renewals to provide a means of doing network renumbering, address re-allocation, or network reconfiguration (for example, a change in DNS server address) in a timely fashion. The goal is to allow you to do this without incurring unacceptable database update overhead.
  
  

As a complication, the server also keeps track of the time at which it last heard from the client. Known as "last-transaction-time," this information is sometimes used by sites as a debugging aid (for example, "How long has it been since we've heard from Beth's PC?"). Maintaining this time robustly requires a write to the database on every client interaction. For more information about this property, see the "last-transaction-time-granularity" section.

Because the last-transaction-time is not integral to the protocol, it does not have to be updated synchronously. Also, because it is used primarily as a debugging aid, it does not have to be entirely accurate. Furthermore, because the in-memory copy is always accurate, you can use the export leases -server command to display the current information even if the data is not up-to-date in the database. For more information about the export leases command, see the "Export Leases" section.

Import-mode

You can put the DHCP server into import mode by enabling the import-mode feature and then restarting the server. You take the server out of import mode by disabling the feature and restarting the server. You can use import-mode to exclude all DHCP lease requests except for the specially tagged ones that come from the nrcmd program during lease import. For more information about the import command, see the "Import Leases" section.

Examples

To enable the client-class facility for this DHCP server, enter:

nrcmd> dhcp enable client-class

 

To disable import mode, enter:

nrcmd> dhcp disable import-mode

 

To display whether discover-interface is enabled or disabled, enter:

nrcmd> dhcp get discover-interfaces

Dhcp Properties

Use the set, get, unset, and show commands to assign and retrieve values from the DHCP's name-value properties.

The syntax is:

Table 2-13 lists and describes the dhcp command properties.

Property	Description
activity-summary-interval	If the log setting flag activity-summary is set, then activity-summary-interval specifies the time between activity summary log messages. The default is 5 minutes.
append-user-class-id-to- selection-tag	Meaningful only if the value of map-user-class-id is 1. When true, this property causes the user class-id to be appended to existing selection tags. When it is false, the user class-id replaces any existing selection tags. The default is true.
collect-performance-stats	Controls whether the DHCP server collects statistics for performance monitoring. The default is disabled.
dns-timeout	Controls the number of milliseconds the DHCP server will wait for a response before retrying a dynamic DNS request. Required. The default is 60000.
docsis-version-id-missing	Specifies a string that gets substituted with the %@docsis-vers% variable in the policy command's boot-file property. This substitution occurs if the DHCP request packet either does not contain a vendor-class-id option or if the option does not contain a DOCSIS version id. Optional. There is no default. The string can contain 255 characters.
drop-old-packets	Specifies the number of seconds a packet can age and still be processed. If the server is very busy, the processing of packets in the UDP input queue can be delayed. The DHCP protocol allows clients to retry packets that have not been processed within a few seconds. Therefore, allowing the server to process packets that are older than a small number of seconds could increase the congestion. If the age of a packet is greater than the value of drop-old-packets when the server processes it, the server drops the packet. The default value is 8 seconds.
extension-trace-level	Is the default value of the extension trace level for every request object. You can override this value by setting the extension-trace-level in a user-written extension. Setting the level to zero causes very little tracing. Setting the level to three causes considerable tracing. Optional. The default is 0. For more information about DHCP extension creation, see the "Extension Properties" section.
failover-backup-percentage	The percentage of currently available (unreserved) addresses that the main server should send to the backup server to be used for allocations to new DHCP clients when the main server is down. The value is only meaningful in the main server. If it is defined in a backup server, it is ignored (to enable copying of configurations). Optional. The default 10 percent.
failover-backup-server	If failover is enabled server-wide, this is the DNS name of the backup server associated with all scopes that do not have an explicit failover-backup-server value configured. If this DNS name resolves to the IP address of the current server, then this server operates as the backup server for all of these scopes. It is an error if both the main and backup server names resolve to IP addresses that reside on the same server. Optional. There is no default.
failover-bulking	Controls whether multiple lease state updates are contained on one failover BNDUPD. Affects only the lease state updates generated by DHCP client activity.
failover-dynamic-bootp-backup- percentage	The percentage of currently available (unreserved) addresses that the main server should send to the backup server for scopes on which dynamic BOOTP has been enabled. Optional. There is no default. For more information, see the "Failover-backup-percentage" section.
failover-lease-period-factor	Is the multiple of the desired lease period used to update the backup server when the main server informs it of a new DHCP client lease period. The default is 1.50. For more information, see the "Failover-lease-period-factor" section.
failover-main-server	If failover is enabled server-wide, this is the DNS name of the main server associated with all scopes that do not have an explicit failover-main-server value configured. If this DNS name resolves to the IP address of the current server, then this server operates as the main server for all of these scopes. It is an error if both the main and backup server names resolve to IP addresses that reside on the same server. Optional. There is no default.
failover-maximum-client-lead-time	The maximum client lead time, in seconds. Optional. The default is 3600 seconds (one hour). The maximum client lead time controls how much ahead of the backup server the client's lease expiration can be. You must define it in the main server. If you define it in the backup server, it is ignored (to enable copying of configurations).
failover-poll-interval	Failover partners will poll one another at this interval (in seconds) in order to confirm network connectivity. Optional. The default is 15 seconds.
failover-poll-timeout	The interval (in seconds) after which failover partners, who cannot communicate, will know that they have lost network connectivity. Optional. The default is 60 seconds.
failover-recover time	Controls whether the server performs initialization and then goes into RECOVER state. If server A is running, server B issues this command to ask for the state of server A. This property takes a time argument. You enter the time as month (name or its first three letters), day, hour (24 hour) year (fully specified year or last two digits), all enclosed in double quotes. For example, "Jun 30 20:00:00 2000."
failover-safe-period	This is the safe period, in seconds. It does not have to be the same on both main and backup servers. It only has meaning if you have enabled the failover-use-safe-period property. You must define it in the main server. Optional. The default is 24 hours. For more information, see the Network Registrar User's Guide.
failover-use-safe-period	If you have specified a failover-safe-period, you have to enable the failover-use-safe-period property to cause Network Registrar to go into the PARTNER-DOWN state automatically. If you do not enable failover-use-safe-period, Network Registrar will never go into the PARTNER-DOWN state automatically. You must use the server dhcp setPartnerDown command. Optional. The default is disabled. For more information, see the "setPartnerDown" section.
get-subnet-mask-from-policy	Causes the DHCP server to search all relevant policies for a subnet mask option, when constructing a response to send to a client. Normally, the DHCP server retains the subnet mask configured in the scope containing the base being granted to the DHCP client. Optional. The default is false. For more information, see the "Examples" section and the Network Registrar User's Guide.
ignore-requests-for-other-servers	Prevents the normal DHCP server response to requests for other servers. Normally, if the DHCP server sees a client requesting a lease from another server for an IP address that this server is configured to control, it sets the lease to UNAVAILABLE. However, some clients may send request packets with bad server ID options (rather than packets actually directed to other servers). This could cause IP addresses to be erroneously considered unavailable. You can set the ignore-requests-for-other-servers property to prevent the server from changing leases to UNAVAILABLE when they are requested of another server (or have bad server ID options).
inhibit-busy-optimization	Prevents the server from using optimization to recover from periods of congestion. By default, the DHCP server determines that it is heavily loaded when the number of request packets reaches two-thirds of the total allocated. It logs a message and attempts to recover from the congestion by performing several optimizations. For example, it relaxes the requirement to keep the client's last transaction time updated to the granularity specified by last-transaction-time-granularity. When the number of request packets drops to one-third of the total allocated, the server logs a message and returns to normal operation. If the inhibit-busy-optimization property is set, the server does not use the optimizations or log the messages when it gets congested.
ldap-mode	Determines the preference for using LDAP servers if more than one LDAP server is configured. The servers can operate in two modes: round-robin and failover. If you set the mode to round-robin, the DHCP server ignores the servers' preferences. That is, it treats all LDAP servers—those configured to handle client queries and those configured to accept lease-state updates—equally. If you set the mode to failover, the DHCP server uses the active LDAP server with the lowest preference. If the preferred server loses its connection or fails, the DHCP server uses the next LDAP server in preference order. The DHCP server uses servers with equal preference in round-robin order. Optional. There is no default.
last-transaction-time-granularity	Specifies the number of seconds Network Registrar guarantees that the last transaction time is accurate. Optional. The default is 30 seconds. Do not set it lower than 30 seconds. For optimal performance, set it to a value that is greater than half of your lease interval. For more about this property, see the "Defer-lease-extensions" section.
log-settings	Determines which events are logged in the log files. Logging additional detail about events can be helpful when you are analyzing a problem. But leaving detailed logging enabled for a long period can cause the log files to fill up. Refer to the "Log Settings" section for information about how to control what type of events are logged. The default flags are default, incoming-packets, and missing options.
map-user-class-id	Determines the handling of user class-id. This property is global and is set for all DISCOVER packets. The values are: 0 = ignore the user class-id option. (default) 1 = map the user class-id option to selection-tag. 2 = map the user class-id option to client-class.
max-dhcp-requests	Controls the number of buffers the DHCP server allocates for receiving packets from DHCP clients and failover partners. At least 100 buffers should be allocated and perhaps as many as several thousand would be reasonable in some installations. Required. The default is 500.
max-dhcp-responses	Controls the number of buffers the DHCP server allocates for responding to DHCP clients and communicating with failover partners. The number of buffers allocated should be at least two times the number allocated for max-dhcp-requests. Perhaps as many as several thousand would be reasonable in some installations. Required. The default is 1000. The server will configure additional responses if failover is configured.
max-dns-packets	Controls the size of buffers DHCP allocates for communication with DNS servers. You can reduce the DHCP server's memory requirement by reducing the number of DNS packets, at the risk of missing updates. Required. The default is 100.
max-dns-renaming-retries	Controls the number of times the DHCP server can try to add a host into DNS even if it detects that the host's name is already present in DNS. This field controls the number of times the DHCP server will attempt to modify a host's name to resolve a conflict. Required. The default is 2.
max-dns-retries	Controls the number of times the DHCP server attempts to add a host to the DNS server even if it detects that the host's name is already present. Required. The default is 3.
max-dns-ttl	Sets the Time To Live (TTL) ceiling, in seconds, for DNS records added through dynamic DNS. When the DHCP server adds a DNS record, it sets the TTL to less than one-third of the lease time, or this ceiling value. Note that the DNS record's effective TTL may be determined by the DNS zone's minimum TTL. Required. The default is 86400.
max-ping-packets	Sets the number of buffers that the server will allocate for sending and receiving ICMP ping messages. Optional. There is no default. For more information about the scope's ping-client's feature, see the "Scope Features" section.
max-waiting-packets	Sets the number (n) of packets that are allowed to wait for processing for a particular IP address. Only the most recently received n packets (of an IP address) are queued for processing. If an additional packet associated with that IP address arrives and n are already queued, the oldest packet is dropped and the new one is queued. Duplicate packets are also dropped. (A duplicate packet is any packet whose XID, client-id, and MAC address are equivalent to one already queued.) If you accept the default of 0, all packets are processed. Optional. Note   The log setting `dropped-waiting-packets' will control whether a message is logged when these packets are dropped. For more information about this log setting, see "Log Settings" section.
mcd-blobs-per-bulk-read	The number of blob objects to be read by a bulk read. This parameter is used to tune DHCP start and reload times. Generally, a higher value results in faster server start and reload times, at the cost of using more memory. Values can be any number between 1 and 2500.
return-client-fqdn-if-asked	Controls whether the system returns the client-FQDN (Fully Qualified Domain Name) option to the client in the outgoing packet if the client requests it in the parameter request list. (For example, the client may want to know the status of the DNS activity.) Optional. The default is true. Note   The system always sets the flags in the option to 0x3 and the RCODE1 and RCODE2 to 255. It also sends back whatever string was sent in, even if the use-client-fqdn property is turned off and no matter what the actual name is in DNS (or may ultimately be in DNS).
save-lease-renewal-time	Specifies whether the server saves the lease renewal time. If you set it to true, the server saves the lease renewal time (that is, the minimum time in which the client is expected to issue a lease renewal) as part of the lease in persistent memory. The default is false. (no saving of the lease renewal time).
save-vendor-class-id	Specifies whether the server saves the vendor-class-identifier. If you set it to true, the server saves the vendor-class-identifier as offered in the DHCP request's vendor-class-identifier option as part of the lease in persistent memory. This affects what can be stored in an LDAP directory. Optional.The default is false (Do not save the vendor-class-identifier.).
skip-client-lookup	If true, this property causes the DHCP server to skip looking up the client entry for client class processing. When you set this property to false, the DHCP server looks up the client entry first. The default is false.
scope-selection-tags	The list of scope selection tags associated with this server property. In this context, the term tags refers to a named entity that is used to control matching client and client-class entries with candidate scopes. There is no default.
sms-lease-interval	Used to set the time interval, in milliseconds, between sending addresses to SMS. After you install a future release of Microsoft BackOffice Resource Kit (which will contain an enhanced version of smsrsgen.dll), reduce this interval or set it to 0. Optional. The default is 1100.
sms-library-path	Overrides the internal default value for the name of the SMS dll. The default is the empty string. If you specify an empty string, the system defaults to the internal server default of smsrsgen.dll.
sms-network-discovery	Causes the DHCP server to generate SMS (System Management Server) network discovery records. To enable this property, set it to 1; to disable it, set it to 0. Use this property in conjunction with the server DHCP updateSms command. The default is 0. For more information, see the "Server" section.
sms-site-code	Specifies the site code of the SMS server that receives discovery records when you issue the updateSms command. Optional. There is no default. This property has to be initialized to the appropriate SMS site code for the updateSms command to operate.
use-client-fqdn	Specifies that the system is to examine the client-FQDN (Fully Qualified Domain Name) option for the hostname. If there are any characters after the first dot in an FQDN option, they are ignored because the domain is determined from the scope. Set this property to false if you do not want the server to determine a hostname from this option, possibly because the client is sending unexpected characters. Optional. The default is true.
use-client-fqdn-first	Specifies that the system is to examine the client-FQDN option on incoming packets first, before the host-name option, when determining a hostname for a client. If there is a client-FQDN option with a hostname specified, the system uses that hostname. If the system finds no client-FQDN option in the incoming packet, the system uses the host-name option. If the use-client-fqdn-first parameter is set to false, the system examines the host-name option first and use any name found in that option. If that option does not appear, it then examines the client-FQDN option for a host name. Optional. The default is true.
use-host-name	Specifies that the system examines the host-name option for the hostname. Set this property to false if you do not want the server to determine a hostname from this option, possibly because the client is sending unexpected or "junk" characters. Optional. The default is true.

Examples

To set the value of the get-subnet-mask-from-policy property, enter:

nrcmd> dhcp set get-subnet-mask-from-policy=true

 

To enable SMS network discovery and specify the site code of the SMS server as aic, enter these commands:

nrcmd> dhcp set sms-network-discovery 1

nrcmd> dhcp set sms-site-code aic

nrcmd> server DHCP reload

nrcmd> server DHCP updateSms

Configuring the sms-library-path Property

When you install the Microsoft BackOffice Resource Kit, the system path is not updated to reflect the location of the SMS dll. Use one of the following methods to configure this property: setting the property to the relative path or setting it to the absolute path.

Setting the Property to the Relative Path

To set the property to relative path, follow these steps:

<sms installation directory name>\diagnose
 

Step 2   Set this property to the name of the dll.

nrcmd> dhcp set sms-library-path "smsrsgen.dll"

 

or just accept the system default:

nrcmd> dhcp unset sms-library-path

Setting the Property to the Absolute Path

If you do not want to change the system path, enter the following command to set this property to the absolute path of the dll location:

nrcmd> dhcp set sms-library-path "\\Program Files\\Resource 
Kit\\sms\\diagnose\\smsrsgen.dll"

Failover-backup-percentage

For all servers or scopes for which you have enabled failover, you must set the failover-backup-percentage. This is the number of currently available (not reserved) leases that the backup server can use for allocations to new DHCP clients when the main server is down. You can use the default, which is 10 percent, or specify another value.

For scopes on which you have enabled dynamic BOOTP, you need to use the failover-dynamic-bootp-backup-percentage property rather than the failover-backup-percentage property. The failover-dynamic-bootp-backup-percentage is the percentage of available addresses that the main server should send to the backup server for use with BOOTP clients.

Note   You must define this percentage on the main server. If you define it on the backup server, Network Registrar ignores it (to enable duplicating configuration through scripts). If you do not define it, Network Registrar uses the default or specified failover-backup-percentage.

The failover-dynamic-bootp-backup-percentage is distinct from the failover-backup-percentage property, because if dynamic BOOTP is enabled on a scope, a server will never, even in PARTNER-DOWN state, grant leases on addresses that are available to the other server. Network Registrar will not grant leases because they may be given out by the partner using dynamic BOOTP, and can never safely be assumed to be available again.

To properly support dynamic BOOTP while using the failover protocol, do the following on every LAN segment in which you want BOOTP support:

• Create one scope to be used for dynamic BOOTP
  
  
• Enable BOOTP and dynamic BOOTP
  
  
• Disable DHCP for that scope
  
  

For more information, see the Network Registrar User's Guide.

Failover-lease-period-factor

The client and the backup server can have different information about a lease expiration. The failover-lease-period-factor controls how much ahead of the client the backup server's lease expiration information can be. Whereas, the failover-maximum-client-lead-time controls how much ahead of the backup server the client's lease expiration information can be.

The larger the value, the more independent the main server is of the operation of the backup and the less performance impact the failover protocol has on the main server. However, the larger the value, the longer the backup will have to wait to time-out an expired lease and re-use it for a different client in the event that the main fails and the backup takes over DHCP functions.

• If you specify a value of 1.00, it would be the same as the lease period that the main would give the DHCP client. If you do this, the main server will never be able to offer any client a lease time or lease extension of more than the maximum client lead time.
  
  
• If you specify a value of 2.0, it would be twice the lease period the main would give the client.
  
  

You must define this property for the scope in the main server. If it is defined in a backup server, it is ignored (to enable duplicating the configurations through scripts). The default is 1.5 which is a good value for most sites.

The lease period interacts with the lease renewal period. If you increase the lease renewal period to a value greater than 50 percent, you must also increase the lease factor. There should be a ratio of 2:1 between the renewal and lease factor. For example if you increase the renewal time to 80 percent the lease factor should be 1.8.

Log Settings

Table 2-14 describes the flags that can be set with the log-settings property.

Examples

To suppress warning messages for unconfigured or missing options, enter:

nrcmd> dhcp set log-settings=default,incoming-packets

nrcmd> server dhcp reload

 

To turn on client and client-class debugging for the DHCP server, enter:

nrcmd> dhcp set log-settings=client-detail

nrcmd> server dhcp reload

 

To turn off debugging for the DHCP server, enter:

nrcmd> dhcp set log-settings=default

nrcmd> server dhcp reload

DHCP Extension Methods

Use the method commands attachExtension, detachExtension, and listExtensions to configure extensions to run at the supported extensions points for the DHCP server. (See Table 2-15.) You can configure one or more extensions to be run at each extension point. If multiple extensions are configured for a given extension point, the order in which they execute can be controlled by specifying a sequence number when attaching each extension. For more information about extensions, see the "Extension" section.

• The attachExtension method sets the specified extension point to call the named extension. If the extension point is already configured to call an extension, use the sequence property to specify the order in which extensions are executed (1, 2, 3,...). If you do not specify a sequence number for the extension you are adding, Network Registrar overwrites the existing extension with the new value.
  
  
• The detachExtension method removes extensions from the specified extension point. If you do not include a sequence number when specifying the extension point, Network Registrar removes the extension at sequence number 1. Otherwise, it removes the extension at the specified sequence number.
  
  
• The listExtensions method shows the currently configured extensions and their sequence numbers (if multiple extensions are configured) at each extension point.
  
  

The syntax is:

Note   It is recommended that you run listExtensions for an extension point before attaching a new extension. Check the result to ensure that the new extension has a different sequence number than any existing extensions.

Extension Points

Table 2-15 summarizes the extension points available to the DHCP server.

Extension points are discussed in more detail in Chapter 4 and Appendix D of this guide.

Examples

After you have defined an extension, use the attachExtension command to add the test extension at the extension point post-packet-decode by entering:

nrcmd> dhcpattachExtension post-packet-decode test 1

 

To remove the extension test from the extension point post-packet-decode, enter:

nrcmd> dhcp detachExtension post-packet-decode

 

To list all the extensions points and any extensions associated with them, enter:

nrcmd> dhcp listExtensions

DHCP Forwarding

You can forward DHCP traffic from one DHCP server to another under the control of a Network Registrar extension. The DHCP forwarding feature is important in situations where the other server is not one that you manage. This is most likely to occur in environments where multiple vendors supply DHCP services for clients on the same virtual LAN.

The DHCP forwarding feature works in the following way:

As the DHCP server processes these scripts, it checks the environment dictionary for this string:

cnr-forward-dhcp-request

cnr-request-forward-address-list

It expects a list of comma-separated IP addresses with an optional colon-delimited port number, as in the following example:

192.168.168.15:1025,192.168.169.20:1027

By default, the server forwards to Port 67. It sends a copy of the entire client request to each IP address and port in turn. If any element in the list is invalid, the server stops trying to parse the list.

For more information about extension points, see the"Extension" section.

Other dhcp Commands

Other commands affecting the DHCP server, such as

are described in "Server Commands" section.

Troubleshooting MAC Addresses

As an additional aid to troubleshooting your configuration, you can use the example extension, dextrace, distributed on the Network Registrar CD-ROM. It looks for a particular MAC address in every input packet. When it finds that MAC address, it enables packet sniffing for just that input and any corresponding output packet. You can configure this extension using the CLI, and the configuration commands are in the example source file for dexextension.c. This extension places only a very small load on the server and is suitable for long-term use when trying to diagnose a DHCP problem in which a troublesome MAC address is known, but it is not possible (or perhaps not convenient) to manually stimulate that DHCP client directly to find the problem.

Dhcp-interface

The dhcp-interface command allows you to add, remove, and list the IP addresses of your server's hardware card (such as Ethernet or Token Ring), also called the Interface card. Interfaces are named with the IP address and net mask for the physical device.

Network Registrar uses the distinguished interface named default to provide configurable default values for interfaces that the DHCP server discovers automatically. If you delete the default interface, the DHCP server uses hard-coded default values for port numbers and socket buffer sizes for the interfaces that it auto-discovers.

You can list the interfaces to provide either an explicit list of interfaces that the DHCP server should listen on, or an explicit list of interfaces that the DHCP server should not listen on.

• If you enable discover-interfaces, the DHCP server uses the OS platform support to enumerate all of the active interfaces on the machine, and (unless there is an interface configuration with the ignore feature enabled) attempts to listen on each of these.
  
  
• If you disable discover-interfaces, the DHCP server consults the interface list for all interfaces that do not have the ignore feature enabled, and attempts to listen on each of these.
  
  

The dhcp-interface command provides more functionality than is provided through the GUI, and provides it in a different form:

• The GUI allows you to specify the address and netmask of only one address to use, and it does not allow you to modify any of the interface properties.
  
  
• The GUI displays the address and net mask of the first non-default interface that has been configured, and allows you to change the address and netmask for this interface.
  
  

The syntax is:

The maskbits parameter defined for scopes can be specified as 24 (for a 24-bit network, such as a 255.255.255.0 netmask) or 16 (for a 16-bit network, such as a 255.255.0.0 netmask).

Table 2-16 lists and describes the dhcp-interface command properties.

Examples

To create two different interface configurations, enter:

nrcmd> dhcp-interface 192.168.1.12/24 create 

nrcmd> dhcp-interface 10.1.2.3/24 create

 

To cause Network Registrar not to look at one interface, enter the following. Note that you must have created the interface specification before you can set it to be ignored.

nrcmd> dhcp-interface 10.1.2.3/24 set ignore=true

 

To delete the interface specification 10.1.2.3/24, enter:

nrcmd> dhcp-interface 10.1.2.3/24 delete

 

To list all the specified interfaces, enter:

nrcmd> dhcp-interface list

Dns

The dns command allows you to enable or disable DNS server features. Note that in Network Registrar there is only one DNS server per cluster, hence you do not need to reference the server by name.

The syntax is:

Table 2-17 lists and describes the dns command features.

Incremental Transfer

The incremental transfer feature (ixfr-enable) allows you to control how your DNS server handles incremental transfer. If you enable incremental transfer, you need to set or accept the default value of the ixfr-expire-interval property.

Table 2-18 describes the ixfr-expire-interval property of the incremental transfer feature (ixfr-enable).

AXFR Workaround

When BIND 8.2.2p5 responds to an IXFR query, it erroneously returns the value AXFR (full zone transfer) in the Question field of the response packet. By default, Network Registrar adheres to RFC 1995, so it expects the value IXFR in that field and, therefore, rejects the BIND 8.2.2p5 response of AXFR. You can relax the IXFR query validation check by entering the following:

nrcmd>dns enable relax-ixfr-query-validation

 

Network Registrar then allows IXFR responses with either an IXFR or AXFR in the Question field.

Examples

To enable incremental transfer for all your zones, enter:

nrcmd> dns enable ixfr-enable

 

To disable incremental transfer for the single secondary zone example.com, enter:

nrcmd> zone example.com disable ixfr

 

To disable incremental transfer for the single remote-dns server (or subnet) 128.103.1.1, enter:

nrcmd> remote-dns create 128.103.1.1 ixfr=false

 

For more information about setting incremental transfer on specific zones or remote DNS servers, see the "Zone" section or the "Remote-dns" section.

Notify

The notify feature enables a Network Registrar DNS master server to inform its slave servers that changes have been made to its zone. The changes are not communicated in the NOTIFY packet. Instead, the slave servers initiate a zone transfer in response.

Because a master server for a zone does not know specifically which slave servers transfer from it, Network Registrar notifies all registered name servers for the zone (name servers listed in the NS Resource Records) when the zone changes. The sole exception to this policy is that Network Registrar does not notify the server named in the SOA mname field (the primary master). For more information about NOTIFY, see RFC 1996.

If you enable the notify feature, you must set or accept the defaults for the properties listed in Table 2-19.

Examples

To disable NOTIFY for all the zones, enter:

nrcmd> dns disable notify

 

You can use IXFR and NOTIFY together, but you do not have to. You might want to disable NOTIFY for a quickly changing zone for which immediate updates on all secondaries does not warrant the constant NOTIFY traffic. Such a zone might benefit from having a short refresh time and a disabled NOTIFY.

nrcmd> zone example.com set refresh=30m

nrcmd> zone example.com disable notify

 

For more information about setting zone properties, see the "Zone" section.

Dns Properties

Use the set, get, and unset commands to assign and retrieve values from the DNS server's name-value properties.

The syntax is:

Table 2-20 lists and describes the dns command properties.

Default TTL Responses

Network Register responds to authoritative queries with an explicit TTL value, if one exists. If none exists, the default behavior is to use the value of defttl, which is the default TTL for the zone. Databases originating from earlier versions of Network Registrar do not have this zone attribute. Therefore, they use the minimum TTL, as defined in the SOA of the zone, for the default TTL when there is no explicit TTL.

Enabling the enforce-min-ttl property causes Network Registrar to use the minimum TTL instead of the default TTL. In this configuration, Network Registrar uses minttl, the minimum SOA TTL, as the default for resource records with no TTL values. Additionally, it uses minttl as a floor value. That is, resource records that have explicit TTL values that are smaller than the minimum SOA TTL assume the value of the minimum SOA TTL.

When the enforce-min-ttl property is disabled, Network Registrar assumes the default TTL when responding with a zone transfer with resource records that do not have explicit TTL values. If the default TTL value for the zone is administratively altered, then Network Registrar automatically forces a full zone transfer to any secondary requesting a zone transfer.

TTL in BIND Zone Exports and Imports

When Network Registrar receives a BIND zone export request, it records the default TTL for the zone in a BIND directive ($TTL). The value of the directive is determined by the rules described in the "Default TTL Responses" section.

Network Registrar also recognizes $TTL directives for BIND imports. The first $TTL directive it encounters serves as the default TTL for the zone. This value is assigned to defttl for future use. Subsequent $TTL directives do not override the first directive; that is, they do not change the default TTL for the zone. Instead, they provide the TTL for subsequent resource records that have no explicit TTL values. Subsequent resource records that have no TTL assume the TTL stated in the most recently encountered $TTL directive. For example, the BIND zone file shown here:

$ORIGIN c.
@ IN SOA ns joe 10 10800 3600 604800 7200
$TTL 3600
z IN A 1.2.3.4
$TTL 7200
y IN A 1.2.3.5
x 1800 IN A 1.2.3.6
$TTL 9800
w IN A 1.2.3.7
t 13400 IN A 1.2.3.8

is imported as:

default TTL: 3600

c. IN SOA ns joe 10 10800 3600 604800 7200
z IN A 1.2.3.4
y 7200 IN 1.2.3.5
x 1800 IN A 1.2.3.6
w 9800 IN 1.2.3.7
t 13400 IN A 1.2.3.8

Notice that z does not have an explicit TTL value. Instead, it assumes the default TTL (3600). Also notice that Network Registrar assigns both y and w explicit TTL values based on the last encountered $TTL directives.

If the BIND zone file contains no $TTL directives, Network Registrar assumes the SOA minimum TTL value as the default TTL. For example, the zone file that follows is missing a $TTL directive:

$ORIGIN c.
@ IN SOA ns joe 10 10800 3600 604800 7200
z IN A 1.2.3.4
y IN A 1.2.3.5
x 1800 IN A 1.2.3.6
w IN A 1.2.3.7
t 13400 IN A 1.2.3.8

Network Registrar imports this file as:

default TTL: 7200

c. IN SOA ns joe 10 10800 3600 604800 7200
z IN A 1.2.3.4
y IN 1.2.3.5
x 1800 IN A 1.2.3.6
w IN 1.2.3.7
t 13400 IN A 1.2.3.8

Dns Methods

The dns method commands let you add, list, or remove specific servers for dealing with root-hint servers, exception servers, forwarding servers, and flushing the cache.

RootHint Method

The root hint method allows you to specify the names and addresses of the root servers. After you specify these servers, Network Registrar queries them for their root-name server records, which in turn are used to resolve other names. As such, these values need not be exact, but they need to be accurate enough for the Network Registrar DNS server to retrieve the correct information.

The syntax is:

Examples

To add the root name server a.root-servers.net, enter:

nrcmd> dns addRootHint a.root-servers.net 198.41.0.4

 

To remove the root name server a.root-servers.net, enter:

nrcmd> dns removeRootHint a.root-servers.net

 

To list the root name servers, enter:

nrcmd> dns listRootHints 

Exception Method

Use the exception method only if you do not want your DNS server to use the standard name resolution for querying root name servers for names outside the domain. The exception method allows you to specify the resolution exception domains and the associated servers' IP addresses.

The syntax is:

The resolution exception covers subzone delegations. If the global forwarding is set and a subzone is in the resolution exception list, the query for that subzone goes to the name server that appears in the exception list and not to the forwarder.

Note   In early versions of Network Registrar, when the global forwarding option is set, any query for the subzone delegation goes to the forwarder, not to the server that is authoritative for that subzone.

Examples

For example, the sample company, QuickExample, has four subsidiaries: red, blue, yellow, and green. Each of them has its own domain under the .com domain. But when users at red.com. want to use resources at blue.com, their DNS server knows that it is not authoritative for blue.com., and thus attempts to locate blue.com. by asking the root name servers.

To use exception handling, the administrator at red.com. lists all the domains that users might want to access, and at least one corresponding name server. In this case, the administrator would list the three other domains for the QuickExample company.

To add the exception server blue.com., enter:

nrcmd> dns addException blue.com. 192.168.1.4

 

To remove the name server blue.com., enter:

nrcmd> dns removeException blue.com.

 

To list the name servers, enter:

nrcmd> dns listExceptions 

 

Forwarder Method

The forwarder method allows you to specify the addresses of any name servers that you want your Network Registrar DNS server to use as forwarders. Network Registrar forwards recursive queries to these servers before forwarding queries to the Internet-at-large. Note that you can use the exception method to override forwarding for specific domains.

The syntax is:

Examples

To add the forwarder server 192.168.1.4, enter:

nrcmd> dns addForwarder 192.168.1.4

 

To remove the name server 192.168.1.4, enter:

nrcmd> dns removeForwarder 192.168.1.4

 

To list the forwarder servers, enter:

nrcmd> dns listForwarders 

Flushing the Cache

Use the dns flushCache command to stop the disk cache file from growing, but the actual behavior depends on whether your DNS server is running or stopped.

• If the DNS server is running, Network Registrar clears all expendable entries from the cache database file. Flushing the cache does not cause the file to shrink in size, due to the nature of the database, but does create free space within it. Because the memory cache is unaffected by this operation, recently in-use cache entries are not lost and performance is not significantly affected.
  
  
• If the DNS server is stopped, Network Registrar interprets the request to flush all entries and thus removes the cache database file. Network Registrar reinitializes the database when you restart the server.
  
  

To clear a cache that has grown too large, stop the server, enter the command, then restart the server.

The syntax is:

Rebuilding Resource Records Indexes

Use the dns rebuildRR-Indexes command if you need to rebuild your resource records indexes. You might need to rebuild your resource records indexes if you observe resource or host list data that appears inconsistent or if data appears to be missing. Rebuilding your resource records should correct any inconsistencies.

Note   The dns rebuildRR-Indexes command removes any duplicate resource records it finds in the database. A subsequent reload of the DNS server may produce the following diagnostic message: nrcmd> host_namenrcmd> zone_namenrcmd> This warning is to be expected in this case and you can safely ignore it.

The syntax is:

Exit

The exit command allows you to exit the current nrcmd program session. Network Registrar writes all your unsaved changes to the database. If Network Registrar is unable to save your changes, it displays the same error code as if you had used the save command.

The syntax is:

Example

To quit the Network Registrar command line interface when you are in interactive mode, enter:

nrcmd> exit

Export

The export command allows you to export Network Registrar DHCP and DNS server information.

• export addresses writes all IP addresses to a database or text file.
  
  
• export leases writes current and/or expired leases to a file
  
  
• export zone writes the specified DNS zone into a file in BIND format.
  
  
• export zonenames writes the names of the DNS server's forward and/or reverse zones to a file.
  
  
• export hostfile creates a hostfile in UNIX host file format.
  
  

The syntax is:

Export Addresses

The export addresses command allows you to export all active IP addresses into a specified database or CSV (comma-separated value) text file.

The syntax is:

To specify the clusters that you want the export command to query, use the .nrconfig configuration file. This is the same configuration file that the report command uses. If there is an [export-addresses] section in the configuration file, the export command uses the clusters specified in that section instead of the default cluster.

When you run the export addresses command, its output depends on what you specify:

• Specify file= to create a CSV text file.
  
  
• Specify database= to create a new database table in the specified database.
  
  
• Specify the table=option to use that table name; otherwise it uses the default table name of "ip_addresses."
  
  

If the table already exists in the specified database when you run the export command, it is cleared (and the columns reset) before the new data is written. Network Registrar does not provide a warning or confirmation if it clears an existing table.

• If you specify no option, it writes the output in CSV format to the standard output.
  
  

Note   You cannot specify both file= and database= in the same command.

The time-ascii and time-numeric options specify how date/time fields are output to a CSV text file or when the timestamp data type is not supported by the target database. The default is time-ascii.

Specifying the Config File

If you do not specify a config file, the export addresses 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 begin with the character # (comment), a section header enclosed in square brackets, or a parameter=value pair or its continuation.

[export addresses]
clusters=machine1 username password, machine2 username password [...]
 

Network Registrar strips leading white space from each line and ignores blank lines.

Specifying Clusters

You can specify cluster in a variety of ways and Network Registrar follows a precedence order. Any of the specific cluster specifications can override the default specification or previous specification.

• The default cluster (localhost).
  
  
• The UNIX environment or Windows NT registry variable AIC_CLUSTER.
  
  
• The -C flag on the command line allows you to specify a single cluster.
  
  
• The clusters property in the config file allows you to specify a group of clusters. For example, to specify clusters, enter the following in the .nrconfig file or other specified configuration file:
  

#Cluster information for export addresses

[export addresses] 

#clusters=<clustername> <username> <password>,...

clusters=host1 admin, host2, host3 admin3 passwd3

 

Separate cluster specifications with commas. Within each cluster specification, separate the three arguments with spaces. For long lines you can use continuation lines. You can embed carriage returns; you do not need to use continuation escape indicators.

You can optionally specify a user name and password for the cluster. If you do not provide a user name or password for a particular cluster, Network Registrar uses the last user name or password listed. If you do not provide user names or passwords, Network Registrar uses the information from the command line -N and -P arguments, and then the NT Registry or environment variables AIC_NAME and AIC_PASSWORD.

If Network Registrar cannot find a user name or password or the supplied user name and password are incorrect, the lease-notification command issues a warning for that cluster.

Reported Errors

The export addresses command attempts to establish communication with the clusters you have specified. It reports an error in the following cases:

• If the export addresses command cannot establish communication with any of the selected clusters, it issues messages on each cluster it could not reach and exits with the "101 OK, with warnings."
  
  
• If the export addresses command cannot connect to the database or manipulate the table, it reports "326 Database access error:" followed by the text reported by ODBC.
  
  
• If ODBC is not installed on the system, it reports "340 ODBC 3.x or higher required. ODBC not installed." If there is an incompatible version of ODBC preset, it issues the message, "340 ODBC 3.x or higher required. ODBC.y installed."
  
  

Note   If successful, the export addresses command prints "100 OK" both before and after Network Registrar lists the addresses. The first "100 OK" means that the command is being processed (without rejection because of existing locks, licensing problems, or command syntax errors). The second "100 OK" indicates that the command successfully completed its processing.

Data Format

The export addresses command writes the database output to the ip_addresses table or to the specified table name. Table 2-21 shows the columns in the ip_addresses table.

The fields listed as "May be NULL" are null if the specified information is not available:

• dns_name is NULL for a DHCP lease that is not bound to a DNS name
  
  
• requested_name, mac_address, client_id, client_class, lease_state_change_time, lease_expiration_time, and lease_transaction_time are NULL except for DHCP addresses
  
  

The mac_address field is a text field of the form type,length,hex:hex:hex..., such as "1,6,06:44:40:26:f5:0f". The type and length are both in decimal whereas the data is in hexadecimal.

Field data types that are not supported by the target database are replaced with text (varchar) fields with the form listed in Table 2-22:

Column names that exceed the target database's supported maximum name width are truncated to the allowable width.

CSV Text File

If you specify writing the output to a CSV text file, the export addresses command writes each line in the file as one row in the database. The export addresses command outputs each field to the text file in the order listed in Table 2-21. Each field is terminated by a comma, except for the last. The first line in the file is not a table row, but instead contains a "#" followed by the text of each of the column names separated by commas. All fields that require text substitution are handled as described in the previous section.

Note   The output is in no guaranteed order. The order can depend on the data in the system. Therefore, if order is important to you, use a tool to sort the data.

Addresses Reported

The export addresses command reports every address configured in every server that is specified in the config file. This includes addresses specified in DHCP scope ranges, DNS static addresses, and explicitly reserved addresses both for DNS and DHCP servers. Addresses in DHCP scope ranges that are not in use (allocated or reserved) however, do not appear in the table.

The report displays multiple entries for an address if the address is served by more than one server, in more than one scope, or has multiple DNS names. Thus, you cannot use a unique column as a key, but you can generate a unique key from a set of columns such as ip_address, type, cluster_name, scope_pool_name, or dns_name.

Export Leases

The export leases command writes the state of the leases to a file. It has two modes: client-side and server-side.

• The export leases -client command writes the state of all the current leases to the output file.
  

When you use the export leases -client command, Network Registrar reads the database. If the servers are running, system performance may be affected.

• The export leases -server command writes the state of all the current and expired leases to the DHCP server's log directory using the output file you specify.
  

When you use the export leases -server command, Network Registrar does not read the database, so it is significantly faster. You also can only run the command if the server is running. Because the server is doing some extra work while it is building the export file, it may be slowed somewhat, but the time involved is usually so short that the performance impact is not noticeable.

Note   Network Registrar exports the time values as day, month, date, time, year, for example, Mon Apr 13 16:35:48 1998. For more information about the file formats, see the "Import and Export File Formats" section in this guide.

The syntax is:

The filename is the name of output file or "-" for standard out for client-side exports. You cannot use the dash with the -server option. In addition, the server-side export does not permit filenames with any non-alphanumeric character, such as "." for example.

The time-ascii and time-numeric options control which date/time format the export command uses. The default is time-ascii.

Examples

To export the client leases to the output file leaseOut, enter:

nrcmd> export leases -client leaseOut 

 

The export leases -client command writes out the lease time as a string, which is the day, month, date, time, year format, such as Apr 13 16:35:48 1998.

To export all the currently held and expired leases to the output file leaseOut, enter:

nrcmd> export leases -server leaseOut

 

The export leases -server command writes out the lease times as integers, which are the number of seconds since midnight GMT Jan 1, 1970. For example, 903968580.

Export Zone

The export zone command writes the specified DNS zone into a file in the BIND format.

The syntax is:

• Arguments can be either "static" or "dynamic."
  
  
• output-file is the name of the file to create for the DNS zone data.
  
  
• domain-name is the name of the domain whose data you want to write to a file.
  
  

For example, to write the contents of the Example domain, enter:

nrcmd> export zone example.com static hosts.local 

Export Zonenames

The export zonenames command exports the names of the zones in the server. You can specify forward, reverse, or both to cause the command to export the forward zones, reverse zones, or all the zones, respectively.

The syntax is:

Export Hostfile

The export hostfile command creates a hostfile, in UNIX hostfile format, from all the zones in the server. It ignores reverse zones. It creates hostfile records from A records, CNAME records, and HINFO records. The hostfile record consists of the IP Address, the FQDN, aliases created from the A records and CNAME records, and comments created from HINFO records.

The syntax is:

Extension

The extension command allows you to configure and integrate user-written DHCP extensions into the DHCP server.

To extend the DHCP server with an extension, do the following:

UNIX:
For Tcl this is /opt/nwreg2/extensions/DHCP/tcl.
For C or C++ this is /opt/nwreg2/extensions/DHCP/dex

Windows NT:
For Tcl this is \program files\network registrar\extensions\dhcp\tcl
For C or C++ this is \program files\network registrar\extensions\dhcp\dex

It is best to place these extensions in the appropriate directory for TCL or C/C++ extensions. Then, when configuring the filename, just enter the filename itself (with no "/" or "\").

If you want to place extensions in subdirectories, you must enter the filename with a path separator. These are different depending on the operating system on which your DHCP server is running.

Note   When entering a filename that contains a "\" character on Windows NT, you must enter it with a "\" (because "\" is an escape character for the CLI). For example, to enter the filename "debug\myextension.tcl" enter debug\\myextension.tcl.

Step 2   Configure the DHCP server to recognize this extension, using the extension command.

Step 3   Attach the configured extension to one or more DHCP extension points using the dhcp attachExtension command. For more information about the command, see the "DHCP Extension Methods" section. For more information about choosing extensions points and writing extensions, see "Using Extension Points" in this guide.

Step 4   Reload the server.

Note   The DHCP server reads extensions only when you reload the server. So if you change an extension, you must reload the DHCP server.

The syntax is:

Example

To configure a Tcl extension, enter:

nrcmd> extension mytclext create Tcl mytclfile.tcl mytclentry

 

The contents of mytclfile.tcl might be:

proc mytclentry{request response environ}{
	$environ log LOG_INFO "helloworld"
}

Extension Properties

Use the set, get, and unset commands to assign and retrieve values from the extension's properties.

The syntax is:

Table 2-23 lists and describes the extension command properties.

Force-Lock

When you execute a nrcmd command, the program attempts to get an exclusive lock for the cluster to which it is connected. If it is unable to get an exclusive lock, it displays a warning. Without an exclusive lock, you can issue only the following commands: client, lease, zone add, help, and force-lock.

The force-lock command obtains an exclusive lock. Use this command with caution, because running more than one program that updates the Network Registrar database can cause database corruption.

If you use the force-lock command to unlock a cluster, the command writes the warning to the log file on the client machine, not on the cluster.

Example

To force an exclusive lock, enter:

nrcmd> force-lock

Help

The help command allows you to display the nrcmd program's online help.

• If you enter the help command without any arguments, Network Registrar displays a list of all the commands.
  
  
• If you specify the help command with an argument, Network Registrar displays the help page for the command of that name.
  
  

You can select the sections of the help page output by specifying the section names after the help cmd command. The section names are:

• SYNOPSIS—The valid syntax for the command
  
  
• DESCRIPTION—A textual description of the command behavior
  
  
• EXAMPLES—Examples of the command usage
  
  
• PROPERTIES—Descriptions of the features and properties
  
  
• STATUS—Description of the status codes returned by this command
  
  

The syntax is:

Examples

To print the list of commands, enter:

-> help 
100 Ok
 

To print the contents of the help man page, enter:

-> help help

100 Ok
 

To print the contents of the help command's synopsis, enter:

-> help help synopsis

100 Ok
SYNOPSIS
help 
help <cmd> [<section>...]

Import

The import command allows you to import lease information into the DHCP server configuration or import the contents of a BIND named.boot file into the DNS server configuration.

Import Leases

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

Step 2   If the host names for the leases are to be dynamically entered into DNS as part of the import, configure zones in the DNS server to allow dynamic updates. For more information, see the "Zone" section.

Step 3   Set the DHCP server to import mode so that it will not respond to other lease requests during the lease importing. For more information, see the "Dhcp" section.

Note   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 13 16:35:48 1998). For more information about the file formats, see the "Import and Export File Formats" section.

The syntax is:

Note   Importing permanent leases fails if you have disabled the permanent leases option.

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

Example

To import the file LeaseIn to the DHCP server, enter:

nrcmd> import leases LeaseIn

 

If the lease time in the import file is greater than the lease time that the client would have received if it were to acquire a lease using the DHCP server's existing configuration, the client is given the lesser lease time. In other words, suppose it is 2 p.m. and your scope is configured for a one hour lease. According to the file you are importing, the lease time will not expire until 5 p.m. After you import the file, the lease will expire at 3 p.m. and not at 5 p.m.

If your import file specifies a DNS zone name, the zone name will not be used when DNS is updated. If it specifies a host name, the host name will be used when DNS is updated, unless 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 placed in a zone other than the default associated with the scope is to specify that zone in a client or client-class entry.

Import Named.boot

BIND 4.x.x uses a boot file, called named.boot, to point the server to its database files. You can import your entire BIND 4.x.x configuration by using the import command. The import command does not import BIND 8.x.x named.config files.

The syntax is:

Example

To import the file /etc/named.boot to the DNS server, enter:

nrcmd> import named.boot /etc/named.boot

 

Note   You should use UNIX style pathnames even when running the import command on Windows NT.

The previous example on Windows NT might look like this:

nrcmd> import named.boot c:/etc/named.boot

 

When a zone file contains an $INCLUDE directive, BIND searches for the include file relative to the directory specified by the directory directive in the named.boot file, whereas the nrcmd program searches for the include file relative to the directory containing the zone file being processed.

To avoid this problem, ensure that the BIND configuration uses absolute paths whenever specifying an include file in a zone file. If your zone files contain relative paths when specifying include files and the directory containing the zone file is not the same as the directory specified by the directory directive in the named.boot file, your configuration will not load properly. You will need to convert the relative paths in your zone files to absolute paths to import your BIND configuration into Network Registrar. An example of a configuration and how it might be fixed follows.

Directory Hierarchy

/etc/named.boot

/usr/local/domain/primary/db.example

/usr/local/domain/primary/db.include

/usr/local/domain/secondary

Configuration Files

/etc/named.boot:

# BIND searches for zone files and include files relative to

# /usr/local/domain

directory /usr/local/domain

# BIND finds zone file in /usr/local/domain/primary primary

example.com primary/db.example

# end of /etc/named.boot

/usr/local/domain/primary/db.example

# BIND searches for include file relative to /usr/local/domain

$INCLUDE primary/db.include

# end of /usr/local/domain/primary/db.example

To make the configuration loadable, change the relative path in the file db.example to an absolute path.

$INCLUDE primary/db.include

$INCLUDE /usr/local/domain/primary/db.include

Mapping Boot File Directives to Nrcmd

Table 2-24 lists and describes the boot file directives that are supported by the BIND 4.9.6 distribution and the corresponding nrcmd command syntax that is generated. Directives that Network Registrar does not support are marked with the word unsupported, and the directives that require no action from Network Registrar are marked with the word none.

Table 2-24 lists the BIND to nrcmd commands mappings.

Ldap

The ldap command allows you to associate remote LDAP servers with Network Registrar and set their attributes.

The syntax is:

Examples

To create the LDAP server object myserver with a host name of myserver.mycompany.com, enter:

nrcmd> ldap myserver create myserver.mycompany.com

 

To delete an ldap server object myserver, enter:

nrcmd> ldap myserver delete

 

To list the ldap server objects, enter:

nrcmd> ldap list

Ldap Features

Use the enable, disable, or get commands to enable, disable, or determine whether the feature has been set.

The syntax is:

Table 2-25 lists and describes the ldap command features. After you enable a feature, you can set its properties.

Ldap Properties

Use the set, get, and unset commands to assign and retrieve values from the LDAP server's properties.

The syntax is:

Table 2-26 lists and describes the ldap command properties.

The dictionary associates with the create-string-dictionary property can contain multiple pairs of LDAP attributes. Each pair is set using a separate setEntry command. For example, to assign different string values to the attributes givenname and carlicense, enter:

nrcmd> ldap test-server setEntry create-string-dictionary givenname="abcdefg"

 
nrcmd> ldap test-server setEntry create-string-dictionary carlicense="123-456"

Ldap Dictionaries

Use the setEntry, getEntry, and unsetEntry commands to set, query, and clear elements of the various dictionary properties in the LDAP server configuration. These dictionary properties provide a convenient mapping from string keys to string values.

The syntax is:

Note   An LDAP attribute can appear only once in each dictionary. A second setEntry command that supplies an existing key will replace that key.

Table 2-27 lists and describes the ldap command dictionary properties.

Examples

To configure a query-dictionary to search for the surname (sn) and use its data to specify the client's DHCP host name, enter:

nrcmd> ldap dirserver setEntry query-dictionary sn=host-name

 

To configure a query-dictionary to search for the first name (givenname) to use for the specific client-class name, enter:

nrcmd> ldap myserver setEntry query-dictionary givenname=client-class-name

 

To configure a query-dictionary to search for the locality name to use for the domain name, enter:

nrcmd> ldap myserver setEntry query-dictionary localityname=domain-name

 

To create a string-dictionary with an attribute named myattribute assigned to a string named my string, enter:

nrcmd> ldap myserver setEntry create-string-dictionary

myattribute="my string" 

Lease

The lease command allows you to view and manipulate the current DHCP leases in the cluster.

The syntax is:

Table 2-28 describes the lease command actions. Table 2-29 describes properties that affect the lease list command.

All lease command actions take effect immediately. You do not need to reload the server.

Example

To activate lease 192.168.1.9, enter:

nrcmd> lease 192.168.1.9 activate 

Using the Lease Reservation Commands

send-reservation

Observe the following conditions when using the send-reservation command:

• Make sure the reservation already exists (at least in the nrcmd internal database).
  
  
• While the scope in which the reservation exists in nrcmd must already exist in the DHCP server, the particular IP address does not have to have appeared in the ranges for that scope.
  
  
• If you are using failover on the scope in which the reservation resides, issue the send-reservation command first to the backup and then to the main server. (Make sure that you have issued the scope add-reservation command to both systems first.)
  
  

Example

To create a reservation for IP address 192.168.1.9 and add it to the open cluster's database without reloading the DHCP server, enter these commands:

nrcmd> scope myscope addReservation 192.168.1.9 1,6,00:a0:24:2e:9c:20 

nrcmd> save 

nrcmd> lease 192.168.1.9 send-reservation 

Note   You should save the reservation (the second command in the example) to ensure that it is preserved across server reload because issuing the send-reservation command alone affects only the server's internal memory.

For more information about the scope name addReservation command, see the "Scope Reservation Method Commands" section.

delete-reservation

Observe the following conditions when using the delete-reservation command:

• Make sure the reservation has already been removed from the nrcmd internal database.
  
  
• If you are using failover on the scope in which the reservation resides:
  
  

  a. Issue the delete-reservation command to the backup server.

  b. Issue the delete-reservation command to the main server.

  c. Issue a scope removeReservation command to both systems.

Example

To create a reservation and send it to server 192.168.1.9, enter these commands:

nrcmd> lease 192.168.1.9 delete-reservation 

nrcmd> scope myscope removeReservation 192.168.1.9 1,6,00:a0:24:2e:9c:20 

nrcmd> save 

Note   You should save the results of this operation to ensure that it is preserved across server reload because issuing the delete-reservation command alone affects only the server's internal memory.

For more information about the scope name removeReservation command, see the "Scope Reservation Method Commands" section.

Reserving An Address That Is Currently Leased

It is possible to delete a reservation for one client and send a 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 set up a reservation and lease, as follows:

nrcmd> scope my-scope addReservation 204.253.96.180 1,6,01:02:03:04:05:06

nrcmd> save

nrcmd> lease 204.253.96.180 send-reservation

nrcmd> lease 204.253.96.180 activate

nrcmd> save

 

Client 1,6,01:02:03:04:05:06 does a DHCPDISCOVER and gets an offer for 204.253.96.180. The client then does a DHCPREQUEST and gets an ACK for the same IP address.

As time passes, client 1,6,01:02:03:04:05:06 does several DHCPREQUESTs that are renewals, which are acknowledged. Then, at some time prior to the expiration time of the lease by client 1,6,01:02:03:04:05:06 on 204.253.96.180, you terminate the reservation as follows:

nrcmd> lease 204.253.96.180 de-activate

nrcmd> scope my-scope removeReservation 204.253.96.180

nrcmd> save

nrcmd> lease 204.253.96.180 delete-reservation

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

nrcmd> scope my-scope addReservation 204.253.96.180 1,6,02:01:02:01:02:01

nrcmd> save

nrcmd> lease 204.253.96.180 send-reservation

nrcmd> lease 204.253.96.180 activate

nrcmd> save

 

Now you have an IP address that is leased to one client, but reserved for another. If the new client (1,6,02:01:02:01:02:01) does a DHCPDISCOVER prior to the original client (1,6,01:02:03:04:05:06) doing a DHCPDISCOVER, it will not get 204.253.96.180. Instead, it will receive a random IP address from the dynamic pool.

When the original client (1,6,01:02:03:04:05:06) sends its next DHCPREQUEST to renew the lease on 204.253.96.180, it will get a DHCPNAK. 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 204.253.96.180.

After this, client 1,6,01:02:03:04:05:06 will be given whatever lease is appropriate for it: some reservation other than 204.253.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 will get 204.253.96.180.

Although you could force the availability of a lease, as follows,

nrcmd> lease 204.253.96.180 force-available

 

that will not stop the original client (1,6,01:02:03:04:05:06) from using 204.253.96.180. Also, it will not prevent the new client (1,6,02:01:02:01:02:01) getting 204.253.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. This is as true of reservations made by the send-reservation command as it is of reservations made solely in nrcmd in the configuration database. Thus, making a reservation for one client will not cause another client to lose that lease right away, although it does cause that client to receive a NAK response the next time it contacts the DHCP server (which could be seconds or could be days). Additionally, the client that has reserved the IP address will not get it if some other client already has it; it will get 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
  
  

Lease Command Properties

Use get to display the values from the lease properties. These properties are read-only.

The syntax is:

Table 2-30 lists and describes the lease command properties.

Properties	Description
address	The IP address of this lease.
client-dns-name	The DHCP server attempted (possibly successfully) to enter this name into the DNS server for this client. It is related to the client-host-name, but may not be identical due to name collisions in the DNS server database.
client-domain-name	The domain name specified (if any) into which to put the client's DNS name.
client-flags	A variety of flags relating to the client. For more information about these flags, see the "Client Flags" section.
client-host-name	The DNS name that the client requested the DHCP server place into the DNS server.
client-id	The client-id specified by the client, or one synthesized by the DHCP server for this client (if client-id-created-from-mac-address is set in the client-flags).
client-last-transaction-time	The time at which the client most recently contacted the DHCP server.
client-mac-addr	The MAC address which the client presented to the DHCP server.
client-os-type	Specifies the operating system of the leased client. If you have enabled failover, the main server transmits this value to the backup server. The syntax of this property's value is OS-name major.minor. Other examples are: LANMAN Server, LANMAN Workstation, MAC OS, Microsoft Windows, Microsoft Windows 2000 Professional, Microsoft Windows 95, Microsoft Windows 9x, Microsoft Windows for Workgroups, Microsoft Windows NT Advanced Server, Microsoft Windows NT Server, Microsoft Windows NT Workstation 3.51, Microsoft Windows NT Workstation 4.0, Netware, and OS/2. Note   This property is only used by the updateSms command and has no other purpose.
expiration	The time at which the lease will expire.
flags	Flags for the lease are either reserved or deactivated. The lease is reserved for some MAC address or the lease is de-activated, which means that it should not be used. Any clients that are using de-activated leases will receive a NAK on their next renewal attempt.
lease-renewal-time	The minimal time in which the client is expected to issue a lease renewal.
start-time-of-state	The time at which the state last changed to its current value. Use this property to determine when the lease was made unavailable.
state	The current state of the lease. See Table 2-32.

Client Flags

Table 2-31 describes the client lease command flags.

The following flags are for internal use only: client-valid, client-fqdn-present, client-updates-name, clear-host-name, host-name-has-changed, and domain-name-has-changed.

States

Table 2-32 describes the client lease command states.

Lease-notification

The lease-notification command allows you to receive notification when the number of available addresses in a scope is exceeded. You can specify the notification limit either as the number of free addresses or the percentage of free addresses. You can also specify who will receive e-mail notification.

The syntax is:

Although you can use the lease-notification command interactively, its primary use is as an automated command. For more information, see the "Running the Lease-notification Command Automatically on UNIX" section and the "Running the Lease-notification Command Automatically on Windows NT" section.

Examples

To specify scope 1 with an available value of 10% and e-mail recipients billy, joe, and jane, enter:

nrcmd> lease-notification available=10% scopes=scope1 recipients=billy,joe,jane 
mail-host=mailhost

 

To specify the range of scopes 192.32.1.0-192.32.1.255, the config file .nrNotification, the recipients admin, an available value of 13 leases, and the Windows NT mail host as mailhost, enter:

nrcmd> lease-notification scopes=192.32.1.0-192.32.1.255

config=/home/bob/.nrNotification recipients=admin@comco.com available=13

mail-host=mailhost

Note   If successful, the lease-notification command prints "100 OK" both before and after Network Registrar lists the addresses. The first "100 OK" means that the command is being processed (without rejection because of existing locks, licensing problems, or command syntax errors). The second "100 OK" indicates that the command successfully completed its processing.

Lease-notification Properties

Table 2-33 lists and describes the lease-notification command properties.

Specifying the Config File

If you do not specify a config 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.

Specifying Clusters

You can specify clusters in a variety of ways and Network Registrar follows a precedence order. Any of the specific cluster specifications can override the default specification or previous specification:

• The default cluster (localhost).
  
  
• The UNIX environment or Windows NT registry variable AIC_CLUSTER.
  
  
• The -C flag on the command line allows you to specify a single cluster.
  
  
• The clusters property in the config file allows you to specify a group of clusters. For example, to specify clusters, enter the following in the .nrconfig file or other specified configuration file:
  

Cluster information for lease notification
[lease-notification] 
clusters=<clustername> <username> <password>...
clusters=host1 admin, host2, 
	host3 admin3 passwd3

Note   You should separate the three-cluster arguments with spaces. For long lines you can use continuation lines, that is, you do not need to use continuation escape indicators. You can optionally specify a username and password for the cluster. If you do not provide a username or password for a particular cluster, Network Registrar uses the last username or password listed. If you do not provide user names or passwords, Network Registrar uses the information from the command line -N and -P arguments, and then the NT Registry or environment variables AIC_NAME and AIC_PASSWORD.

If Network Registrar cannot find a username or password or the supplied username and password are incorrect, the lease-notification command issues a warning for that cluster.

Running the Lease-notification Command Automatically on 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. For example, to run the lease-notification command at 00:15 and 12:15 (15 minutes after midnight and noon) Monday through Friday, specify the following command to crontab:

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 nrcmd 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 nrcmd lease-notification command by means of crontab, the user environment variables AIC_CLUSTER, AIC_NAME, and AIC_PASSWORD are ignored. Because the command being run could be viewed by others, for security reasons, you should not provide the password through the -P option on the command line.

The cluster name, user, and password information for the cluster you want the nrcmd command to run from should be supplied 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 file must be read explicitly in the crontab entry with . .profile specification. Note that the first "." is the shell command that causes the file to be read and must be followed by white space. For notification on a different cluster, or clusters, than the one on which ncrmd is running, you need to specify the following information:

• clusters to be checked in a config file as described in"Specifying the Config File" 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 you create by changing its permissions with the UNIX command chmod go-rw config_file.

Running the Lease-notification Command Automatically on Windows NT

Use the Scheduled Tasks service available in Windows NT Explorer under My Computer to schedule the nrcmd lease-notification command. If you do not find a Scheduled Tasks folder under My Computer, you will 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.

License

The license command allows you to specify the license key for a cluster or to view the license key or the license's expiration date. Your license key is located on the back of the Cisco Network Registrar CD case. You need to enter your license the first time you configure any cluster.

• If you have a permanent license, you will not see the license message again unless you move your cluster to another machine.
  
  
• If you have an evaluation copy of Network Registrar, you have a license that will expire.
  
  
• If you have an invalid or missing licensing key, you will not be able to configure or manage the Network Registrar servers. The servers themselves however, will continue to function normally.
  
  
• If the license will expire in seven or fewer days, you will see a warning when you start Network Registrar.
  
  

The syntax is:

Table 2-34 lists and describes the license command properties.

Example

To set the license, you must run the nrcmd program in interactive mode, then exit and rerun the nrcmd program. To set the license to key 1234 abcd 5678 efgh, enter:

nrcmd -C cluster1 -N admin -P changeme 
nrcmd> license set key=1234-abcd-5678-efgh

100 Ok
nrcmd> exit

Option-datatype

The option-datatype command allows you to define DHCP option data types as required to accommodate devices from a variety of vendors. You can create a collection of standard DHCP option data types, such as IPADDR, BYTE and IPADDR_ARRAY, to support requirements for complex data types.

The syntax for creating, deleting, and listing option data type definitions is:

where name is the name of the data type to be created or deleted.

Note   The option datatype name is case-insensitive.

Option-datatype Field Method Commands

You can define, undefine, and list individual fields within an option data type definition using the defineField, undefineField, and listField methods.

The syntax is:

Table 2-35 describes the properties of the defineField and undefineField methods.

Option Data Types

Table 2-36 lists the option data types supported by the nrcmd program.

Option-datatype Read-only Feature

To complete the option data type definition process and to avoid further changes to the definition, enable the read-only feature. The syntax is:

To make subsequent changes to the option data type, disable the read-only feature:

Note   The read-only feature should be enabled for an option data type before it is used in a vendor-option command.

Option-datatype Example

There are four main steps to configure Network Registrar to support a device that expects to receive vendor-specific DHCP options from the DHCP server:

The example that follows is based on the Intel Preboot Execution Environment (PXE) Specification, Version 2.0. For continuity and completeness, the example includes all three commands required to accomplish its task. Refer to the "Vendor-option" section and the "Policy" section for more information about those commands.

nrcmd> option-datatype IntelPXE_odt_suboption_8 create 

nrcmd> option-datatype IntelPXE_odt_suboption_8 defineField boot_server_type 1 WORD 

nrcmd> option-datatype IntelPXE_odt_suboption_8 defineField boot_server_IP_list 2 
IPADDR_ARRAY

nrcmd> option-datatype IntelPXE_odt_suboption_8 enable read-only

 

Here Intel_PXE_odt_suboption_8 describes the format for Suboption 8 of an IntelPXE-compatible network device. Please note that several suboptions with different formats are required for an IntelPxE device. Each suboption should be mapped into Network Registrar using a separate set of option-datatype commands.

Step 2   Create vendor option. Once the suboption formats are mapped to vendor-specific option data types or to standard DHCP options, you are ready to create a vendor option for an IntelPxE device. The command

nrcmd> vendor-option IntelPXE_vso create "PXEclient:Arch:xxxxxx:UNDI:yyyzzz"
 

where "PXEclient:Arch:xxxxxx:UNDI:yyyzzz" exactly matches the string provided by the vendor as the Class Identifier (Option 60) for the device, creates the vendor option "IntelPXE_vso."

Step 3   Define all required suboptions. Suboption 8 is assigned to the option data type IntelPXE_odt_suboption_8 as follows:

nrcmd> vendor-option IntelPXE_vso defineSuboption suboption_8 8 IntelPXE_odt_suboption_8 
array 

 

Repeat this command for each suboption required for the device.

Step 4   Set the data of the vendor option by setting the values of each suboption. In this example, the policy named "network-1.2.3" is set for Suboption 8 of the vendor-specific DHCP option named "IntelPXE_vso" to have the following values:

nrcmd> policy network-1.2.3 setVendorOption IntelPXE_vso {suboption_8[0]} 
boot_server_type 2 
nrcmd> policy network-1.2.3 setVendorOption IntelPXE_vso {suboption_8[0]}

boot_server_IP_list 192.168.25.4,192.168.25.5
nrcmd> policy network-1.2.3 setVendorOption IntelPXE_vso {suboption_8[1]} 
boot_server_type 8

nrcmd> policy network-1.2.3 setVendorOption IntelPXE_vso {suboption_8[1]} 
boot_server_IP_list 192.168.25.6 

Note   This reference guide follows the convention of using square brackets to indicate that an argument is optional. However, in this example the square brackets and the braces in {suboption_8[0]} are parts of the syntax required to specify the value of the array field.

Policy

The policy command allows you to configure DHCP policy configurations. A policy is a collection of DHCP option values that can be associated with a range of addresses in a scope, or with a specific client or client-class configuration.

The syntax is:

Example

To create the policy CompanyB, enter:

nrcmd> policy CompanyB create

Policy Features

You can enable, disable, or determine whether the feature has been set. You use the enable, disable, or get commands.

The syntax is:

Table 2-37 lists and describes the policy command features. For more information about lease time, see "Lease Times" section.

Policy Properties

Use the set and get commands to assign and retrieve values from the policy's properties.

The syntax is:

Table 2-38 lists and describes the policy command properties.

Example

To set the grace period to three days for policy 168.1-net, enter:

nrcmd> policy 168.1-net set grace-period=3d

Policy Reply Options

When the server is getting ready to return option data to a client, it examines up to seven policies: the client's embedded policy, the client's policy, the client's client-class's embedded policy, the client's client-class's policy, the client's lease's scope's embedded policy, the client's lease's scope's policy, and the system default policy, in that order.

Then the server looks through the policies for a reply-options list. It looks for bootp- or dhcp-reply-options depending on the client. The server uses the first list it finds. For each option in the list, the server looks through all of the policies, in order, and returns the data from the first policy that has a matching option. There is no requirement that the data that the server returns must come from the same policy that the reply-options list came from. If the server finds a reply-options list, it looks for each option in the list individually, and searches all of the related policies if necessary.

There is also no requirement that the options mentioned in a reply-options list be present in the policy that contains the list. The nrcmd program allows you to type in a string, and that string can name any option. The Network Registrar GUI, however, presents a special dialog box for adding a reply-options property to a policy that restricts you to the options already configured in the policy. This is a GUI-only restriction; the server does not impose this restriction.

Policy Command Options

You can set individual option values with the setOption method, unset option values with the unsetOption method, and view option values with the getOption and listOptions methods. When you set an option value, the DHCP server replaces any existing value or creates a new one, as needed, for the given option name.

Note   For a list of all the DHCP options that you can configure, type the nrcmd program help dhcp-option command.

The syntax is:

Note   This reference guide follows the convention of using square brackets to indicate that an argument is optional. However, in this case the square brackets and the braces in are parts of the syntax required to specify the value of an array field.

Table 2-39 describes the policy command option methods.

Table 2-40 describes the properties of the policy command option methods.

Examples

To specify the lease time in a scope, enter:

nrcmd> policy 168.1-net setOption dhcp-lease-time 608400

 

To list the standard DHCP options in a policy, enter:

nrcmd> policy 168.1-net listOptions

 

To list the vendor-specific options in a policy, enter:

nrcmd> policy 168.1-net listVendorOptions

 

To set data for vendor-specific options in a policy, enter:

nrcmd> policy 168.1-net setVendorOption IntelPXE_vso {suboption_8[0]} 

boot_server_type 200 
 

This sets data for the boot_server_type field in item 0 of the array named suboption_8. You would enter the "200" as a string, and not convert it to hexidecimal.

To set data for vendor-specific options in a policy whose option datatype field is an array (in this example, boot_server_IP_list), use comma-separated values:

nrcmd> policy network-1.2.3 setVendorOption IntelPXE_vso {suboption_8[0]}

boot_server_IP_list 192.168.25.4,192.168.25.5
 

You would enter the "192.168.25.4,192.168.25.5" as a string, and not convert it to hexidecimal.

Policy Lease Time Method Commands

The setLeaseTime command allows you to set the values of lease times and the getLeaseTime command to display the value of a lease time.

The syntax is:

The lease time is the value of the dhcp-lease-time DHCP option. You should specify the time in seconds.

Lease Times

A policy contains two lease times: the client lease time and the server lease time.

• You set the client lease time through the setLeaseTime method. This lease time determines how long the client believes its lease is valid.
  
  
• You set the server lease time through server-lease-time property. This lease time determines how long the server considers the lease valid. Note that the server lease time is independent of the lease's grace period; that is, the server will not allocate the lease to another client until after the server's lease period has expired and the grace period has expired.
  
  

You might want to establish these two different lease times if you want to retain information about clients' DNS names and yet have them renew their leases frequently. When you use a single lease time and it expires, the server no longer keeps that client's DNS name. If, however, you use a short client lease time and a longer server lease time, the client information is retained even after the client's lease has expired.

Caution Although Network Registrar supports the use of two lease times for special situations, it is generally recommended that you not use the server-lease-time property.

Remote-dns

The remote-dns command allows you to control the behavior of the DNS server when it is communicating with other DNS servers. Use it to either control incremental transfer or to send multiple records per TCP packet.

The syntax is:

Table 2-41 lists and describes the remote-dns command properties.

Example

To create the remote server description 128.103.1.1 with the net mask of 255.255.0.0, enter:

nrcmd> remote-dns create 128.103.1.1/16 

 

Note   Each net mask octet is composed of 8 bits. In the previous example, the first two octets are significant, thus the netmask is 16. If the first three octets are significant, the net mask is 24.

Remote-dns Features

You can enable, disable, or determine whether the feature has been set. You use the enable, disable, or get commands.

Table 2-42 lists and describes the remote-dns command features.

Examples

When you enable or disable incremental transfer, Network Registrar looks for the most specific match. That is, it matches the machine with the longest mask. Use this feature to specify a group of servers with a single command.

To enable all DNS servers on this network to perform incremental transfer, enter:

nrcmd> remote-dns create 128.103.0.0/16 ixfr=true

 

To disable incremental transfers on all DNS servers on this network, enter:

nrcmd> remote-dns create 128.103.1.0/24 ixfr=false

Report

The report command allows you to produce a summary of dynamic and static IP address utilization for one or more clusters.

The syntax is:

Table 2-43 lists and describes the report command properties.

Examples

To create a report of static DNS addresses and dynamic DHCP addresses, enter:

nrcmd> report

 

To create a report of only DHCP scopes, enter:

nrcmd> report dhcp-only

Note   If successful, the report command prints "100 OK" both before and after Network Registrar lists the addresses. The first "100 OK" means that the command is being processed (without rejection because of existing locks, licensing problems, or command syntax errors). The second "100 OK" indicates that the command successfully completed its processing.

Specifying Clusters

You can specify cluster in a variety of ways and Network Registrar follows a precedence order. Any of the specific cluster specifications can override the default specification or previous specification.

• The default cluster (localhost)
  
  
• The UNIX environment or Windows NT registry variable AIC_CLUSTER
  
  
• The -C flag on the command line allows you to specify a single cluster.
  
  
• The clusters property in the config file allows you to specify a group of clusters. For example, to specify clusters, enter the following in the config file:
  
  

Note   You should separate the three cluster arguments with spaces. For long lines use continuation lines, that is, you do not need to use continuation escape indicators. You can optionally specify a user name and password for the cluster. If you do not provide a username or password for a particular cluster, Network Registrar uses the last username or password listed. If you do not provide user names or passwords, Network Registrar uses the information from the command line -N and -P arguments, and then the Windows NT Registry or environment variables AIC_NAME and AIC_PASSWORD.

If Network Registrar cannot find a username or password or the supplied username and password are incorrect, then the report command issues a warning for that cluster.

Displaying the Summary

The report command displays a row of information for each subnet specified by scope or deduced from DNS static address assignments outside of scopes.

The report command displays subtotal rows when more than one scope shares a common subnet, and for addresses that share a common subnet as specified by their address and mask. Note that the report command assumes that there is no overlap between static addresses and scope ranges.

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

• Network number, in hexadecimal
  
  
• 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 following values:

• Cluster name
  
  
• Scope role—If using failover, the value is MAIN or BACKUP.
  
  
• Scope name
  
  
• Addresses—Value is the total addresses within the scope ranges, addresses = free + dynamically leased + reserved + unavailable + de-activated + other available
  
  
• Free, addresses within a range and in the available state and not flagged reserved or de-activated
  
  
• % free, as a percentage of all addresses within scope ranges
  
  
• Reserved—Value is within a range and flagged reserved, unless unavailable
  
  
• Leased—Value is within a range and in the leased, offered expired, or released state, even if flagged reserved or de-activated
  
  
• Dynamically leased—Value is within a range and in the leased, offered, or expired state, unless flagged reserved or de-activated
  
  
• Unavailable, within a range and marked as unavailable by the server, regardless of flags
  
  
• De-activated, within a range and flagged deactivated, unless unavailable
  
  
• Other available, leases set aside for the failover partner to lease when communication is interrupted
  
  
• Other reservations, addresses marked reserved which are not within a scope range