Cisco CNS Network Registrar CLI Reference Guide, 6.0
Using the nrcmd Commands
Downloads: This chapterpdf (PDF - 1.18MB) | Feedback

Using the nrcmd Commands

Table Of Contents

Using the nrcmd Commands

acl

address-block

address-block-policy

admin

client

client-class

client-class-policy

client-policy

custom-option

dhcp

dhcp-interface

dns

exit

export

extension

force-lock

help

import

key

ldap

lease

lease-notification

license

namespace

option-datatype

policy

quit

remote-dns

report

save

scope

scope-policy

scope-selection-tag

server

session

subnet

tftp

trap

vendor-option

zone


Using the nrcmd Commands


This chapter contains descriptions for all the nrcmd commands and their attributes, alphabetically arranged in sections by command. The command syntax appears at the beginning of each section, followed by the syntax descriptions, attribute descriptions, and any usage guidelines. See the "Attribute Flags" section for the types of attributes—required, optional, and read-only.

Attributes with time values are described with a default unit of time. However, you can append the characters "w," "d," "h," "m," or "s" immediately after the time value to translate the unit into weeks, days, hours, minutes, or seconds, respectively, if it fits in the allowed range of values. You can also mix time units in a single value, such as "1d6h" and "1d360m" (which are equivalent to "30h" and "1800m").


Note If you use the get keyword to get the value of a valid attribute, but its value is not defined, Network Registrar returns the unexpected error "308 Unknown parameter." However, using the show or list keyword shows the attribute in the resulting list.


Table 2-1 lists all the nrcmd commands.


acl

The acl command creates an access control list (ACL) with which you can specify who has access to perform dynamic DNS updates. You can include these items in the ACL:

Key

IP address

Network address (IP address and mask)

Another ACL

Use the acl command together with the update-acl attribute of the dns and zone commands.

acl name create "[!]key value] value[,...]"

acl name delete

acl name add [!]key value

acl name remove [!]key value

acl name set match-list="[!]key value] value[,...]"

acl name get match-list

acl name unset match-list

acl name show

acl list

acl listnames

Syntax Description

acl name create "[!]key value] value[,...]"

Creates an ACL based on a key (include the key keyword), host or network address, or another ACL. Use the ! symbol for negation.

nrcmd> acl security-acl create "key securitykey1" 
nrcmd> acl neg-acl create !192.168.2.1/16 

acl name delete

Deletes the specified ACL.

acl name add [!]key value

Adds a key (include the key keyword), host or network address, or another ACL element to an ACL.

acl name remove [!]key value

Removes an element from an ACL. For a key, use the key keyword.

acl name set match-list="[!]key value] value[,...]"

Sets the match list for the ACL.

acl name get match-list

Gets the match list for the ACL.

acl name unset match-list

Unsets the match list for the ACL.

acl name show

Shows the values associated with a specified ACL.

acl list

Displays all ACLs and the values associated with them.

acl listnames

Displays only the names of ACLs.

Related Commands

dns, key, zone

address-block

The address-block command creates and sets attributes for Network Registrar address blocks.

An address block is a contiguous range of IP address space that is delegated to the DHCP server for assignment. The DHCP server expects to subdivide these address blocks for delegation to some other server or device, or for its own use in interaction with DHCP clients.

Address blocks can parent one or more subnets. Subnets are also contiguous ranges of IP address space that are bound to a specific client, usually a router or another DHCP server. Address blocks and subnets are similar to scopes in that they contain address ranges and other attributes necessary to configure the DHCP client-server interaction. Unlike scopes, address blocks and subnets do not have the address ranges available for assignment to DHCP clients and do not contain reserved addresses.

In a virtual private network (VPN) deployment where multiple VPNs use the same private address space, you can use logically identical address blocks simultaneously on multiple VPNs.

address-block name create netaddr [attribute=value...]

address-block name delete

address-block name set attribute=value [attribute=value...]

address-block name unset attribute

address-block name get attribute

address-block name [show]

address-block list

address-block listnames

address-block listsubnets

Syntax Description

See Table 2-2 for the address-block command attributes and their descriptions.

address-block name create netaddr [attribute=value...]

Creates an address block with a certain network address (including netmask prefix), and optionally adds attributes. See Table 2-2 for the attributes to use with this command. The policy is the only required attribute, which defaults to the default policy if omitted.

nrcmd> address-block red create 10.1.0.0/16 policy=Policy1 

address-block name delete

Deletes an address block.

address-block name set attribute=value [attribute=value...]

Sets one or more attributes for the address block. The policy is the only required attribute, which defaults to the default policy if omitted.

nrcmd> address-block red set namespace=vpn-red 

address-block name unset attribute

Unsets an optional address block attribute. You cannot unset the policy attribute.

address-block name get attribute

Gets the value for an address block attribute.

address-block name [show]

Shows the values of all attributes of the address block.

address-block list

Lists all address blocks and their attributes.

address-block listnames

Lists only the names of all address blocks.

address-block listsubnets

Lists the subnets created from the address block.

Attributes

Table 2-2 describes the address-block command attributes and their values and defaults, if any.

Table 2-2 address-block Command Attributes 

Attribute
Usage
Description

address

create
set

IP address of the address block. Use the set command to rename the address block. Required, no default.

default-subnet-
size

set
get
unset

Default subnet size for allocations from this address. Optional, default 28.

deprecated

enable
disable
unset

Whether or not to deprecate the address block. The server ignores a deprecated address block for new subnet allocations. It allows existing clients to renew their subnets, but indicates to them that the subnet is deprecated. The client then prepares to release the deprecated subnet or subnets back to the server. Optional, default disable.

embedded-policy

get

Embedded policy object for this address-block. Read-only. Gets its value from the address-block-policy command.

namespace

set
get
unset

A "virtual" property. You can set the namespace of an address-block by setting this attribute instead of the namespace-id attribute. When you set this attribute, the namespace ID of that namespace becomes the namespace-id attribute value. You can also get the namespace of an address-block and it returns the name of the namespace associated with the current namespace-id. No default.

namespace-id

set
get
unset

Namespace ID of the namespace in which the address block resides. You must define the namespace using the namespace name create namespace-id command. See the "namespace" section. If unset, the global namespace is used. Optional, default is to use the current namespace as set by the session set current-namespace command, or, if undefined there, the global namespace. No default.

policy

set
get

Name of the policy associated with the address-block. See the "policy" section to create the policy. Required, default is the default policy.

segment-name

set
get

Label for the LAN that this address block is part of. To group multiple, logical IP subnets on a single, physical LAN, give each address block the same value. The server ignores character case when comparing values. Optional, no default.

selection-tags

set
get

List of tag strings that are compared with incoming allocation requests' selection tags. All of a request's tags must match an address block's selection tags in order for the address block to be used to satisfy the request. Separate multiple tags with a comma (do not include commas in tag names). Optional, no default.


Related Commands

address-block-policy, namespace, subnet

address-block-policy

The address-block-policy command configures DHCP embedded policies for address blocks. An address-block-policy is a policy object embedded within (and limited to) an address-block object. Each address block may contain option data within its embedded policy, and may refer to a named policy with more option data, such as a router IP address. For the priority of what option data the server returns to a subnet, see the Network Registrar User's Guide for a description of the policy reply options.

The DHCP server implicitly creates and deletes embedded address-block-policies when you create or delete the corresponding address blocks. You manipulate the address-block-policy using the name of the corresponding address-block.

For the syntax and descriptions, see the "policy" section.

Attributes

See Table 2-18 for the attribute descriptions. Except where noted in the table, many policy command attributes also apply to address block policies.

Related Commands

acl, client-policy, client-class, client-class-policy, policy, scope

admin

The admin command configures administrators for the cluster. You can choose any string for the administrator's name. Network Registrar uses a password to authenticate each administrator.

admin name create [attribute=value]

admin name delete

admin name set attribute=value

admin name unset attribute

admin name get attribute

admin name enterPassword

admin name [show]

admin list

admin listnames

Syntax Description

See Table 2-3 for the admin command attributes and their descriptions.

admin name create [attribute=value]

Creates an administrator (and optionally sets one or more attributes). If an entry already exists, the command overwrites it. To avoid exposing the password through the password attribute, use the admin name enterPassword command instead.

admin name delete

Deletes an administrator.

admin name set attribute=value

Sets an administrator attribute. To avoid exposing the password through the password attribute, use the admin name enterPassword command instead.

admin name unset attribute

Unsets an attribute.

admin name get attribute

Gets an attribute. Passwords are displayed as asterisks.

admin name enterPassword

Returns entry and confirmation prompts for a password, which is not echoed on the screen.

admin name [show]

Shows an administrator name and attributes.

admin list

Lists all administrators and their attributes. Passwords are displayed as asterisks.

admin listnames

Lists just the administrators' names.

Attributes

Table 2-3 describes the admin command attributes and their values and defaults, if any.

Table 2-3 admin Command Attributes 

Attribute
Usage
Description

groups

set
get
unset

List of administrator groups, separated by commas. This is usually set in the Network Registrar Web UI. However, you can edit the group list, based on the existing group names in the Web UI. Optional, no default.

nrcmd-flags

set
get
unset

Access level to the Network Registrar user interfaces—limited or full. Optional, default unset, which is essentially disable. The flags are:

1—limited—Access to unconstrained host, zone, and DHCP server administration.

2—full—Access to unconstrained host, zone, DHCP server, and global administration.

password

set
get
unset

Administrator password. Using this attribute exposes the password as plain text. To avoid this, use the admin name enterPassword command.

superuser

enable
disable
unset

Whether to give the administrator superuser privileges in the Web UI. There can be multiple superuser administrators in the Web UI. If enabled, overrides the nrcmd-flags attribute setting. Optional, default unset, which is essentially disable.


client

The client command assigns attributes to a specific client entry. These attributes determine what type of IP address or policy Network Registrar assigns to the requesting host. Network Registrar always stores the client identifier (MAC address or default) in lowercase characters.

client {macaddress | default} create [attribute=value...]

client {macaddress | default} delete

client {macaddress | default} set attribute=value [attribute=value...]

client {macaddress | default} unset attribute

client {macaddress | default} get attribute

client {macaddress | default} [show]

client list

client listnames

Syntax Description

See Table 2-4 for the client command attribute descriptions.

client macaddress create [attribute=value...]
client default create [attribute=value...]

Creates the client identifier as a MAC address or the word default (and optionally defines its attributes). The default client configuration applies to all clients that do not have an explicit configuration. If an entry for the client already exists, the command overwrites it. If you modify the default client configuration, you must reload the server. The DHCP server reads the client configuration data each time it receives a request for an IP address. If you modify a client that a MAC address identifies, you do not have to reload the server. However, if you modify the default client configuration, you must reload the server.

Identify a client by its MAC addresses or by the word default. Specify the MAC address in the form hardware,length,address (including the commas). A sample Ethernet MAC address is 1,6,00:d0:ba:d3:bd:3b.

hardware—Usually 1 (Ethernet) or 6 (Token Ring), but can be any number from 1 through 255.

length—Octets in the MAC address (usually 6, but can be any number from 1 through 16).

address—MAC address itself, with octets separated by colons, and each octet having a two-character hex value from 00 through FF (not case-sensitive).

nrcmd> client 1,6,00:d0:ba:d3:bd:3b create client-class-name=external 

client macaddress delete
client default delete

Deletes the client entry.

client macaddress set attribute=value [attribute=value...]
client default set attribute=value [attribute=value...]

Sets one or more attributes for the client.

client macaddress unset attribute
client default unset attribute

Unsets the value of an attribute for the client.

client macaddress get attribute
client default get attribute

Gets the value of an attribute for the client.

client macaddress [show]
client default [show]

Shows the values of all attributes assigned to the client.

client list

Lists all clients and any attributes assigned to them.

client listnames

Lists just the client identifiers.

Attributes

Table 2-4 describes the client and client-class command attributes and their values and defaults, if any.

Table 2-4 client Command Attributes 

Attribute
Usage
Description

action

set
get
unset

For clients and client-classes, the action to take for the client. Optional, no default. Use one or more of these comma-delimited tokens:

exclude—Server ignores all communication from this client. If you use the command on the default client (client default action=exclude), only a client specifically registered through the client command can communicate with the server.

one-shot—Server does not renew or re-offer any lease made to the client (either directly or in a client-class entry).

use-release-grace-period—Server delays the effect of DHCPRELEASE messages that the client sends. A release-grace-period for the policy specifies the delay time. During the grace period, the client's lease is not available for any other client.

none—No action.

authenticate-until

set
get
unset

For clients only, limits the authentication time to the duration that you specify, in a date format or the forever keyword. Dates can be in the -2h (two hours ago, for example) or month day hour:minute[:second] year format. Optional, no default.

client-class-name

set
get
unset

For clients only, the client-class to which the client belongs. If the client is not in a client-class, the DHCP server uses the default client-class. Optional, no default.

client-lookup-id

set
get
unset

For client-class only, the expression that evaluates to a string (or a blob that is a valid string). The resulting value specifies the key value to be used to look up the client in the client database, either locally or through LDAP. Enclose a simple expression in double quotes, or prefix the pointer to the file containing the expression with an @ symbol (see the Network Registrar User's Guide). Optional, no default.

default-
namespace

set
get
unset

For clients and client-classes, the namespace to put it in if it does not already have a vpn-id or vrf-name value. Optional, no default.

domain-name

set
get
unset

For clients and client-classes, the domain name of the zone to use when performing dynamic DNS updates. The server places the client's address (A) resource record in this zone. For the domain-name string to have an effect, use the scope name enable dynamic-dns command (the default) for the scope that allocated the address. Optional, no default.

embedded-policy

get
unset

For clients and client-classes, the embedded policy for the client, as set by the client-policy command. Read-only, but you can unset all the embedded policy attributes, while retaining the policy name.

host-name

set
get
unset

For clients and client-classes, the string to replace or generate the client host name. The first form is a string that does not start with an ampersand (@). This form is used to override the DHCP client request host-name option value. When you enter a valid name, the DHCP server ignores the host-name option value and uses this attribute value instead. You can use any valid DNS name except that it cannot include underscores.

The second form is a string that starts with the special token @. Network Registrar uses this form to signal special handling:

@host-name-option—The server uses whatever host-name DHCP option the client sends. This is the default behavior if there is no entry for the host-name option in either the client or client-class.

@no-host-name-option—The server drops the host-name DHCP option that the client sends and does not replace it. If you disabled DNS name synthesis, the client has no name placed in DNS.

@use-macaddress—The server synthesizes 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 name in DNS.

For the host-name string to have an effect, you must set scope name enable dynamic-dns (the default) in the scope that includes the address. Optional, no default; if blank, uses the host-name DHCP option.

limitation-id

set
get
unset

For client-classes only, the expression that evaluates a blob or a string that can be used as a blob. The resulting value relates leases for which there is a maximum limit on the number of simultaneous active ones allowed. Configure the limit using the policy name set limitation-count command. Also, see the over-limit-client-class-name attribute. Enclose a simple expression in double quotes, or prefix the pointer to the file containing the expression with an @ symbol (see the Network Registrar User's Guide). Optional, no default.

over-limit-client-
class-name

set
get
unset

For clients and client-classes, the client-class name to use if the client exceeds the allowable limit of simultaneous active leases with a common limitation ID (see the limitation-id attribute). Optional, no default.

override-
namespace

set
get
unset

For clients and client-classes, the namespace to put it in, no matter what it provides for a vpn-id or vrf-name value. If you specify an override namespace on the client-class, and a default namespace for the client, the override namespace on the client-class takes precedence over the default namespace on the client. Optional, no default.

policy-name

set
get
unset

For clients and client-classes, the policy to add to the Network Registrar DHCP policy search list for this client. Optional, no default.

selection-criteria

set
get
unset

For clients and client-classes, the scope-selection tag or (comma-separated) tags to build the scope inclusion list. See the "scope-selection-tag" section for how to create scope-selection tags. Optional, no default.

selection-criteria-
excluded

set
get
unset

For clients and client-classes, the scope-selection tag or (comma-separated) tags to exclude when building the scope exclusion list. See the "scope-selection-tag" section for how to create scope-selection tags. Optional, no default.

unauthenticated-
client-class-name

set
get
unset

For clients only, the name of the client-class to use if the client is no longer authenticated. Optional, no default.

user-defined

set
get
unset

For clients and client-classes, the user-defined string, such as a foreign key in a separate authorization database. This attribute has no effect on server operation. Optional, no default.


Related Commands

client-policy, client-class, client-class-policy, policy, scope, scope-policy, scope-selection-tag

client-class

The client-class command applies a set of attributes to a group or class of DHCP client configurations. Unlike most client configurations, the DHCP server reads the client-class configurations at server startup time. Therefore, you must reload the server for changes to take effect.

client-class name create [attribute=value...]

client-class name delete

client-class name set attribute=value [attribute=value...]

client-class name unset attribute

client-class name get attribute

client-class name [show]

client-class list

client-class listnames


Note You must enable client-class processing for the server before Network Registrar can recognize client-classes.
nrcmd> dhcp enable client-class


Syntax Description

See Table 2-4 for the client command attribute descriptions. Except where noted in the table, many client command attributes also apply to the client-class command.

client-class name create [attribute=value...]

Creates the client-class (and optionally defines its attributes). You must enable client-class processing for this to go into effect.

nrcmd> dhcp enable client-class 
nrcmd> client-class internal create 
nrcmd> dhcp reload 

client-class name delete

Deletes the client-class.

client-class name set attribute=value [attribute=value...]

Sets one or more attributes for the client-class. See Table 2-4 for the attributes.

client-class name unset attribute

Unsets a client-class attribute.

client-class name get attribute

Gets an attribute value for the client-class.

client-class name [show]

Shows the values of all attributes assigned to the client-class.

client-class list

Lists all client-classes and any attributes assigned to them.

client-class listnames

Lists just the client-class names.

Attributes

See Table 2-4 for the attribute descriptions.

Related Commands

client, client-policy, client-class-policy, dhcp, ldap, policy, scope-policy

client-class-policy

The client-class-policy command configures embedded policies for client-classes. Each client-class can contain option data in its embedded policy and can refer to a named policy with more option data, such as a router IP address. Network Registrar implicitly creates and deletes an embedded client-class policy when you create and delete the corresponding client-class. You manipulate the client-class policy using the name of the client-class to which the embedded policy is attached.

For the syntax and descriptions, see the "policy" section.

Attributes

See Table 2-18 for the attribute descriptions. Except where noted in the table, many policy command attributes also apply to client-class policies.

Related Commands

client, client-policy, client-class, policy, scope-policy

client-policy

The client-policy command configures embedded policies for clients. Each client can contain option data in its embedded policy and can refer to a named policy with more option data, such as a router IP address. Network Registrar implicitly creates and deletes an embedded client policy when you create or delete the corresponding client. You manipulate the client policy using the name of the client to which the embedded policy is attached.

For the syntax and descriptions, see the "policy" section.

Attributes

See Table 2-18 for the attribute descriptions.

Related Commands

client-class, client-class-policy, policy, scope-policy

custom-option

The custom-option command creates and deletes custom DHCP options. You can also use this command to redefine any predefined DHCP options. If you delete this option, its definition returns to its original value.

custom-option name create number type [desc="string"]

custom-option name delete

custom-option name set attribute=value [attribute=value...]

custom-option name unset attribute

custom-option name get attribute

custom-option name [show]

custom-option list

custom-option listnames

Syntax Description

custom-option name create number type [desc="string"]

Creates a custom option with a name, maps it to an option number, defines the data type, and optionally sets an attribute value. The positional attributes (in their correct order) are:

name—Name of the custom option. Be consistent in naming the options in lowercase.

number—Option number. Creating custom options that use the site-specific numbers 128 through 254 avoids conflicting with public DHCP options (see RFC2489). The DHCP options are listed in the appendices to the Network Registrar User's Guide.

type—Valid data type. Table 2-5 lists the option data types. Optional, no default. See the Network Registrar User's Guide for more information.

desc="string"—Description string. Optional, no default. Includes quotation marks if there are spaces between words.

nrcmd> custom-option red create 100 IPADDR 
nrcmd> custom-option blue create 101 BYTE_ARRAY 

This example creates a custom option that overlays the public time-offset option with a new definition:

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


Note As shown in the example, you can create custom options that override public DHCP or BOOTP options. Cisco Systems highly recommends not doing this. Also, do not give the custom option a name in the form "option-number," unless number is a numeric value from 1 through 254 that is not defined. This entry generates a "duplicate object - option already exists" message:

nrcmd> custom-option option-192 create 192 INT


custom-option name delete

Deletes a custom option. If the custom option is an overlay of a public option, the option reverts to its previous definition.

custom-option name set attribute=value [attribute=value...]

Sets or resets one or more attributes for a custom option.

name=name—Changes the name of the custom option, preferably in lowercase.

number=number—Changes the option number. Numbers 128 through 254 are reserved for site-specific options. Optional, no default. The DHCP option numbers you should avoid using are listed in the appendices to the Network Registrar User's Guide.

type=type—Changes the valid data type (see Table 2-5). Optional, no default. See the Network Registrar User's Guide for more information about option validation types.

desc=string—Adds or changes the description string. Optional, no default.

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

custom-option name unset attribute

Unsets the value of a custom option attribute.

custom-option name get attribute

Gets the value of an attribute for a custom option.

custom-option name [show]

Shows the attributes of a custom option.

custom-option list

Lists all custom options and any attributes assigned to them.

custom-option listnames

Lists just the names of the custom options.

Option Data Types

Table 2-5 lists the option data types that the nrcmd program supports.

Table 2-5 Option Data Types 

Option Data Type
Type Name (Number)
Definition

boolean

BOOL (1)

TRUE or FALSE.

byte

BYTE (7)

8-bit unsigned integer.

byte array

BYTE_ARRAY (8)

Sequence of bytes represented in the form xx[:xx...] in which x is a hex character 0 through 9 or a through f. For example, to enter a series of four bytes containing the values 192, 168, 73 and 144, enter their hex values as "c0:a8:49:90." Enter the ASCII string "ABCijk123" as "41:42:43:69:6a:6b:31:32:33."

IP address

IPADDR (5)

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

IP address array

IPADDR_ARRAY (6)

Array of IP addresses.

signed array

INT_ARRAY (3)

Array of 32-bit signed integers.

signed integer

INT (2)

32-bit signed intege.r

string

STRING (4)

ASCII text string.

unsigned array

UINT_ARRAY (12)

Array of 32-bit unsigned integers.

unsigned integer

UINT (11)

32-bit unsigned integer.

word

WORD (9)

16-bit unsigned integer.

word array

WORD_ARRAY (10)

Array of 16-bit unsigned integers.


Related Commands

option-datatype, vendor-option

dhcp

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

dhcp enable attribute

dhcp disable attribute

dhcp set attribute=value [attribute=value...]

dhcp unset attribute

dhcp get attribute

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

dhcp [show]

dhcp limitationList ipaddr [limitation-id] show

dhcp attachExtension extension-point extension-name [sequence-number]

dhcp detachExtension extension-point [sequence-number]

dhcp listExtensions

dhcp setPartnerDown partner-server [date]

dhcp getRelatedServers column-separator=string

dhcp updateSMS [all]


Note See also the "server" section for other server control commands.


Syntax Description

See Table 2-6 for the dhcp command attribute descriptions.

dhcp enable attribute

Enables an attribute for the DHCP server.

nrcmd> dhcp enable client-class 

dhcp disable attribute

Disables an attribute for the DHCP server.

nrcmd> dhcp disable import-mode 

dhcp set attribute=value [attribute=value...]

Sets one or more attributes for the DHCP server.

nrcmd> dhcp set failover-maximum-client-lead-time=60 

dhcp unset attribute

Unsets the value of a DHCP server attribute.

dhcp get attribute

Gets the value of an attribute for the DHCP server.

nrcmd> dhcp get discover-interfaces 

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

Supplies the DHCP server with a cutoff time to apply to the history records. When you reload the server, it examines the history database and deletes any records with an expiration time older than the date value.

nrcmd> dhcp trimIPHistory "Tue Dec 31 19:00:00 2002" 
101 Reload Needed 

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

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

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

For more information on trimming, refer to the chapter on configuring DHCP scopes and leases in the Network Registrar User's Guide.

dhcp [show]

Shows the values of the DHCP server attributes.

dhcp limitationList ipaddr [limitation-id] show

Determines the DHCP clients and their leases that are currently associated by a common limitation-id for the client (see the "client" section). This is useful when a DHCP client was denied service because the number of existing clients with a common limitation-id equals the allowed limitation-count, as set for a policy (see the "policy" section). It then determines which existing clients with that limitation-id have active leases.

If you specify both the ipaddr and limitation-id arguments, the ipaddr determines the network in which to search, and does not have to be an actual IP address that the DHCP server could allocate. In this case, the limitation-id must be a blob in nn:nn:nn format (such as 01:02:03) or a string in "string" format. If you omit the limitation-id, the ipaddr must be the IP address of a currently active lease, and the limitation-id used for the command will be the one associated with that lease.

dhcp attachExtension extension-point extension-name [sequence-number]

Sets the specified extension point to call an extension. This example adds an extension named test to the extension point post-packet-decode:

nrcmd> dhcp attachExtension post-packet-decode test 1 

If the extension point is already configured to call an extension, use the sequence number to specify the order in which Network Register is to execute the extensions (1, 2, 3,...). If you omit a sequence number, Network Registrar overwrites the existing extension with the new value. See Table 2-8 for descriptions of the extension-point values.

dhcp detachExtension extension-point [sequence-number]

Detaches extensions from an extension point. This example removes the test extension from the post-packet-decode extension point. Network Registrar removes the extension at the specified sequence number. If you omit the sequence number, Network Registrar removes the extension at sequence number 1:

nrcmd> dhcp detachExtension post-packet-decode test 1 

dhcp listExtensions

Lists the currently configured extensions and their sequence numbers (if you configure multiple extensions) at each extension point. Cisco recommends that you run listExtensions for an extension point before attaching a new one. Check the results to ensure that the new extension has a different sequence number than an existing one.

dhcp setPartnerDown partner-server [date]

Notifies the DHCP server that its partner DHCP server is down and moves all appropriate scopes into the PARTNER-DOWN state. Optionally, you can specify the date and time when the partner was last known to operate. The default is the current date. This command is the equivalent of the server dhcp setParnterDown command.


Caution Confirm that the partner server is completely down before issuing the setPartnerDown keyword.

dhcp getRelatedServers column-separator=string

Gets the status of the connection between the DHCP server and its DNS, LDAP, or failover servers. You can optionally specify that the report use string for separating columns. This command is the equivalent of the server dhcp getRelatedServers command. See the Network Registrar User's Guide for the output to this command.

dhcp updateSms [all]

Causes the DHCP server to perform System Management Server (SMS) network discovery. Optionally, including all sends out all leased addresses from the DHCP server to SMS. If you do not include this parameter, the server sends only those addresses leased since the last time you used this command. This command is the equivalent of the server dhcp updateSMS command.

Attributes

Table 2-6 describes the dhcp command attributes and their values and defaults, if any.

Table 2-6 dhcp Command Attributes 

Attribute
Usage
Description

activity-summary-interval

set
get
unset

Time, in seconds, between activity summary log messages if enabled in the activity-summary setting in log-settings. Optional, there is no default.

addr-blocks-default-
selection-tags

set
get
unset

Default selection tag (or list of tags) to be associated with incoming subnet allocation requests that do not contain any subnet name data. Optional, no default.

addr-blocks-use-client-
affinity

enable
disable
unset

The DHCP server tries to allocate subnets to clients using address blocks that they already used. Disabling this attribute causes the server to supply subnets from any suitable address block, based on other selection data in the clients' messages. Optional, default enable.

addr-blocks-use-lan-
segments

enable
disable
unset

Controls whether DHCP subnet-allocation uses the lan-segment attribute when configured on address blocks. Optional, default disable.

addr-blocks-use-selection-
tags

enable
disable
unset

Controls whether the server compares the incoming subnet allocation requests' subnet name data with each address block's selection tags. An address block is only considered if the two match. Optional, default enable.

append-user-class-id-to-
selection-tag

enable
disable
unset

Meaningful only if dhcp set map-user-class-id=1 (map the user class ID to the scope-selection tag). If you set this attribute to true (the default), Network Registrar appends the user class ID to existing scope-selection tags. If set to false, the user class ID replaces any existing tags. See the "scope-selection-tag" section. Optional, default enable.

client-cache-count

set
get
unset

Allocates the specified maximum number of clients to the client cache. The DHCP server allocates the amount at startup and frees it up at shutdown. If you unset the value, client caching is disabled. Optional, default 1000 clients.

client-cache-ttl

set
get
unset

Time to live for the client cache, in seconds. The DHCP server removes the entries in memory after this period. Optional, default 10 seconds.

client-class

enable
disable
unset

Controls whether the DHCP server uses the client and client-class configuration objects to affect request processing. Optional, default disable.

client-class-lookup-id

set
get
unset

Expression to use to determine a client-class solely on data in an incoming DHCP client request. The expression must return a string that is the name of a currently configured client-class, otherwise the string <none> must be returned. Any return that is not a string containing the name of a currently configured client-class or <none> is considered an error. Enclose a simple expression in double quotes, or prefix the pointer to the file containing the expression with an @ symbol (see the Network Registrar User's Guide). Optional, no default.

cnr-5-0-upgraded

get

Shows whether the DHCP server was upgraded for Network Registrar Release 5.0. Read-only.

collect-performance-
statistics

enable
disable
unset

Controls whether the DHCP server collects statistics for performance monitoring. Optional, default disable.

defer-lease-extensions

enable
disable
unset

Controls whether the server renews a client's lease that is less than halfway to its expiration. By default, the server defers the lease extension—does not renew the lease, but grants another one while keeping the lease period. This way, the server can avoid extra database updates. However, if a client is more than halfway to expiration, this setting has no effect, and the server extends the lease to the full configured lease period. Optional, default enable.

delete-orphaned-leases

enable
disable
unset

Leases that are in the lease state database can have a namespace ID recorded with them, or they can be orphaned. When the DHCP server initializes its cache from the lease state database, it expects every lease with a namespace ID to match a configured namespace. If the server finds a lease whose namespace ID does not match a configured namespace, this property controls whether to delete that lease from the database or to ignore that entry (the default), assuming that at some point the server is configured with the appropriate namespace. In either case, the server cannot use the lease. Optional, default disable.

delete-orphaned-subnets

enable
disable
unset

As the DHCP server starts up, it tries to locate the parent namespace and address block of each subnet. If a subnet refers to a namespace that is no longer configured in the server, or if the server cannot locate a parent address block that contains the subnet, the server uses this attribute to decide whether to keep the subnet entry in the state database (the default) or to delete it permanently. Optional, default disable.

discover-interfaces

enable
disable
unset

Controls whether the DHCP server looks at all the interface cards on the host and processes DHCP requests that it receives from any of them. However, it only offers addresses to requests from subnets defined with a valid scope with available addresses. If disabled, the DHCP server uses only its list of configured interfaces. See the "dhcp-interface" section. Optional, default enable.

dns-timeout

set
get

Time, in milliseconds, that the DHCP server waits for a response before retrying a dynamic DNS request. Required, default 60000 milliseconds.

docsis-version-id-missing

set
get
unset

String (maximum 255 characters) that gets substituted with the %@docsis-vers% variable in the policy command's boot-file attribute. This substitution occurs if the DHCP request packet does not contain a vendor-class-id option or the option does not contain a DOCSIS version ID. Optional, no default.

drop-old-packets

set
get
unset

Time, in seconds, that a packet can age and still be processed. If the server is very busy, this could delay processing packets in the UDP input queue. The DHCP protocol lets clients retry packets that are not processed in a few seconds. Therefore, allowing the server to process packets that are older than a few seconds could increase the congestion. If the age of a packet is greater than the value of this attribute when the server processes it, the server drops the packet. Optional, default 4 seconds.

drop-packet-on-extension-
failure

enable
disable
unset

Controls whether the server drops a packet (if possible) when it encounters a failure in an extension. Optional, default enable.

dynamic-dns-fwd-key

set
get
unset

Server-wide security key to process all forward zone dynamic DNS updates. The DNS server is specified by the dns-server-addr attribute and the zone name is specified by the dns-zone-name attribute in a scope object. Optional, no default.

dynamic-dns-rev-key

set
get
unset

Server-wide security key to process all reverse zone dynamic DNS updates. The DNS server is specified by the dns-rev-server-addr attribute and the zone name is specified by the dns-reverse-zone-name attribute in a scope object. Optional, no default.

dynamic-dns-tsig

set
get
unset

Controls whether transaction signatures (TSIG) are used for DNS updates for leases from this server. Optional, default disable-fwd-and-rev. See the "key" section.

enable-fwd-and-rev—Enable TSIG for both forward and reverse zone updates.

disable-fwd-and-rev—Disable TSIG for forward or reverse zone updates (the default).

enable-fwd-only—Enable TSIG for forward updates only.

enable-rev-only—Enable TSIG for reverse updates alone.

expression-configuration-
trace-level

set
get
unset

Trace level to use when configuring DHCP expressions. The range is from 0 through 10, 0 being the lowest amount of tracing and 10 the highest:

0—No additional tracing

2—exp_config_trace_failure_retry—Retry failures

4—exp_config_trace_defns—Definitions

5—exp_config_trace_defn_args—Definition arguments

7—exp_config_trace_find—Find errors

8—exp_config_trace_literal—Literal details

10—exp_config_trace_all—Trace all

There is no performance penalty to specify a high expression-
configuration-trace-level
, as expressions are configured only when the server is started. Optional, default 2 (failure retry).

expression-trace-level

set
get
unset

Trace level to use when executing DHCP expressions. The range is from 0 through 10, 0 being no tracing and 10 the highest amount of tracing:

0—No tracing

1—exp_trace_failures—Failures (including those protected by (try ...))

2—exp_trace_failure_retry—Total failure retries (with trace level = 6 for retry)

3—exp_trace_calls_returns—Function calls and returns

5—exp_trace_args—Function arguments evaluation

6—exp_trace_print_args—Print function arguments

8—exp_trace_conversions—Datatype conversions

10—exp_trace_all—Everything

There is considerable performance penalty to any setting beside 0, 1, or 2. The setting of 1 only traces when there is a failure in an expression. The default setting of 2 re-executes evaluating an expression that fails at the outermost level with the expression-trace-level=10 for the duration of the re-execution, to provide maximum debugging assistance. Optional, default 2.

extension-trace-level

set
get
unset

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 0 (the default) causes very little tracing. Setting the level to 3 causes considerable tracing. Optional, default 0.

failover

enable
disable
unset

Controls whether all scopes that use the failover configuration can engage in failover. See the Network Registrar User's Guide for a description of the attribute states. If disabled (the default), those scopes with failover explicitly enabled for the scope are still available for failover. Optional, default disable.

failover-backup-percentage

set
get
unset

With failover enabled, the percentage of currently available (unleased) addresses that the main server should send to the backup server to allocate to new DHCP clients when the main server is down. The value is only meaningful for the main server. Optional, default 10 percent.

failover-backup-server

set
get
unset

With failover enabled, the DNS name of the backup server associated with all scopes if you did not use the scope name set failover-backup-server command. If this DNS name resolves to the IP address of the current server, this server operates as the backup server for all of these scopes. It is an error if both the main and backup server names resolve to addresses on the same server. Optional, no default.

failover-bulking

enable
disable
unset

With failover enabled, controls whether a failover bind update (BNDUPD) contains multiple lease state updates. Affects only the lease state updates that DHCP client activity generates. Optional, no default.

failover-dynamic-bootp-
backup-percentage

set
get
unset

With failover enabled, the percentage of currently available (unreserved) addresses that the main server should send to the backup server for scopes set with scope name enable bootp. Optional, no default.

failover-lease-period-factor

set
get
unset

With failover enabled, the multiple of the lease period used to update the backup server when the main server informs it of a new DHCP client lease period. Optional, default factor of 1.5.

failover-main-server

set
get
unset

With failover enabled, the DNS name of the main server associated with all scopes where scope name set failover-main-server is not set. If this DNS name resolves to the IP address of the current server, this server operates as the main server for all of these scopes. It is an error if both the main and backup server names resolve to addresses on the same server. Optional, no default.

failover-maximum-client-
lead-time

set
get
unset

With failover enabled, the maximum client lead time (MCLT), in seconds. The MCLT is the maximum time that one server can extend a client's lease beyond what its partner knows it to be. You must define the MCLT on the main server, which communicates it to its partner. It is ignored on a backup server. Optional, default 3600 seconds (60 minutes).

failover-poll-interval

set
get
unset

With failover enabled, the polling interval of the failover partners (in seconds) to confirm network connectivity. Optional, default 15 seconds.

failover-poll-timeout

set
get
unset

With failover enabled, the interval (in seconds) after which failover partners who cannot communicate know that they lost network connectivity. Optional, default 60 seconds.

failover-recover

set
get
unset

With failover enabled, time at which the server performs initialization and goes into RECOVER state. If server A is running, server B issues this command to ask for the state of server A. Dates can be in the -2h (two ago, for example) or month day hour:minute[:second] year format. Optional, default none.

failover-safe-period

set
get
unset

With failover enabled and the failover-use-safe-period attribute set, the safe period, in seconds. You must define it in the main server. The safe period can differ on the main and backup servers. See the Network Registrar User's Guide for more information. Optional, default 86400 seconds (24 hours).

failover-use-safe-period

enable
disable
unset

With failover enabled and the failover-safe-period attribute set, you must enable this attribute to cause Network Registrar to go into the PARTNER-DOWN state automatically. If you disable this attribute (the default), Network Registrar never goes into the PARTNER-DOWN state automatically. You must then use the dhcp setPartnerDown command. Optional, default disable.

force-dns-updates

enable
disable
unset

Controls whether the DHCP server retries a dynamic DNS update whenever a client renews its lease, even if the server thinks that the update was already completed successfully. Optional, default disable.

get-subnet-mask-from-
policy

enable
disable
unset

Controls whether the DHCP server searches all relevant policies for a subnet mask option when constructing a response to send to a client. Normally, the DHCP server retains the subnet mask configured in the scope containing the base being granted to the DHCP client. Optional, default disable.

hardware-unicast

enable
disable
unset

Controls whether the DHCP server sends unicast rather than broadcast responses when a client indicates that it can accept a unicast. This attribute is only available on these operating systems: Solaris, Windows 2000, and Windows NT. Optional, default enable.

ignore-icmp-errors

enable
disable
unset

With this attribute enabled (the default), if you configured the DHCP server to send ICMP ECHO (ping-before-offer) requests, the server makes unavailable any address for which it receives an ECHO reply within its configured timeout period. If you disable this attribute, the DHCP server also treats ICMP DEST_UNREACHABLE and TTL_EXPIRED error messages that it receives after sending ICMP ECHO requests as grounds for making an address unavailable. Optional, default enable.

ignore-requests-for-other-
servers

enable
disable
unset

Controls whether to prevent the normal DHCP server response to client requests for other servers. Normally, if the DHCP server sees a client requesting a lease from another server for an address that this server is configured to control, it sets the lease to unavailable. However, some clients could send request packets with bad server ID options (rather than packets actually directed to other servers) that the server could wrongly interpret as the address being unavailable. You can enable this attribute to prevent this from occurring. Optional, no default.

import-mode

enable
disable
unset

Controls whether to have the DHCP server recognize only packets generated from the import leases command and to ignore all others. You can use this attribute if you want to update your DHCP server and prevent clients from receiving addresses during this period. Optional, default disable.

inhibit-busy-optimization

enable
disable
unset

Controls whether to prevent the server from using optimization to recover from periods of congestion. By default, the DHCP server determines that it is heavily loaded when the number of request packets reaches two-thirds of the total allocated. It logs a message and attempts to recover from the congestion by performing several optimizations. For example, it relaxes the requirement to keep the client's last transaction time updated to the granularity specified by the last-transaction-time-
granularity
attribute.

When the number of request packets drops to one-third of the total allocated, the server logs a message and returns to normal operation. If you enable the inhibit-busy-optimization attribute, the server does not use the optimizations or log the messages when it gets congested. Optional, default disable.

initial-environment-
dictionary

set
get
unset

Contains attribute-value pairs that initialize all environment dictionaries in the DHCP server. You can use these attribute-value pairs to configure extensions or expressions without having to rewrite the executable code in the extension or expression. The string must have the format "attribute1=value1,attribute2=value2, ... ,attributen=valuen". Optional, no default.

ip-history

enable
disable
unset

Controls recording IP history data for the IP history database. See the Network Registrar User's Guide for details. Default, disable.

ip-history-dir

set
get
unset

Path to the directory of the database containing the IP (lease) history. You must set this attribute if you use the dhcp enable ip-history command. Store the history files on a different disk partition from the server's lease state database. Because of this, use absolute paths. Use forward slashes (/) as path separators and quote paths containing space characters. Optional.

last-transaction-time-
granularity

set
get
unset

Time, in seconds, that Network Registrar guarantees that the last transaction time is accurate. Do not set this lower than the default of 60 seconds. For optimal performance, set it to a value that is greater than half of your lease interval. Optional, default 60 seconds.

ldap-mode

set
get
unset

Determines the preference for using LDAP servers if multiple LDAP servers are configured. Optional, no default. There are two possible values:

round-robin—The DHCP server ignores the servers' preferences. It treats all LDAP servers (those configured to handle client queries and those configured to accept lease-state updates) equally.

failover—The DHCP server uses the active LDAP server with the lowest preference. If the preferred server loses its connection or fails, the DHCP server uses the next LDAP server in preference order. The DHCP server uses servers with equal preference in round-robin order.

log-settings

set
get
unset

Determines which events to log in the log files. See Table 2-7. Logging additional detail about events can help analyze a problem. However, leaving detailed logging enabled for a long period can fill up the log files. Optional, the default flags are default, incoming-packets, and missing-options.

mac-address-only

enable
disable
unset

Controls whether the DHCP server uses 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. You can use this argument to identify all clients that use the server. Optional, default disable; deprecated for Network Registrar 6.0.

map-user-class-id

set
get
unset

Determines the handling of user class-id. This attribute is global and is set for all DISCOVER packets. Optional, default 0. The values are:

0—Ignore the user class-id option (default).
1—Map the user class-id option to the scope-selection tag. See the "scope-selection-tag" section.
2—Map the user class-id option to the client-class.

max-dhcp-requests

set
get

Controls the number of buffers the DHCP server allocates for receiving packets from DHCP clients and failover partners. When enabling failover, allocate at least 150 buffers. Up to 1500 buffers could be reasonable for high capacity installations. When buffer size exceeds capacity, a burst of DHCP activity can clog the server with requests that become stale before they are processed. This results in an increasing processing load that can severely degrade performance as clients try to obtain a new lease. A lower buffer setting throttles requests and avoids wasted processing on requests that would otherwise be stale. Required. The default is 500.

When using LDAP client lookups, buffers should not exceed the LDAP lookup queue size defined by the total number of LDAP connections and the maximum number of requests allowed for each connection. Set the LDAP queue size to match the LDAP server's capacity to service client lookups.

max-dhcp-responses

set
get

Number of buffers that the DHCP server allocates for responding to DHCP clients and communicating with failover partners. The number of buffers allocated should be at least two times the number allocated for the max-dhcp-requests attribute. Perhaps as many as several thousand is reasonable in some installations. Required, default 1000 buffers (if failover is configured, the server configures additional responses).

max-dns-packets

set
get

Number of DNS packet buffers that the DHCP server allocates for sending dynamic updates to the DNS server. You can reduce the DHCP server's memory requirement by reducing the number of DNS packets, at the risk of missing updates. Required, no default.

max-dns-renaming-retries

set
get

Number of times that the DHCP server can try to add a host in DNS even if it detects that the host's name is already present. This controls the number of times the DHCP server tries to modify a host's name to resolve a conflict on each failed update. Required, default two (2) retries.

max-dns-retries

set
get

Number of times that the server tries to send dynamic updates to a DNS server. Required, default three (3) retries.

max-dns-ttl

set
get

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 could actually be the zone's minimum TTL. Required, default 86400 seconds (24 hours).

max-ping-packets

set
get
unset

Number of buffers that the server allocates for sending and receiving ICMP ping messages, if you use the scope name enable ping-clients command. See Table 2-20. Required, no default.

max-waiting-packets

set
get
unset

Number of packets that can wait for processing for an address. The server queues only the most recently received n packets (of an address) for processing. If an additional packet associated with that address arrives and n packets are already queued, the server drops the oldest packet and queues the new one. See the dropped-waiting-packets log setting attribute in Table 2-7. It also drops duplicate packets (whose XID, client ID, and MAC address are the same as one already queued). If you accept the default of 0, the server processes all packets. Optional, default 0.

mcd-blobs-per-bulk-read

set
get
unset

Number of binary large objects (blobs) for a bulk read. Use this attribute to tune DHCP start and reload times. Generally, a higher value results in faster server start and reload times, at the cost of using more memory. Optional, values from 1 through 2500, there is no default.

one-lease-per-client

enable
disable
unset

Controls whether to have the DHCP server release any other leases that the client may have had on this server. Because the default behavior for the Network Registrar DHCP server is to store all the leases that a client obtains, this attribute ensures that the DHCP server only stores one lease. A client might obtain a number of leases if a user with a laptop travels throughout the building and requests leases at different locations on the network. Optional, default disable; deprecated for Network Registrar 6.0.

return-client-fqdn-if-asked

enable
disable
unset

Controls whether the system returns the client-fqdn (fully qualified domain name) option to the client in the outgoing packet if the client requests it in the parameter request list. For example, the client may want to know the status of the DNS activity. Optional, default enable.

The flags are always set in the option to 0x3 and the RCODE1 and RCODE2 to 255. Whatever string came in is sent back, even if the use-client-fqdn attribute is turned off and no matter what the actual name is or may ultimately be in DNS.

save-lease-renewal-time

enable
disable
unset

If set to true, the server saves the lease renewal time (the minimum time in which the client is expected to issue a lease renewal) as part of the lease in persistent memory. Optional, default disable.

save-relay-agent-data

set
get
unset

The lease state database in Network Registrar 5.5 and later saves all relay agent data. Therefore, any changes to this attribute have no effect. Optional, no default; deprecated for Network Registrar 6.0.

save-vendor-class-id

enable
disable
unset

Controls whether the server saves the value of DHCP option 60 in memory. This affects what you can store in an LDAP directory. Optional, default disable.

scope-selection-tags

set
get
unset

List of scope-selection tags associated with the server. In this context, refers to a named entity that controls matching client and client-class entries with candidate scopes. See the "scope-selection-tag" section. Optional, no default.

skip-client-lookup

enable
disable
unset

If enabled, causes the DHCP server to skip looking up the client entry for client-class processing. If disabled (the default), the DHCP server looks up the client entry first. Optional, default disable.

sms-lease-interval

set
get
unset

Sets the time interval, in milliseconds, between sending addresses to the System Management Server (SMS). After you install a future release of Microsoft BackOffice Resource Kit (which contains an enhanced version of smsrsgen.dll), reduce this interval or set it to 0. Optional, default 1100 milliseconds.

sms-library-path

set
get
unset

Overrides the internal default value for the name of the SMS dll. The default is the empty string. If you specify an empty string, the system defaults to the internal server default of smsrsgen.dll. Optional, no default.

sms-network-discovery

set
get
unset

Causes the DHCP server to generate SMS network discovery records. To enable this attribute, set it to 1; to disable it, set it to 0 (the default). Use this attribute in conjunction with the dhcp updateSms command. See the "server" section. Optional, default 0.

sms-site-code

set
get
unset

Specifies the site code of the SMS server that receives discovery records when you issue the updateSms keyword. You must initialize this attribute to the appropriate SMS site code for the updateSms keyword to operate. See the "server" section. Optional, no default.

synthesize-reverse-zone

enable
disable
unset

Controls whether the DHCP server automatically generates the name of the reverse zone (in-addr.arpa) that is updated with PTR records. If this attribute is enabled and the scope does not have an explicit dns-reverse-zone-name attribute configured, the server uses the leased IP address and dns-host-bytes attribute on a scope to generate the reverse zone name.Optional, default true.

trim-host-name

enable
disable
unset

Controls whether the DHCP server trims the host-name string to the first period character (used to update dynamic DNS update records and to return the host-name option to clients). If this attribute is enabled, the host-name is truncated before the period. If disabled, the server retains the period characters in the host-name. Optional, default true.

update-dns-for-bootp

enable
disable
unset

If the server replies to a BOOTP request and offers a lease from a scope that is configured for DNS updates, the DHCP server checks this attribute before beginning the update. You can use this attribute to prevent DNS updates for BOOTP clients, while allowing updates for DHCP clients. Optional, default enable.

upgrade-unavailable-
timeout

set
get
unset

Controls the time given a lease in the database that has no expiration, that is, it went unavailable before installing Network Registrar 6.0. Optional, default 86400 seconds (one day).

use-client-fqdn

enable
disable
unset

Controls whether to examine the client-fqdn (fully qualified domain name) option for the host name. If there are characters after the first dot in a client-fqdn option, the server ignores them because it determines the domain from the scope. Set this attribute to false if you do not want the server to determine a host name from this option, possibly because the client is sending unexpected characters. Optional, default enable.

use-client-fqdn-first

enable
disable
unset

Controls whether to examine the client-fqdn option on incoming packets first, before the host-name option, when determining a host name for a client. If there is a client-fqdn option with a host name specified, the system uses that host name. If the system finds no client-fqdn option in the incoming packet, the system uses the host-name option.

If this attribute is set to false, the system examines the host-name option first and uses any name found in that option. If that option does not appear, it examines the client-fqdn option for a host name. Optional, default enable.

use-dns-update-prereqs

enable
disable
unset

By default, the DHCP server uses prerequisites in its DNS update messages when it performs DNS updates on behalf of clients. If this parameter is set to false, the server does not include prerequisites. Without them, the last client who uses a given domain name is associated with that name, even if another client is already associated with it. Optional, default enable.

use-host-name

enable
disable
unset

Controls whether to examine the host-name option for the host name. Disable this attribute if you do not want the server to determine a host name from this option, possibly because the client is sending unexpected characters. Optional, default enable.

use-ldap-client-data

enable
disable
unset

Controls whether the DHCP server attempts to read client-entry data using the configuration supplied by the ldap command. See the "ldap" section. Optional, default disable.

validate-client-name-as-
mac

enable
disable
unset

If set, the user interfaces should require that the name of client entries is a valid MAC address (or the literal string default) and should turn the name into the canonical MAC address format (1,6,xx:xx:xx:xx:xx:xx) that the DHCP server uses as the default client entry lookup key. If set to false, the user interfaces allow creating client entries with arbitrary names, which could match the lookup keys generated from the client-lookup-id expression. Optional, default enable.

vpn-communication

enable
disable
unset

If enabled (the default), the DHCP server can communicate with DHCP clients on a different virtual private network (VPN) from that of the DHCP server by using an enhanced DHCP relay agent capability. This enhanced capability is signalled by the appearance of the server-id-override suboption in DHCP option 82. Optional, default enable.


DHCP Log Settings

See Table 2-7 for the log flags that you can set using the dhcp command. The log setting that is enabled by default is incoming-packets.

You can modify the logging behavior of the DHCP server by setting flags on the log-settings attribute. For example, you can suppress warning messages for unconfigured or missing options.

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

You can turn on client and client-class debugging for the DHCP server.

nrcmd> dhcp set log-settings=client-detail 

You can also turn off debugging entirely for the DHCP server. In each case, reload the server.

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

Table 2-7 DHCP Log Flags 

Flag
Messages Logged to name-dhcp-1-log

activity-summary

Every five minutes. This is useful when you enable many of the no-xxx log settings because it provides some indication of the activity in the server without imposing the load required for a log message corresponding to each DHCP message. Configure the frequency for these messages using the dhcp set activity-summary-interval command.

client-criteria-
processing

When the server examines a scope to find an available lease or to determine if a lease is still acceptable for a client who already has one. This setting can be useful when configuring or debugging client-class scope criteria processing. It logs a moderate amount of data, so you should not leave it enabled for long.

client-detail

After every client-class client lookup operation. This line shows all the data found for the client as well as the data found in the client's client-class. This is useful when setting up a client-class configuration and for debugging problems in client-class processing.

default

At a low level in several parts of the DHCP server. This flag is on by default. If you reconfigure the default, this logging does not appear.

dns-update-detail

Additional log messages for all DNS operations. This flag is helpful in diagnosing problems in dynamic DNS operations.

dropped-waiting-
packets

If the system drops packets due to the setting of the max-waiting-packets DHCP attribute. The server may drop packets if the queue length for any IP address exceeds the value of the max-waiting-packets attribute. If the dropped-waiting-packets attribute is enabled, the server logs a message whenever it drops a waiting packet from the queue for an IP address.

failover-detail

Concerning failover protocol operations and state transitions. Setting this does not place a significant load on the server.

incoming-packets

As a single line for every incoming packet. This setting is especially useful when you initially configure a DHCP server or BOOTP relay, in that an immediate positive indication exists that the DHCP server receives packets. Default enabled.

incoming-packet-
detail

With the contents of every DHCP packet received by the DHCP server in human readable form. This setting enables the built-in DHCP packet sniffer for input packets. The log files fill up (and turn over) very rapidly when you enable this setting. It also causes a significant performance impact on the DHCP server, so that you should not leave it enabled for long.

ldap-create-detail

When the DHCP server sends a request creating a lease state entry to an LDAP server, receives a response from an LDAP server, or retrieves a result or error message from an LDAP server.

ldap-query-detail

When the DHCP server initiates a query to an LDAP server, receives a response from an LDAP server, or retrieves a query result or an error message from an LDAP server.

ldap-update-detail

When the DHCP server sends a lease update request to an LDAP server, receives a response from an LDAP server, or a retrieves a result or error message from an LDAP server.

leasequery

When processing leasequery packets without internal errors, and when a lease query results in an acknowledgement (ACK) or negative acknowledgement (NAK) message.

minimal-config-info

Reduces the number of configuration messages that Network Registrar logs when the server starts or reloads. In particular, the server does not log a message for every scope when this flag is set.

missing-options

When a policy does not include an option a DHCP client requests, so that the DHCP server cannot supply it. This flag is on by default.

no-dropped-bootp-
packets

Prevents logging the single line message normally logged for every dropped BOOTP packet.

no-dropped-dhcp-
packets

Prevents logging the single line message normally logged for every DHCP packet dropped due to DHCP configuration. See the no-invalid-packets flag for messages associated with packets dropped because they are invalid.

no-failover-activity

Prevents logging normal activity messages and some warning messages logged for failover. Serious error log messages continue to appear independently of this log setting.

no-failover-conflict

Prevents logging warnings about potential conflicts between failover partners, but still logs errors. Setting this log setting can greatly reduce the amount of logging produced by a failover without losing the errors.

no-invalid-packets

Prevents logging the single line message normally logged for every DHCP packet dropped for being invalid. See the no-dropped-dhcp-packets flag for messages associated with packets dropped because of the DHCP server configuration.

no-reduce-logging-
when-busy

When the server is very busy. Normally, the DHCP server reduces logging when it becomes very busy, such as when it uses over two-thirds of the available receive buffers (which is itself a configurable value). To do this, it sets the no-success-messages, no-dropped-dhcp-packet, no-dropped-bootp-packets, no-failover-activity, and no-invalid-packet flags and clears everything else except the activity-summary flag. When it is no longer very busy, such as when only one-third of the available receive buffers used, the server restores the previous settings. Setting this flag prevents Network Registrar from taking these actions.

no-success-messages

Prevents logging the single line message normally logged for every successful outgoing DHCP response packet. This affects logging for only successful outgoing DHCP response packets. This log setting can greatly increase server performance.

no-timeouts

Prevents logging messages associated with the timeout of leases or offers.

outgoing-packet-
detail

Contents of every DHCP packet transmitted by the DHCP server in a human readable form. Enables the built-in DHCP packet sniffer for output packets. The log files fill up (and turn over) very rapidly when this setting is enabled. Enabling this setting also causes a performance impact on the DHCP server because of the volume of outgoing packets so you should not leave it enabled for long.

unknown-criteria

As a single-line when 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.


Extension Points

Table 2-8 summarizes the extension points available for controlling the DHCP server (in general sequential order).

Table 2-8 dhcp Command Extension Points 

Extension Point
Purpose

check-lease-
acceptable

Reached immediately after the server determines that the current lease is acceptable for this client. The extension can examine the results of that operation and can cause the routine to return different results.


Caution Use this extension point with extreme care. Incorrect usage can create an infinite loop in the server.

post-class-lookup

If called after the client-class lookup is performed, allows you to modify the values looked up, particularly the limitation-id attribute value.

post-client-lookup

Examines the results of the entire client-class processing operation and acts based on those results, such as rewriting the results or dropping the packet. You can use this extension point to place data items in the environment dictionary to affect the processing of an extension running at the pre-packet-encode extension point. Note that you cannot change the client-class at this point, but you can override certain values determined by the client or client-class already examined.

post-packet-decode

First extension point encountered when a request arrives. It immediately follows the decoding of the input packet and precedes any processing on the data in the packet. The primary activity for an extension at this point is to read information from an input packet and act on it, for example, to rewrite the input packet.

post-send-packet

Updates an external process or database with information about a request or response.

pre-client-lookup

Runs only if you set dhcp enable client-class for the server. This extension point allows an extension to:

Modify the client that is looked up during client-class processing.

Specify individual data items to override any data items found from the client entry or the client-class that it specifies.

Instruct the server to skip the client lookup altogether. In this case, the only client data used is that specified.

Drop the packet.

pre-packet-encode

Rewrites information in the response packet that the DHCP server sends to the user. This extension point comes after the response packet is ready for encoding into a packet sent to the DHCP client. Typically, you can add options to the packet at this extension point. The server can also drop the packet at this point, but the server already recorded its values in its internal database.

pre-dns-add-forward

Chooses the name and affects the number of DNS retries during update operations. Network Registrar might call this extension point multiple times for a single DNS update operation.


Related Commands

dhcp-interface, key, lease, policy, scope, server

dhcp-interface

The dhcp-interface command adds, removes, and lists Network Registrar DHCP interfaces. In Network Registrar, a DHCP interface is a logical representation of the hardware interface (such as a server's Ethernet or Token Ring network interface card) that the DHCP server uses. DHCP interfaces get the name of the address and subnet mask of the physical device they represent. Additionally, Network Registrar uses the 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 hardcoded default values for port numbers and socket buffer sizes for the interfaces that it autodiscovers.

dhcp-interface ipaddress/maskbits create

dhcp-interface {ipaddress/maskbits | default} delete

dhcp-interface ipaddress/maskbits set {mask=value | ignore=true | false}

dhcp-interface {ipaddress/maskbits | default} get {addr | mask | ignore}

dhcp-interface {ipaddress/maskbits | default} [show]

dhcp-interface list

dhcp-interface listnames

Syntax Description

dhcp-interface ipaddress/maskbits create [attribute=value...]

Creates a DHCP interface specification named by the IP address and network prefix bits of the physical interface. You can specify the mask bits as 24 or 16.

dhcp-interface {ipaddress/maskbits | default} delete

Deletes a DHCP interface. If you delete the default interface, the DHCP server uses hardcoded default values for port numbers, and socket buffer sizes for the interfaces that it autodiscovers.

dhcp-interface ipaddress/maskbits set {mask=value | ignore=true | false}

Sets the subnet mask or ignore attribute, or both. The ignore attribute enables or disables the server to ignore this interface, which might be the case if you had several interfaces. You can disable to temporarily disable a specific interface in a list. To change the interface address, delete and recreate the interface. Optional, no default.

dhcp-interface {ipaddress/maskbits | default} get {addr | mask | ignore}

Gets the value of an attribute for the DHCP interface.

dhcp-interface {ipaddress/maskbits | default} [show]

Shows the values of all attributes assigned to the DHCP interface.

dhcp-interface list

Lists all DHCP interfaces and any attributes assigned to them.

dhcp-interface listnames

Lists just the DHCP interface names.

Related Commands

dhcp

dns

The dns command sets and enables or disables DNS server attributes. Note that in Network Registrar there is only one DNS server per cluster, hence you do not need to reference the server by name.

dns enable attribute

dns disable attribute

dns set attribute=value [attribute=value...]

dns unset attribute

dns get attribute

dns [show]

dns addRootHint name ipaddress [ipaddress...]

dns removeRootHint name

dns listRootHints

dns addException name ipaddress [ipaddress...]

dns removeException name

dns listExceptions

dns addForwarder ipaddress [ipaddress...]

dns removeForwarder ipaddress

dns listForwarders

dns flushCache

dns rebuildRR-Indexes

dns forceXfer secondary

dns scavenge


Note See also the "server" section for other server control commands.


Syntax Description

See Table 2-9 for a list of the dns command attribute descriptions.

dns enable attribute

Enables a DNS server attribute.

dns disable attribute

Disables a DNS server attribute, such as to disable NOTIFY for all the zones.

nrcmd> dns disable notify 

dns set attribute=value [attribute=value...]

Sets one or more attributes of the DNS server.

dns unset attribute

Unsets the value of a DNS attribute.

dns get attribute

Gets the value of an attribute for the DNS server.

dns [show]

Shows all the DNS server attributes.

dns addRootHint name ipaddress [ipaddress...]

Adds the named root server at a specific IP address using the root hint method. After you specify these servers, Network Registrar queries them for their root NS records that resolve other names. These values need not be exact, but should be accurate enough for the DNS server to retrieve the correct information.

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

dns removeRootHint name

Removes a root name server.

nrcmd> dns removeRootHint a.root-servers.net 

dns listRootHints

Lists a root name server.

dns addException name ipaddress [ipaddress...]

Adds an exception server at a specific IP address.

nrcmd> dns addException blue.com. 192.168.1.4 

dns removeException name

Removes an exception server.

dns listExceptions

Lists all the exception name servers.

dns addForwarder ipaddress [ipaddress...]

Adds the IP address 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.

nrcmd> dns addForwarder 192.168.1.4 

dns removeForwarder ipaddress

Removes a forwarder server at the IP address.

dns listForwarders

Lists all the forwarder servers.

dns flushCache

Flushes the cache file to stop it from growing. The behavior depends on whether your DNS server is running or stopped.

dns forceXfer secondary

Forces full zone transfers for every secondary zone, regardless of the SOA serial numbers, to synchronize DNS data store. If a normal zone transfer is already in progress, the command schedules a full zone transfer for that zone immediately after the normal zone transfer finishes.

dns scavenge

Causes scavenging on all zones that have the scvg-enabled attribute enabled.

Attributes

Table 2-9 describes the dns command attributes and their values and defaults, if any.

Table 2-9 dns Command Attributes 

Attributes
Usage
Description

activity-summary-
interval

set
get
unset

Time, in seconds, between activity summary log messages if enabled in the activity-summary setting in log-settings. Optional, default 300 (5m).

axfr-multirec-
default

enable
disable

Default multirecord full zone transfer (AXFR) choice for remote servers not found in the remote server list. Optional, default disable.

checkpoint-interval

set
get
unset

Interval (in seconds) at which to checkpoint zones (take the latest snapshot in the zone checkpoint database). The checkpoint interval set at the zone level overrides this value. Required, default 19800 seconds (three hours).

fake-ip-name-
response

enable
disable

Controls whether the server, if queried for a domain name that resembles an IP address (for example, an A record like 192.168.40.40), automatically responds with a NXDOMAIN status without even trying to query (or forward to) other servers. Required, default enable.

hide-subzones

enable
disable

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

ixfr-enable

enable
disable

Controls the incremental transfer behavior for zones for which you did not configure a specific behavior. If incremental transfer is enabled, then you must also set the value of the ixfr-expire-interval attribute or accept the default value. Required, default enable.

ixfr-expire-interval

set
get

Longest interval to maintain a secondary zone solely with incremental transfers. After this period, the server requests a full zone transfer. Required, default 604800 seconds (seven days).

lame-deleg-notify

enable
disable

Controls whether to notify when a server listed in a parent zone's delegation of subzones does not know that it is authoritative for the zone. Required, default enable.

local-port-num

set
get

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

log-settings

set
get

Determines which events to log, as set using a bit mask. See Table 2-10. Logging additional details about events can help analyze a problem. However, leaving detailed logging enabled for a long period can fill the log files and affect server performance. Required, default is all settings except scavenge-details and tsig-details.

max-cache-ttl

set
get

Maximum amount of time to retain cached data. Required, default 604800 seconds (seven days).

max-negcache-ttl

set
get

Sets an upper bound on the amount of time that a Network Registrar DNS server caches a negative response. (This attribute replaces the neg-cache-ttl attribute used in previous versions of Network Registrar, but not compliant with RFC 2308.) The allowable range in seconds is 0 to 2147483647. A value of 0 indicates no upper bound. The default is 3600 seconds (one hour).

mem-cache-size

set
get

Size of the memory cache, in kilobytes. Required, default 200 KB.

neg-cache-ttl

set
get

How long, in seconds, to cache information learned from other name servers about nonexistent names or data. Use with pre-6.0 releases only; replaced by the max-negcache-ttl attribute. Required, default 600.

no-fetch-glue

enable
disable

Controls whether you want the DNS server, when composing a response to a query, to fetch missing glue records. Glue records are A records with 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. Required, default disable.

no-recurse

enable
disable

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 enable no-recurse, you make your name server a noncaching server. Required, default disable.

notify

enable
disable

Controls sending NOTIFY messages for zones incurring a change. You must also set the other notify- attributes or accept their defaults. Required, default enable.

notify-defer-cnt

set
get

With NOTIFY enabled, the maximum number of UPDATE changes to accumulate during the notify-wait period. If this number is exceeded, Network Registrar sends notification before the notify-wait period passes. Required, default 100 changes.

notify-min-interval

set
get

With NOTIFY enabled, the minimum interval required before sending notification of consecutive changes on the same zone to a particular server. Required, default two (2) seconds.

notify-rcv-interval

set
get

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

notify-send-stagger

set
get

With NOTIFY enabled, the interval to stagger notification of multiple servers of a particular change. Required, default one (1) second.

notify-wait

set
get

With NOTIFY enabled, the period of time to delay, after an initial zone change, before sending change notification to other name servers. Use this attribute to accumulate multiple changes. Required, default five (5) seconds.

query-source-
address

set
get

Source IP address from which, the DNS server sends queries to other servers when resolving names for clients. A value of 0.0.0.0 indicates that the operating system will use the best local address, based on the destination. Required, no default.

query-source-port

set
get

UDP port number from which the DNS server sends queries to other servers when resolving names for clients. A value of zero indicates the need to choose a random port. If this attribute is unset, the port used to listen for queries sends the queries (see the local-port-num attribute). Required, no default.

remote-port-num

set
get

UDP and TCP port to which the DNS server sends queries to other servers. Required, default port 53.

round-robin

enable
disable

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

save-negative-
cache-entries

enable
disable

Controls whether to have the server store negative-query-results cache entries in its cache.db file. If disabled, the server discards negative cache entries evicted from the in-memory cache instead of storing them in the cache.db file. Required, default enable.

scvg-ignore-
restart-interval

set
get

Interval, in seconds, for which a server restart does not recalculate a start scavenging time. Required, default 7200 seconds (two hours).

scvg-interval

set
get

With scavenging enabled, the interval, in seconds, at which the zone is scheduled for scavenging. The zone setting of the same attribute overrides this setting. Range 3600 (one hour) through 31536000 seconds. Required, default 604800 seconds (seven days).

scvg-no-refresh-
interval

set
get

With scavenging enabled, the interval, in seconds, during which actions, such as dynamic updates, do not refresh the timestamp on a record. The zone setting of the same attribute overrides this setting. Range 3600 (one hour) through 31536000 seconds. Required, default 604800 seconds (seven days).

scvg-refresh-
interval

set
get

With scavenging enabled, the interval, in seconds, during which the record can have a timestamp refreshed. The zone setting of the same attribute overrides this setting. Range 3600 (one hour) through 31536000 seconds. Required, default 604800 seconds (seven days).

simulate-zone-top-
dynupdate

enable
disable

For Windows 2000 Domain Controller compatibility, when processing a dynamic update packet that attempts to add or remove A records from the name of a zone, respond as if the update was successful, rather than with a refusal, as would normally occur from the static/dynamic name conflict. No update to the records at the zone name actually occurs, although the response indicates that it does. Required, default disable.

slave-mode

enable
disable

Controls whether the server should be a slave server that relies entirely on forwarders for data not in its cache. This attribute 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. Required, default disable.

subnet-sorting

enable
disable

Controls whether to re-order address records in responses to queries based on the subnet of the client. Because clients often only look at the first record of a set, enabling this attribute can help localize network traffic onto a subnet. This attribute applies only to answers to queries from clients located on the same subnet as the DNS server. Required, default disable (as implemented in BIND 4.9.7).

update-acl

set
get
unset

Adds or updates one or more ACLs to a DNS server. If set, the server uses ACLs to control what networks or servers can perform dynamic DNS updates. Use the ! symbol to negate a value, such as:

nrcmd> dns set update-acl=acl1,!acl2 

See the "acl" section. If you set this attribute at the zone level, it overrides the server attribute. Required, no default.

update-relax-zone-
name

enable
disable

Controls relaxing of the RFC 2136 restriction on the zone name record in dynamic updates. This attribute allows updates to specify a zone name, which is any name within an authoritative zone, rather than the exact name of the zone. Required, default disable.


DNS Log Settings

Table 2-10 describes the flags you can set with the log-settings attribute, along with their numerical equivalents. All the settings are enabled by default except the scavenge-details and tsig-details settings. If you make changes to the settings, reload and restart the server.

Table 2-10 DNS Log Flags 

Flag
Number
Logs

activity-summary

20

Server activity at intervals set by the activity-summary-interval attribute (default five minutes).

config

1

Server configuration and de-initialization (unconfiguration).

config-details

22

Generates detailed information during server configuration

datastore

8

Datastore processing that provides insight into various events in the server's embedded databases.

ddns

2

High level dynamic update messages.

ddns-details

17

Resource records added or deleted due to dynamic DNS updates.

ddns-refreshes

15

Dynamic DNS update refreshes for Widows 2000 clients.

ddns-refreshes-
details

16

Resource records refreshed during dynamic DNS updates for Windows 2000 clients.

lame-delegation

13

Lame delegation events, although enabled by default. Disabling this flag could prevent the log from getting filled with frequent lame delegation encounters.

notify

5

NOTIFY transactions.

query-errors

21

Errors encountered while processing DNS queries.

root-query

14

Queries and responses from root servers.

scavenge

9

Zones scavenged of dynamic resource records.

scavenge-details

10

More detailed scavenged zone output (disabled by default).

server-operations

11

General high server events, such as those pertaining to sockets and interfaces.

tsig

18

Allows logging of events associated with transaction signature (TSIG) DDNS updates.

tsig-details

19

Causes more detailed logging pertaining to TSIG to be displayed (disabled by default).

xfr-in

3

Inbound full and incremental zone transfers.

xfr-out

4

Outbound full and incremental zone transfers.


Related Commands

server, zone

exit

The exit command writes all unsaved changes to the database and then terminates the current nrcmd session. If Network Registrar cannot save your changes, it displays an error code. The quit command is equivalent to the exit command.

exit

quit


Note It is good practice to make the last line of code in a batch file an explicit exit command. Also terminate this line in the batch file with an end-of-line character.


Related Commands

quit, save

export

The export command exports Network Registrar DHCP and DNS server information.

export addresses file=CSV-text-file
[namespace=name]
[
config=config-file]
[dhcp-only]
[time-ascii | time-numeric]

export addresses database=db-name user=username password=password [table=name]
[
namespace=name]
[
config=config-file]
[
dhcp-only]
[
time-ascii | time-numeric]

export hostfile [file]

export leases {-client | -server}
[
-namespace name]
[
-time-ascii | -time-numeric] file

export zone name {static | dynamic | both} file

export zonenames {forward | reverse | both} file

export key keyname file

export keys file

Syntax Description

export addresses file=CSV-text-file [namespace=name] [config=config-file] [dhcp-only]
                            [time-ascii | time-numeric]

Exports all active IP addresses in a comma-separated value (CSV) text file, if specified. If you omit the file, it writes the output in CSV format to the standard output.

Output of the export command can include the namespace specification. The value can be any valid, predefined namespace name, or the reserved words global and all. Global indicates all addresses not in any of the defined namespaces. All indicates all namespaces, including the global one. If you omit the namespace, the current one applies, as set by the session set current-namespace command. If the current namespace is undefined, the global namespace applies. Network Registrar adds the ID of the namespace at the end of each output line in the export file.

Use these conventions for export addresses keywords.

Configuration file—If it exists, the default configuration file is .nrconfig. To use a configuration file other than the default file, use the config keyword to identify your configuration file. If there is an [export-addresses] section in the configuration file, the export command uses the clusters that the section specifies instead of the default cluster. If you omit a configuration file, the export addresses command looks for a default .nrconfig file. This is the same configuration file that the report command uses. Network Registrar looks for the file first in your current directory, then in your home directory, and finally in the AIC_INSTALL_PATH/conf directory. It uses the first file it encounters.

Each line of the configuration file must begin with the character # (comment), a section header enclosed in square brackets, or a parameter=value pair or its continuation. For example:

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

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

dhcp-only—This keyword causes the command to output only DHCP information and not DNS information.

Database tables—The table keyword specifies the database table to which the command exports address information. If you omit this keyword, Network Registrar writes to the default table name ip_addresses. If the table already exists in the specified database when you run the export command, Network Registrar clears (and resets the columns) before writing the new data. Network Registrar does not provide a warning or confirmation if it clears an existing table.

Date and time—The optional time-ascii and time-numeric keywords specify how to output date/time fields to a CSV text file and when the target database does not support the timestamp data type. The default is time-ascii.

export addresses database=db-name user=username password=password [table=name]
[namespace=name] [config=config-file] [dhcp-only]
[time-ascii | time-numeric]

Exports all active IP addresses into a database table. See the Network Registrar User's Guide for the database output format of the export addresses command.

export hostfile [file]

Creates a host file, in UNIX host file format, from all the zones in the server, ignoring reverse zones. It creates hostfile records from A records, CNAME records, and HINFO records. Each host file record consists of the IP address, FQDN, aliases created from the A and CNAME records, and comments created from HINFO records.

export leases {-client | -server} [-namespace name] [-time-ascii | -time-numeric] file

Writes the state of all the current leases to the output file. The export leases -client command writes out the lease time as a string in the month, day, time, year format, such as Apr 15 16:35:48 2002.

nrcmd> export leases -client leaseout.txt 

The export leases -server command writes out the state of all current and expired leases to the DHCP server's log directory using the output file that you specify. It writes lease times as integers representing the number of seconds since midnight GMT Jan 1, 1970, for example, 903968580.

nrcmd> export leases -server leaseout.txt 

The file is either the name of the output file or a dash (-) for the standard output for client side exports. You cannot use the dash with the -server keyword. In addition, the server side export does not permit any nonalphanumeric character such as a dot (.) in filenames. For the syntax of the entries in the output file, see the Network Registrar User's Guide.


Note Leases exported with the -client and -server options may show different results when also using dynamic DNS updates, if there is a conflict with the client's host name. This occurs because the lease exported with the -client option shows the host name requested by the client, while a lease exported with the -server option shows the host name used by the server to perform the DNS update.


export zone name {static | dynamic | both} file

Writes the specified DNS zone into a file in the BIND zone file format, where name is the zone whose data you want to write to a file. This example exports the contents of the example.com zone to the hosts.local file:

nrcmd> export zone example.com. static hosts.local 

export zonenames {forward | reverse | both} file

Exports just the zone names for a particular zone type—forward, reverse, or both—to a file.

export key keyname file

Exports a single transaction signature (TSIG) key that is configured on the cluster to a file. Generates a key definition in BIND syntax so that it can be imported into other clusters or copied into BIND configurations. See the "key" section.

export keys file

Exports all the TSIG keys that are configured on the cluster to a file. Generates key definitions in BIND syntax so that they can be imported into other clusters or copied into BIND configurations.

Related Commands

import, key, report

extension

The extension command configures and integrates user-written DHCP extensions into the DHCP server. See the Network Registrar User's Guide for details on extensions and extension point programming.

extension name create language file entry [init-args=value init-entry=value]

extension name delete

extension name set attribute=value [attribute=value...]

extension name unset attribute

extension name get attribute

extension name [show]

extension list

extension listnames


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


Syntax Description

See Table 2-11 for the extension command attribute descriptions.

extension name create lang file entry [init-args=value init-entry=value]

Creates a client and optionally assigns initial entry point attributes. The command line attributes are:

lang—Language in which the extension or module is implemented, either Tcl or Dex. Required, no default.

file—Filename relative to the directory extensions in the installation, as an absolute pathname, but cannot contain a sequence of two dots (..). Required, no default.

entry—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. Required, no default.

For the initial entry point attributes, see Table 2-11.

This example configures an extension named ext1 using the Tcl file tclfile1.tcl having the entry mytclentry:

nrcmd> extension ext1 create Tcl tclfile1.tcl mytclentry 

extension name delete

Deletes an extension.

extension name set attribute=value [attribute=value...]

Sets one or more attributes for the extension.

extension name unset attribute

Unsets the value of an extension attribute.

extension name get attribute

Gets the value of an attribute for the extension.

extension name [show]

Shows the values of all attributes assigned to the extension identified by name.

extension list

Lists all extensions and any attributes assigned to them.

extension listnames

Lists just the extension names.

Attributes

Table 2-11 describes the extension command attributes and their values and defaults, if any.

Table 2-11 extension Command Attributes 

Attribute
Usage
Description

entry

set
get

Name of the entry point for the module. This function is called from any extension point to which this module is bound. Required, no default.

file

set
get
unset

Filename relative to the directory extensions in the installation, or as an absolute pathname, but cannot contain a sequence of two dots (..). Required, no default.

init-args

set
get
unset

Arguments to pass to the init-entry function. Optional, no default.

init-entry

set
get
unset

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. Optional, no default.

lang

set
get

Language in which the extension or module is implemented:

Tcl—Module is a Tcl extension (tcl7.5)

Dex—Module is a shared object with C calling interfaces

Required, no default.


Related Commands

dhcp

force-lock

When you execute a nrcmd command, it tries to get an exclusive lock for the cluster to which it is connected. If it cannot get an exclusive lock, it displays a warning.

Without an exclusive lock, you can issue only these commands:

client

lease

zone add

help

force-lock


Caution Use the force-lock command carefully, because running more than one program that updates the Network Registrar database can cause database corruption. Always check with the other user that currently has the lock. Do not use the force-lock command if the other user exits nrcmd during the time you receive the lock notification, or the command will fail and you will have to restart the session. Instead, the session will become available and you can simply continue with the normal commands.

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

nrcmd> force-lock 

help

The help command displays the nrcmd program online help.

help

help command [section...]


Tip You can set the screen buffer size and window size to view the entire content of the help item.


Syntax Description

help

If you enter the help command without any arguments, Network Registrar displays a list of all the commands.

help command [section...]

If you specify the help command with a command name, Network Registrar displays the help page for the command of that name. Optionally, you can use the section attribute to limit the response to a specified section of the command message.

The section names are:

synopsis—Valid syntax for the command

description—Textual description of the command behavior

examples—Examples of the command usage

attributes—Descriptions of the attributes

status—Description of the status codes that this command returns

This example prints the synopsis section of the help file for the help command:

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

import

The import command imports DHCP lease data or a BIND named.boot file into the DNS server.

import keys file

import leases file

import named.boot file

import named.conf file


Note Use UNIX style pathnames even when running the import command on Windows.

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


Syntax Description

import keys file

Imports the keys file. The key import generates as many keys as it finds in the import file. For details on keys, see the "key" section.

import leases file

Imports the leases in the file to the DHCP server. The client is given the lesser of the lease times:

In the import file, or

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

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

If your import file specifies a DNS zone name, the server does not use the zone name when it updates DNS. If the file specifies a host name, the server uses the host name when updating DNS, unless the host name was overridden by a host-name specification in a client or client-class entry.

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

You can specify the namespace for imported leases at the end of each lease entry in the import file. The namespace must be predefined. See the "namespace" section. All leases without explicit namespace entries are assigned to the current (or global) namespace.

nrcmd> import leases LeaseIn 

import named.boot file

Imports the BIND 4.x.x named.boot file. This points the server to its database files, such as the /etc/named.boot file on UNIX or Windows.

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

import named.conf file

Imports the BIND 8 or BIND 9 named.conf file. This points the server to its database files, such as the /etc/named.conf file on UNIX or Windows.

nrcmd> import named.conf /etc/named.conf 

Related Commands

dhcp, export, scope, zone

key

The key command creates and manages transaction signature (TSIG) keys for dynamic DNS updates. TSIG security, as defined in RFC 2845, enables both DNS and DHCP servers to authenticate dynamic DNS updates. TSIG security uses the HMAC-MD5 (or keyed-MD5) algorithm to confirm the integrity of data transmitted over open networks between parties that share a common secret key. The DHCP server uses TSIG keys to create TSIG resource records while processing dynamic DNS updates.

To configure TSIG security on a DHCP server, you must first create a shared key, then enable dynamic DNS update for your scopes (by enabling the dynamic-dns attribute). Also, enable the dynamic-dns-tsig attribute for forward or reverse zones for the scope or on the server level.


Note The CLI does not propagate keys to both DHCP servers in a failover configuration. You must use the failover tool in the Web UI to do this.


key name create secret [attribute=value...]

key name delete

key name set attribute=value

key name unset attribute

key name get attribute

key name show

key list

key listnames

Syntax Description

See Table 2-20 for a description of key command attributes.

key name create secret [attribute=value...]

Creates a TSIG key by associating a key name with a shared secret value. RFC 2845 recommends that the name concatenate, in FQDN format, the names of the hosts using the key. Enter the shared secret value as base64-encoded. You can use the cnr_keygen utility to generate key secrets in this form (see the Network Registrar User's Guide for details).

nrcmd> key host-a.host-b.example.com. create 
	"xGVCsFZ0/6e0N97HGF50eg==" algorithm=hmac-md5 type=tsig time-skew=300s 

key name delete

Deletes the specified TSIG key.

key name set attribute=value...

Sets the value of an attribute for the specified TSIG key.

key name unset attribute

Unsets an attribute for the specified TSIG key.

key name get attribute

Gets the value of an attribute for the specified TSIG key.

key name show

Displays the attributes of the specified TSIG key.

key list

Lists all security keys and their attributes.

key listnames

Lists only the names of the TSIG keys.

Attributes

Table 2-12 describes the key command attributes.

Table 2-12 key Command Attributes

Attribute
Usage
Description

algorithm

set
get

Encryption algorithm used to sign messages. RFC 2845 and Network Registrar support HMAC-MD5 encryption only. Required, default hmac-md5.

secret

set
get

Shared secret used to encrypt the messages. Enter it in base64-encoded format. The longer the secret, the more secure the encryption. Required, no default.

security-type

set
get

Type of security used. RFC 2845 and Network Registrar support TSIG only. Required, default TSIG.

time-skew

set
get
unset

Number of seconds of error permitted in the signature time. This is the GMT that can elapse (+ or -) between when you add the TSIG record on the client side and when the server receives it. The shorter the time skew, the more secure the encryption. Optional, default five minutes (300s), with a range of one second (1s) to one hour (1h).

Note Ensure that the system clocks between the DNS and DHCP servers fall within the time skew period.


Related Commands

acl, dhcp, dns, export, scope, zone

ldap

The ldap command associates remote Lightweight Directory Access Protocol (LDAP) servers with Network Registrar and sets their attributes.

ldap server create hostname [attribute=value...]

ldap server delete

ldap server enable attribute

ldap server disable attribute

ldap server set attribute=value [attribute=value...]

ldap server unset attribute

ldap server get attribute

ldap server setEntry dictionary-attribute-key=value

ldap server unsetEntry dictionary-attribute-key

ldap server getEntry dictionary-attribute-key=value

ldap server [show]

ldap list

ldap listnames

Syntax Description

See Table 2-13 for the ldap command attributes and their descriptions.

ldap server create hostname [attribute=value...]

Creates a name entry for the LDAP server at the hostname (and optionally assigns values to its attributes). This example creates the LDAP server object myserver with a host name of myserver.mycompany.com:

nrcmd> ldap myserver create myserver.mycompany.com 

ldap server delete

Deletes the entry for an LDAP server.

nrcmd> ldap myserver delete 

ldap server enable attribute

Enables an LDAP server attribute. After you enable an attribute, you can set its values.

ldap server disable attribute

Disables an LDAP attribute.

ldap server set attribute=value [attribute=value...]

Sets one or more attributes for the LDAP server.

ldap server unset attribute

Unsets the value of an LDAP attribute.

ldap server get attribute

Displays the value of an attribute of the LDAP server.

ldap server setEntry dictionary-attribute-key=value

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

create-dictionary—Maps LDAP attributes to DHCP lease attributes. If an entry does not exist, this sets entries in this dictionary to the value of its corresponding DHCP lease attribute. Optional, no default.

create-string-dictionary—Maps LDAP attributes to user specified strings. If an entry does not exist, this sets entries in this dictionary to the matching string. Optional, no default.

env-dictionary—The server can retrieve additional LDAP attributes along with client attributes. If any of these are in a query's results, their values are made available to scripts through the request's environment dictionary. This keys the LDAP value by the value in the query env-dictionary. Optional, no default.

query-dictionary—Mapping between the names of LDAP attributes and DHCP attributes. The server tries to retrieve all the LDAP attributes specified in the dictionary. When a query succeeds, the server sets the values for any LDAP attributes that it returns in the corresponding client attribute. Optional, no default.

This attribute also controls the mapping of an LDAP attribute name to the embedded policy. The LDAP attribute name associated with the embedded-policy value is used to create an embedded policy. If the server finds the particular LDAP attribute name, it decodes the attribute data as if it were an encoding of the client-embedded policy. For details about LDAP configuration, see the Network Registrar User's Guide.

update-dictionary—Maps LDAP attributes to DHCP lease attributes. When an LDAP object is modified, each LDAP attribute present in this dictionary is set to the value of its corresponding DHCP lease attribute. Optional, no default.

ldap server unsetEntry dictionary-attribute-key

Unsets the value of a dictionary attribute. See the setEntry syntax description.

ldap server getEntry dictionary-attribute-key=value

Retrieves information from various dictionaries in the LDAP server configuration. See the setEntry syntax description.

ldap server [show]

Shows the values of the attributes of the named LDAP server.

ldap list

Lists the names of the remote LDAP servers and any attributes assigned to them.

ldap listnames

Lists just the names of the remote LDAP servers.

Attributes

Table 2-13 describes the ldap command attributes and their values and defaults, if any.

Table 2-13 ldap Command Attributes 

Attribute
Usage
Description

can-create

enable
disable
unset

Controls whether an LDAP server can create new entries to store lease state updates. Optional, default disable.

can-query

enable
disable
unset

Controls whether to use an LDAP server for client queries. Optional, default disable.

can-update

enable
disable
unset

Controls whether to use an LDAP server to store lease state updates. Optional, default disable.

connections

set
get
unset

The Network Registrar LDAP facility is multithreaded. Each LDAP object has a configurable number of connections associated with it. Network Registrar creates one thread for each connection configured in an LDAP object, and each thread can have a maximum of LDAP requests associated with its request queue (by enabling the limit-requests attribute and setting a max-requests attribute value). The connections attribute is primarily a performance tuning parameter. In some cases, more than one connection can improve overall throughput. The amount depends on the load on the LDAP server. With many applications using LDAP, five connections would be appropriate; with just Network Registrar using LDAP, 25 would be appropriate. Optional, default one connection.

create-object-
classes

set
get
unset

With the can-create attribute enabled, Network Registrar names of the object classes inherited by a newly created entry in the directory. Optional, no default.

default-attribute-
value

set
get
unset

String assigned to any LDAP attributes, listed in the create or update dictionaries, that do not have matching lease attributes. You can list these LDAP attributes in the create update dictionaries. If you omit a value, Network Registrar uses the string default. Optional, default default.

dn-attribute

set
get
unset

If the server can construct the distinguished name (DN) of the LDAP object to update (or create) from one of the lease attributes, it formats the specified dn-attribute using the dn-format string to construct the object filter that specifies the LDAP server to modify. Optional, no default.

dn-create-format

set
get
unset

Distinguished name (DN) for entry creation. A %s is required at the entry level and is replaced by the value of the dn-attribute. If you can construct the DN of the LDAP object created from one of the lease's attributes, the server formats the specified dn-attribute using the dn-format string. Optional, no default.

dn-format

set
get
unset

Formats the dn-attribute for entry modification. A %s is required at the entry level and is replaced by the value of the dn-attribute. If you can construct the DN of the LDAP object updated from one of the lease's attributes, the server formats the specified dn-attribute using the dn-format string to construct the query filter. Optional, no default.

hostname

set
get
unset

Host name of the LDAP server. Required for creation, no default.

limit-requests

enable
disable
unset

Controls whether to limit the number of outstanding queries on each LDAP client connection. Optional, default enable.

max-referrals

set
get
unset

Limits the number of LDAP referrals the server follows when querying. A value of zero (the default) means "do not follow referrals." Optional, default 0 referrals.

max-requests

set
get
unset

With ldap enable limit-requests, limits the number of outstanding queries of a single LDAP connection. You can improve performance (and avoid swamping the LDAP server) by limiting the number of outstanding queries. For example, if the LDAP server can handle only 100 requests, setting max-requests=20 with connections=5 might be appropriate. Adjust the parameters one at a time and monitor the results. Optional, default 20 requests.

password

set
get
unset

Password of a user with access to the parts of the directory that DHCP uses. (You can configure LDAP servers to allow anonymous access, so this is optional.) Optional, no default.

port

set
get
unset

Port on the remote LDAP server. Optional, no default.

preference

set
get
unset

Preferential order of LDAP servers, specified as a positive integer. 1 is the highest preference value. Optional, default value of 1.

referral-attr

set
get
unset

Name of the LDAP attribute that may indicate that an LDAP response is a referral. Optional, no default. The referral may or may not contain the DN for which to query:

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 the DN is not present, 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

set
get
unset

If the referral-attr 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. Optional, no default.

search-filter

set
get
unset

Search filter to apply in the client-entry query. The server formats the client's MAC address using the filter to specify the object that contains the client-entry data. An optional %s at the entry level is replaced by the value of the dn-attribute. Optional, no default.

search-path

set
get
unset

Name of an object in the directory to use as a query's starting point. Together, the search-path and search-scope attributes control the portion of the directory that the server searches. An optional %s at the entry level is replaced by the value of the dn-attribute. Optional, no default.

search-scope

set
get
unset

Scope of the search. Optional, default subtree. Can be one these values:

subtree—Server searches all the children of the search-path (default)

onelevel—Server only searches the immediate children of the base object

base—Server only searches the base object itself

threadwaittime

set
get
unset

If there are outstanding queries or updates, the interval (in milliseconds) at which each LDAP connection polls for results and processes queries, updates and creates. Optional, default 100 ms.

timeout

set
get
unset

Seconds that the DHCP server should wait for a response to an individual query. After a query times out, the server may retry another LDAP server connection or drop the query if there is no other connection. Note that timeout values for queries are smaller than those for updates. Optional, default 10 seconds. Note that a separate query-timeout attribute (at a lower visibility level) is set to 3 seconds by default for LDAP query operations.

update-search-
attribute

set
get
unset

If the DHCP server cannot directly determine the DN of the object to update, it must issue a query to retrieve the DN. In that case, the server uses data in the lease's search-attribute attribute and formats it using the update-search-filter attribute. Optional, no default.

update-search-
filter

set
get
unset

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

update-search-
path

set
get
unset

Starting point for the portion of the directory that contains the LDAP objects that the server updates. The update-search-path and the update-search-scope together control the portion of the directory that contains the objects to update. Optional, no default.

update-search-
scope

set
get
unset

The update-search-path and the update-search-scope together control the portion of the directory that contains the objects to update. Optional, no default. The scope can be:

subtree—Server searches all the children of the search-path

onelevel—Server only searches the immediate children of the base object

base—Server only searches the base object itself

username

set
get
unset

DN of a user with access to the parts of the directory that DHCP uses. (You can configure LDAP servers to allow anonymous access, so this is optional). Optional, no default.


Related Commands

dhcp

lease

Use the lease command to view and manipulate the current DHCP leases in the cluster. All lease command attributes are read-only, and all actions take effect immediately. The ipaddress value can be a simple IP address or can include the namespace, in the syntax namespacename/ipaddress. See the "namespace" section. You do not need to reload the server with this command.

lease ipaddress activate

lease ipaddress deactivate

lease ipaddress send-reservation

lease ipaddress delete-reservation

lease ipaddress force-available

lease ipaddress get-scope-name

lease ipaddress macaddr

lease ipaddress get attribute

lease ipaddress [show]

lease list

lease list -lansegment ipaddress mask

lease list -macaddr macaddress

lease list -subnet ipaddress mask

Syntax Description

See Table 2-14 for the lease command attribute descriptions.

lease ipaddress activate

Activates a lease, but does not change the state of a lease marked as unavailable. The ipaddress value can include the address' namespace, in this slash-separated format:

namespacename/ipaddress

If there is no namespace prefix for the address, the value set by the session set current-namespace applies. See the "session" section, or the global namespace if the current namespace is not set.

nrcmd> lease 192.168.1.9 activate 

lease ipaddress deactivate

De-activates a lease from being given out or renewed, but does not change the state of the lease.

lease ipaddress send-reservation

Sends an existing reservation to the server immediately without having to reload the server. Use this keyword in conjunction with the scope name addReservation command.

lease ipaddress delete-reservation

Deletes an existing reservation from the DHCP server immediately without requiring a server reload. To delete the lease from the internal nrcmd database, follow this command with the scope name removeReservation command.

lease ipaddress 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, ensure that, before you use the keyword, the client holding the lease stopped using the lease.

lease ipaddress get-scope-name

Shows the scope to which a lease belongs.

lease ipaddress macaddr

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

lease ipaddress get attribute

Gets the value of an attribute for a lease.

lease ipaddress [show]

Shows the lease attributes for a specific address.

lease list

Lists all the leases in all namespaces. Note that there is no namespace modifier for this command.

lease list -lansegment ipaddress mask

Lists all leases in a LAN segment, including all leases in primary scopes for the address and mask. It also includes all leases in secondary scopes whose primary scope matches the address and mask.

lease list -macaddr macaddress

Lists all leases associated with the specified MAC address. Examples of acceptable formats for the MAC address are:

1,6,00:d0:ba:d3:bd:3b

00:d0:ba:d3:bd:3b

00d0bad3bd3b

lease list -subnet ipaddress mask

Lists all leases in a subnet for the network address and mask.

Attributes

Table 2-14 describes the lease command attributes and their values. They are all read-only attributes.

Table 2-14 lease Command Attributes 

Attribute
Usage
Description

address

get

IP address of the lease.

client-binary-client-
id

get

Binary form of the client's MAC address, if any.

client-dns-name

get

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 attribute, but may not be identical due to name collisions in the DNS server database.

client-domain-name

get

Domain (if any) to which the client's DNS name belongs.

client-flags

get

The client-flags attribute value can be any of these 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 does not report it.

dns-update-pending—DNS operation is pending for this client.

in-limitation-list—The lease is presently in a limitation list using the limitation ID shown.

reverse-dns-up-to-date—The reverse (PTR record) DNS entry is current in the DNS database.

client-host-name

get

DNS name that the client requested the DHCP server place into the DNS server.

client-id

get

Client ID that the client specifies, or one that the DHCP server for this client synthesizes (if client-id-created-from-mac-address is set in the client-flags).

client-last-
transaction-time

get

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

client-mac-addr

get

MAC address that the client presented to the DHCP server.

client-os-type

get

Operating system of the leased client. This attribute is used only by the updateSms keyword and has no other purpose. If you enable failover, the main server transmits this value to the backup server. The syntax of this attribute's value is OS-name major.minor.

Other examples are: LANMAN Server, LANMAN Workstation, MAC OS, Microsoft Windows, Microsoft Windows 2000 Professional, Microsoft Windows 95, Microsoft Windows 9x, Microsoft Windows for Workgroups, Microsoft Windows NT Advanced Server, Microsoft Windows NT Server, Microsoft Windows NT Workstation 3.51, Microsoft Windows NT Workstation 4.0, Netware, and OS/2.

expiration

get

Date and time when the lease expires.

flags

get

Flags for the lease are backup, deactivated, dynamic, or reserved:

backup—The state for this lease was recorded by a server whose role was backup with respect to this lease.

deactivated—The lease is de-activated, which means that you should not use it. Any client that uses de-activated leases receives a NAK on its next renewal attempt.

dynamic—The lease was last written by a server that knew only about the lease because it was created by a send-reservation command.

reserved—The lease is reserved for some MAC address. The table that relates MAC addresses to leases is in the scope.

Flags can also include initialized, valid, and failover-updated.

lease-renewal-time

get

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

limitation-id

get

This value relates together leases for which there exists a maximum limit on the number of simultaneous active leases allowed. It is defined in the client or client-class.

namespace-id

get

Identifier for the namespace, if any.

relay-agent-circuit-
id

get

Accesses and manipulates the relay-agent circuit-id data as stored with a response's lease.

relay-agent-option

get

Contents of the relay agent information option from the most recent client interaction.

relay-agent-remote-
id

get

Accesses and manipulates the relay-agent-remote-id data as stored with a response's lease.

relay-agent-server-
id-override

get

IP address in the server-id-override suboption of the relay agent information option.

relay-agent-subnet-
selection

get

IP address in the subnet-selection suboption of the relay agent information option.

relay-agent-vpn-id

get

Contents of the vpn-id suboption of the relay agent information option. For a description of the VPN ID format, see Table 2-16.

start-time-of-state

get

Date and time when the state last changed to its current value. Use this attribute to determine when the lease was made unavailable.

state

get

Current state of the lease. This can be any of these:

available—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 did not renew the lease and it expired. Upon expiration, the DHCP server schedules the removal of the client's DNS information.

leased—Currently leased to the client whose information appears in the lease.

offered—Offered to the associated client. In many cases, the database is not written with information concerning offering a lease to a client, because there is no requirement to update stable storage with this information.

other-available—Used only when failover is enabled. A lease in this state is available for allocation by the other server in the failover pair, but not available for allocation by this server.

released—The client released the lease, but the server was configured to apply a release grace period. The lease is not available until the grace period expires.

pending-available—Used only when failover is enabled. A lease in this state is available as soon as this server can synchronize its available state with the other server.

unavailable—The lease is unavailable. It was made unavailable because of some conflict. A ping attempt might show that the IP address was already in use by another client, or the DHCP server might notice another DHCP server handing out this lease.

vendor-class-id

get

Client ID specified by the client.


Related Commands

dhcp, lease-notification, namespace, scope, session

lease-notification

Use the lease-notification command to receive notification about the number of available addresses in a scope. You can specify the notification limit either as the number of free addresses or the percentage of free addresses. You can also specify who should receive e-mail notification.

lease-notification available={number | percentage%}
[
config=config-file]
[
leasing-only]
[
recipients=recipient[,recipient] [mail-host=name [errors-to=recipient]]]
[
scopes={{scopename | address-range}[,scopename | address-range,....]}]
[
namespace=name]

Although you can use the lease-notification command interactively, its primary use is as an automated command.

Syntax Description

lease-notification available={number | percentage%}
[config=config-file]
[leasing-only]
[recipients=recipient[,recipient] [mail-host=name [errors-to=recipient]]]
[scopes={{scopename | address-range}[,scopename | address-range,...]}]
[namespace=name]

Table 2-15 describes the lease-notification keywords. Note that keywords and attributes associated with the recipients and scopes keywords apply only in connection with those keywords. This example specifies scope1 with an available value of 10% and e-mail recipients billy, joe, and jane:

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

To specify the range of scopes 192.68.1.0 to 192.68.1.255, the configuration file .nrNotification, the recipients administrator, an available value of 13 leases, and the Windows mail host as mailhost, enter:

nrcmd> lease-notification scopes=192.68.1.0-192.68.1.255 
	config=/home/bob/.nrNotification recipients=admin@comco.com available=13 
	mail-host=mailhost 


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


Table 2-15 lease-notification Command Keywords

Keyword
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 omit a configuration file, Network Registrar searches for the default .nrconfig file.

errors-to

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

leasing-only

If you specify leasing-only, Network Registrar displays only the scopes that can offer leases. If failover is enabled, this includes scopes for which one of these conditions applies:

The role is main and the failover state is NORMAL, COMM-INTERRUPTED, or PARTNER DOWN.

The role is backup and the failover state is COMM-INTERRUPTED or PARTNER DOWN.

mail-host

On Windows, you must specify a mail-host.

On UNIX, the mail host is generally already configured for the sendmail program. You can verify that your UNIX 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. If mail is not configured, you must specify a mail-host.

namespace

If you specify a namespace, you can enter the namespace name or the keywords all or global. The all keyword notifies of addresses in all the configured namespaces. The global keyword notifies of all addresses not in any specific namespace.

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 addresses. If you omit any scopes or addresses, Network Registrar checks all scopes that the specified cluster manages.


Related Commands

lease

license

The license command adds and distributes license keys across multiple Network Registrar servers. Keys are maintained in a separate license file (product.licenses in the installation's config subdirectory) so that you can easily redistribute keys to other servers by copying the file after the key is correctly entered into the first server. You must enter your license key the first time you configure any cluster.

Permanent license—You do not see the license message again unless you move your cluster to another machine.

Evaluation copy of Network Registrar—You have a license that expires.

Invalid or missing licensing key—You cannot configure or manage the Network Registrar servers. However, the servers themselves continue to function normally.

License expires in seven or fewer days—You see a warning when you start Network Registrar.

license set key=value

license get {expiration | key}

license [show]

Syntax Description

license set key=value

Legacy command that sets the key value for the license. Anyone can set the license key for the first time. Only the Web UI superuser, global administrator, or administrator set up with full access (using the admin name set nrcmd-flag=full command) can reset it. To set a new license key, run the nrcmd program in interactive mode, then exit and rerun the nrcmd program.

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

license get {expiration | key}

Gets the expiration or key values for the license, if you have permission to do so. If you are set up as with limited access (using the admin name set nrcmd-flag=limited command), you cannot set or get the attributes, except initially.

license [show]

Legacy command that shows the encrypted license key value.

Related Commands

admin

namespace

The namespace command creates, deletes, sets, and lists attributes for namespaces. A namespace distinguishes a set of DHCP server objects that are independent of otherwise identical objects in other namespaces. The DHCP server groups address blocks and their associated subnets, and scopes and their associated leases by namespace. A namespace has a descriptive name.

There are two ways to use namespaces:

Through address blocks—By creating subnets

Through scopes—By creating leases

In virtual private network (VPN) deployments, for example, you can create a namespace for each VPN, based on the vpn-id. The namespaces allow the DHCP server to distinguish among multiple instances of a single logical IP subnet when that subnet is used in multiple independent VPNs. The server also groups each lease in the subnet by namespace, so that the server can interact with clients on VPNs that use the same IP address space.

namespace name create id [attribute=value]

namespace name delete

namespace name set attribute=value

namespace name unset attribute

namespace name get attribute

namespace name [show]

namespace list

namespace listnames

Syntax Description

namespace name create id [attribute=value]

Creates a namespace using a unique name and unique namespace identifier. The namespace requires the name and an id. You cannot use the reserved words all or global for the namespace name.

The namespace can take two attributes, the VPN Routing and Forwarding instance (VRF) name and the VPN identifier (See Table 2-16). Network Registrar associates an incoming packet with the namespace if either the VRF name or VPN ID appears in the vpn-id option or vpn-id suboption (each can carry only one at a time in the packet).

You can change the namespace name using the set command, unless the namespace is the current namespace defined by the session set current-namespace command or the new name is not unique. You cannot change the namespace-id value. See the "session" section.

namespace name delete

Deletes a namespace.

namespace name set attribute=value

Changes the namespace name or sets one of the other attributes (see Table 2-16). You can change the namespace name only to another unique name. You cannot change the namespace-id value.

namespace name unset attribute

Unsets the value of an attribute.

namespace name get attribute

Gets the value of an attribute.

namespace name [show]

Shows the values of all attributes assigned to the namespace.

namespace list

Lists the namespaces and their properties.

namespace listnames

Lists just the names of all the namespaces.

Attributes

Table 2-16 describes the namespace command attributes and attribute=value pairs.

Table 2-16 namespace Command Attributes 

Attribute
Usage
Description

addr-blocks-
default-selection-
tags

set
get
unset

Specifies the default selection tag (or list of tags) that are associated with incoming subnet-allocation requests in this namespace that does not contain any subnet name data. Optional, no default.

addr-blocks-use-
client-affinity

enable
disable
unset

The DHCP server attempts to allocate subnets to clients using address blocks that the clients have already used. Use this parameter to disable that behavior, in which case the server supplies subnets from any address block that is suitable (based on other selection data in the clients' messages. Optional, no default.

addr-blocks-use-
lan-segments

enable
disable
unset

Controls whether DHCP subnet allocation uses the lan-segment attribute when configured on address blocks. Optional, no default.

addr-blocks-use-
selection-tags

enable
disable
unset

Controls whether the server compares incoming subnet allocation requests' subnet name data with each address block's selection tags. An address block is only considered if the two match. Optional, no default.

description

set
get
unset

Description for the namespace. Optional, no default.

id

create
set
get

Unique identifier for the namespace. Must be a positive number. Required, no default.

name

create
set
get
unset

Unique name string for the namespace; for example, Red or Blue. Required, no default.

vpn-id

set
get
unset

Unique identifier for the VPN associated with the namespace. The VPN identifier is in the format oui:index, such as a1:3f6c. It consists of a three-octet VPN authority organizationally unique identifier (OUI), assigned by the IEEE organization (RFC 2685), that corresponds to the VPN owner or ISP, followed by a colon, and a four-octet index number corresponding to the VPN serviced by the authority. DHCP and the Remote Authentication Dial-In User Service (RADIUS) use the VPN ID to identify a VPN. RADIUS can use it to assign dial-in users to the proper VPN, based on each user's authentication information. Optional, no default.

vrf-name

set
get
unset

Unique virtual routing forwarding (VRF) name, as derived from the relay agent router configuration. Optional, no default.


Related Commands

acl, scope, session, subnet

option-datatype

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


Note The option datatype name is not case-sensitive.


option-datatype name create

option-datatype name delete

option-datatype name defineField field position datatype [flags]

option-datatype name undefineField field

option-datatype name listFields

option-datatype name enable read-only

option-datatype name disable read-only

option-datatype name [show]

option-datatype list

option-datatype listnames

Syntax Description

option-datatype name create

Creates an option data type.

option-datatype name delete

Deletes an option data type.

option-datatype name defineField field position datatype [flags]

Defines a field of an option data type. Specifies the field name, numeric position among other fields, data type, and optional formatting flags. The attributes of this command are:

field—Name of the field to define or undefine in the option data type definition. Required, no default.

position—Position number of the field being defined in the option data type definition. Required, no default.

datatype—Currently supported DHCP option data type. This specifies the data type of the field being defined in the new option data type definition. It can be BOOL, BYTE, WORD, INT, UINT, STRING, IPADDR, BYTE_ARRAY, WORD_ARRAY, INT_ARRAY, UINT_ARRAY, or IPADDR_ARRAY. See Table 2-17. Required, no default.

flags—One or more comma-separated strings specifying formatting of the data type. Optional, no default.

The supported flags are:

little-endian—Lower-byte-first ordering, such as for Intel devices.

counted-array—Data in an array field is preceded by a byte that gives the length of the array. This is valid only for an array type, such as IPADDR_ARRAY.

exclude-from-dhcp-packet—Data to exclude in this field from the packet that the DHCP server sends the DHCP client.

option-datatype name undefineField field

Undefines a field name for an option data type.

option-datatype name listFields

Lists any fields defined for an option data type.

option-datatype name enable read-only

Prevents further changes to the definition of an option data type.


Note You should enable the read-only attribute for an option data type before using it in a vendor-option command.


option-datatype name disable read-only

Allows you to make changes to the definition of an option data type (the default).

option-datatype name [show]

Shows the attributes for an option data type.

option-datatype list

Lists the DHCP option data types and any attributes assigned to them.

option-datatype listnames

Lists just the names of the DHCP option data types.

Option Data Types

Table 2-17 lists the data type values that Network Registrar supports.

Table 2-17 Option Data Types 

Option Data Type
Datatype (Number)
Definition

boolean

BOOL (1)

TRUE or FALSE.

byte

BYTE (7)

8-bit unsigned integer.

byte array

BYTE_ARRAY (8)

Sequence of bytes represented in the form xx[:xx...] in which x is a hex character 0 through 9 or a through f. For example, to enter a series of four bytes containing the values 192, 168, 73 and 144, enter their hex values as c0:a8:49:90. Enter the ASCII string ABCijk123 as 41:42:43:69:6a:6b:31:32:33.

IP address

IPADDR (5)

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

IP address array

IPADDR_ARRAY (6)

Array of IP addresses.

signed array

INT_ARRAY (3)

Array of 32-bit signed integers.

signed integer

INT (2)

32-bit signed integer.

string

STRING (4)

ASCII text string.

unsigned array

UINT_ARRAY (12)

Array of 32-bit unsigned integers.

unsigned integer

UINT (11)

32-bit unsigned integer.

word

WORD (9)

16-bit unsigned integer.

word array

WORD_ARRAY (0)

Array of 16-bit unsigned integers.


Related Commands

vendor-option

policy

The policy command configures DHCP policy configurations. A policy is a collection of DHCP option values to associate with a range of addresses in a scope, or with a specific client or client-class configuration. Network Registrar considers policy reply options in a hierarchy of options. For details on these reply options, see the Network Registrar User's Guide.

The policy command can stand alone. You can explicitly create, list, or list names only for a policy. However, there are four additional policy object types that you indicate as hyphenated prefixes to the policy command—address-block-, client-, client-class-, and scope-.

For example, type-policy can be just policy, but can also be address-block-policy, client-policy, client-class-policy, or scope-policy.

policy name create [attribute=value...]

[type-]policy name delete

[type-]policy name enable attribute

[type-]policy name disable attribute

[type-]policy name set attribute=value [attribute=value...]

[type-]policy name unset attribute

[type-]policy name get attribute

[type-]policy name [show]

policy list

policy listnames

[type-]policy name setOption option value

[type-]policy name unsetOption option

[type-]policy name getOption option

[type-]policy name listOptions

[type-]policy name setVendorOption vendoroption suboption-syntax field value

[type-]policy name unsetVendorOption vendoroption suboption-syntax field

[type-]policy name getVendorOption vendoroption suboption-syntax field

[type-]policy name listVendorOptions [vendoroption]

[type-]policy name setLeaseTime value

policy default

[type-]policy [option] inhibit-all-renews

[type-]policy [option] inhibit-all-renews-at-reboot

Syntax Description

See Table 2-18 for the policy command attribute descriptions.

policy name create [attribute=value...]

Creates a policy (and optionally assigns attribute values).

nrcmd> policy CompanyB create 

[type-]policy name delete

Deletes a policy.

[type-]policy name enable attribute

Enables the attribute for a policy.

[type-]policy name disable attribute

Disables the attribute for a policy.

[type-]policy name set attribute=value [attribute=value...]

Sets an attribute to a value for a policy.

nrcmd> policy default set grace-period=3d 
nrcmd> address-block-policy 10.10.0.0/16 set offer-timeout=2m 
nrcmd> client-policy 1,6,00:d0:ba:d3:bd:3b set server-lease-time=5d 
nrcmd> client-class-policy CableModem set dhcp-reply-options=all-subnets-local 
nrcmd> scope-policy testScope set bootp-reply-options=time-offset 
nrcmd> dhcp reload 

[type-]policy name unset attribute

Unsets the value of an attribute for a policy. You cannot unset required attributes.

[type-]policy name get attribute

Gets the value of an attribute for a policy.

[type-]policy name [show]

Shows the values of all attributes assigned to a policy.

policy list

Lists all policies and any attributes assigned to them.

policy listnames

Lists the names of all policies.

[type-]policy name setOption option value

Sets the value of a standard DHCP option name to a value for a policy.

nrcmd> policy default setOption dhcp-lease-time 608400 

For a list of all the DHCP options that you can configure, use the help dhcp-option command.

[type-]policy name unsetOption option

Unsets the value of an option for a policy.

[type-]policy name getOption option

Gets the value of an option for the policy.

[type-]policy name listOptions

Lists the standard options in a policy.

nrcmd> policy default listOptions 
(51)dhcp-lease-time: 604800 

[type-]policy name setVendorOption vendoroption suboption field value
[type-]policy name setVendorOption vendoroption {suboption[index]} field value

Associates a vendor-supplied DHCP option (vendoroption) and its suboption with the policy and assigns a value to a field of the suboption. Use the suboption-index syntax when a suboption is an array that requires braces and square brackets.

You must create the name of the vendor option using the option-datatype and vendor-option commands before you can use it in the policy command.

[type-]policy name unsetVendorOption vendoroption suboption field
[type-]policy name unsetVendorOption vendoroption {suboption[index]} field

Deletes the association between the specified policy and a vendor-supplied DHCP option suboption field. Use the suboption-index syntax for arrays.

[type-]policy name getVendorOption vendoroption suboption-syntax field
[type-]policy name getVendorOption vendoroption {suboption[index]} field

Gets vendor-specific option data for the policy.

[type-]policy name listVendorOptions [vendoroption]

Lists data for all vendor options in a policy or, optionally, lists data for a specific vendor option.

nrcmd> policy 168.1-net listVendorOptions 

[type-]policy name setLeaseTime value

Sets the client lease time to value for a policy. The lease time is the value of the dhcp-lease-time DHCP option.

To view the lease time value, use the [type-]policy name listOptions command. The time is displayed in seconds.

Attributes

Table 2-18 describes the [type-]policy command attributes.

Table 2-18 policy Command Attributes 

Attribute
Usage
Description

allow-client-a-
record-update

enable
disable
unset

Allows the client to update the A record. If the client sets the flags in the FQDN option to indicate an A record update in the request, and if this attribute is enabled, the server allows the client to do the A record update. Otherwise, the server does the A record update based on other server configurations. Optional, default disable.

allow-dual-zone-
dns-update

enable
disable
unset

If enabled, the DHCP server returns the client-fqdn option (81) so that the client can perform an A record update itself. Also, the server performs an A record update on the client's behalf. This is required to support certain DHCP deployments that represent their clients in two DNS zones. If both the allow-client-a-record-update and allow-dual-dns-update attributes are enabled, the latter takes precedence. Optional, default disable.

allow-lease-time-
override

enable
disable
unset

Clients can request a specific lease time. If this attribute is disabled, the server does not honor requested lease times longer than the server's normal lease time. Optional, default enable.

bootp-reply-
options

set
get
unset

List of names of options to return in any replies to BOOTP clients. You do not need to configure the options themselves in the same policy as the reply-options list; the server searches the hierarchy of policies for each option named in the list. Optional, no default.

dhcp-reply-
options

set
get
unset

List of names of options to return in any replies to DHCP clients. You do not need to configure the options themselves in the same policy as the reply-options list; the server searches the hierarchy of policies for each option named in the list. Optional, no default.

giaddr-as-
server-id

enable
disable
unset

Causes the DHCP server to set the server-id option on a DHCPOFFER and DHCPACK to the giaddr of the incoming packet, instead of the address of the server (which is the default). All unicast renews are then sent to the relay agent instead of directly to the DHCP server, and so renews arrive at the DHCP server with option 82 (relay-agent-info) data appended to the packet. Some relay agents may not support this capability and in some complex configurations the giaddr may not actually be an address to which the DHCP client can unicast a packet. In these cases, the DHCP client cannot renew a lease, and always performs a rebinding operation (where the client broadcasts instead of unicasting a request to what it believes is the DHCP server). Optional, default disable.

grace-period

set
get
unset

Time, in seconds, between the expiration of a lease and the time it is made available for re-assignment. Optional, default 300 seconds (five minutes).

inhibit-all-
renews

enable
disable
unset

Causes the server to reject all renewal requests and forces the client to obtain a new address whenever it contacts the DHCP server. Optional, default disable.

inhibit-renews-
at-reboot

enable
disable
unset

Allows clients to renew their leases, but forces them to obtain new addresses each time that they reboot. Optional, default disable.

limitation-count

set
get
unset

Sets the number of clients with identical limitation keys that are allowed to access your network. Supply an integer value greater than zero (0). The limitation-id attribute is set using the client command. See the "client" section.

offer-timeout

set
get
unset

The time, in seconds, that the server waits to re-offer a lease if a client does not accept it. Optional, default 120 seconds (two minutes).

packet-file-name

set
get
unset

Name of the boot file for a client's boot process. The server returns this filename in the file field of its replies. Optional, no default, but cannot be longer than 127 characters. This attribute can also contain these variable substitution values:

%@docsis-vers%—If you specify the DOCSIS version value, the server substitutes it with the version presented in the DHCP request packet's vendor-class-identifier option. This version can be either docsis1.0 or docsis1.1. If the vendor-class-id option is missing or does not contain a DOCSIS version string, the server substitutes the docsis-version-id-missing string. See Table 2-6.

%@mac-addr%—If you specify the MAC address value, the server substitutes this string with the source MAC address as presented in the DHCP request packet.

packet-server-
name

set
get
unset

Host name of a server to use in a client's boot process. The server returns this host name in the sname field of its replies. Optional, no default, but cannot be longer than 64 characters.

packet-siaddr

set
get
unset

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

permanent-leases

enable
disable
unset

When enabled, grants permanent leases to clients. Optional, default disable.

server-lease-time

set
get
unset

Time that the server believes the lease is valid. It may help for the server to consider leasing for a longer period than the client requests so as to get more frequent client communication, along with the stability of long lease times. This value is not used unless it is longer than the lease time in the dhcp-lease-time option found through the normal traversal of policies. Optional, no default.

split-lease-times

enable
disable
unset

Controls whether the server uses the value of the server-lease-time attribute to determine the length of a lease, rather than using the lease time returned to the client. Optional, default disable.

unavailable-
timeout

set
get
unset

Controls the time that a lease remains unavailable before it becomes available again. Optional, default 86400 seconds (one day).


Related Commands

admin, client-class, client-class-policy, client-policy, dhcp, scope, scope-policy, vendor-option

quit

The quit command writes all unsaved changes to the database and then terminates the current nrcmd session. If Network Registrar cannot save your changes, it displays an error code. The exit command is equivalent to the quit command.

quit

exit

Related Commands

exit, save

remote-dns

The remote-dns command controls the behavior of the DNS server when it is communicating with other DNS servers. Use it either to control incremental zone transfers or send multiple records per transmission control protocol (TCP) packet.

remote-dns ipaddress[/maskbits] create [ixfr={true | false} | multirec={true | false}]

remote-dns ipaddress[/maskbits] delete

remote-dns ipaddress[/maskbits] enable {ixfr | multirec}

remote-dns ipaddress[/maskbits] disable {ixfr | multirec}

remote-dns ipaddress[/maskbits] unset {ixfr | multirec}

remote-dns ipaddress[/maskbits] [show]

remote-dns list

remote-dns listnames

Syntax Description

remote-dns ipaddress[/maskbits] create [ixfr={true | false} | multirec={true | false}]

Creates a remote DNS server description. See the enable syntax description for the optional attributes. This example creates the remote server description 192.168.1.1 with the net mask of 255.255.0.0:

nrcmd> remote-dns create 192.168.1.1/16 


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


remote-dns ipaddress[/maskbits] delete

Deletes a remote DNS server description.

remote-dns ipaddress[/maskbits] enable {ixfr | multirec}

Enables incremental zone transfers (IXFRs), multiple records, or both for a remote DNS server.

ixfr—Whether a foreign server supports incremental transfer and to query it 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. Optional, initial default disable.

multirec—Whether to send a remote server zone transfers (AXFR) with multiple records in one TCP packet. Older DNS servers crash when they receive such transfers, despite being allowed by the protocol. Optional, initial default disable.

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 attribute to specify a group of servers with a single command.

This example enables all DNS servers on this network to perform incremental transfer:

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

This example disables incremental transfers on all DNS servers on this network:

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

remote-dns ipaddress[/maskbits] disable {ixfr | multirec}

Disables incremental zone transfers or multiple records for a remote DNS server. See the enable syntax description.

remote-dns ipaddress[/maskbits] unset {ixfr | multirec}

Unsets the incremental zone transfers or multiple records attribute for the remote DNS server.

remote-dns ipaddress[/maskbits] [show]

Shows the attributes for the remote DNS server.

remote-dns list

Lists all remote DNS server descriptions and any attributes assigned to them.

remote-dns listnames

Lists just the names of the remote DNS servers.

Related Commands

dns, server

report

The report command produces a summary of dynamic and static IP address use for one or more clusters.

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

Syntax Description

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

When you use the report command with no keywords, it creates a report of static DNS addresses and dynamic DHCP addresses for the cluster on which it is running and sends the report to standard output. You can limit the report, redirect it to a file, and change its column delimiters by using the keywords. Table 2-19 describes the report command attributes.


Note If successful, the report command prints "100 Ok" both before and after Network Registrar lists the addresses. The first "100 Ok" means that the command is being processed (without errors). The second "100 Ok" indicates that the command processing completed successfully.


Table 2-19 report Command Keywords 

Keywords
Description

column-
separator

Character string that you want the report to use between the columns. The default is a single space. If you specify whitespace, you must precede it with a backslash (\) and, if entering it on the command line, use quotation marks. For example: "\ ".

config

File in which you can specify multiple clusters.

dhcp-only

Summary of just the DHCP information.

file

Filename to which the report command writes the output. If you omit a filename, the report command appears on the screen. Because it can take a long time to collect DNS data, you should not run the report command interactively when requesting DNS summaries.

leasing-only

Only scopes that can offer leases should appear in the report. If failover is enabled, this includes scopes for which one of these conditions applies:

The role is main and the failover state is NORMAL, COMMUNICATION-INTERRUPTED, or PARTNER DOWN.

The role is backup and the failover state is COMM-INTERRUPTED or PARTNER DOWN.

mask-bits

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.

namespace

If you specify a namespace, you can enter its name or the keyword global. This reports on addresses in a specific namespace, or those in the global, unspecific namespace.


Related Commands

export

save

The save command validates and saves your changes to the database.

save

Related Commands

server

scope

The scope command creates and edits DHCP scopes.

scope name create addr mask [attribute=value...]

scope name delete

scope name enable attribute

scope name disable attribute

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

scope name unset attribute

scope name get attribute

scope name [show]

scope list

scope listnames

scope name listLeases

scope name changeMask netmask

scope name clearUnavailable

scope name addRange start end

scope name removeRange start end

scope name listRanges

scope name addReservation ipaddr macaddr

scope name removeReservation {ipaddr | macaddr}

scope name listReservations

Syntax Description

See Table 2-20 for the scope command attribute descriptions.

scope name create ipaddress mask [attribute=value...]

Creates a scope (and optionally sets an attribute). Specify the scope mask in base-10 (such as 255.255.255.0), not in hexadecimal.

nrcmd> scope testscope create 192.168.1.0 255.255.255.0 

scope name delete

Deletes a scope.

scope name enable attribute

Enables an attribute for a scope.

nrcmd> scope testscope enable dynamic-dns 

scope name disable attribute

Disables an attribute for a scope.

nrcmd> scope testscope disable dynamic-bootp 

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

Sets one or more attributes for a scope.

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

scope name unset attribute

Unsets an attribute for a scope. You cannot unset required attributes.

scope name get attribute

Gets the value of an attribute for a scope. This example gets the DNS zone name:

nrcmd> scope testscope get dns-zone-name 

scope name [show]

Shows the values of all attributes assigned to a scope.

scope list

Lists all scopes and any attributes assigned to them.

scope listnames

Lists just the names of scopes.

scope name listLeases

Lists the leases in a scope. This list can be very long.

scope name clearUnavailable

Clears the unavailability of leases in a scope to make them all available.

scope name changeMask netmask

Changes the network mask of a scope.

nrcmd> scope testScope changemask 255.255.254.0 

scope name addRange start end

Adds a range of addresses to a scope. The start and end values can be host numbers or IP addresses. Host numbers are relative to the initial address in the subnet defined by the scope, and full IP addresses must fall within this subnet. If the combined ranges are contiguous, Network Registrar merges them, if possible.

nrcmd> scope testScope addRange 192.168.1.10 192.168.1.20 
nrcmd> scope testScope addRange 10 20 

scope name removeRange start end

Removes a range of available addresses in a scope, specified by start and end addresses. If removing a range breaks the address continuity, Network Registrar splits the ranges.

nrcmd> scope testscope removeRange 192.168.1.10 192.168.1.15 

scope name listRanges

Lists the available addresses in a scope.

scope name addReservation ipaddr macaddr

Adds a reservation to a scope.

nrcmd> scope testScope AddReservation 192.168.1.10 1,6,00:d0:ba:d3:bd:3b 


Tip You can use the lease name send-reservation command to send the reservation immediately to the server without reloading it. For more information, see the "lease" section.


scope name removeReservation {ipaddress | macaddress}

Removes a reservation from a scope. Specifying the MAC address or IP address of the client.

nrcmd> scope testscope removeReservation 192.168.1.10 

scope name listReservations

Lists the reservations in a scope.

Attributes

Table 2-20 describes the scope command attributes and their values and defaults, if any.

Table 2-20 scope Command Attributes 

Attribute
Usage
Description

addr

show

Address of the subnet for which this scope contains addresses. Read-only.

bootp

enable
disable
unset

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. Optional, default disable.

deactivated

enable
disable
unset

A scope that does not extend leases to clients. It treats all of the addresses in its ranges as if they were individually de-activated. Optional, no default.

dhcp

enable
disable
unset

Controls whether the DHCP server does accept DHCP requests for this scope. Disable DHCP for a scope to use the scope for BOOTP exclusively, or to temporarily de-activate it. Optional, default enable.

dns-host-bytes

set
get
unset

Number of the bytes in a lease's IP address to use when forming in-addr.arpa names. The server forms names in the in-addr.arpa zone by prepending these bytes of the address (in reverse order) to the reverse zone name. If unset, the server synthesizes an appropriate value based on the scope's subnet size. Optional, no default.

dns-reverse-
zone-name

set
get
unset

Name of the inverse (in.addr.arpa) zone that is updated with PTR and TXT records. Optional, no default.

dns-rev-server-
addr

set
get
unset

Address of the reverse DNS server for the zone into which the server should add PTR records. Optional, no default.

dns-server-addr

set
get
unset

IP address of the primary DNS server on which the forward zone resides. Optional, no default.

dns-zone-name

set
get
unset

Name of the DNS zone to which to add a DHCP client's host (A record). Optional, no default.

dynamic-bootp

enable
disable
unset

Controls whether the server accepts dynamic BOOTP requests for this scope. Dynamic BOOTP requests are BOOTP requests that do not match a reservation, but can come from the available lease pool. To use this attribute, you must also enable bootp. Optional, default disable.

dynamic-dns

enable
disable
unset

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

dynamic-dns-
fwd-key

set
get
unset

TSIG key to process forward zone dynamic DNS updates for all leases in the scope. Overrides the server setting unless dynamic-dns-tsig is set to use-server-settings. Optional, no default.

dynamic-dns-
rev-key

set
get
unset

TSIG key to process reverse zone dynamic DNS updates for all leases in the scope. Overrides the server setting unless dynamic-dns-tsig is set to use-server-settings. Optional, no default.

dynamic-dns-
tsig

set
get
unset

Enables or disables TSIG for forward or reverse zone updates. Optional, default use-server-settings. See the "key" section.

enable-fwd-rev—Enable TSIG for forward and reverse zone updates

disable-fwd-rev—Disable TSIG for forward and reverse zone updates

enable-fwd-only—Enable TSIG for forward zone updates only

enable-rev-only— Enable TSIG for forward zone updates only

use-server-settings—Uses the DHCP server setting as the default (the default). Note that the server setting defaults to disable-fwd-rev.

embedded-
policy

get

Embedded policy for the scope. Read-only. This attribute gets its value from the scope-policy command.

failover

set
get
unset

Controls whether the scope should participate in failover, with three possible values:

scope-enabled

scope-disabled

use-server-settings (default)

See the Network Registrar User's Guide for the failover property states. Optional, default is use-server-settings (dhcp enable/disable failover).

failover-backup-
percentage

set
get
unset

Percentage of available addresses that the main server should send to the backup server. If defined for a scope, you must define it for the scope in the main server. If defined in a backup server, it is ignored (to enable copying of configurations). The value overrides the server values for failover-backup-percentage and failover-dynamic-bootp-backup-
percentage
, and the value defined here is used for this scope, whether or not this scope supports dynamic BOOTP. If defined as zero (0), no addresses go to the backup server. Because zero is a significant value, once defined, you must unset this attribute for the scope to use the server default values for failover-backup-percentage or failover-dynamic-bootp-backup-
percentage
. Optional, no default.

failover-backup-
server

set
get
unset

String representing the DNS name of the backup server associated with this LAN segment. If the DNS name resolves to the IP address of the current server, then this server operates as the backup server for this scope. It is an error if the names of both the main and backup server resolve to the IP addresses that reside on the same server. If the failover- main-server is set to "local" or is not configured on this scope or in the server-wide default, this server is considered to be the main server for the scope. Optional, no default.

failover-main-
server

set
get
unset

String representing the DNS name of the main server associated with this LAN segment. If the DNS name resolves to the IP address of the current server, then this server operates as the main server for this scope. It is an error if the names of both the main and backup server resolve to the IP addresses that reside on the same server. If you do not configure the backup server on this scope or in the server-wide default, then this server is the main server for this scope. If the failover-backup-server is set to "local" or is not configured on this scope or in the server-wide default, this server is considered to be the main server for the scope. Optional, no default.

ignore-declines

enable
disable
unset

Determines whether the scope should turn off recognition of server lease declines. Optional, no default.

mask

show

Mask associated with the scope's subnet address. Read-only.

namespace

set
get
unset

A "virtual" property. You can set the namespace of a scope by setting this attribute instead of the namespace-id attribute. When you set this attribute, the namespace ID of that namespace becomes the namespace-id attribute value. You can also get the namespace of a scope and it returns the name of the namespace associated with the current namespace-id. No default.

namespace-id

set
get
unset

ID of the namespace in which the addresses in the scope reside. You must define the namespace using the namespace name create id command. See the "namespace" section. If unset, the ID of the global namespace is used. Optional, default is the current namespace.

ping-clients

enable
disable
unset

Controls whether the server should attempt to ping an address. If enabled, also indicate a ping timeout. Optional, default disable.

ping-timeout

set
get
unset

The number of milliseconds that the DHCP server should wait for ping responses. If you make this value too large, you slow down the lease offering process. If you make this value too small, you reduce the effectiveness of pinging addresses before offering them. Three hundred milliseconds is a frequent compromise. Optional, default 300 ms.

policy

set
get
unset

Name of the policy associated with the scope. Required, default is default policy. This means that the scope uses all the properties set in the default policy (including the lease time), unless specifically reset.

primary-addr

get

IP address of the primary scope for a secondary scope. Read-only.

primary-mask

get

Subnet mask of a secondary scope's primary scope. Read-only.

primary-scope

set
get
unset

Primary scope for a secondary scope. Setting the value of this attribute on a scope designates the scope as being secondary to another scope. You must 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. To remove the status of secondary from the scope (that is, promote it to being a primary scope), you must unset this attribute. Optional, no default.

primary-subnet

set
get
unset

Subnet address and mask of the scope's primary scope, used when multiple logical IP subnets are present on the same physical network.

renew-only

enable
disable
unset

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 does not change the client associated with any of its leases, other than to allow a client currently using an available IP address to continue to use it. Optional, no default.

selection-tags

set
get
unset

Comma-separated list of selection criteria associated with a scope. The scope compares a client's selection criteria to this list to determine whether the client can obtain a lease from the scope. Optional, no default.

subnet

set
get

Network address of the IP subnet represented by the scope. Required, no default.

synthesize-name

enable
disable
unset

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

synthetic-name-
stem

set
get
unset

Prefix of the default host name to use if clients do not supply host names. Optional, no default.

trap-free-
address-high

enable
disable
unset

Controls whether you set a trap on the scope to alert you when the number of free addresses gets high. When a scope is created, the trap-free-address-high attribute is enabled. Also, the trap-free-address-low, trap-free-address-low-threshold and trap-free-address-high-threshold attributes are undefined. See the "trap" section. See also the trap-free-address-high-threshold attribute. Optional, default enable.

trap-free-
address-high-
threshold

set
get
unset

Number or percentage threshold for the free-address trap on this scope. Percentages must be followed by a (%) sign.The high threshold must be greater than or equal to the low threshold. See the "trap" section. See also the trap-free-address-high attribute. Optional, no default.

trap-free-
address-low

enable
disable
unset

Controls whether you set a trap on the scope to alert you when the number of free addresses gets low. See the "trap" section. See also the trap-free-address-low-threshold attribute. Optional, no default.

trap-free-
address-low-
threshold

set
get
unset

Number or percentage threshold for the free-address trap on this scope. Percentages must be followed by a (%) sign. The low threshold must be less than or equal to the high threshold. See the "trap" section. See also the trap-free-address-low attribute. Optional, no default.

update-dns-first

enable
disable
unset

Controls whether the DNS server is updated before the lease is granted. Optional, default disable.

update-dns-for-
bootp

enable
disable
unset

If the server replies to a BOOTP request and offers a lease from a scope that is configured to perform DNS updates, it checks this attribute before beginning the DNS update. This attribute prevents DNS updates for BOOTP clients while allowing updates for DHCP clients. You can also control this attribute globally using the dhcp enable/disable update-dns-for-bootp command, but the scope setting overrides it. Optional, no default.


Related Commands

admin, client-class, client-class-policy, client-policy, dhcp, policy, scope-policy, scope-selection-tag

scope-policy

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

The DHCP server implicitly creates and deletes embedded scope-policies when you create or delete the corresponding scopes. You manipulate the scope-policy using the name of the corresponding scope.

For the syntax and descriptions, see the "policy" section.

Attributes

See Table 2-18 for the attribute descriptions.

Related Commands

client-policy, client-class, client-class-policy, policy, scope

scope-selection-tag

The scope-selection-tag command defines the tags that you add for the scope selection criteria for scopes, clients, and client-classes.


Note Creation of scope selection tags is no longer required for Network Registrar 6.0.


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 tags defined for the scopes on this network. If the client entry refers to tags that are not present in any scope in the network, the server handles the tags depending on whether the reference is to include or exclude tags. If the reference is for exclusion, the tags have no effect. If the tags are not present and the reference is for inclusion, the server determines that there is no acceptable scope on that network for this client.

scope-selection-tag name create

scope-selection-tag name delete

scope-selection-tag list

Syntax Description

scope-selection-tag name create

Creates a scope-selection tag.

nrcmd> scope-selection-tag internal create 

scope-selection-tag name delete

Deletes a scope-selection tag.

nrcmd> scope-selection-tag internal delete 


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


scope-selection-tag list

Lists all scope-selection tags.

nrcmd> scope-selection-tag list 

Related Commands

admin, client-class, client-class-policy, dhcp

server

The server command affects the behavior of the DNS, DHCP, or TFTP server. Any time you change the server configuration, use the reload command or the Network Registrar GUI to reload the server.


Timesaver The server keyword is optional. You can enter all these commands starting with just the server type.


[server] {dns | dhcp | tftp} enable [start-on-reboot]

[server] {dns | dhcp | tftp} disable [start-on-reboot]

[server] {dns | dhcp | tftp} start

[server] {dns | dhcp | tftp} stop

[server] {dns | dhcp | tftp} get version

[server] {dns | dhcp | tftp} getHealth

[server] {dns | dhcp | tftp} getStats

[server] {dns | dhcp | tftp} reload

[server] dhcp getRelatedServers [column-separator=string]

[server] dhcp setPartnerDown partner-server [date]

[server] dhcp updateSms [all]

[server] {dns | dhcp | tftp} serverLogs nlogs=value logsize=value

[server] {dns | dhcp | tftp} serverLogs [show]

[server] {dns | dhcp | tftp} setDebug category=level [output]

[server] {dns | dhcp | tftp} unsetDebug

Syntax Description

The syntax descriptions use the convention {dns | dhcp | tftp} to indicate that you can use the command with the DNS, DHCP, or TFTP servers. There are no attributes other than those specified in the syntax. You can omit the server keyword in each case.

[server] {dns | dhcp | tftp} enable [start-on-reboot]

Enables a server. With the start-on-reboot attribute, the Server Agent starts the server when you reboot. You might want to disable this for clusters that provide a single protocol service. By default, the DNS and DHCP servers are enabled, while the TFTP server is disabled, to start on reboot.

[server] {dns | dhcp | tftp} disable [start-on-reboot]

Disables a server or the optional start-on reboot attribute. See the enable syntax.

nrcmd> dns disable start-on-reboot 

[server] {dns | dhcp | tftp} start

Starts a server DNS, DHCP, or TFTP server.

[server] {dns | dhcp | tftp} stop

Stops a server (DNS, DHCP, or TFTP). This does not terminate the server process, but stops it from handling further requests.

[server] {dns | dhcp | tftp} get version

Gets the version number of the server software. Useful when describing version information to the Cisco Technical Assistance Center (TAC).

[server] {dns | dhcp | tftp} getHealth

Gets the current health of a server. 0 indicates that the server is not running. 1 through 10 indicate how well the server is running—10 indicates the highest health. The DNS and TFTP server return values of either 0 or 10. If there is an incremental drop in the server health value, look at the log files for the server as the best indication of health.

[server] {dns | dhcp | tftp} getStats

Gets a server's current statistics.

[server] {dns | dhcp | tftp} reload

Stops and immediately restarts the server. When the server restarts, it rereads all of its configuration information and its previously saved state information and then begins operating.

[server] dhcp getRelatedServers [column-separator=string]

Gets the status of the connection between the DHCP server and its DNS, LDAP, or failover servers. You can optionally specify that the report use string for column separators.

[server] dhcp setPartnerDown partner-server [date]

Notifies the DHCP server that its partner DHCP server is down and moves all appropriate scopes into the PARTNER-DOWN state. Optionally, you can specify the date and time when the partner was last known to operate. The default is the current date.


Caution Ensure that the partner server is really down before using the setPartnerDown keyword.

[server] dhcp updateSms [all]

Causes the DHCP server to perform System Management Server (SMS) network discovery. Optionally, including all sends out all leased addresses from the DHCP server to SMS. Omitting all sends only those addresses leased since the last time you used this command.

[server] {dns | dhcp | tftp} serverLogs nlogs=value logsize=value

Sets or changes nlogs, the number of server logs, and logsize, the size of the server logs in bytes for a server. Valid values for nlogs are 2 through 100. The value of logsize is in bytes, and the optional K and M suffixes scale the specified value by 1000 or 1,000,000, respectively. Valid values for logsize are 10000 through 500000000 (or 10K through 500M) bytes. This example sets the DNS server to generate up to seven log files of five million bytes each. Restart the AIC Server Agent for the changes to take effect:

nrcmd> dns serverLogs nlogs=7 logsize=5M 
nrcmd> exit 
(UNIX)> /etc/init.d/aicservagt start 
(Windows)> net start "AIC Server Agent 2.0" 

[server] {dns | dhcp | tftp} serverLogs [show]

Displays the number and size of log files.

[server] {dns | dhcp | tftp} setDebug category=level [output]

Sets the debugging level and debug message output location. See Table 2-21 for the most commonly used server debug category codes and levels. The debug details increase as you increase the level number. The valid output values are MLOG (the default), FILE file, and WINDOW. If you reload the DNS server after enabling the debug settings through the GUI, Network Registrar disables debug. You must re-enable the debug setting.

nrcmd> server dhcp setDebug VX=1 FILE c:\debugfile.txt 


Note Setting the debug level can have a serious impact on your system performance. Contact the Cisco Technical Assistance Center (TAC) first before using it.


[server] {dns | dhcp | tftp} unsetDebug

Unsets debugging for the server.

Table 2-21 Server Debug Category Codes 

Server
Category
Level
Description

DNS

D

1-6

Server initialization, forwarding, server generated queries, incremental and full zone transfer requests and responses.

 

U

1-2

Dynamic DNS updates.

 

N

1-5

NOTIFY packets.

 

P

2-3

DNS packets.

DHCP

VX

1

Incoming and outgoing detailed packet tracing.

 

KP

1-9

Dynamic DNS update packet tracing and full details on all messages to and from LDAP, including all attribute values.

 

Q

1-9

Quality-of-service tracing.

 

Y

1-4

Failover tracing.

TFTP

E

1-5

CSRC 1.0 extension object.

 

F

1-5

File handling.

 

C

1-5

Server configuration.

 

S

1-5

TFTP session handling.

 

D

1-5

Statistics.

 

P

1-5

Packet handling.

 

T

1-5

Timer handling.


Related Commands

dns, dhcp, tftp

session

The session command sets session control parameters on your CLI command session.

The session assert functionality allows a nrcmd batch script to assert that a given condition is true. If the condition is true, the command has no effect, but if it is not true, the nrcmd exits at that point. Some uses for the session assert functionality are to ensure that the nrcmd session has an exclusive lock on the Network Registrar database, or to ensure that server configuration data has or has not changed since a previous point.

session set default-format={user | script}

session set current-namespace=name

session unset current-namespace

session set visibility={5 | 3 | 1}

session get {cluster | default-format | user-name | visibility}

session [show]

session cache {refresh | clear}

session assert server.dbsn == server-version-minor-serial-number

session assert server.dbsn != server-version-minor-serial-number

session assert locked

Syntax Description

session set default-format={user | script}

Sets the default format for the CLI session, either user or script:

user—Show objects in a user-readable format, one attribute per line (the default)

script—Show objects in script-suitable format, one object per line

The default is user format. This example sets the output for script processing:

nrcmd> session set default-format=script 

session set current-namespace=name

Sets the namespace for the session. Use this command to set the default namespace when there is a namespace expected for a CLI command, but that command does not have an explicit entry for the namespace, you cannot explicitly enter it for the command. If you do not use this command, Network Registrar uses the global namespace.The namespace value can either be a namespace name or its ID. Network Registrar reserves the namespace values all (refers to all namespaces, including global) and global (there is no namespace associated with the DHCP server objects). If the string matches an already defined namespace name, Network Registrar considers it a namespace name. Otherwise, Network Registrar considers it a namespace ID and the CLI tries to convert it into a namespace ID number. See the "namespace" section.

session unset current-namespace

Equivalent of the session set current-namespace="" command.

session set visibility={5 | 3 | 1}

Sets the session visibility, or what verbosity of attributes you can set or display for the session. A value of 1 gives the highest visibility. The default session visibility is 5. You cannot unset the visibility attribute.


Caution Do not change the default session visibility of 5 unless directed to do so by the Cisco Technical Assistance Center (TAC).

session get {cluster | default-format | user-name | visibility}

Displays the cluster, default format, username, or visibility for the session.

session [show]

Shows the values of all attributes assigned to the CLI session.

session cache {refresh | clear}

The CLI caches many configuration objects that it reads. If multiple users are making changes simultaneously, one CLI instance might have cached an out of date version of an object. The session cache refresh command causes the CLI to clear its local cache of all unmodified objects, forcing it to reread objects from the configuration database. The session cache clear command forces the CLI to clear all cached data, whether or not unsaved changes were made.

session assert server.dbsn != server-version-minor-serial-number

Asserts that a specific server's configuration data changed. Scripts use this command to get updates on changes to the Network Registrar server configuration data.

nrcmd> session assert dhcp.dbsn != 42 

The following script emits the list of scopes, and the new DHCP server DBSN value only if the value changes from 110. It assumes that the output from this script is parsed by an external process that is trying to keep the list of scopes up-to-date with Network Registrar.

session assert dhcp.dbsn != 110 

session assert locked

Use this command before any CLI commands that require a lock on the session. If any of the commands that follow require a lock, the CLI session exits.

subnet

Use the subnet command to view and manipulate the current DHCP subnets the server creates with the address-block command. All subnet command actions take effect immediately. The ipaddress value can be a simple IP address or can include the namespace in the syntax namespacename/ipaddress. See the "namespace" section. You do not need to reload the server.

subnet ipaddress/mask activate

subnet ipaddress/mask deactivate

subnet ipaddress/mask force-available

subnet ipaddress/mask get attribute

subnet ipaddress/mask [show]

subnet list

Syntax Description

See Table 2-22 for the subnet command attributes and their descriptions.

subnet ipaddress/mask activate

Activates a subnet, but does not change the status of a subnet marked as unavailable. The ipaddress/mask value can include the namespace, in this slash-separated format:

namespacename/ipaddress/mask

If there is no namespace prefix for the address, the value set by the session set current-namespace applies. See the "session" section.

nrcmd> subnet 192.168.1.9 activate 

subnet ipaddress/mask deactivate

De-activates a subnet from being given out or renewed, but does not change the state of the subnet.

subnet ipaddress/mask force-available

Makes a currently held subnet available, even a subnet marked as unavailable. Because using the force-available action may compromise the integrity of your IP address allocations, ensure that before you use this command, the client assigned the subnet is no longer using it.

subnet ipaddress/mask get attribute

Gets the value of an attribute for a subnet. See Table 2-14.

subnet ipaddress/mask [show]

Shows the subnet attributes for a specific address.

subnet list

Lists all the subnets.

Attributes

Table 2-22 describes the subnet command attributes and their values. They are all read-only attributes.

Table 2-22 subnet Command Attributes 

Attribute
Usage
Description

address

get

Subnet's address (including the mask). Required, no default.

client-domain-name

get

Domain name that the client specifies in its messages (if any).

client-flags

get

Either client-valid or client-id-created-from-mac-address (the client ID was created for internal use from the client's MAC address). Optional, no default.

client-host-name

get

Host Name that the client specifies (if any).

client-id

get

Client ID of the subnet's client. Optional, no default.

client-last-
transaction-time

get

Time that the client most recently contacted the DHCP server. Optional, no default.

client-mac-addr

get

MAC address that the client presents to the DHCP server. Optional, no default.

expiration

get

Expiration time of the subnet's binding. Optional, no default.

high-water

get

Highest utilization level recorded since the last statistics. Optional, no default.

in-use-addresses

get

Number of addresses that the client currently uses. Optional, no default.

last-transaction-
time

get

Time at which the client last communicated with the server about the subnet. Optional, no default.

namespace-id

get

ID of the namespace that contains the subnet. Optional, no default.

relay-agent-option

get

Contents of the relay agent information option from the most recent client interaction. Optional, no default.

selection-tags

get

String that the client presented when it last leased or renewed the subnet binding.

state

get

Subnet's state, which can be none=0, available=1, other-available=2, offered=3, leased=4, expired=5, released=6, unavailable=7, or pending-available=8. Optional, no default.

unusable-addresses

get

Number of addresses marked unusable. Optional, no default.


Related Commands

acl, namespace

tftp

The tftp command enables or disables TFTP server attributes. Because there is only one TFTP server per cluster within Network Registrar, you do not need to refer to the server by name.

tftp enable attribute

tftp disable attribute

tftp set attribute=value [attribute=value...]

tftp unset attribute

tftp get attribute

tftp [show]

tftp setTraceLevel value

tftp getTraceLevel

tftp reload


Note See also the "server" section for other server control commands.


Syntax Description

See Table 2-23 for the tftp command attributes and their descriptions.

tftp enable attribute

Enables a TFTP server attribute. See Table 2-23 for the attributes with a usage of enable or disable.

nrcmd> tftp enable file-caching 

tftp disable attribute

Disables a TFTP server attribute.

tftp set attribute=value [attribute=value...]

Sets one or more attributes of the TFTP server. See Table 2-23 for the attributes with a usage of set.

nrcmd> tftp set file-cache-directory="CacheDir" 
nrcmd> tftp reload 

Note that if you use this command, you must set the cache directory and reload the server. If file-cache is enabled, but file-cache-directory is not set, no files are cached. Even if file-cache is disabled, but file-cache-directory is set, the files in the directory are still accessible to clients.

tftp unset attribute

Unsets the value of an attribute of the TFTP server. You cannot unset required attributes.

tftp get attribute

Gets the value of an attribute for the TFTP server.

tftp [show]

Shows the TFTP server attributes.

tftp setTraceLevel value

Level of tracing that the TFTP server uses. Trace output is written to the file_tftp_1_log file in the server's logs directory. Trace statements go to the file_tftp_1_log on Windows NT and to the file_tftp_1_trace file on Solaris. Each integer value from 0 through 4 enables another cumulative trace level:

0—Disables all server tracing (default)

1—Displays all server log messages in the trace file

2—Also displays the client IP address and port for all TFTP packets

3—Also displays header information for all TFTP packets

4—Also displays the first 32 bytes of TFTP packet data


Note Only enable packet tracing if the Cisco TAC instructs you to. Tracing has significant impact on the performance level of the server. Also, do not enable packet tracing for long periods of time.


tftp getTraceLevel

Reports the trace level. Use only when investigating server problems.

tftp reload

Reloads the TFTP server and updates the files in cache.

Attributes

Table 2-23 describes the tftp command attributes and their values and defaults, if any.

Table 2-23 tftp Command Attributes 

Attribute
Usage
Description

active-directory-
domain

set
get

Name of an active directory domain that the TFTP server uses to provide dynamic configuration file support. Required, no default.

csrc-
configuration-file

set
get

Path to a configuration file the TFTP server uses when loading the Cisco Subscriber Registration Center (CSRC) version 1.0 library. The TFTP server can then generate dynamic DOCSIS modem configuration files. The location of the CSRC configuration file is typically /CSRC_INSTALL_DIR/conf/csrc.cfg. Required, no default.

default-device

set
get

Name of the default disk device the TFTP server uses when none is specified in the pathname in the TFTP request. This attribute is designed for use on Windows to specify a default drive letter. Required, no default.

docsis-access

enable
disable

How the TFTP server should respond to dynamic DOCSIS file requests from TFTP clients. Relevant for users of CSRC 1.0 only. If this attribute is disabled, the TFTP server refuses dynamic DOCSIS file requests and sends an access violation error to the client. Required, default disable.

docsis-file-
logging

enable
disable

Whether the TFTP server should log generated DOCSIS files to disk. Relevant for users of CSRC 1.0 only. If this attribute is enabled, the TFTP server logs each generated DOCSIS configuration file to a tftp subdirectory within the server logs directory. Relevant for users of CSRC 1.0 only. Required, default disable.

docsis-log-file-
count

set
get

Maximum number of DOCSIS configuration log files that the TFTP server maintains in the TFTP subdirectory within the server logs directory. Relevant for users of CSRC 1.0 only. Once this limit is reached, the TFTP server removes one DOCSIS log file for each new log file it creates. Required, default 100 log files.

docsis-pathname-
prefix

set
get

Pathname prefix that the TFTP server recognizes as the trigger to create a DOCSIS configuration file. Relevant for users of CSRC 1.0 only. This prefix must match the one that the DHCP server is using to generate the DOCSIS filename that DHCP sends to the TFTP client. Required, default /docsis.

file-cache

enable
disable

Determines whether the TFTP server should perform file caching on files located in the directory that the file-cache-directory attribute specifies. File caching allows the server to run faster by loading the files into memory, up to the maximum set by the file-cache-max-memory-size attribute. Upon reload, Network Registrar logs the name of each cached file, and skips any files it cannot load. It reads in all files as binary data and translates them as the TFTP client requests. Writing directly to cache is not allowed. Optional, default disable.

file-cache-
directory

set
get

Path to an existing directory where the TFTP server finds the files to put into cache, if enabled by the file-cache attribute. The server loads all these files on startup and on reloading, up to the maximum set by the file-cache-max-memory-size attribute. Use pathnames relative to the value of the home-directory attribute only. Network Registrar does not cache any files in this directory's subdirectories. Optional, no default, but the value is appended to the home directory path.

file-cache-max-
memory-size

set
get
unset

Maximum memory size, in bytes, of the file cache. Network Registrar loads all files into cache that cumulatively fit this memory size. If set to 0, Network Registrar does not cache any data, even if you enable file caching. Optional, default 32000 bytes.

home-directory

set
get

Path to a home directory that the TFTP server uses to resolve TFTP requests. With the use-home-directory-as-root attribute disabled, Network Registrar uses the value of the home-directory attribute plus the paths specified in the search-list to resolve requests. Required, default is the /data/tftp subdirectory of the installation directory.

initial-packet-
timeout

set
get

Initial time that the TFTP server waits after sending a response to a client before declaring that response timed-out and sending a retransmission to the client. Required, default five (5) seconds.

ldap-host-name

set
get

Host name or IP address of an LDAP server that the TFTP server uses to provide dynamic configuration file support. Relevant for users of CSRC 1.0 only. Required, default localhost.

ldap-initial-
timeout

set
get

Initial time the TFTP server waits after sending a request to an LDAP server before declaring that request timed-out and sending a retransmission to the server. Relevant for users of CSRC 1.0 only. Required, default 10 seconds.

ldap-maximum-
timeout

set
get

Maximum time that the TFTP server waits after transmitting the initial LDAP request before giving up retrying on that request. Relevant for users of CSRC 1.0 only. Required, default 60 seconds.

ldap-password

set
get

Password that the TFTP server uses when connecting to an LDAP server. Relevant for users of CSRC 1.0 only. Required, no default.

ldap-port-number

set
get

Port number that the TFTP server uses when communicating with an LDAP server. Relevant for users of CSRC 1.0 only. Required, default 389.

ldap-root-dn

set
get

Root distinguished name that the TFTP server uses to locate the root of the directory tree for dynamic configuration file support. Relevant for users of CSRC 1.0 only. Required, no default.

ldap-use-ssl

enable
disable

Controls whether the TFTP server uses SSL when communicating with an LDAP server. Relevant for users of CSRC 1.0 only. If this attribute is disabled, the TFTP server does not use SSL when communicating with LDAP. Required, default disable.

ldap-user-name

set
get

Username of the TFTP server when connecting to an LDAP server. Relevant for users of CSRC 1.0 only. Required, no default.

log-file-count

set
get

Number of log files that the TFTP server maintains in the server logs directory. Required, default four (4) files.

log-file-size

set
get

Size of each log file that the TFTP server maintains in the server logs directory. Required, default 1024 KB.

log-level

set
get
unset

Level of verbosity that the TFTP server employs when writing log messages to the TFTP server log file. Required, default level 3. Each integer value from zero through four enables these cumulative log levels. It is best to maintain the log level at the default of 3 (information).

0—None: no log messages written.

1—Error: present condition inhibits the TFTP server operation, such as there is no LDAP server.

2—Warning: present condition can cause operational problems, such as connection timeouts. Also includes errors.

3—Information: provides normal server informational messages (default). Also includes warnings and errors.

4—Activity: normal server operation, such as client requests and replies. Also includes information, warnings, and errors.

log-settings

set
get
unset

The TFTP server allows control over additional details about the events listed in the log-settings.The additional detail can be very helpful when analyzing a problem, but can cause the log files to fill up quickly (and therefore to turn over frequently, possibly losing important information) if left enabled for a long period of time. Optional, default is default.

The possible log setting flags are:

default—Causes the logging in the server to be active. Success messages print to the log for each successful transfer.

   

no-success-messages—Causes the single line message that is normally logged for every successful read from the TFTP server to not appear. Affects logging only for successful file reads from the TFTP server.

max-inbound-
file-size

set
get

Maximum file size that limit the TFTP server enforces for a file written to the TFTP server. The write-access attribute must be enabled. Required, default 1024 KB.

min-socket-
buffer-size

set
get

Minimum socket buffer size that the TFTP server uses for the well known port on which it is listening for TFTP requests. Required, default 65536.

packet-trace-level

set
get

Specifies the level of verbosity that the TFTP server employs when writing messages to the server trace file. Each integer value from 1 through 4 enables increasing levels of tracing. Setting packet trace level to 0 disables tracing. Required, default 0 (disabled).

port-number

set
get

UDP port number that the TFTP server uses to listen for TFTP requests. Required, default port 69.

read-access

enable
disable

How the TFTP server should respond to file read requests from TFTP clients. If this attribute is disabled, the TFTP server refuses file read requests and sends an access violation error to the client. Required, default enable.

search-list

set
get

Comma-separated list of paths that the TFTP server uses to resolve TFTP requests. If you enable use-home-directory-as-root, the server ignores the paths in the search list and uses the home directory to resolve all TFTP requests. Required, no default.

session-timeout

set
get

Maximum length of time that the TFTP server waits after transmitting the initial response before giving up retrying on that response. If no response is received from the client within this timeout period, the TFTP session is terminated. Required, default 20 seconds.

use-home-
directory-as-root

enable
disable

Whether the TFTP server treats pathnames contained in TFTP requests as if the paths were rooted at the specified home directory. If this attribute is enabled, the TFTP server attempts to resolve both absolute and relative pathnames to paths located beneath the specified home directory. Required, default disable.

write-access

enable
disable

How the TFTP server should respond to file write requests from TFTP clients. If this attribute is disabled, the TFTP server refuses file write requests and sends an access violation error to the client. Limitations—If enabled, the client can only write to a file that already exists on the server. The max-inbound-file-size attribute dictates the incoming file size. Required, default disable.

write-allow-file-
create

enable
disable

Whether to allow file creation on a PUT. With write-access enabled, if this attribute is disabled, the file must exist on the server; if enabled, the file does not need to exist and is created. The max-inbound-file-size value sets the file size limit. Required, default disable.


Related Commands

server

trap

The trap command enables or disables Simple Network Management Protocol (SNMP) traps. You can use traps to warn of error conditions and possible problems with the Network Registrar DNS, DHCP, or TFTP servers. These conditions include depleting the DHCP server scope address pools and communication loss with other servers.

trap enable trap

trap disable trap

trap set {free-address-low-threshold=value | free-address-high-threshold=value}

trap unset {free-address-low-threshold | free-address-high-threshold}

trap get {free-address-low-threshold | free-address-high-threshold}

trap [show]

trap addRecipient recipient host [community] [port]

trap removeRecipient recipient

trap listRecipients

Syntax Description

trap enable trap

Activates a trap. See Table 2-24 for the traps and their corresponding SNMP notification names. The default trap name is trap.

trap disable trap

De-activates a trap.

trap set {free-address-low-threshold=value | free-address-high-threshold=value}

Sets either or both of the two free address threshold attributes. In both cases, the valid values are digits and optionally a single trailing percent (%) character; the integer range is 0 through 2147483647 and percentages must be 0 through 100:

free-address-low-thresholdThreshold value for the free-address-low trap; default is 20%

free-address-high-thresholdReset value for the free-address trap; default is 20%

See the Network Registrar User's Guide for restrictions to free-address traps. This example sets the free-address-low-threshold to 12 percent and the free-address-high-threshold to 22 percent:

nrcmd> trap set free-address-low-threshold=12% 
nrcmd> trap set free-address-high-threshold=22% 

trap unset {free-address-low-threshold | free-address-high-threshold}

Unsets the values of one of the free address threshold attributes.

trap get {free-address-low-threshold | free-address-high-threshold}

Gets the value of the free address threshold.

trap [show]

Shows the values of the free address thresholds.

trap addRecipient recipient host [community] [port]

Adds the trap recipient to the cluster's trap recipient list. The Network Registrar servers reference the trap recipients through aliases to allow multiple recipients at the same address, but at different ports. The attributes are:

recipient—Required unique (cluster-wide) identifier for the recipient.

host—Required string representation of the host name or IP address of the recipient platform.

community—Optional community string that you can specify as part of the trap PDU for authentication purposes (the default community string is public).

port—Optional port to which Network Registrar directs the trap (default is 162).

trap removeRecipient recipient

Removes a trap recipient from the cluster's trap recipient list. You can delete a trap recipient from the list, but you cannot modify the recipients.

trap listRecipients

Lists all the trap recipients in the cluster's trap recipient list and their attributes.

Traps

Table 2-24 describes the traps and their corresponding SNMP notification names. All the traps are initially enabled by default.

Table 2-24 trap Command Traps 

Trap
SNMP Notification
Detects or Determines

address-conflict

ciscoNetRegAddressConflict

Address conflict with another server

dhcp-failover-config-
mismatch

ciscoNetRegFailover
ConfigurationMismatch

Configuration mismatch with a DHCP failover peer

dns-queue-too-big

ciscoNetRegDNSQueueToo
Big

DHCP server's queue of DNS messages is too large

duplicate-address

ciscoNetRegDuplicateAddress

Duplicate IP address

free-address-high

ciscoNetRegFreeAddressHigh

Free IP address count is no longer too low (default 20%)

free-address-low

ciscoNetRegFreeAddressLow

Free IP address count is too low (default 20%)

other-server-not-
responding

ciscoNetRegOtherServerNot
Responding

Another server is not responding

other-server-
responding

ciscoNetRegOtherServer
Responding

Another server is responding

server-start

ciscoNetRegServerStart

Server is started

server-stop

ciscoNetRegServerStop

Server is stopped


vendor-option

The vendor-option command defines the option data format for vendor-specific options (DHCP option 43) as required to accommodate devices from a variety of vendors. You can:

Create a vendor-specific option by name and associate it with a class-identifier string (option 60).

Specify suboptions 1 through 255 in each vendor-specific option.

vendor-option name create vendor-class-id

vendor-option name delete

vendor-option name enable read-only

vendor-option name disable read-only

vendor-option name defineSuboption suboption number datatype [flags]

vendor-option name undefineSuboption suboption

vendor-option name listSuboptions

vendor-option name [show]

vendor-option list

vendor-option listnames

Syntax Description

vendor-option name create vendor-class-id

Creates a vendor option and assigns the class-identifier string (DHCP Option 60) for the supported device. The option name is not case-sensitive. Do not use a hyphen (-) as part of the name. The vendor-class-id should be unique to each vendor option name.

vendor-option name delete

Deletes a vendor option.

vendor-option name enable read-only

Prevents further changes to a vendor option. Enable the read-only attribute of the vendor-specific DHCP option before you use the option in a policy name setVendoroption command to set the data for the option.

vendor-option name disable read-only

Allows changes to a vendor option (the default).

vendor-option name defineSuboption suboption number datatype [flags]

Defines a suboption for a vendor option. The attributes are:

suboption—Name of the suboption to define or undefine for the vendor option

number—Number of the suboption to add to the vendor option (from 1 through 255, with a default value of 43)

option-datatype—Name of the option datatype or standard DHCP option

flags—Comma-separated string of flags specifying formatting of the vendor option

The supported flags are:

array—Allows data for multiple suboptions when using the policy command to set vendor options.

no-suboption-opcode—Specifies that the DHCP server skips the byte that contains the suboption number.

no-suboption-len—Specifies that the DHCP server skips the byte that contains the length of the suboption data. Devices that use an empty suboption to indicate the end of vendor-specific DHCP option data may require this.

no-suboption-data—Specifies that the DHCP server skips the suboption data bytes. Devices that use an empty suboption to indicate the end of vendor-specific DHCP option data may require this.

vendor-option name undefineSuboption suboption

Makes a suboption-name undefined for a vendor option.

vendor-option name listSuboptions

Lists any suboptions defined for a vendor option.

vendor-option name [show]

Lists the attributes for a vendor option.

vendor-option list

Lists all vendor options and any attributes assigned to them.

vendor-option listnames

Lists just the names of the vendor options.

Related Commands

option-datatype

zone

The zone command creates and edits DNS zones, as well as forces zone transfers.

zone name create primary file=BINDfile

zone name create primary nameserver person [attribute=value...]

zone name create secondary address [attribute=value...]

zone name delete

zone name enable attribute

zone name disable attribute

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

zone name unset attribute

zone name get attribute

zone name [show]

zone list

zone listnames

zone name forceXfer secondary

zone name addHost hostname IPaddress [alias...]

zone name removeHost hostname

zone name listHosts

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

zone name removeRR owner [type [data]]

zone name addDynRR owner [ttl] [class] type data

zone name removeDynRR owner [type [data]]

zone name removeCachedRR owner [type [data]]

zone name cleanRR

zone name listRR {all | static | dynamic}

zone name getScavengeStartTime

zone name scavenge

zone name chkpt

zone name dumpchkpt

Syntax Description

See Table 2-25 for the zone command attributes and their descriptions.

The name is the fully qualified domain name (FQDN), including the trailing dot.

zone name create primary file=BINDfile

Creates a primary zone by importing data from the BIND (zone) format file.

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

zone name create primary nameserver person [attribute=value...]

Creates a primary zone, along with the DNS name server and the person in charge (and optionally any additional attributes). Note that re-creating an existing zone overwrites the old one.

The zone command automatically creates the SOA and NS resource records for you. Use the zone name addRR command to create an A record for the name server that you specified in the nameserver value. This example creates an SOA record ns.test.org. andy.test.org. and an NS record ns.test.org:

nrcmd> zone test.org. create primary ns andy 

Both of these records have the name of the zone ("test.org." or "@"). Because name server ns.test.org. is in the test.org. zone, you must also provide an A record for it.

nrcmd> zone test.org. addRR ns A 192.168.2.2 
nrcmd> server dns reload 

zone name create secondary address [attribute=value...]

Creates a secondary zone, along with the IP address of the primary name server for zone transfers (and optionally any additional attributes).

zone name delete

Deletes a zone.

zone name enable attribute

Enables an attribute of a zone.

zone name disable attribute

Disables an attribute of a zone.

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

Sets one or more attributes for a zone.

zone name unset attribute

Unsets the value of an attribute of the zone.

zone name get attribute

Gets the value of an attribute of the zone.

zone name [show]

Shows the values of all attributes for a zone.

zone list

Lists all zones and their attributes.

zone listnames

Lists just the zone names.

zone name forceXfer secondary

Forces the secondary server to initiate a zone transfer.

nrcmd> zone test.org. forceXfer secondary 


Note The primary argument is currently not implemented.


zone name addHost hostname IPaddress [alias...]

Adds the host name to a zone, along with its IP address and optional aliases.

nrcmd> zone example.com. addHost bethpc 192.168.1.10 

zone name removeHost hostname

Removes a host from a zone.

zone name listHosts

Lists the hosts for a zone.

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

Adds a resource record of a certain type for a zone. The attributes of this command are:

class—Class of resource record, always IN (for Internet) in DNS.

owner—Owner of the resource record. You can specify the resource record's owner name as one of these:

If the same name as the zone name—Enter the (@) symbol

If the name is in the same domain—Relative name

Fully qualified domain name (FQDN)

ttl—Resource record time to live (in seconds).

type—Type of resource record, such as PTR or A. For full descriptions, see the Network Registrar User's Guide.

data—Data that depends on the resource record type.

For the resource record addition to take effect, you must reload the server. This example adds a Name Server (NS) resource record:

nrcmd> zone example.com addRR @ NS ns.green.example.com. 
nrcmd> server dns reload 

zone name removeRR owner [type [data]]

Removes all specified static resource records from a zone. Specify resource records by owner; owner and type; or owner, type, and data. Note that for the removal to take effect, you need to reload the server. See the attributes in the addRR syntax description.

zone name addDynRR owner [ttl] [class] type data

Adds a dynamic resource record of a certain type for a zone. The attributes of this command are the same as for the addRR keyword, except that the type can only be A, CNAME, PTR, SRV, or TXT.

zone name removeDynRR owner [type [data]]

Removes all specified dynamic resource records from a zone. Specify resource records by owner; owner and type; or owner, type, and data. Specifying a type without data removes the entire resource record set; including the data removes the specific dynamic resource record only. The DNS server must be running. Changes take effect immediately; you do not need to reload the server. See the attributes in the addRR syntax description.

zone name removeCachedRR owner [type [data]]

Removes non-authoritative resource records from in-memory and persistent (non-authoritative) cache. With the type omitted, this removes the entire name set; if included without data, this removes the resource record set; with both type and data included, this purges the specific resource record. See the attributes in the addRR syntax description.

zone name cleanRR

Cleans out zone records that remain after you remove a zone. This example deletes a zone's unused or obsolete resource records.

nrcmd> zone example.com cleanRR 

zone name listRR {all | static | dynamic}

Displays the resource records for a zone. You can display all the resource records, or just the static or dynamic resource records.

zone name getScavengeStartTime

Gets the time for the next scheduled zone scavenging.

zone name scavenge

Causes scavenging on all zones that have enabled the scvg-enabled attribute.

zone name chkpt

Forces an update to the zone checkpoint database for the specified zone. Set the checkpoint interval using the zone name set checkpoint-interval command.

zone name dumpchkpt

Creates a humanly readable file of the latest zone checkpoint.

Attributes

Table 2-25 describes the zone command attributes.

Table 2-25 zone Command Attributes 

Attribute
Usage
Description

auth-servers

set
get

For a secondary zone only, the list of IP addresses of servers from which to transfer data. Required for a secondary zone, no default.

checkpoint-
interval

set
get
unset

Interval (in seconds) at which to checkpoint the zone (take the latest snapshot in the zone checkpoint database). Optional, no default.

defttl

set
get
unset

For a primary zone only, default TTL for this zone. Network Registrar responds to authoritative queries with an explicit TTL value, if one exists. If none exists, it responds with the default TTL value. Required for a primary zone, default 86400 seconds (24 hours).

dynamic

enable
disable

For a primary zone only, enables or disables RFC 2136 dynamic updates to the zone. The most typical source of these updates is a DHCP server. Required, default enable.

ixfr

enable
disable
unset

For a secondary zone only, enables or disables requesting incremental transfers. Overrides the ixfr-enable setting for the server. Optional, no default.

nameservers

set
get
unset

Comma-separated list of name servers, in fully qualified domain name format. Optional, no default.

notify

enable
disable
unset

Enables notifying other authoritative servers when this zone changes. The setting overrides the global notify value for this zone. Optional, no default.

notify-set

set
get

List of additional servers to notify when the zone changes. All servers listed in NS records for the zone, except the server described by the ns zone attribute (mname field of the SOA record), receive notifications. Network Registrar also notifies servers listed in the notify-set value. Optional, defaults to empty.

origin

get

Fully qualified name of the zone's root. Read-only.

restrict-xfer

enable
disable

If enabled, restricts zone transfers to a specific set of hosts. If you restrict zone transfers, you need to use the restricted-set attribute to list the servers allowed to perform zone transfers. Required, default disable.

restricted-set

set
get

With zone name enable restrict-xfer, the set of IP addresses that can request zone transfers. Network Registrar treats addresses with zeros in the least significant octets as network numbers, with implicit masks in octet multiples. Required, default zero entries, no value.

scvg-enabled

enable
disable

For a primary zone only, enables or disables dynamic resource record scavenging of the zone. Use this for Microsoft clients, with other scavenging attribute settings. See the Network Registrar User's Guide. This setting overrides that on the server level. Required, default disable.

scvg-ignore-
restart-
interval

set
get
unset

For a primary zone only, the interval, in seconds, for which a server restart does not recalculate a start scavenging time. This setting overrides that on the server level. Optional, no default.

scvg-interval

set
get
unset

For a primary zone only, with zone name enable scvg-enabled, the interval, in seconds, at which the zone is scheduled for scavenging. This setting overrides that on the server level. Optional, server defaults apply, range 3600 seconds (one hour) through 31536000 seconds (six years).

scvg-no-
refresh-
interval

set
get
unset

For a primary zone only, with zone name enable scvg-enabled, the interval, in seconds, during which actions such as dynamic or prerequisite-only updates do not advance the timestamp for scavenging. This setting overrides that on the server level.Optional, server defaults apply, range 3600 seconds (one hour) through 31536000 seconds (six years).

scvg-refresh-
interval

set
get
unset

For a primary zone only, with zone name enable scvg-enabled, the interval, in seconds, during which actions such as dynamic DNS updates and prerequisite-only updates advances the zone timestamp. This setting overrides that on the server level. Optional, server defaults apply, range 3600 seconds (one hour) through 31536000 seconds (six years).

subzone-
forward

set
get
unset

For zones with forwarders set (through the dns addForwarder command), the normal Network Registrar behavior is to ignore delegation to subzone name servers and forward queries to these forwarding servers instead. You would normally need to set a resolution exception (through the dns addException command) to the subzone server. This might be impractical for large numbers of subzones. With the subzone-forward attribute set to no-forward, when the server receives a query for any of its subzones, it tries to find relevant subzone NS records, resolve their corresponding IP addresses, and delegate the query to those IP addresses. Default normal.

update-acl

set
get
unset

Adds or updates one or more ACLs to a zone. If set, the ACLs control what networks or servers can perform dynamic DNS updates. Use the ! symbol to negate a value, such as:

nrcmd> zone example.com. set update-acl=acl1,!acl2 

See the "acl" section. Setting the attribute at the zone level overrides the server setting. (This attribute replaces the dynupdate-set attribute from the previous release.) Optional, no default.


Related Commands

acl, dns, server