Using the Nrcmd Commands

The Network Registrar nrcmd command is a command-line based configuration tool. It allows you to set all Network Registrar configurable options as well as 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:

admin name create [prop=value]

admin name delete

admin list

For example, to create the administrator bob with the password xyz, type:

nrcmd> admin bob create password=xyz

To delete the administrator bob, type:

nrcmd> admin bob delete

Admin Properties

You can use the set, get and show commands to assign and retrieve values from the admin properties.

The syntax is:

admin name set prop=value [prop=value]

admin name get prop

admin name show

admin name enterPassword [password]

If you want to enter a password without having 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.

Table 2-1 lists and describes the admin properties.

Table 2-1: Admin Properties

Properties Description

password

The administrator's password

Properties	Description
password	The administrator's password

Client

The client and client-class commands allow you to 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 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 in order for the change to take effect.

The way that you specify the client is by using 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,00:a0:24:2e:9c:20.

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.

The syntax is:

client name create [prop=value]

client name delete

client list

For example, to create a client that is a member of the external client-class, type:

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:, type:

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

To list all the client-classes, type:

nrcmd> client list

Client Properties

The property list contains the name and values in the following format:

prop=value{,value}

Note that 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.

You use the set and get commands to set and display their values.

The syntax is:

client macaddress set prop=val

client macaddress get prop

client macaddress show

Table 2-2 lists the client command properties.
Table 2-2: Client Command Properties

Property Description

action

The action to take for this client. You can specify either "exclude" or "one-shot". For more information about these actions, see the "Action Strings" section.

authenticate-until

(Client-only) Specifies whether to limit the authentication time to the duration you have specified. For more information about how to specify the time, see "Authenticate-Until" section.

client-class-name

(Client-only) The client-class to which the client belongs. Note that the client-class-name property may only appear in the client entry. It is an error to specify a client-class name property in a client-class object. If the client is not a member of a client-class, then the DHCP server uses the default client-class properties.

domain-name

The domain name to use when performing DNS updates. Places the client's A record in this DNS domain.

host-name

The host name. Use this string to replace any host-name DHCP option sent by the DHCP client. For more information about host names, see the "Host Name Strings" section.

policy-name

The policy to add to Network Registrar's DHCP policy search list for this client.

selection-criteria

The scope selection tags to build the scope inclusion list.

selection-criteria-excluded

The scope selection tags to build the scope exclusion list.

unauthenticated-client-class-name

The name of the client-class to use if this client is no longer authenticated.

user-defined

A user-defined string that can be set and queried. This property has no effect on the operation of the DHCP server.

Property	Description
action	The action to take for this client. You can specify either "exclude" or "one-shot". For more information about these actions, see the "Action Strings" section.
authenticate-until	(Client-only) Specifies whether to limit the authentication time to the duration you have specified. For more information about how to specify the time, see "Authenticate-Until" section.
client-class-name	(Client-only) The client-class to which the client belongs. Note that the client-class-name property may only appear in the client entry. It is an error to specify a client-class name property in a client-class object. If the client is not a member of a client-class, then the DHCP server uses the default client-class properties.
domain-name	The domain name to use when performing DNS updates. Places the client's A record in this DNS domain.
host-name	The host name. Use this string to replace any host-name DHCP option sent by the DHCP client. For more information about host names, see the "Host Name Strings" section.
policy-name	The policy to add to Network Registrar's DHCP policy search list for this client.
selection-criteria	The scope selection tags to build the scope inclusion list.
selection-criteria-excluded	The scope selection tags to build the scope exclusion list.
unauthenticated-client-class-name	The name of the client-class to use if this client is no longer authenticated.
user-defined	A user-defined string that can be set and queried. This property has no effect on the operation of the DHCP server.

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.

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

You can use the one-shot action to allocate provisional addresses. Provisional addresses are useful in cases where 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 the one-shot argument as the action for the default client (or in the client-class specified by the default client). This configuration will cause 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 reallocated 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 reallocated 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, since 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.

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.

The syntax is for the client-class command is as follows:

client-class name create [prop=value]

client-class name delete

client-class list

For example, to create the client-class internal, type:

nrcmd> client-class internal create

To delete the client-class internal, type:

nrcmd> client-class internal delete

To list the all the client-classes, type:

nrcmd> client-class list

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

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

Note Although you can use the same properties as the client command, you cannot use the 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 as follows:

client-class name set prop=val [prop=value]

client-class name get prop

client-class name show

For descriptions of the properties, see the "Client Command 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.

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 for the custom-option command is as follows:

custom-option name create optnum opttype

custom-option name delete

custom-option name show

custom-option list

custom-option name get prop

custom-option name set prop=value

Table 2-3 lists the custom-option command properties.

Table 2-3: Custom-Option Properties

Property Description

optnum

Specifies the option number. Read-only

opttype

Specifies the option type. It can be BOOL, BYTE, WORD, INT, UINT, STRING, IPADDR, BYTE_ARRAY, WORD_ARRAY, INT_ARRAY, UINT_ARRAY, or IPADDR_ARRAY. For more information about types, see "Option Types" section.

desc

Optional, default null-string. You can use this property for a description.

Property	Description
optnum	Specifies the option number. Read-only
opttype	Specifies the option type. It can be BOOL, BYTE, WORD, INT, UINT, STRING, IPADDR, BYTE_ARRAY, WORD_ARRAY, INT_ARRAY, UINT_ARRAY, or IPADDR_ARRAY. For more information about types, see "Option Types" section.
desc	Optional, default null-string. You can use this property for a description.

Option Types

Table 2-4 lists the option types supported by the nrcmd command.

Table 2-4: Option Types

Option Type <opttype> Definition

boolean

BOOL

TRUE or FALSE

byte

BYTE

8-bit unsigned integer

word

WORD

16-bit unsigned integer

signed integer

INT

32-bit signed integer

unsigned integer

UINT

32-bit unsigned integer

string

STRING

ASCII text string

IP address

IPADDR

IP address in the form of a.b.c.d

byte array

BYTE_ARRAY

Binary string of the form xx[:xx] in which x is 0-9a-f

word array

WORD_ARRAY

Array of 16-bit unsigned integers

signed array

INT_ARRAY

Array of 32-bit signed integers

unsigned array

UINT_ARRAY

Array of 32-bit unsigned integers

IP address array

IPADDR_ARRAY

Array of IP addresses

Option Type	<opttype>	Definition
boolean	BOOL	TRUE or FALSE
byte	BYTE	8-bit unsigned integer
word	WORD	16-bit unsigned integer
signed integer	INT	32-bit signed integer
unsigned integer	UINT	32-bit unsigned integer
string	STRING	ASCII text string
IP address	IPADDR	IP address in the form of a.b.c.d
byte array	BYTE_ARRAY	Binary string of the form xx[:xx] in which x is 0-9a-f
word array	WORD_ARRAY	Array of 16-bit unsigned integers
signed array	INT_ARRAY	Array of 32-bit signed integers
unsigned array	UINT_ARRAY	Array of 32-bit unsigned integers
IP address array	IPADDR_ARRAY	Array of IP addresses

For example, to create a custom option called red, mapped to number 100, of type IPADDR, type:

nrcmd> custom-option red create 100 IPADDR

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

nrcmd> custom-option blue create 101 BYTE_ARRAY

To give custom-option blue a description, type:

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), type:

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

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

nrcmd> custom-option list

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

nrcmd> custom-option green delete

To redefine time-offset option to change the format of its user-printable name, type:

nrcmd> custom-option TimeOffset create 2 INT

To display the option's new definition, type:

nrcmd> custom-option TimeOffset show

DHCP

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

The syntax for the dhcp command is as follows:

dhcp disable feature

dhcp enable feature

dhcp get feature

Table 2-5 lists and describes the DHCP features.

Table 2-5: DHCP Features

Feature Description

cisco-dhcp-proxy

Controls whether the DHCP server uses the source address of the packet, if it is non-zero, in lieu of the giaddr field. Note that the DHCP server uses this feature only for DHCP packets, not BOOTP packets. The default is enabled. For more information about this feature, see the "Cisco DHCP Proxy" section.

client-class

Controls whether or not the DHCP server uses the client and client-class configuration objects to affect request processing. Default disabled.

defer-lease-extensions

Controls whether or not the DHCP server extends leases that are less than half expired. Default disabled, which means that the DHCP server will always extend leases (except in the first 30 seconds) to accommodate protocol retries. For more information about this feature, see the "Defer Lease Extensions" section.

discover-interfaces

Causes the DHCP server to find all the interface cards on the host and process DHCP requests that it receives from any of them. It will, however, only offer addresses to requests from subnets in which you have defined a valid scope with available addresses. If you do not enable this feature, the DHCP server uses only its list of configured interfaces. Default enabled.

drop-packet-on-extension-
failure

Causes the server to drop a packet (if possible) when it encounters a script failure. Default enabled.

hardware-unicast

Controls whether the DHCP server sends unicast rather than broadcast responses when a client indicates that it can accept a unicast. This feature may not be available on all platforms.

ignore-icmp-errors

If you enable this feature and you have configured the DHCP server to send ICMP ECHO requests before offering addresses, the server will make unavailable any address for which it receives an ECHO reply within its configured timeout period. If you disable this feature, the DHCP server will also treat ICMP DEST_UNREACHABLE and TTL_EXPIRED error messages which it receives after sending ICMP ECHO requests as grounds for making an address unavailable.

import-mode

Causes the DHCP server to recognize only packets generated from the nrcmd command's import leases command and ignore all others. You can use this property if you want to update your DHCP server and prevent clients from receiving addresses during this period. Default disabled. For more about import mode, see "Import Mode" section.

mac-address-only

Causes the DHCP server to use the client's MAC address as the only client identifier. The standard behavior, as specified in RFC 2132, is to use the client ID option (if it is present) as the unique client identifier. If you specify the mac-address-only argument, the DHCP server ignores the client's ID and uses its MAC address instead. You can use this argument to have a single, consistent way of identifying all clients that use your DHCP server. Default disabled.

one-lease-per-client

Causes the DHCP server to release any other leases the client may have had on this server. Since the default behavior for the Network Registrar DHCP server is to store all the leases a client obtains, this command ensures that only one lease is stored. A client might obtain a number of leases if a user with a laptop traveled throughout the building and requested leases at different locations on the network.

update-dns-for-bootp

If the server is replying to a BOOTP request, and is offering a lease from a scope that is configured for DNS updates, the DHCP server checks this property before beginning the update. You can use this feature to prevent DNS updates for BOOTP clients, while allowing updates for DHCP clients.

use-ldap-client-data

Controls whether the DHCP server attempts to read client-entry data through LDAP, that is, using the configuration supplied by the ldap command. For more information about the ldap command, see the "LDAP Features" section.

Feature	Description
cisco-dhcp-proxy	Controls whether the DHCP server uses the source address of the packet, if it is non-zero, in lieu of the giaddr field. Note that the DHCP server uses this feature only for DHCP packets, not BOOTP packets. The default is enabled. For more information about this feature, see the "Cisco DHCP Proxy" section.
client-class	Controls whether or not the DHCP server uses the client and client-class configuration objects to affect request processing. Default disabled.
defer-lease-extensions	Controls whether or not the DHCP server extends leases that are less than half expired. Default disabled, which means that the DHCP server will always extend leases (except in the first 30 seconds) to accommodate protocol retries. For more information about this feature, see the "Defer Lease Extensions" section.
discover-interfaces	Causes the DHCP server to find all the interface cards on the host and process DHCP requests that it receives from any of them. It will, however, only offer addresses to requests from subnets in which you have defined a valid scope with available addresses. If you do not enable this feature, the DHCP server uses only its list of configured interfaces. Default enabled.
drop-packet-on-extension- failure	Causes the server to drop a packet (if possible) when it encounters a script failure. Default enabled.
hardware-unicast	Controls whether the DHCP server sends unicast rather than broadcast responses when a client indicates that it can accept a unicast. This feature may not be available on all platforms.
ignore-icmp-errors	If you enable this feature and you have configured the DHCP server to send ICMP ECHO requests before offering addresses, the server will make unavailable any address for which it receives an ECHO reply within its configured timeout period. If you disable this feature, the DHCP server will also treat ICMP DEST_UNREACHABLE and TTL_EXPIRED error messages which it receives after sending ICMP ECHO requests as grounds for making an address unavailable.
import-mode	Causes the DHCP server to recognize only packets generated from the nrcmd command's import leases command and ignore all others. You can use this property if you want to update your DHCP server and prevent clients from receiving addresses during this period. Default disabled. For more about import mode, see "Import Mode" section.
mac-address-only	Causes the DHCP server to use the client's MAC address as the only client identifier. The standard behavior, as specified in RFC 2132, is to use the client ID option (if it is present) as the unique client identifier. If you specify the mac-address-only argument, the DHCP server ignores the client's ID and uses its MAC address instead. You can use this argument to have a single, consistent way of identifying all clients that use your DHCP server. Default disabled.
one-lease-per-client	Causes the DHCP server to release any other leases the client may have had on this server. Since the default behavior for the Network Registrar DHCP server is to store all the leases a client obtains, this command ensures that only one lease is stored. A client might obtain a number of leases if a user with a laptop traveled throughout the building and requested leases at different locations on the network.
update-dns-for-bootp	If the server is replying to a BOOTP request, and is offering a lease from a scope that is configured for DNS updates, the DHCP server checks this property before beginning the update. You can use this feature to prevent DNS updates for BOOTP clients, while allowing updates for DHCP clients.
use-ldap-client-data	Controls whether the DHCP server attempts to read client-entry data through LDAP, that is, using the configuration supplied by the ldap command. For more information about the ldap command, see the "LDAP Features" section.

Cisco DHCP Proxy

The cisco-dhcp-proxy feature provides support for certain Cisco devices that implement a DHCP proxy function. The cisco-dhcp-proxy feature causes the DHCP server to use a non-zero IP source address as the giaddr (gateway address) of a DHCP packet when no giaddr is specified in the packet. This feature causes no change in the processing for DHCP clients that are not local or for any BOOTP clients. For locally connected DHCP clients (where the giaddr must be zero), the source address is normally zero (per the DHCP RFC), and so the subnet on which they belong is determined using the interface address on which the packet arrived---which is the correct behavior.

Because it might be possible that some locally connected clients might be affected by the cisco-dhcp-proxy feature, you can disable it. Such a client would have to send packets to the DHCP server using a non-zero source address (which they should not do), and this would cause them to be unable to get an IP address. If a client is having difficulty receiving an IP address, you can determine whether it is caused by the cisco-dhcp-proxy feature by checking the logs. Look for the phrase "with source IP address x.y.z.a" in the message that begins: "Server received a packet-type packet from... via: {Interface | Garrett} e.f.g.h" and that contains the client's MAC address or Client ID and hostname (if any). If you see such a message for a locally connected client, then you should consider disabling cisco-dhcp-proxy feature.

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. Since 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. Since 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 MCD. 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---Since 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. And since it is used primarily as a debugging aid, it does not have to be entirely accurate. Furthermore, since 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 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 command during lease import. For more information about the import command, see the "Import Leases" section.

For example, to enable the client-class facility for this DHCP server, type:

nrcmd> dhcp enable client-class

To disable import mode, type:

nrcmd> dhcp disable import-mode

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

nrcmd> dhcp get discover-interfaces

DHCP Properties

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

The syntax is:

dhcp get prop

dhcp set prop=value [prop=value]

dhcp unset prop

dhcp show

Table 2-6 lists and describes the DHCP properties.

Table 2-6: DHCP Properties

Property Description

dns-timeout

Controls the number of milliseconds the DHCP server will wait for a response before retrying a dynamic DNS request.

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. For more information about DHCP extension creation, see the "Extension Properties" section.

last-transaction-time-granularity

Specifies the number of seconds Network Registrar guarantees that the last transaction time is accurate. 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 your lease interval. For more about this property, see the "Defer Lease Extensions" section.

log-settings

Controls whether the DHCP server logs additional detail about the events listed in the log-settings. This can be helpful when you are analyzing a problem, but leaving it enabled for a long period can cause the log files to fill up. For more information about the different log settings, see the "Log Settings" section.

max-dhcp-requests

Controls the size of buffers DHCP allocates for responding to DHCP clients. At least 100 buffers of each type should be allocated, and perhaps as many as several thousand would be reasonable in some installations.

max-dhcp-responses

Controls the size of buffers DHCP allocates for receiving packets from DHCP clients. At least 100 buffers of each type should be allocated, and perhaps as many as several thousand would be reasonable in some installations.

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.

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 in order to resolve a conflict.

max-dns-retries

Controls the number of times the DHCP server attempts to send dynamic DNS updates to a DNS server.

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.

max-ping-packets

The number of buffers the server will allocate for sending and receiving ICMP ping messages. For more information, see the scope's ping-client's feature, see the "Scope Features" section.

scope-selection-tags

The list of scope selection tags associated with this scope. 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.

Property	Description
dns-timeout	Controls the number of milliseconds the DHCP server will wait for a response before retrying a dynamic DNS request.
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. For more information about DHCP extension creation, see the "Extension Properties" section.
last-transaction-time-granularity	Specifies the number of seconds Network Registrar guarantees that the last transaction time is accurate. 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 your lease interval. For more about this property, see the "Defer Lease Extensions" section.
log-settings	Controls whether the DHCP server logs additional detail about the events listed in the log-settings. This can be helpful when you are analyzing a problem, but leaving it enabled for a long period can cause the log files to fill up. For more information about the different log settings, see the "Log Settings" section.
max-dhcp-requests	Controls the size of buffers DHCP allocates for responding to DHCP clients. At least 100 buffers of each type should be allocated, and perhaps as many as several thousand would be reasonable in some installations.
max-dhcp-responses	Controls the size of buffers DHCP allocates for receiving packets from DHCP clients. At least 100 buffers of each type should be allocated, and perhaps as many as several thousand would be reasonable in some installations.
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.
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 in order to resolve a conflict.
max-dns-retries	Controls the number of times the DHCP server attempts to send dynamic DNS updates to a DNS server.
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.
max-ping-packets	The number of buffers the server will allocate for sending and receiving ICMP ping messages. For more information, see the scope's ping-client's feature, see the "Scope Features" section.
scope-selection-tags	The list of scope selection tags associated with this scope. 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.

For example, to set the scope selection tag internal, type:

nrcmd> dhcp set scope-selection-tags=internal

To display whether hardware-unicast has been set, type:

nrcmd> dhcp get hardware-unicast

To make the one-lease-per-client have no value, type:

nrcmd> dhcp unset one-lease-per-client

Log Settings

You can set the following flags:

client-criteria-processing---This setting causes Network Registrar to a log message whenever it examines a scope to find an available lease or whenever it examines a scope to determine if a lease is still acceptable for a client who already has one. This setting can be very useful when configuring or debugging client-class scope criteria processing. It causes a moderate amount of information to be logged, and you should not leave it enabled as a matter of course.
client-detail---This setting causes Network Registrar to log a single line at the conclusion of every client-class client lookup operation. This line shows all the data found for the client as well as the data that was found in the client's client-class. This setting is useful when setting up a client-class configuration, and for debugging problems in client-class processing.
default---The default provides a low level of logging in several parts of the DHCP server. If you unconfigure the default, even this logging will not appear.
incoming-packets---This setting (on by default) causes Network Registrar to log a single line message for every incoming packet. This setting is especially useful when you are initially configuring a DHCP server or a BOOTP relay, in that an immediate positive indication exists that the DHCP server is receiving packets.
incoming-packet-detail---This setting causes Network Registrar to display the contents of every DHCP packet received by the DHCP server in a human readable way. This setting enables the built-in DHCP packet sniffer for input packets. The log files will fill up (and turn over) very rapidly when you have enabled this setting. This setting also causes a significant performance impact on the DHCP server, and you should not leave it enabled as a matter of course.
missing-options---This setting (on by default) causes Network Registrar to log a message whenever an option requested by a DHCP client has not been configured in a policy and therefore cannot be supplied by the DHCP server.
outgoing-packet-detail---This setting causes Network Registrar to display the contents of every DHCP packet transmitted by the DHCP server in a human readable way. This setting enables the built-in DHCP packet sniffer for output packets. The log files will fill up (and turn over) very rapidly when this setting is enabled. This setting also causes a significant performance impact on the DHCP server, and you should not leave it enabled as a matter of course.
unknown-criteria---This setting causes Network Registrar to display a single-line log message whenever the DHCP server finds a client entry that specifies a selection-criteria or selection-criteria-excluded that is not found in any scope appropriate for that client's current network location.

For example, to suppress warning messages for unconfigured or missing options, type:

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

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

nrcmd> dhcp set log-settings=client-detail
nrcmd> dhcp reload

To turn off debugging for the DHCP server, type:

nrcmd> dhcp set log-settings=default
nrcmd> dhcp reload

Troubleshooting MAC Addresses

As an additional aid to troubleshooting your configuration you can use the example extension, dextrace, distributed on the Network Registrar CD. 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 some 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 in order to find the problem.

DHCP Extension Commands

You can use the attachExtension, detachExtension, and listExtensions commands to configure the extensions points in the server you have defined. You can name each extension point and associate one extension with it. For more information about extensions, see the "Extension" section.

attachExtension sets the specified extension point to call the named extension. If the extension point is already configured to call an extension, Network Registrar overwrites it with the new value.
detachExtension removes any extension configuration from the specified extension point.
listExtensions shows the current configurations for each extension point.

The syntax is:

dhcp attachExtension extension-point extension-name

dhcp detachExtension extension-point

dhcp listExtensions

For example, after you have defined an extension, you can add the test extension at the extension point post-packet-decode by typing:

nrcmd> dhcp attachExtension post-packet-decode test

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

nrcmd> dhcp detachExtension post-packet-decode

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

nrcmd> dhcp listExtensions

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. This command provides functionality in the following form:

The GUI only allows you to specify the address and netmask of 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:

dhcp-interface ipaddr/maskbits create [prop=value]

dhcp-interface ipaddr/maskbits delete

dhcp-interface list

dhcp-interface ipaddr/maskbits show

dhcp-interface ipaddr/maskbits get prop

dhcp-interface ipaddr/maskbits set prop=value [prop=value]

dhcp-interface ipaddr/maskbits unset prop

Table 2-7 lists and describes the DHCP interface properties.

Table 2-7: DHCP Interface Properties

Property Description

addr

The IP address of the interface.

ignore

Indicates that the server should ignore this interface, which might be the case if you had several interfaces. You can use this property to temporarily disable a specific interface in a list of interfaces.

mask

The subnet number.

Property	Description
addr	The IP address of the interface.
ignore	Indicates that the server should ignore this interface, which might be the case if you had several interfaces. You can use this property to temporarily disable a specific interface in a list of interfaces.
mask	The subnet number.

For example, to create two different interface configurations, type:

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, type 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, type:

nrcmd> dhcp-interface 10.1.2.3/24 delete

To list all the specified interfaces, type:

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:

dns disable feature

dns enable feature

dns get feature

Table 2-8 lists and describes DNS features.

Table 2-8: DNS Features

Feature Description

hide-subzones

Required, default disabled. Configures the server to hide information about the subzone hierarchy for all zones delegated from this server. This feature collapses a portion of the domain namespace into one virtual zone.

ixfr-enable

Required, default enabled. Controls the incremental transfer behavior for zones for which you have not configured a specific behavior. For more information about incremental transfer, see the "Incremental Transfer" section.

lame-deleg-notify

Required, default disabled. Controls whether you want Network Registrar to notice and log when a DNS server listed in a parent-zone's delegation of subzones does not know that it is authoritative for the zone.

no-fetch-glue

Required, default disabled. Controls whether you want the DNS server, when composing a response to a query, to fetch missing glue records. Glue records are DNS A records that specify the address of a domain's authoritative name server. Normal DNS responses include NS records and their A records related to the name being queried.

no-recurse

Required, default disabled. Controls whether you want to disable forwarding client queries to other name servers when your DNS server is not authoritative for data being queried. If you disable recursive queries, you make your name server a noncaching server.

notify

Required, default enabled. Controls NOTIFY sending notification for zones for which you have not configured a specific behavior. For more information about NOTIFY, see the "NOTIFY" section.

round-robin

Required, default enabled. Controls whether you want round-robin cycling of equivalent records in responses to queries. Equivalent records are records of the same name and type. Since clients often only look at the first record of a set, enabling this feature can help balance loads and keep clients from forever trying to talk to an out-of-service host.

slave-mode

Required, default disabled. Controls whether you want this server to be a slave server, which is a server that relies entirely on forwarders for data that is not in its cache. This command has no effect unless you also specify the corresponding forwarders. Note that you can override slave-mode for specific domains with the DNS exception method. For more information about the exception method, see "Exception Method" section.

subnet-sorting

Required, default disabled, as implemented in BIND 4.9.7. Specifies whether you want the address records in responses to queries to be reordered based on the subnet of the client. Since clients often only look at the first record of a set, enabling this feature can help localize network traffic onto a subnet. This feature only applies on answers to queries from clients located on the same subnet as the DNS server.

update-relax-
zone-name

Required, default disabled. Enables relaxation of the RFC 2136 restriction on the zone name record in dynamic updates. This feature allows updates to specify a zone name, which is any name within an authoritative zone, rather than the exact name of the zone.

Feature	Description
hide-subzones	Required, default disabled. Configures the server to hide information about the subzone hierarchy for all zones delegated from this server. This feature collapses a portion of the domain namespace into one virtual zone.
ixfr-enable	Required, default enabled. Controls the incremental transfer behavior for zones for which you have not configured a specific behavior. For more information about incremental transfer, see the "Incremental Transfer" section.
lame-deleg-notify	Required, default disabled. Controls whether you want Network Registrar to notice and log when a DNS server listed in a parent-zone's delegation of subzones does not know that it is authoritative for the zone.
no-fetch-glue	Required, default disabled. Controls whether you want the DNS server, when composing a response to a query, to fetch missing glue records. Glue records are DNS A records that specify the address of a domain's authoritative name server. Normal DNS responses include NS records and their A records related to the name being queried.
no-recurse	Required, default disabled. Controls whether you want to disable forwarding client queries to other name servers when your DNS server is not authoritative for data being queried. If you disable recursive queries, you make your name server a noncaching server.
notify	Required, default enabled. Controls NOTIFY sending notification for zones for which you have not configured a specific behavior. For more information about NOTIFY, see the "NOTIFY" section.
round-robin	Required, default enabled. Controls whether you want round-robin cycling of equivalent records in responses to queries. Equivalent records are records of the same name and type. Since clients often only look at the first record of a set, enabling this feature can help balance loads and keep clients from forever trying to talk to an out-of-service host.
slave-mode	Required, default disabled. Controls whether you want this server to be a slave server, which is a server that relies entirely on forwarders for data that is not in its cache. This command has no effect unless you also specify the corresponding forwarders. Note that you can override slave-mode for specific domains with the DNS exception method. For more information about the exception method, see "Exception Method" section.
subnet-sorting	Required, default disabled, as implemented in BIND 4.9.7. Specifies whether you want the address records in responses to queries to be reordered based on the subnet of the client. Since clients often only look at the first record of a set, enabling this feature can help localize network traffic onto a subnet. This feature only applies on answers to queries from clients located on the same subnet as the DNS server.
update-relax- zone-name	Required, default disabled. Enables relaxation of the RFC 2136 restriction on the zone name record in dynamic updates. This feature allows updates to specify a zone name, which is any name within an authoritative zone, rather than the exact name of the zone.

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-9 lists the property for which you will need to set or accept the defaults if you enable incremental transfer.

Table 2-9: Incremental Transfer Property

Property Description

ixfr-expire-interval

Required, default 604800 seconds (7 days). Indicates the longest interval to allow a secondary zone to be maintained solely with incremental transfers. After this period, the server requests a full zone transfer. Validation: 0 <= x <= 2147483647

Property	Description
ixfr-expire-interval	Required, default 604800 seconds (7 days). Indicates the longest interval to allow a secondary zone to be maintained solely with incremental transfers. After this period, the server requests a full zone transfer. Validation: 0 <= x <= 2147483647

For example, to enable incremental transfer for all your zones, type:

nrcmd> dns enable ixfr-enable

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

nrcmd> zone example.com disable ixfr

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

nrcmd> remote-dns create 128.103.1.1 set 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

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

Since a master server for a zone does not know specifically which slaves 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 NOTIFY, you need to set or accept the defaults for the properties listed in Table 2-10.

Table 2-10: NOTIFY Properties

Property Description

notify-defer-cnt

Required, default 100. The maximum number of changes you want to accumulate during the notify-wait period. If this number is exceeded, Network Registrar sends notification before the notify-wait period has passed.

notify-min-interval

Required, default 2 seconds. The minimum interval required before sending notification of consecutive changes on the same zone to a particular server.

Validation: 0 <= x <= 2147483647

notify-rcv-interval

Required, default 5 seconds. For secondary zones, the minimum amount of time between the completion of processing of one notification (serial number testing and/or zone transfer), and the start of processing of another notification.

Validation: 0 <= x <= 2147483647

notify-send-stagger

Required, default 1 second. The interval to stagger notification of multiple servers of a particular change.

Validation: 0 <= x <= 2147483647

notify-wait

Required, default 5 seconds. The period of time to delay, after an initial zone change, before sending change notification to other name servers. This property allows you to accumulate multiple changes, and thus limit the number of times the serial number advances.

Validation: 0 <= x <= 2147483647

Property	Description
notify-defer-cnt	Required, default 100. The maximum number of changes you want to accumulate during the notify-wait period. If this number is exceeded, Network Registrar sends notification before the notify-wait period has passed.
notify-min-interval	Required, default 2 seconds. The minimum interval required before sending notification of consecutive changes on the same zone to a particular server. Validation: 0 <= x <= 2147483647
notify-rcv-interval	Required, default 5 seconds. For secondary zones, the minimum amount of time between the completion of processing of one notification (serial number testing and/or zone transfer), and the start of processing of another notification. Validation: 0 <= x <= 2147483647
notify-send-stagger	Required, default 1 second. The interval to stagger notification of multiple servers of a particular change. Validation: 0 <= x <= 2147483647
notify-wait	Required, default 5 seconds. The period of time to delay, after an initial zone change, before sending change notification to other name servers. This property allows you to accumulate multiple changes, and thus limit the number of times the serial number advances. Validation: 0 <= x <= 2147483647

For example, to disable NOTIFY for all zones, type:

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

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

The syntax is:

dns get prop

dns set prop=value [prop=value]

dns unset prop

dns show

Table 2-11 lists and defines the DNS properties.

Table 2-11: DNS Properties

Property Description

local-port-num

Required, default 53. Specifies the UDP and TCP port number on which the DNS server listens for queries.

Validation: [1, 65535]

max-cache-ttl

Required, default 7 days. Indicates the maximum amount of time that you want Network Registrar to retain cached information.

Validation: 0 <= x <= 2147483647

mem-cache-size

Required, default 200 KB. Indicates the size of the in-memory record cache, in kilobytes.

Validation: 0 <= x <= 2147483647

neg-cache-ttl

Required, default 10 minutes. Indicates how long information learned from other name servers about non-existent names or data should be cached.

Validation: 0 <= x <= 2147483647

remote-port-num

Required. Specifies the UDP and TCP port to which the DNS server sends queries to other servers.

Validation: [1, 65535]

Property	Description
local-port-num	Required, default 53. Specifies the UDP and TCP port number on which the DNS server listens for queries. Validation: [1, 65535]
max-cache-ttl	Required, default 7 days. Indicates the maximum amount of time that you want Network Registrar to retain cached information. Validation: 0 <= x <= 2147483647
mem-cache-size	Required, default 200 KB. Indicates the size of the in-memory record cache, in kilobytes. Validation: 0 <= x <= 2147483647
neg-cache-ttl	Required, default 10 minutes. Indicates how long information learned from other name servers about non-existent names or data should be cached. Validation: 0 <= x <= 2147483647
remote-port-num	Required. Specifies the UDP and TCP port to which the DNS server sends queries to other servers. Validation: [1, 65535]

DNS Methods

The DNS methods commands allow you to 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 be able to retrieve the correct information.

The syntax is:

dns addRootHint name addr [addr]

dns removeRootHint name

dns listRootHints

For example, to add the root name server a.root-servers.net, type:

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

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

nrcmd> DNS removeRootHint a.root-servers.net

To list the root name servers, type:

nrcmd> DNS listRootHints

Exception Method

You need only use the exception method 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:

dns addException name addr [addr]

dns removeException name

dns listExceptions

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., type:

nrcmd> DNS addException blue.com. 192.168.1.4

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

nrcmd> DNS removeException blue.com.

To list the name servers, type:

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:

dns addForwarder addr [addr]

dns removeForwarder addr

dns listForwarders

For example, to add the forwarder server 192.168.1.4, type:

nrcmd> DNS addForwarder 192.168.1.4

To remove the name server 192.168.1.4, type:

nrcmd> DNS removeForwarder 192.168.1.4

To list the forwarder servers, type:

nrcmd> DNS listForwarders

Flushing the Cache

You can 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 completely clear a cache that has grown too large, stop the server, type the command, and restart the server.

The syntax is:

dns flushCache

Rebuilding Resource Records Indexes

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

The syntax is:

dns rebuildRR-Indexes

Exit

The exit command allows you to exit the current nrcmd command 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:

exit

For example, to quit Network Registrar's command line interface when you are in interactive mode, type exit:

nrcmd> exit

Export

The export command allows you to write the state of all the leases or the contents of a DNS zone on a specific cluster to a file.

The syntax is:

export leases [-server|-client] filename

export zone zone name [{static|dynamic|both} [file]]

export zonenames [{forward|reverse|both} [file]]

export hostfile [file]

Export Leases

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

The export command, with the argument leases -client, writes the state of all the current leases to the output file. For a description of the file format, refer to the "Import and Export File Formats" section.

For best results you should run the export command when the DHCP server is stopped. Although you can run the export command while the DHCP server is running without any negative effect on the server, if you do you might get some inconsistencies.

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.

The syntax is:

export leases [-server|-client] filename

The filename is the name of output file or "-" for standard out for client-side exports. Note that 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.

For example, to export the client leases to the output file leaseOut, type:

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 the all the currently held and expired leases to the output file leaseOut, type:

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 Jan 1, 1970. For example, 903968580.

Export Zone

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

The syntax is:

export zone zone-name arguments output-file

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, type:

nrcmd> export zone example.com static hosts.local

Export Zonenames

The export command with the argument zonenames 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 zonenames {forward|reverse|both} output-file

Export Hostfile

The export command with the argument hostfile 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:

export hostfile output-file

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:

Step 1 Write the extension in either Tcl, C or C++, and install it in the server extensions directory.

Solaris:
For Tcl this is /opt/AICnwreg2/extensions/DHCP/tcl.
For C or C++ this is /opt/AICnwreg2/extensions/DHCP/dex

Windows NT:
For Tcl this is \aic\registrar\extensions\dhcp\tcl
For C or C++ this is\aic\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 file name, just type the file name itself (with no / or \).

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

When entering a file name that contains a \ character on NT, you must enter it with a \\ (since \ is an escape character for the CLI). For example, to enter the file name "debug\myextension.tcl", enter debug\\myextension.tc.l.

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 Commands" section. For more information about choosing extensions points and writing extensions, see "Using Extension Points."

Step 4 Reload the server.

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

The syntax is:

extension name create lang file entry [prop=value]

extension name delete

extension list

For example, to configure a Tcl extension, type:

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

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

The syntax is:

extension name get prop

extension name set prop=value [prop=value]

extension name unset prop

extension name show

Table 2-12 lists and describes the extension properties.

Table 2-12: Extension Properties

Property Description

entry

Required (set by create), default <none>.The name of the entry point for the module. This function is called from any extension point to which this module is bound. The arguments for this function are server-implementation specific.

file

Required (set by create), default <none>.This file name is relative to the directory extensions in the installation. It cannot be a absolute pathname, nor can it contain any sequence of two dots (..).

init-args

Optional, default <none>.The arguments that should be passed to the init-entry point function. For more information about how the DHCP server parses this information, see "The Init-Entry Entry Point" section.

init-entry

Optional, default <none>.The name of the init-entry point. If you set it, Network Registrar calls this function when the server loads the module and when the server shuts down. For more information about this entry point, see "The Init-Entry Entry Point" section.

lang

Required (set by create), default <none>. The language in which the extension or module is implemented. Tcl indicates that the module is a Tcl extension (tcl7.5). Dex indicates that the module is a shared object with C calling interfaces.

name

Required (set by create), default <none>. The name of the extension or module. Network Registrar uses this name to assign extensions or modules to extension points. Changing this property renames the extension.

Property	Description
entry	Required (set by create), default <none>.The name of the entry point for the module. This function is called from any extension point to which this module is bound. The arguments for this function are server-implementation specific.
file	Required (set by create), default <none>.This file name is relative to the directory extensions in the installation. It cannot be a absolute pathname, nor can it contain any sequence of two dots (..).
init-args	Optional, default <none>.The arguments that should be passed to the init-entry point function. For more information about how the DHCP server parses this information, see "The Init-Entry Entry Point" section.
init-entry	Optional, default <none>.The name of the init-entry point. If you set it, Network Registrar calls this function when the server loads the module and when the server shuts down. For more information about this entry point, see "The Init-Entry Entry Point" section.
lang	Required (set by create), default <none>. The language in which the extension or module is implemented. Tcl indicates that the module is a Tcl extension (tcl7.5). Dex indicates that the module is a shared object with C calling interfaces.
name	Required (set by create), default <none>. The name of the extension or module. Network Registrar uses this name to assign extensions or modules to extension points. Changing this property renames the extension.

Force-Lock

The nrcmd command uses the same locking mechanism as Network Registrar. When you execute a command, the command 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. You can only issue 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.

To force an exclusive lock, type:

nrcmd> force-lock

Help

You can use the help command to display the nrcmd command's online help.

If you type 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 man page for the command of that name.

You can select the sections of the man 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 using the command
PROPERTIES---Descriptions of the features and properties
STATUS---Description of the status codes returned by this command

The syntax is:

help

help cmd [section]

For example, to print the list of commands, type:

-> help 
100 Ok

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

-> help help
100 Ok

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

-> 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 need to perform several configuration steps:

Step 1 Configure scopes in the DHCP server for the leases that you plan to import. For more information, see the "Scope" section.

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.

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

Note For all the time fields, you can use either the number of seconds since 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:

import leases file

For example, to import the file LeaseIn to the DHCP server, type:

nrcmd> import leases LeaseIn

If the lease time in the import file is greater than the lease time the client would have received if it were to acquire a lease, 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., not 5 p.m.

If your import file specifies a 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 Files

BIND uses a boot file, called named.boot, to point the server to it database files. You can import your entire BIND configuration by using the import command.

The syntax is:

import named.boot file

For example, to import the file /etc/named.boot to the DNS server, type:

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

You should use UNIX style paths 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

There is one known incompatibility between the way BIND loads named.boot configurations and the way the nrcmd command loads named.boot configurations.

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 command searches for the include file relative to the directory containing the zone file being processed.

You can avoid this problem completely if your 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-13 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-13: BIND to Nrcmd

BIND Nrcmd

directory new-directory

None---Supported within the named.boot file parser.

include file

None---supported within the named.boot file parser.

primary domain-name-of-zone file

zone create domain-name-of-zone primary file=file

secondary domain-name-of-zone ip-addr-list [backup-file]

zone create domain-name-of-zone secondary ip-addr [,ip-addr...]

forwarders ip-addr-list

dns addForwarder ip-addr [ip-addr...]

slave

dns enable slave-mode

tcplist ip-addr-or-network-list

zone domain-name-of-zone enable restrict-xfer

zone domain-name-of-zone set restricted-set=ip-addr [,ip-addr...]

xfernets ip-addr-or-network-list

zone domain-name-of-zone enable restrict-xfer zone domain-name-of-zone set restricted-set=ip-addr [,ip-addr...]

max-fetch number

dns set xfer-client-concurrent-limit=number

domain local-domain-name

unsupported

cache domain-name file

unsupported

sortlist network-list

unsupported

stub domain ip-addr-list [backup-file]

unsupported

bogusns ip-addr-list

unsupported

check-names primary/secondary/response fail/warn/ignore

unsupported

options forward-only

dns enable slave-mode

options no-recursion

dns enable no-recurse

options no-fetch-glue

dns enable no-fetch-glue

options fake-iquery

None---Network Registrar only supports fake iquery

options query-log

unsupported

limit transfers-in number

dns set xfer-client-concurrent-limit=number

limit transfers-per-ns number

unsupported

limit datasize number

unsupported

limit files number

unsupported

BIND	Nrcmd
directory new-directory	None---Supported within the named.boot file parser.
include file	None---supported within the named.boot file parser.
primary domain-name-of-zone file	zone create domain-name-of-zone primary file=file
secondary domain-name-of-zone ip-addr-list [backup-file]	zone create domain-name-of-zone secondary ip-addr [,ip-addr...]
forwarders ip-addr-list	dns addForwarder ip-addr [ip-addr...]
slave	dns enable slave-mode
tcplist ip-addr-or-network-list	zone domain-name-of-zone enable restrict-xfer zone domain-name-of-zone set restricted-set=ip-addr [,ip-addr...]
xfernets ip-addr-or-network-list	zone domain-name-of-zone enable restrict-xfer zone domain-name-of-zone set restricted-set=ip-addr [,ip-addr...]
max-fetch number	dns set xfer-client-concurrent-limit=number
domain local-domain-name	unsupported
cache domain-name file	unsupported
sortlist network-list	unsupported
stub domain ip-addr-list [backup-file]	unsupported
bogusns ip-addr-list	unsupported
check-names primary/secondary/response fail/warn/ignore	unsupported
options forward-only	dns enable slave-mode
options no-recursion	dns enable no-recurse
options no-fetch-glue	dns enable no-fetch-glue
options fake-iquery	None---Network Registrar only supports fake iquery
options query-log	unsupported
limit transfers-in number	dns set xfer-client-concurrent-limit=number
limit transfers-per-ns number	unsupported
limit datasize number	unsupported
limit files number	unsupported

Ldap

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

The syntax is:

ldap name create hostname [prop=value]

ldap name delete

ldap list

For example, to create an LDAP server object myserver with a host name of myserver.mycompany.com, type:

nrcmd> ldap myserver create myserver.mycompany.com

To delete an ldap server object myserver, type:

nrcmd> ldap myserver delete

To list the ldap server objects, type:

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:

ldap name disable feature

ldap name enable feature

ldap name get feature

Table 2-14 lists and describes the LDAP features. Note that after you enable a feature you can set its properties.

Table 2-14: LDAP Features

Feature Description

can-query

Optional, default false. Enables you to refine queries to the LDAP server.

can-update

Optional, default false. Enables you to specify the types of updates to the LDAP server.

limit-requests

Optional, default false. Enables you to limit the number of outstanding queries to the LDAP server. If you enable this feature you can set the maxprequest property.

Feature	Description
can-query	Optional, default false. Enables you to refine queries to the LDAP server.
can-update	Optional, default false. Enables you to specify the types of updates to the LDAP server.
limit-requests	Optional, default false. Enables you to limit the number of outstanding queries to the LDAP server. If you enable this feature you can set the maxprequest property.

LDAP Properties

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

The syntax is:

ldap name get prop

ldap name set prop=value [prop=value]

ldap name unset prop

Table 2-15 lists and describes the LDAP properties.

Table 2-15: LDAP Properties

Property Description

connections

The number of connections that the server should make to a particular LDAP server. This is primarily a performance-tuning parameter. In some cases, more than one connection can improve overall throughput.

dn-attribute

If the dn (distinguished name) of the LDAP object to update can be constructed from one of the lease attributes, the specified dn-attribute is formatted using the dn-format string to construct the object filter that specifies the LDAP server to be modified.

dn-format

Formats the dn-attribute. A %s is required and is replaced with the value of the dn-attribute.

hostname

The host name of the server to connect to. Network Registrar needs the host name for LDAP servers.

max-referrals

The limit on the number of LDAP referrals Network Registrar will follow when querying. A value of zero means "don't follow referrals."

max-requests

Limits any single LDAP connection to this number of outstanding queries. You may choose to limit the number of outstanding queries to improve performance. The DHCP server uses this configuration information when preparing client-entry queries.

password

The password of a user with access to the parts of the directory that DHCP will use. (LDAP servers can be configured to allow anonymous access, so this is optional).

port

The port to connect to. (There is a default.)

preference

A positive integer. LDAP servers can be used in preference order: 1 is the highest preference value.

referral-attr

The name of the LDAP attribute that may indicate that an LDAP response is a referral. The referral may or may not contain the dn to query for. If the dn is present (the current server assumes this), it is used as the search path along with a wildcard search scope in the query that follows the referral. If not, the search path is built by formatting the data in the referral attribute with the referral filter, and the existing search scope is used.

referral-filter

If the referral attribute does not contain a dn, the referral-attribute's data is formatted with this filter expression to build a search path, and the existing search scope for the LDAP server is used.

search-filter

The filter to be applied in the query. A %s is required and is replaced by the value of the dn attribute.

search-path

The name of an object in the directory to use as a query's starting-point. The path and the scope together control the portion of the directory that are searched.

search-scope

The scope can be SUBTREE (all children of the search path will be searched), ONELEVEL (only one the immediate children of the base object will be searched), or BASE (only the base object will be searched).

timeout

The number of seconds the DHCP server should wait for a response to an individual query. After a query times out, the server may re-try another LDAP server connection, or drop it.

threadwaittime

The interval (in milliseconds) at which each LDAP client connection polls for results, if it has outstanding queries or updates.

update-search-attribute

If the LDAP object's dn cannot be determined directly, the DHCP server must issue a query to retrieve the dn. In that case, the DHCP server uses these parameters to extract the data from a lease attribute (specified by the search-attribute, and format it using the search-filter expression).

update-search-filter

Formats the update-search-attribute. A %s is required and is replaced with the value of the dn-attribute.

update-search-path

The search filter (built using either the dn attribute or the search attribute) is used along with the path and scope to specify the LDAP object that should be updated.

update-search-scope

The search scope is used to specify the LDAP object that should be updated.

username

The distinguished name of an object with access to the parts of the directory that DHCP will use. (Because you can configure LDAP servers to allow anonymous access, this property is optional.)

Property	Description
connections	The number of connections that the server should make to a particular LDAP server. This is primarily a performance-tuning parameter. In some cases, more than one connection can improve overall throughput.
dn-attribute	If the dn (distinguished name) of the LDAP object to update can be constructed from one of the lease attributes, the specified dn-attribute is formatted using the dn-format string to construct the object filter that specifies the LDAP server to be modified.
dn-format	Formats the dn-attribute. A %s is required and is replaced with the value of the dn-attribute.
hostname	The host name of the server to connect to. Network Registrar needs the host name for LDAP servers.
max-referrals	The limit on the number of LDAP referrals Network Registrar will follow when querying. A value of zero means "don't follow referrals."
max-requests	Limits any single LDAP connection to this number of outstanding queries. You may choose to limit the number of outstanding queries to improve performance. The DHCP server uses this configuration information when preparing client-entry queries.
password	The password of a user with access to the parts of the directory that DHCP will use. (LDAP servers can be configured to allow anonymous access, so this is optional).
port	The port to connect to. (There is a default.)
preference	A positive integer. LDAP servers can be used in preference order: 1 is the highest preference value.
referral-attr	The name of the LDAP attribute that may indicate that an LDAP response is a referral. The referral may or may not contain the dn to query for. If the dn is present (the current server assumes this), it is used as the search path along with a wildcard search scope in the query that follows the referral. If not, the search path is built by formatting the data in the referral attribute with the referral filter, and the existing search scope is used.
referral-filter	If the referral attribute does not contain a dn, the referral-attribute's data is formatted with this filter expression to build a search path, and the existing search scope for the LDAP server is used.
search-filter	The filter to be applied in the query. A %s is required and is replaced by the value of the dn attribute.
search-path	The name of an object in the directory to use as a query's starting-point. The path and the scope together control the portion of the directory that are searched.
search-scope	The scope can be SUBTREE (all children of the search path will be searched), ONELEVEL (only one the immediate children of the base object will be searched), or BASE (only the base object will be searched).
timeout	The number of seconds the DHCP server should wait for a response to an individual query. After a query times out, the server may re-try another LDAP server connection, or drop it.
threadwaittime	The interval (in milliseconds) at which each LDAP client connection polls for results, if it has outstanding queries or updates.
update-search-attribute	If the LDAP object's dn cannot be determined directly, the DHCP server must issue a query to retrieve the dn. In that case, the DHCP server uses these parameters to extract the data from a lease attribute (specified by the search-attribute, and format it using the search-filter expression).
update-search-filter	Formats the update-search-attribute. A %s is required and is replaced with the value of the dn-attribute.
update-search-path	The search filter (built using either the dn attribute or the search attribute) is used along with the path and scope to specify the LDAP object that should be updated.
update-search-scope	The search scope is used to specify the LDAP object that should be updated.
username	The distinguished name of an object with access to the parts of the directory that DHCP will use. (Because you can configure LDAP servers to allow anonymous access, this property is optional.)

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 strings keys to string values.

The syntax is:

ldap name setEntry prop key=value

ldap name getEntry prop key=value

ldap name unsetEntry prop key

Table 2-16 lists and describes the LDAP dictionary properties.

Table 2-16: LDAP Dictionary Properties

Properties Description

env-dictionary

Controls whether additional LDAP attributes are retrieved along with client-entry attributes. If any of these are present in a query's results, their values are made available to scripts through the request's environment dictionary. The LDAP value is keyed by the value in the LDAP query env-dictionary.

query-dictionary

Controls the mapping between the names of LDAP attributes and client-entry attributes. The server will attempt to retrieve all of the LDAP attributes specified in the dictionary. When a query succeeds, the values for any LDAP attributes that it returns are set in the corresponding client-entry attributes.

update-dictionary

The dictionary that maps LDAP attributes to DHCP lease attributes. When an LDAP object is modified, each LDAP attribute that is present in this dictionary is set to the value of its corresponding DHCP lease attribute.

Properties	Description
env-dictionary	Controls whether additional LDAP attributes are retrieved along with client-entry attributes. If any of these are present in a query's results, their values are made available to scripts through the request's environment dictionary. The LDAP value is keyed by the value in the LDAP query env-dictionary.
query-dictionary	Controls the mapping between the names of LDAP attributes and client-entry attributes. The server will attempt to retrieve all of the LDAP attributes specified in the dictionary. When a query succeeds, the values for any LDAP attributes that it returns are set in the corresponding client-entry attributes.
update-dictionary	The dictionary that maps LDAP attributes to DHCP lease attributes. When an LDAP object is modified, each LDAP attribute that is present in this dictionary is set to the value of its corresponding DHCP lease attribute.

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

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, type:

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

To configure a query-dictionary to search for the localityname to use for the domain name, type:

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

Lease

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

The syntax is:

lease list

lease withMACaddr mac address

lease name show

lease name activate

lease name deactivate

lease name force-available

lease name macaddr

Table 2-17 lists and describes the lease command actions.

Table 2-17: Lease Command Actions

Action Description

activate

Removes the deactivate flag from the lease, but does not change the status of a lease marked as unavailable.

deactivate

Prevents the lease from being given out or renewed, but doesn't change the state of the lease.

force-available

Makes a currently held lease available, even a lease marked as unavailable. Because using the force-available action may compromise the integrity of your IP address allocations, make sure that before you use the command the client holding the lease has stopped using the lease.

macaddr

Displays the most recent MAC address associated with this lease. If no MAC address was ever associated with this lease (or if the lease has become unavailable), then Network Registrar displays the error message, "302 Not Found."

show

Displays the lease attributes for a specific address.

withMACaddr

Lists all leases that are associated with the specified MAC address.

Action	Description
activate	Removes the deactivate flag from the lease, but does not change the status of a lease marked as unavailable.
deactivate	Prevents the lease from being given out or renewed, but doesn't change the state of the lease.
force-available	Makes a currently held lease available, even a lease marked as unavailable. Because using the force-available action may compromise the integrity of your IP address allocations, make sure that before you use the command the client holding the lease has stopped using the lease.
macaddr	Displays the most recent MAC address associated with this lease. If no MAC address was ever associated with this lease (or if the lease has become unavailable), then Network Registrar displays the error message, "302 Not Found."
show	Displays the lease attributes for a specific address.
withMACaddr	Lists all leases that are associated with the specified MAC address.

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

For example, to activate lease 192.168.1.9, type:

nrcmd> lease 192.168.1.9 activate

Lease Command Properties

You can use get to display the values from the lease properties. These properties are read-only.

The syntax is:

lease name get prop

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

Table 2-18: 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 "Client Flags".

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.

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 deactivated, which means that it should not be used. Any clients that are using deactivated leases will be NAK'ed on their next renewal.

start-time-of-state

The time at which the state last changed to its current value. You can use this property to determine when the lease was made unavailable.

state

The current state of the lease.

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 "Client Flags".
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.
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 deactivated, which means that it should not be used. Any clients that are using deactivated leases will be NAK'ed on their next renewal.
start-time-of-state	The time at which the state last changed to its current value. You can use this property to determine when the lease was made unavailable.
state	The current state of the lease.

Client Flags

You can use the following client flags:

client-dns-name-up-to-date---the client-dns-name (A record) is current in the DNS server database.
client-id-created-from-mac-address---the client-id was created for internal use from the client-supplied MAC address. If this is true, the server will not report it.
dns-update-pending---a DNS operation is pending for this client.
reverse-dns-up-to-date---the reverse (PTR record) DNS entry is current in the DNS database.

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

available---the lease is not currently leased by any client. Any client information is from the most recent client-to-lease or be-offered this lease.
expired---the client has not renewed the lease, and it expired. Upon expiration the DHCP server scheduled removal of the client's DNS information.
leased---the lease is currently leased to the client whose information appears in the lease.
offered---the lease is offered to the associated client. In many cases, the database is not written with information concerning offering a lease to a client, since there is no requirement to update stable storage with this information.
unavailable---the lease is unavailable. It was made unavailable because of some conflict. A ping attempt might have shown that the IP address was already in use by another client, or the DHCP server might have noticed another DHCP server handing out this lease.

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:

lease-notification available=number|percentage% [config=config file] [errors-to=recipient mail-host=name] [recipients=recipient[,recipient] [mail-host= name [errors-to= receipient]]][scopes=scope name|address range[,scope name|address range,...]]

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

For example, to specify scope 1 with an available value of 10% and e-mail recipients billy, bob, and jane, type:

nrcmd> lease-notification available=10% scopes=scope1 recipients=billy,bob,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 NT mail host as mailhost, type:

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

Lease-Notification Properties

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

Table 2-19: Lease-notification Properties

Property Description

available

Specify either a number or percentage of available addresses. If the number or percentage of available addresses is equal to or less than the specified value for the scopes being checked, Network Registrar generates a report listing information about the scopes that reach or exceed the available value.

config

Specify a configuration file. If you do not specify a configuration file, Network Registrar searches for the default .nrconfig file. For more information about the search order, see the "Specifying the Config File" section.

errors-to

If you specify a mail-host you may also specify the e-mail address of the sender of the e-mail in order to provide a return path for bounced e-mail. The default value is postmaster.

mail-host

On NT, you must specify a mail-host. On Solaris the mail host is generally already configured for the sendmail program. You can verify that your Solaris system is properly configured by issuing the command date | mail your-email-address and observing whether or not the date is e-mailed to you.

recipients

If you specify the e-mail addresses of one or more recipients, Network Registrar sends an e-mail report to those addresses. Otherwise, Network Registrar directs the report to standard output.

scopes

Specify the scopes either by their names or as a range or ranges of addresses. Network Registrar checks any scope containing any address that falls within the range of address. If you do not list any scopes or addresses, Network Registrar checks all scopes managed by the specified cluster.

Property	Description
available	Specify either a number or percentage of available addresses. If the number or percentage of available addresses is equal to or less than the specified value for the scopes being checked, Network Registrar generates a report listing information about the scopes that reach or exceed the available value.
config	Specify a configuration file. If you do not specify a configuration file, Network Registrar searches for the default .nrconfig file. For more information about the search order, see the "Specifying the Config File" section.
errors-to	If you specify a mail-host you may also specify the e-mail address of the sender of the e-mail in order to provide a return path for bounced e-mail. The default value is postmaster.
mail-host	On NT, you must specify a mail-host. On Solaris the mail host is generally already configured for the sendmail program. You can verify that your Solaris system is properly configured by issuing the command date \| mail your-email-address and observing whether or not the date is e-mailed to you.
recipients	If you specify the e-mail addresses of one or more recipients, Network Registrar sends an e-mail report to those addresses. Otherwise, Network Registrar directs the report to standard output.
scopes	Specify the scopes either by their names or as a range or ranges of addresses. Network Registrar checks any scope containing any address that falls within the range of address. If you do not list any scopes or addresses, Network Registrar checks all scopes managed by the specified cluster.

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 several ways:

The default cluster (localhost).
The Solaris environment or 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:

# Cluster information for lease notification
[lease-notification] 
# Clustername Username Password 
clusters=host1 admin passwd1,host2 admin,host3,host3 admin2 passwd2

Note that 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 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.

Running Lease-notification Automatically on Solaris

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/bin/nrcmd lease-notification available=10%
config=/home/jsmith/.nrconfig addresses=192.32.1.0-192.32.128.0 recipients=jsmith,jdoe@american.com 1>/dev/null 2>&1

You can perform crontab editing by running the Solaris 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 path name on the crontab command line. You can determine the full path name in your environment with the Solaris 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. Since 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 your home directory. 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. If you want the nrcmd command to run the notification command on a different cluster than the one on which it is being run, you also need to supply a config file with a fully specified path name.

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 Solaris chmod go-rw config_file command.

Running Lease-notification Automatically on NT

You can 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, but the at command can only schedule a command to run once a day or less.

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 2.5 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:

license set prop=value

license get prop

license show

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

Table 2-20: License Command Properties

Properties Description

expiration

The expiration date of the license. Note that the date is read-only.

key

The license key

Properties	Description
expiration	The expiration date of the license. Note that the date is read-only.
key	The license key

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

nrcmd -C cluster1 -N admin -P aicuser
nrcmd> license set key=1234-abcd-5678-efgh
100 Ok
nrcmd> exit

Listaddr

The listaddr command provides the address utilization reporting functionality of the listaddr.bat command available in earlier versions of Network Registrar. Because the output from this command was designed for analysis tools such as spreadsheets, the formatting is not ideal for end-users.

Note The listaddr 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 or licensing problems). The second "100 OK" indicates that the list was produced successfully.

The output for the listaddr command is a series of eight-column, comma-separated rows. There is one row for each known address. Thus, the total output can be quite verbose. A column may be empty if the usage of that column does not apply to the address. Table 2-21 lists and describes the meanings of the columns.

Table 2-21: listaddr Output

Column Description

1

IP address in unsigned hexadecimal format.

2

IP address in the canonical dotted format.

3

Type of the address. These types are defined as follows:

STATIC---assigned to a host through DNS.

DYNAMIC---assigned to a host through a DHCP lease.

UNALLOCATED---the address is in the range of a DHCP scope, but is not in use.

RESERVED---the address is reserved for a host through DHCP.

4

DNS name of host, for assigned addresses only.

5

State of the address. This field is blank for any address other than those assigned through DHCP leases. The values for such addresses are: Available, Unavailable, Leased, Expired, Deactivated.

6

Native host name, for addresses assigned through a DHCP lease. This is usually the Windows or UNIX name for the host.

7

MAC address, for addresses assigned through a DHCP lease.

8

Expiration time, for DHCP dynamic addresses.

Column	Description
1	IP address in unsigned hexadecimal format.
2	IP address in the canonical dotted format.
3	Type of the address. These types are defined as follows:
STATIC---assigned to a host through DNS.
DYNAMIC---assigned to a host through a DHCP lease.
UNALLOCATED---the address is in the range of a DHCP scope, but is not in use.
RESERVED---the address is reserved for a host through DHCP.
4	DNS name of host, for assigned addresses only.
5	State of the address. This field is blank for any address other than those assigned through DHCP leases. The values for such addresses are: Available, Unavailable, Leased, Expired, Deactivated.
6	Native host name, for addresses assigned through a DHCP lease. This is usually the Windows or UNIX name for the host.
7	MAC address, for addresses assigned through a DHCP lease.
8	Expiration time, for DHCP dynamic addresses.

The syntax is:

listaddr

For example, to run listaddr, type:

nrcmd> listaddr

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:

policy name create [prop=value]

policy name delete

policy list

For example, to create the policy CompanyB, type:

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:

policy name enable feature

policy name delete feature

policy name get

Table 2-22 lists and describes the policy features.

Table 2-22: Policy Features

Feature Description

allow-lease-time-override

Optional, default true Clients may request a specific lease time. The server will not honor those requested lease times if this attribute is false. The server will not honor a client's lease time if the time is longer than the server's normal lease time.

permanent-leases

Optional, default false. Specifies that leases for this scope should be permanently granted to requesting clients.

split-lease-times

Optional, default false. Controls whether the server uses the value of its lease time (server-lease-time) to determine the length of the lease. The DHCP server offers clients lease times that reflect the configured lease-time option from the appropriate policy.

Feature	Description
allow-lease-time-override	Optional, default true Clients may request a specific lease time. The server will not honor those requested lease times if this attribute is false. The server will not honor a client's lease time if the time is longer than the server's normal lease time.
permanent-leases	Optional, default false. Specifies that leases for this scope should be permanently granted to requesting clients.
split-lease-times	Optional, default false. Controls whether the server uses the value of its lease time (server-lease-time) to determine the length of the lease. The DHCP server offers clients lease times that reflect the configured lease-time option from the appropriate policy.

Policy Properties

You can use the set and get commands to assign and retrieve values from the policy's properties.

The syntax is:

policy name get prop

policy name set prop=value

Table 2-23 lists and describes the policy properties.

Table 2-23: Policy Properties

Property Description

bootp-reply-options

Optional, default <none> A list of the names of options that should be returned in any replies to BOOTP clients. The options themselves do not have to have been configured in the same policy as the reply-options list; the server will search the hierarchy of policies for each option named in the list. For more information about this property, see the "Policy Reply Options" section.

dhcp-reply-options

Optional, default <none> A list of the names of options that should be returned in any replies to DHCP clients. The options themselves do not have to have been configured in the same policy as the reply-options list; the server will search the hierarchy of policies for each option named in the list. For more information about this property, see the "Policy Reply Options" section.

grace-period

Optional, default 5 minutes. The length of time between the expiration of a lease and the time it is made available for re-assignment.

offer-timeout

Optional, default 2 minutes. If the server offers a lease to a client, but the offer is not accepted, the server will wait the specified number of minutes before making the lease available again.

packet-file-name

Optional, default <none>. The name of a boot file to be used in a client's boot process. The server returns this file name in the 'file' field of its replies. The packet-file-name cannot be longer than 128 characters.

packet-server-name

Optional, default <none>. The host name of a server to use in a client's boot process. The server returns this file name in the 'sname' field of its replies. The packet-server-name field cannot be longer than 64 characters.

packet-siaddr

Optional, default <none>. The IP address of the next server in a client's boot process. For example, this might be the address of a TFTP server used by BOOTP clients. The server returns this address in the siaddr field of its reply.

server-lease-time

Optional, default <none> The time that the server believes the lease is valid. It may be useful to have the server consider leases leased for a longer period than the client in order to get more frequent client communication along with the stability of long lease times.

Property	Description
bootp-reply-options	Optional, default <none> A list of the names of options that should be returned in any replies to BOOTP clients. The options themselves do not have to have been configured in the same policy as the reply-options list; the server will search the hierarchy of policies for each option named in the list. For more information about this property, see the "Policy Reply Options" section.
dhcp-reply-options	Optional, default <none> A list of the names of options that should be returned in any replies to DHCP clients. The options themselves do not have to have been configured in the same policy as the reply-options list; the server will search the hierarchy of policies for each option named in the list. For more information about this property, see the "Policy Reply Options" section.
grace-period	Optional, default 5 minutes. The length of time between the expiration of a lease and the time it is made available for re-assignment.
offer-timeout	Optional, default 2 minutes. If the server offers a lease to a client, but the offer is not accepted, the server will wait the specified number of minutes before making the lease available again.
packet-file-name	Optional, default <none>. The name of a boot file to be used in a client's boot process. The server returns this file name in the 'file' field of its replies. The packet-file-name cannot be longer than 128 characters.
packet-server-name	Optional, default <none>. The host name of a server to use in a client's boot process. The server returns this file name in the 'sname' field of its replies. The packet-server-name field cannot be longer than 64 characters.
packet-siaddr	Optional, default <none>. The IP address of the next server in a client's boot process. For example, this might be the address of a TFTP server used by BOOTP clients. The server returns this address in the siaddr field of its reply.
server-lease-time	Optional, default <none> The time that the server believes the lease is valid. It may be useful to have the server consider leases leased for a longer period than the client in order to get more frequent client communication along with the stability of long lease times.

For example, to set the grace period to three days for policy 168.1-net, type:

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 three policies: the client's policy, the client's client-class's policy, and the client's lease's scope's policy, in that order. The server looks through those policies for option data for which that the client has asked. 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 command 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 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 command help dhcp-option.

The syntax is:

policy name listOptions

policy name setOption optname value

policy name getOption optname

policy name unsetOption optname

Table 2-24 lists and describes the policy options.

Table 2-24: Policy Options

Property Description

listOptions

Lists the options in the named policy.

setOption

Sets the option name and value to the specified policy. The format is optname value. For example, dhcp-lease-time 3600.

getOption

Gets the value of the named option.

unsetOption

Removes the named option from the specified policy.

Property	Description
listOptions	Lists the options in the named policy.
setOption	Sets the option name and value to the specified policy. The format is optname value. For example, dhcp-lease-time 3600.
getOption	Gets the value of the named option.
unsetOption	Removes the named option from the specified policy.

For example, to specify the lease time in a scope, type:

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

To list the options in a policy, type:

nrcmd> policy 168.1-net listOptions

Policy Lease Time Method Commands

You can use the setLeaseTime command to set the values of lease times and the getLeaseTime command to display the value of a lease time.

The syntax is:

policy name setLeaseTime value

policy name getLeaseTime

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

Lease Times

A policy contains two lease times: the 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.

Remote-Dns

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

The syntax is:

remote-dns create addr[/maskbits] [prop=value]

remote-dns name delete

remote-dns list

Table 2-25 lists and describes the remote-dns properties.

Table 2-25: Remote-dns Properties

Property Description

addr

The address of the server or network to which this information applies.

maskbits

The number of bits in the addr attribute that are significant.

Property	Description
addr	The address of the server or network to which this information applies.
maskbits	The number of bits in the addr attribute that are significant.

For example, to create the remote server description 128.103.1.1 with the net mask of 255.255.255.255, type:

nrcmd> remote-dns create 128.103.1.1/16

Note that each net mask octet is composed of 8 bits. In the example above the first two octets are significant, thus the netmask is 16. If just the first three octets were significant, the net mask would be 24, etc.

Remote-dns Features

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

remote-dns name disable feature
remote-dns name enable feature
remote-dns name get feature

Table 2-26 lists and describes the remote DNS server description features.

Table 2-26: Remote-dns Features

Feature Description

ixfr

Optional, default false. Indicates whether or not a foreign server supports incremental transfer and should be queried for incremental (IXFR) before full (AXFR) when asking for zone transfers. Although unwittingly setting this to true is generally harmless, doing so may result in additional transactions to accomplish a zone transfer.

multirec

Optional, default false. Indicates whether or not a remote server can be sent zone transfers (AXFR) with multiple records in one TCP packet. Older DNS servers will crash when receiving such transfers, despite being allowed by the protocol.

For example, 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. You can 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, type:

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

To disable all DNS servers 128.103.1.1/32 from performing incremental transfers, type:

nrcmd> remote-dns create 128.103.1.1/32 ixfr=false

Note that a netmask of 32 is equivalent to no netmask.

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:

report [config=config file][column-separator=character string] [dhcp-only][file=output file][mask-bits=value]

Table 2-27 lists and describes the report properties.

Table 2-27: Report Properties

Property Description

column-separator

Specifies the character string you want used between the columns in the report. The default is a single space. If you specify whitespace, you must escape it with a backslash (\) and if it is entered on the command line, use quotes. For example, =,\ or =",\"

config

A file that allows you to specify multiple clusters.

dhcp-only

Specifies a summary of just the DHCP information.

file

Specifies the file name to which the report command writes the output. If you do not specify a file name, the report command writes to standard out. Note that, since it can take a long time to collect DNS data, you should not run the report command interactively when requesting DNS summaries.

mask-bits

Specifies the number of high-order bits set in the network mask that define a logical subnet for which the report command produces a summary. The default value is 16.

If the value of the mask-bits is less than the default or less than the largest mask of any scope's mask in the report, the report command uses the default value.

For example, to create a report of static DNS addresses and dynamic DHCP addresses, type:

nrcmd> report

To create a report of only DHCP scopes, type:

nrcmd> report dhcp-only

Specifying Clusters

You can specify clusters in several ways:

The default cluster (localhost)
The Solaris environment or 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:

# Cluster information for summary reports 
[report] 
# Clustername Username Password 
clusters=host1 admin passwd1,host2 admin,host3,host3 admin2 passwd2

Note that 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.

If Network Registrar cannot find a user name or password or the supplied user name and password are incorrect, the report command prompts you for the information.

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 commands 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 name
Addresses---total addresses within the scope ranges, addresses = free + dynamically leased + reserved + unavailable + deactivated
Free---addresses within a range and in the available state and not flagged reserved or deactivated
% free---as a percentage of all addresses within scope ranges
Reserved---within a range and flagged reserved, unless unavailable
Leased---within a range and in the leased, offered or expired state, even if flagged reserved or deactivated
Dynamically leased---within a range and in the leased, offered, or expired state, unless flagged reserved or deactivated
Unavailable---within a range and marked as unavailable by the server, regardless of flags
Deactivated---within a range and flagged deactivated, unless unavailable
Other reservations---addresses marked reserved which are not within a scope range

Addresses have both a current state and a pending state after their lease expires.The categories leased and unavailable represent current states. The categories dynamically leased, reserved, and deactivated may represent current or pending states. The category free represents the current state available minus addresses flagged reserved or deactivated. Note that, the leased category overlaps other categories and is not incorporated in the scope total.

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

Total---all addresses in the subnet
Static---addresses statically assigned
Unallocated---addresses unallocated to DHCP scope ranges, otherwise reserved or statically assigned, and therefore available for static assignment or allocation to a scope range
Grand total---at the end of the report a total that summarizes all the data in the subnets

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

Table 2-28: Potential States and Flags for IP Addresses

Flags None Reserved Deactivated Reserved and Deactivated

State

reserved

deactivated

reserved and deactivated

available

free

reserved

deactivated

deactivated

offered

dynamically leased leased

dynamically leased leased

deactivated leased

deactivated leased

leased

dynamically leased leased

dynamically leased leased

deactivated leased

deactivated leased

expired

dynamically leased leased

dynamically leased leased

deactivated leased

deactivated leased

unavailable

unavailable

unavailable

unavailable

unavailable

Save

The save command allows you to validate and save your changes to the database.

The syntax is:

save

Validation

The nrcmd command performs validation when you create objects or modify their properties. It checks that you have supplied the required properties and that their values are valid. It also checks the validity of property values when you set them.

When you issue the save command, Network Registrar performs three levels of validation:

It checks that no other modifications have been made to these objects since they were read from the database.
It checks that all affected references are still valid.
It ensures that the proposed modifications would result in a valid server configuration.

Note If you create dangling references by deleting a referred-to-object such as the policy for a scope, or the client-class for a client, the nrcmd command will not alert you by displaying an error message.

Error Codes

All nrcmd commands return a status code as the first line of output. The status codes are affected by SMTP and other line-oriented protocols. The first word on the line is a three-digit status code, and the remaining output is the descriptive text. The first digit of the status code determines the class of the status.

Table 2-29 lists and describes the save command error codes.

Table 2-29: Save Error Codes

Error Code Description

100 OK

Indicates a successful save.

3xx

Indicates an error in processing the command.

4xx

Indicates an error in communicating with the cluster database server.

5xx

Indicates an internal error in the command.

For more information about error codes, see "Error Codes."

Scope

The scope command allows you to create and edit DHCP scopes.

The syntax is:

scope name create addr mask [prop=value]

scope name delete

scope list

For example, to create a scope, type:

nrcmd> scope testScope create 192.168.1.0 255.255.255.0

Note that you need to specify the scope mask in the base of 10 (such as 255.255.255.0), not in hexadecimal.

To delete a scope, type:

nrcmd> scope testScope delete

To list scopes, type:

nrcmd> scope list

Scope Features

The scope command allows you to enable, disable, or determine whether the feature has been set. You use the enable, disable, or get commands. Note that the get command displays the value of the feature.

The syntax is:

scope name disable feature

scope name enable feature

scope name get feature

Table 2-30 lists and describes the scope features.

Table 2-30: Scope Features

Feature Description

bootp

Optional, default disabled. Controls whether the server accepts BOOTP requests. If you want clients to always receive the same addresses, you need to reserve IP addresses for all your BOOTP clients. For information about how to reserve address, see the "Scope Reservations" section.

dhcp

Optional, default enabled. Controls whether the DHCP server will accept DHCP requests for this scope. You would only disable DHCP for a scope to cause the scope to be used for BOOTP exclusively, or to temporarily deactivate a scope.

dynamic-bootp

Optional, default disabled. Controls whether the server will accept dynamic BOOTP requests for this scope. Dynamic BOOTP requests are BOOTP requests that do not match a reservation, but can be satisfied from the available lease pool. To use this feature, you must also enable BOOTP.

dynamic-dns

Optional, default disabled. Controls whether the DHCP server should attempt to update a DNS server with the name and address information from leases that are granted to requesting clients.

ping-clients

Optional, default disabled. Controls whether the server should attempt to ping an address.

renew-only

Optional, default <none>. Controls whether to allow existing clients to re-acquire their leases, but not to offer any leases to new clients. Note that a renew-only scope will not change the client associated with any of its leases, other than to allow a client currently using an available IP address to continue to use it.

synthesize-name

Optional, default disabled. Controls whether the DHCP server automatically creates DNS host names for DHCP clients who do not provide names. The server can synthesize unique names for clients based on the synthetic-name-stem property.

update-dns-first

Optional, default disabled. Controls whether the DHCP server is updated before the lease is granted.

For example, to enable dynamic DNS update, type:

nrcmd> scope testScope enable dynamic-dns

To disable dynamic BOOTP, type:

nrcmd> scope testScope disable dynamic-bootp

Scope Properties

You can use the set and get commands to assign and retrieve values from the scope's properties.

The syntax is:

scope name get prop=value

scope name set prop=value [prop=value ...]

scope name show

Table 2-31 lists and describes the scope properties.

Table 2-31: Scope Properties

Property Description

addr

Optional, default <none>. The address of the subnet for which this scope contains addresses. (Read-only)

deactivated

Optional, default <none>. A scope that does not extend leases to clients. It treats all of the addresses in its ranges as if they were individually deactivated.

dns-rev-server-addr

Optional, default <none>. The address of the reverse DNS server for the zone into which the server should add PTR records.

dns-reverse-zone-name

Optional, default <none>. The name of the inverse (in.addr.arpa) zone that is updated with PTR and TXT records.

dns-server-addr

Optional, default <none>. The IP address of the primary DNS server on which the forward zone resides.

dns-zone-name

Optional, default <none>. The name of the DNS zone to which a DHCP client's host name should be added (A record).

mask

Optional, default <none>. The mask associated with the scope's network address. (Read-only)

ping-timeout

Optional, default <none>. The number of milliseconds the DHCP server should wait for ping responses. If you make this value too large, you will slow down the lease offering processes. If you make this value too small, you will reduce the effectiveness of pinging addresses before offering them.

policy

Optional, default <none>. The name of the policy associated with this scope.

primary-addr

Optional, default <none>. The IP address of the primary scope for this (secondary) scope.

primary-mask

Optional, default <none>. The subnet mask of this scope's primary scope (if this is a secondary scope).

primary-scope

Optional, default <none>. The primary scope for this (secondary) scope. Use the distinguished name none to indicate no primary scope. You need to specify a primary scope if you have multiple logical subnets on the same physical network segment, and if you allow DHCP to offer addresses from any of the subnets.

selection-tags

Optional, default <none>. The list of selection criteria associated with a scope. The scope compares a client's selection criteria to this list in order to determine whether the client can obtain a lease from the scope.

synthetic-name-stem

Optional, default <none>. The prefix of the default host name to use if clients do not supply host names.

update-dns-for-bootp

Optional, default enabled. If the server is replying to a BOOTP request, and is offering a lease from a scope that is configured to perform DNS updates, it will check this property before beginning the DNS update. This property allows you to prevent DNS updates for BOOTP clients, while allowing updates for DHCP clients.

For example, to set the name of the reverse zone, type:

nrcmd> scope testScope set dns-reverse-zone-name=10.in-addr.arpa.

To get the DNS zone name, type:

nrcmd> scope testScope get dns-zone-name

Scope Method Commands

The scope method commands allow you to add, remove, show, and list ranges and reservations.

Ranges

You can specify the start and end values as host numbers or IP addresses. Note that the start and end values must fall within the network addresses as defined by the scope's addr and the network mask attributes.

If adding addresses to a scope creates a continuous set of addresses, Network Registrar merges the current list of ranges, if possible.
If deleting a range of addresses creates a discontinuous set of addresses, Network Registrar modifies or splits the existing ranges, if necessary.

The syntax is:

scope name addRange start end

scope name listLeases filter

scope name listRanges

scope name removeRange start end

Table 2-32 lists and describes the scope range methods.

Table 2-32: Scope Range Methods

Method Description

addRange

Adds a range of addresses to the named scope.

listLeases

Lists the leases in the named scope.

listRanges

Lists the available addresses in the named scope.

removeRange

Removes the range of available addresses in the named scope.

For example, to add a range, type:

nrcmd> scope testScope addRange 192.168.1.10 192.168.1.20

To delete a range, type:

nrcmd> scope testScope removeRange 192.168.1.10 192.168.1.15

Scope Reservations

The scope command, with the name argument allows you to add, delete, or list the reservations on the named scope.

The syntax is:

scope name addReservation ipaddr macaddr

scope name listReservations

scope name removeReservation [ipaddr|macaddr]

Table 2-33 lists and describes the scope reservation methods.

Table 2-33: Scope Reservation Methods

Method Description

addReservation

Adds the reservation to the named scope.

listReservations

Lists the reservations in the named scope.

removeReservation

Deletes a reservation from the named scope.

For example, to add a reservation, type:

nrcmd> scope testScope AddReservation 192.168.1.10 1,6,00:a0:24:2e:9c:20

To remove a reservation, type the following, specifying either the client's MAC or IP address:

nrcmd> scope testScope removeReservation 192.168.1.10

Scope-selection-tag

The scope-selection-tag command allows you to define tags that are added to the scope selection tag list. After you have defined scope selection tags you can associate them with scopes, clients, and client-classes.

Note If you delete a selection tag, Network Registrar removes it from the selection tag list, but does not remove it from any existing scope, client, or client-class configurations.

The syntax is:

scope-selection-tag name create

scope-selection-tag name delete

scope-selection-tag list

For example, to create the scope selection tag internal, type:

nrcmd> scope-selection-tag internal create

To delete the scope selection tag internal, type:

nrcmd> scope-selection-tag internal delete

To list the scope selection tags, type:

nrcmd> scope-selection-tag list

Number of Scope Selection Tags

Network Registrar limits you to a total of 30 scope selection tags. When the DHCP server configures itself, it checks the number of scope selection tags defined for any network. A network in this context is the aggregation of all of the scopes that are related to a particular subnet. This includes all of the scopes that belong together (because they share a common network number and subnet mask) and all of the scopes that are related to one of these through the use of the primary scope reference. Thus, within all of the scopes that make up a network, there can be no more than 30 scope selection tags.

When the DHCP server reads a client entry (from the local database or from LDAP), the server checks its scope selection inclusion and exclusion criteria against the scope selection tags defined for the scopes on this network. If the client entry references tags that are not present in any scope in the network, then how the server handles the tags depends on whether the reference is to included or excluded tags. If the reference is for excluded tags, then the tag will have no effect. If the reference is for included tags, then the server determines that there is no acceptable scope on that network for this client.

Server

The server command allows you to affect the behavior of the server. After you have used the server command or any other time you have changed the server's configuration, you need to reload the server. You can use the server command or the Network Registrar GUI to reload the server.

Server Commands

The syntax is:

server [DNS | DHCP] cmd

Table 2-34 lists and describes the arguments to the server commands.

Table 2-34: Server Command Arguments

Argument Description

reload

Causes the specified server to be stopped and then immediately restarted. When the server restarts it re-reads all of its configuration information and its previously saved state information and then begins operating.

start

Starts the specified server, either DNS or DHCP.

stop

Stops the specified server, either DNS or DHCP.

getHealth

Gets the specified server's current health.

getStats

Gets the specified server's current statistics.

setDebug

Sets the debugging level and the location of the debug messages. You can specify either MLOG or WINDOW as locations. The default location is MLOG.

unsetDebug

Turns off debugging output.

For example, to stop the DNS server, type:

nrcmd> server DNS stop

To start the DHCP server, type:

nrcmd> server DHCP start

To display the health of the DHCP server, type:

nrcmd> server DHCP getHealth

Server Features

The server features allow you to enable or disable a feature. You use the enable or disable commands to affect the following feature.

The syntax is:

server [DNS | DHCP] enable feature

server [DNS | DHCP] disable feature

Table 2-35 lists and describes the server argument.

Table 2-35: Server Command Argument

Argument Description

start-on-reboot

Controls whether the server is started by the AIC server agent when you reboot. You might want to disable this feature for clusters that want to provide a single protocol service. By default, both the DNS and DHCP servers are enabled.

For example, to disable the DNS server from automatically restarting on reboot, type:

nrcmd> server DNS disable start-on-reboot

Server Properties

Table 2-36 lists and describes the server properties.

Table 2-36: Server Properties

Property Description

version

The version string for the server. This property is useful when describing version information to Technical Support.

Session

The session command allows you to set session control parameters on your nrcmd command session. You can control the visibility level that determines which properties are displayed, and the default output format.

The syntax is:

session set prop=value

session get prop

session show

Table 2-37 lists and describes the session command arguments.

Table 2-37: Session Command Arguments

Property Description

default-format

An enumerated string that can have the following values:

script---show objects in script-suitable format, that is, one attribute per line.

user---show objects in a user-readable format, that is, one object per line.

cluster

The name of the current cluster. This is a read-only property.

user-name

The name of the current user. This is a read-only property.

visibility

Controls which properties are displayed. The default visibility is 5.

For example, to set the output so that it is suitable for script processing, type:

nrcmd> session set default-format=script

Zone

The zone command allows you to create and edit DNS zones.

The syntax is:

zone name create primary file=BINDfile

zone name create primary ns person [prop=value]

zone name create secondary addr [prop=value]

zone name delete

zone list

For example, to create a zone, type:

nrcmd> zone QuickExample.com create primary file=host.local

Note The zone command automatically creates the NS and SOA resource record for you. You need to use the addRR command to create an A record for the name server named in the ns field.

To create both an SOA record with values (ns.test.org. andy.test.org.) and an NS record with value ns.test.org, type:

nrcmd> zone test.org create primary ns andy

Both of these records will have the name of the zone ("test.org." or "@"). Since the name ns.test.org. is within the test.org. zone, you will have to provide an A record for ns.test.org:

nrcmd> zone test.org. addRR ns A 24.10.2.2

Zone Feature Commands

You can enable, disable, or determine the feature that has been set with the enable, disable, or show commands.

The syntax is:

zone name disable feature

zone name enable feature

zone name show

Table 2-38 lists and describes the zone features.

Table 2-38: Zone Features

Feature Description

dynamic

Required, default enabled. (Primary server only) Enables or disables RFC 2136 dynamic updates to the zone. The most typical source of these updates is a DHCP server.

restrict-xfer

Required, default disabled. Restricts zone transfers to a specific set of hosts. If you restrict zone transfers, you need to use the restricted-set property to list the servers that are allowed to perform zone transfers.

ixfr

Optional, default <none>. Applies to secondary zones only. Enables requesting incremental transfer for this zone. When set, (to either to true or false) it overrides the global ixfr-enable value for this zone.

notify

Optional, default <none>. Enables the notification of other authoritative servers when this zone changes. When set, (to either true or false) it overrides the global notify value for this zone.

Incremental Transfer

If you set incremental transfer, then this particular zone will act differently than zones inheriting the server global value.
If you unset incremental transfer, Network Registrar uses the server global IXFR value (and the operation of the GUI specifically depends on this, since it has no way of setting this per-zone feature).

Using the server global value (not setting this value per-zone) gives you an easy way of globally turning IXFR on or off, or setting a general policy for your zones and specific exceptions to the server global value.

Zone Properties

You can use the set and get commands to assign and retrieve values from the zone's properties. These properties depend on the type of zone that you are creating.

The syntax is:

zone name set prop=value [prop=value ...]

zone name get prop

Table 2-39 lists and describes the zone properties.

Table 2-39: Primary Zone Create Properties

Property Description

auth-servers

(Secondary-only). The list of servers from which Network Registrar will transfer data for this zone.

dynupdate-set

The set of IP addresses from which dynamic updates will be accepted, when you have enabled the dynamic feature. The nrcmd command treats addresses with zeroes in the least significant octets as network numbers, with implicit masks in octet multiples.

expire

Optional, default: 604800. The expire interval, in seconds, of the zone. The length of time a secondary can continue to serve zone data without confirmation that it is still current.

Validation: refresh < x < 2147483647

minttl

Optional, default: 86400.The mimimum TTL value to expose in resource records for this zone. Records with lower TTL values will be published with this value.

Validation: 0 <= x <= 2147483647

notify-set

An optional list of additional servers to notify when this zone changes. All servers listed in NS records for the zone with the exception of the server described by the ns property of the zone (the mname field of the SOA record) will receive notifications. Servers listed in the notify-set will also be notified.

ns

Required, default: <none>.The fully-qualified domain name of the primary for this zone. This host is the original or primary source of data for this zone.

person

Required, default: <none>. A domain name which specifies the mailbox of the person responsible for this zone. The first label is a user or mail alias, the rest of the labels are a mail destination. A mailbox of hostmaster@test.com would be represented as hostmaster.test.com.

refresh

Optional, default: 10800. The refresh interval, in seconds, of the zone. Used by secondaries as the period of polling for zone changes.

Validation: 1 <= x <= 2147483647

restricted-set

The set of IP addresses that may request zone transfers when you have enabled the restrict-xfer feature.

retry

Optional, default: 3600. The retry interval, in seconds, of the zone. Used by secondaries as the period of retrying when polling for changes, or attempting zone transfer after encountering errors.

Validation: < (expire - refresh)

serial

Optional, default: 1. The current serial number of the zone. Maintained automatically by the DNS server.

Validation: 0 <= x <= 4294967295

Zone Host Method Commands

You use the following commands to add, remove, and list the hosts for the zone.

The syntax is:

zone name addHost name addr [alias]

zone name removeHost name

zone name listHosts

Table 2-40 lists and describes the host properties.

Table 2-40: Host Properties

Property Description

name

The host's domain name.

addr

The list of addresses assigned to the host.

aliases

An optional list of alias domain names for this host.

For example, to add a host to the QuickExample zone, type:

nrcmd> zone QuickExample.com addHost bethpc 192.168.1.10

Zone Resource Record Method Commands

You use the following commands to add, remove, and list the resource records in the zone or to delete a zone's unused or obsolete resource records.

The syntax is:

zone name addRR name [ttl] [class] type data

zone name removeRR name type data

zone name cleanRR

zone name listRR {all|static|dynamic}

Table 2-41 lists and describes the resource record properties.

Table 2-41: Resource Record Properties

Property Description

name

The resource record's domain name (owner name).

type

The type of resource record, such as PTR or A.

class

The class of resource record, which is always IN (for Internet) in DNS.

ttl

The resource record time to live (in seconds). The length of time the record the client may cache the resource record.

For example, to add a name server resource record, type:

nrcmd> zone QuickExample.com addRR green ns green.QuickExample.com

Note that you can specify the name as either the relative name (if the server is within the same domain), as an absolute name (by supplying the fully qualified domain name), or the same name as the zone name (by using the @ symbol).

To delete a zone's unused or obsolete resource records, type:

nrcmd> zone QuickExample.com cleanRR

Feature	Description
ixfr	Optional, default false. Indicates whether or not a foreign server supports incremental transfer and should be queried for incremental (IXFR) before full (AXFR) when asking for zone transfers. Although unwittingly setting this to true is generally harmless, doing so may result in additional transactions to accomplish a zone transfer.
multirec	Optional, default false. Indicates whether or not a remote server can be sent zone transfers (AXFR) with multiple records in one TCP packet. Older DNS servers will crash when receiving such transfers, despite being allowed by the protocol.

Property	Description
column-separator	Specifies the character string you want used between the columns in the report. The default is a single space. If you specify whitespace, you must escape it with a backslash (\) and if it is entered on the command line, use quotes. For example, =,\ or =",\"
config	A file that allows you to specify multiple clusters.
dhcp-only	Specifies a summary of just the DHCP information.
file	Specifies the file name to which the report command writes the output. If you do not specify a file name, the report command writes to standard out. Note that, since it can take a long time to collect DNS data, you should not run the report command interactively when requesting DNS summaries.
mask-bits	Specifies the number of high-order bits set in the network mask that define a logical subnet for which the report command produces a summary. The default value is 16. If the value of the mask-bits is less than the default or less than the largest mask of any scope's mask in the report, the report command uses the default value.

Flags	None	Reserved	Deactivated	Reserved and Deactivated
State		reserved	deactivated	reserved and deactivated
available	free	reserved	deactivated	deactivated
offered	dynamically leased leased	dynamically leased leased	deactivated leased	deactivated leased
leased	dynamically leased leased	dynamically leased leased	deactivated leased	deactivated leased
expired	dynamically leased leased	dynamically leased leased	deactivated leased	deactivated leased
unavailable	unavailable	unavailable	unavailable	unavailable

Error Code	Description
100 OK	Indicates a successful save.
3xx	Indicates an error in processing the command.
4xx	Indicates an error in communicating with the cluster database server.
5xx	Indicates an internal error in the command.

Feature	Description
bootp	Optional, default disabled. Controls whether the server accepts BOOTP requests. If you want clients to always receive the same addresses, you need to reserve IP addresses for all your BOOTP clients. For information about how to reserve address, see the "Scope Reservations" section.
dhcp	Optional, default enabled. Controls whether the DHCP server will accept DHCP requests for this scope. You would only disable DHCP for a scope to cause the scope to be used for BOOTP exclusively, or to temporarily deactivate a scope.
dynamic-bootp	Optional, default disabled. Controls whether the server will accept dynamic BOOTP requests for this scope. Dynamic BOOTP requests are BOOTP requests that do not match a reservation, but can be satisfied from the available lease pool. To use this feature, you must also enable BOOTP.
dynamic-dns	Optional, default disabled. Controls whether the DHCP server should attempt to update a DNS server with the name and address information from leases that are granted to requesting clients.
ping-clients	Optional, default disabled. Controls whether the server should attempt to ping an address.
renew-only	Optional, default <none>. Controls whether to allow existing clients to re-acquire their leases, but not to offer any leases to new clients. Note that a renew-only scope will not change the client associated with any of its leases, other than to allow a client currently using an available IP address to continue to use it.
synthesize-name	Optional, default disabled. Controls whether the DHCP server automatically creates DNS host names for DHCP clients who do not provide names. The server can synthesize unique names for clients based on the synthetic-name-stem property.
update-dns-first	Optional, default disabled. Controls whether the DHCP server is updated before the lease is granted.

Property	Description
addr	Optional, default <none>. The address of the subnet for which this scope contains addresses. (Read-only)
deactivated	Optional, default <none>. A scope that does not extend leases to clients. It treats all of the addresses in its ranges as if they were individually deactivated.
dns-rev-server-addr	Optional, default <none>. The address of the reverse DNS server for the zone into which the server should add PTR records.
dns-reverse-zone-name	Optional, default <none>. The name of the inverse (in.addr.arpa) zone that is updated with PTR and TXT records.
dns-server-addr	Optional, default <none>. The IP address of the primary DNS server on which the forward zone resides.
dns-zone-name	Optional, default <none>. The name of the DNS zone to which a DHCP client's host name should be added (A record).
mask	Optional, default <none>. The mask associated with the scope's network address. (Read-only)
ping-timeout	Optional, default <none>. The number of milliseconds the DHCP server should wait for ping responses. If you make this value too large, you will slow down the lease offering processes. If you make this value too small, you will reduce the effectiveness of pinging addresses before offering them.
policy	Optional, default <none>. The name of the policy associated with this scope.
primary-addr	Optional, default <none>. The IP address of the primary scope for this (secondary) scope.
primary-mask	Optional, default <none>. The subnet mask of this scope's primary scope (if this is a secondary scope).
primary-scope	Optional, default <none>. The primary scope for this (secondary) scope. Use the distinguished name none to indicate no primary scope. You need to specify a primary scope if you have multiple logical subnets on the same physical network segment, and if you allow DHCP to offer addresses from any of the subnets.
selection-tags	Optional, default <none>. The list of selection criteria associated with a scope. The scope compares a client's selection criteria to this list in order to determine whether the client can obtain a lease from the scope.
synthetic-name-stem	Optional, default <none>. The prefix of the default host name to use if clients do not supply host names.
update-dns-for-bootp	Optional, default enabled. If the server is replying to a BOOTP request, and is offering a lease from a scope that is configured to perform DNS updates, it will check this property before beginning the DNS update. This property allows you to prevent DNS updates for BOOTP clients, while allowing updates for DHCP clients.

Method	Description
addRange	Adds a range of addresses to the named scope.
listLeases	Lists the leases in the named scope.
listRanges	Lists the available addresses in the named scope.
removeRange	Removes the range of available addresses in the named scope.

Method	Description
addReservation	Adds the reservation to the named scope.
listReservations	Lists the reservations in the named scope.
removeReservation	Deletes a reservation from the named scope.

Argument	Description
reload	Causes the specified server to be stopped and then immediately restarted. When the server restarts it re-reads all of its configuration information and its previously saved state information and then begins operating.
start	Starts the specified server, either DNS or DHCP.
stop	Stops the specified server, either DNS or DHCP.
getHealth	Gets the specified server's current health.
getStats	Gets the specified server's current statistics.
setDebug	Sets the debugging level and the location of the debug messages. You can specify either MLOG or WINDOW as locations. The default location is MLOG.
unsetDebug	Turns off debugging output.

Property	Description
default-format	An enumerated string that can have the following values:
	script---show objects in script-suitable format, that is, one attribute per line.
	user---show objects in a user-readable format, that is, one object per line.
cluster	The name of the current cluster. This is a read-only property.
user-name	The name of the current user. This is a read-only property.
visibility	Controls which properties are displayed. The default visibility is 5.

Feature	Description
dynamic	Required, default enabled. (Primary server only) Enables or disables RFC 2136 dynamic updates to the zone. The most typical source of these updates is a DHCP server.
restrict-xfer	Required, default disabled. Restricts zone transfers to a specific set of hosts. If you restrict zone transfers, you need to use the restricted-set property to list the servers that are allowed to perform zone transfers.
ixfr	Optional, default <none>. Applies to secondary zones only. Enables requesting incremental transfer for this zone. When set, (to either to true or false) it overrides the global ixfr-enable value for this zone.
notify	Optional, default <none>. Enables the notification of other authoritative servers when this zone changes. When set, (to either true or false) it overrides the global notify value for this zone.

Property	Description
auth-servers	(Secondary-only). The list of servers from which Network Registrar will transfer data for this zone.
dynupdate-set	The set of IP addresses from which dynamic updates will be accepted, when you have enabled the dynamic feature. The nrcmd command treats addresses with zeroes in the least significant octets as network numbers, with implicit masks in octet multiples.
expire	Optional, default: 604800. The expire interval, in seconds, of the zone. The length of time a secondary can continue to serve zone data without confirmation that it is still current. Validation: refresh < x < 2147483647
minttl	Optional, default: 86400.The mimimum TTL value to expose in resource records for this zone. Records with lower TTL values will be published with this value. Validation: 0 <= x <= 2147483647
notify-set	An optional list of additional servers to notify when this zone changes. All servers listed in NS records for the zone with the exception of the server described by the ns property of the zone (the mname field of the SOA record) will receive notifications. Servers listed in the notify-set will also be notified.
ns	Required, default: <none>.The fully-qualified domain name of the primary for this zone. This host is the original or primary source of data for this zone.
person	Required, default: <none>. A domain name which specifies the mailbox of the person responsible for this zone. The first label is a user or mail alias, the rest of the labels are a mail destination. A mailbox of hostmaster@test.com would be represented as hostmaster.test.com.
refresh	Optional, default: 10800. The refresh interval, in seconds, of the zone. Used by secondaries as the period of polling for zone changes. Validation: 1 <= x <= 2147483647
restricted-set	The set of IP addresses that may request zone transfers when you have enabled the restrict-xfer feature.
retry	Optional, default: 3600. The retry interval, in seconds, of the zone. Used by secondaries as the period of retrying when polling for changes, or attempting zone transfer after encountering errors. Validation: < (expire - refresh)
serial	Optional, default: 1. The current serial number of the zone. Maintained automatically by the DNS server. Validation: 0 <= x <= 4294967295

Property	Description
name	The host's domain name.
addr	The list of addresses assigned to the host.
aliases	An optional list of alias domain names for this host.

Property	Description
name	The resource record's domain name (owner name).
type	The type of resource record, such as PTR or A.
class	The class of resource record, which is always IN (for Internet) in DNS.
ttl	The resource record time to live (in seconds). The length of time the record the client may cache the resource record.

Table of Contents

Using the Nrcmd Commands