|
|
The Network Registrar nrcmd program is a command-line based configuration tool. It allows you to set all Network Registrar configurable options as well as start and stop the servers.
This chapter contains an alphabetic listing of all the commands and their properties.
The admin command allows you to configure administrators for the cluster. You can choose any string for the name. Network Registrar uses the password to authenticate the name. If you create an administrator without a password, Network Registrar cannot authenticate the name, and thus will deny that user access to the cluster.
Because the password is sensitive information, Network Registrar prints its value as'********'.
The syntax is:
admin name create [prop=value]To create the administrator bob with the password xyz, type:
nrcmd>adminbob create password=xyz
To delete the administrator bob, type:
nrcmd>adminbob delete
Use the set, get, and show commands to assign and retrieve values from the admin's properties.
The syntax is:
admin name set prop=value [prop=value]To enter a password and not have Network Registrar display the password on your screen, create an administrator and do not supply a password. Then use the enterPassword command to enter a password and prevent Network Registrar from echoing it on the screen. Network Registrar prompts you to verify the password before it accepts it.
Table 2-1 lists and describes the admin property.
| Properties | Description |
|---|---|
The administrator's password |
The client and client-class commands let you create and manipulate clients and groups of clients for the purpose of determining what type of IP address and/or policy to assign to requesting hosts.
Using the client command you can assign properties to a specific client entry, based on the client's MAC address or the literal string default, which matches any client that does not have a specific client configuration. The properties you can assign include such things as a class of client, a policy, an action, and the inclusion or exclusion of scope selection tags. The DHCP server looks up these properties to determine how it should process the host's request for an IP address.
You can configure common client properties such as selection criteria, in one client-class configuration, and have multiple client configurations use it.
The DHCP server reads the client configuration information each time it receives a request for an IP address, so you do not have to reload the server after modifying these client configurations. If you modify the default client configuration however, you must reload the server in order for the change to take effect.
The way that you specify the client is by using the MAC address in the format of hardware-type,hardware-length,hardware address or the word default. Note that the commas are required.
A sample Ethernet MAC address might be 1,6,06:44:40:26:f5:0f.
The syntax is:
client name create [prop=value]To create a client that is a member of the external client-class, type:
nrcmd> client 1,6,02:02:02:02:02:02 create
client-class-name=external
To delete client 1,6,02:02:02:02:02:02:, type:
nrcmd> client 1,6,02:02:02:02:02:02 delete
To list all the client-classes, type:
nrcmd> client list
The property list contains the name and values in the following format: prop=value{,value}.
For the host-name and domain-name strings to have any effect, you must have enabled dynamic DNS update in the scope from which the IP address was allocated.
Use the set and get commands to set and display their values.
The syntax is:
client macaddress set prop=valueTable 2-2 lists the client command properties.
| Property | Description |
|---|---|
The action to take for this client. You can specify either exclude, ignore, or one-shot. For more information about these actions, see the "Action Strings" section. | |
(Client-only) Specifies whether to limit the authentication time to the duration you have specified. For more information about how to specify the time, see the "Authenticate-Until" section. | |
(Client-only) The client-class to which the client belongs. Note that the client-class-name property may only appear in the client entry. It is an error to specify a client-class name property in a client-class object. If the client is not a member of a client-class, then the DHCP server uses the default client-class properties. | |
The domain name to use when performing DNS updates. Places the client's A record in this DNS domain. | |
The host name. Use this string to replace any host-name DHCP option sent by the DHCP client. For more information about host names, see the "Host Name Strings" section. | |
The policy to add to Network Registrar's DHCP policy search list for this client. | |
The scope selection tags to build the scope inclusion list. | |
The scope selection tags to build the scope exclusion list. | |
The name of the client-class to use if this client is no longer authenticated. | |
A user-defined string that can be set and queried. This property has no effect on the operation of the DHCP server. |
The action string is made up of one or more comma-delimited tokens. Valid tokens are the following:
Use the one-shot action to allocate provisional addresses, which are useful when you want an unknown client to have an address for only a short period of time.
To use the one-shot action in this way, configure it as the action for the default client (or in the client-class specified by the default client). This configuration causes the server to give a lease to an unknown client, but when the lease expires, the server will not respond to that client for the duration of the grace period. After the grace period expires, the server will not respond to that client until the now available lease is reallocated to another client. This final period may be short or long, depending on the number of leases in the scope, and the number of clients using them. Newly available leases go on the end of a queue, and are allocated from the beginning of a queue, so that it might be quite some time before this lease is reallocated to another client.
It is possible to allow the client a relatively short lease time, such as one day, and then specify a long grace period, such as two weeks. In this manner, you can offer an incentive to the client to register with some authority and become a known client, while preventing the lease from being reallocated to another client.
After the lease expires, the client is unable to get another address for the extent of the two-week grace period. Note that you can configure the lease and grace period differently for each scope, so that the non-provisional leases can have different lease and grace periods.
After the lease is reallocated to another client, all record of the first client's use is lost, and the first client could get another lease as an unknown client and have another opportunity to register.
Using provisional addresses would be less restrictive if you use multiple DHCP servers, because each one operates its one-shot capabilities independently. Thus, with the above approach and two DHCP servers, an unregistered client could get two days of provisional address use every two weeks.
When the authentication for a client entry is no longer authenticated, the DHCP server uses the value of the unauthenticated-client-class property for the name of the client-class entry to use in answering this DHCP request. If the unauthenticated-client-class property is not set or if there is no client-class entry in the unauthenticated-client-class property, the DHCP server ignores the DHCP request; that is, the server will not provide the client an IP address.
The following are valid authentication values:
If you specify 98 or 99, Network Registrar assumes 1998 or 1999. If you specify a lower number, such as 05 or 10, Network Registrar assumes 2005 or 2010.
The value you specify in the host-name property can be one of two general forms.
The first form is a string that does not start with a "@." This form of host-name value is used to override the DHCP client-request host name. When you enter a valid name, you cause the DHCP server to ignore any host name specified by this client, and instead use this client-entry property. The actual value of the host-name option in the client's DHCP packet is ignored.
The second form is a string that starts with the special token "@." Network Registrar uses this form of host-name value to signal the following special handling.
The client-class command allows you to apply a set of properties to a group or class of clients.
The syntax is:
client-class name create [prop=value]
client-class name delete
client-class list
To create the client-class internal, type:
nrcmd> client-class internal create
To delete the client-class internal, type:
nrcmd> client-class internal delete
To list the all the client-classes, type:
nrcmd> client-class list
The client-class command allows you to configure and display common properties for DHCP client configurations using the set, get and show commands.
Unlike most client configurations, the DHCP server reads the client-class configurations at server start-up time, and thus you must reload the server for changes to take affect.
The syntax is:
client-class name set prop=value [prop=value]
client-class name get prop
client-class name show
For descriptions of the properties, see the "Client Properties" section.
The server processes client and client-class property values in the following way:
The client-class-policy command allows you to configure DHCP embedded policies for client classes. A client-class-policy is a policy object embedded within (and limited to) a client-class object. Each client-class may contain option data within its embedded policy, and may refer to a named policy with more option data, such as a router IP address.
Embedded client-class-policies are implicitly created and deleted when you create or delete the corresponding client-classes. You manipulate the client-class-policy using the name of the client-class to which the embedded policy is attached.
You can enable, disable, or determine whether the feature has been set. You use the enable, disable, or get commands.
The syntax is:
client-class-policy client-class-name enable featureTable 2-3 lists and describes the client-class-policy features. For more information about lease time, see "Lease Times" section.
| Feature | Description |
|---|---|
Optional, default none. Clients may request a specific lease time. The server does not honor those requested lease times if this attribute is false. The server does not honor a client's lease time if the time is longer than the server's normal lease time. | |
Optional, default none. Specifies that leases for this client-class policy should be permanently granted to requesting clients. | |
Optional, default none. Controls whether the server uses the value of the server-lease-time property to determine the length of a lease, rather than using the lease time returned to the client. |
Use the set and get commands to assign and retrieve values from the client-class-policy's properties.
The syntax is:
client-class-policy client-class-name get propTable 2-4 lists and describes the client-class-policy properties.
| Property | Description |
|---|---|
Optional, default none. A list of the names of options that should be returned in any replies to BOOTP clients. The options themselves do not have to have been configured in the same client-class-policy as the reply-options list. The server searches the hierarchy of policies for each option named in the list. For more information about this property, see the "Client-Class-Policy Reply Options" section. | |
Optional, default none. Supplies the name of the executable file from which to boot or obtain configuration data. This property can also contain the following variable substitution values:
| |
Optional, default none A list of the names of options that should be returned in any replies to DHCP clients. The options themselves do not have to have been configured in the same policy as the reply-options list. The server searches the hierarchy of policies for each option named in the list. For more information about this property, see the "Client-Class-Policy Reply Options" section. | |
Optional, default none. The length of time between the expiration of a lease and the time it is made available for re-assignment. | |
Optional, default none. If the server offers a lease to a client, but the offer is not accepted, the server waits the specified number of minutes before making the lease available again. | |
Optional, default none. The name of a boot file to be used in a client's boot process. The server returns this file name in the file field of its replies. The packet-file-name cannot be longer than This property can also contain the following variable substitution values:
| |
Optional, default none. The host name of a server to use in a client's boot process. The server returns this file name in the sname field of its replies. The packet-server-name field cannot be longer than | |
Optional, default none. The IP address of the next server in a client's boot process. For example, this might be the address of a TFTP server used by BOOTP clients. The server returns this address in the siaddr field of its reply. | |
Optional, default none. The time that the server believes the lease is valid. It may be useful to have the server consider leases leased for a longer period than the client in order to get more frequent client communication along with the stability of long lease times. | |
vendor-class-identifier | Optional, default none. This property is used by clients and servers to exchange vendor-specific information. The information is an opaque object of n octets, presumably interpreted by vendor-specific code on the clients and servers. The vendor is indicated in the vendor-class-identifier option. |
To set the grace period to three days for client-class-policy 168.1-net, type:
nrcmd> client-class-policy 168.1-net set grace-period=3d
When the server is getting ready to return option data to a client, it examines up to seven policies: the client's embedded policy, the client's policy, the client's client-class's embedded policy, the client's client-class's policy, the client's lease's scope's embedded policy, the client's lease's scope's policy, and the system default policy, in that order. The server looks through these policies for option data that the client has asked for.
Then the server looks through the policies for a reply-options list. It looks for bootp- or dhcp-reply-options depending on the client. The server uses the first list it finds. For each option in the list, the server looks through all of the policies, in order, and returns the data from the first policy that has a matching option. There is no requirement that the data that the server returns must come from the same policy that the reply-options list came from. If the server finds a reply-options list, it looks for each option in the list individually, and searches all of the related policies if necessary.
There is also no requirement that the options mentioned in a reply-options list be present in the client-class-policy that contains the list. The nrcmd program allows you to type in a string, and that string can name any option. The Network Registrar GUI, however, presents a special dialog box for adding a reply-options property to a client-class-policy that restricts you to the options already configured in the client-class-policy. This is a GUI-only restriction; the server does not impose this restriction.
You can set individual option values with the setOption command, unset option values with the unsetOption command, and view option values with the getOption and listOptions commands. When you set an option value, the DHCP server replaces any existing value or creates a new one, as needed, for the given option name.
The syntax is:
client-class-policy client-class-name listOptionsTable 2-5 lists and describes the client-class-policy options.
| Property | Description |
|---|---|
Lists the options in the named client-class-policy. | |
Sets the option name and value to the specified client-class-policy. The format is optname value. For example, dhcp-lease-time 3600. | |
Gets the value of the named option. | |
Removes the named option from the specified client-class-policy. |
To specify the lease time in a client-class-policy, type:
nrcmd> client-class-policy 168.1-net setOption dhcp-lease-time 608400
To list the options in a client-class-policy, type:
nrcmd> client-class-policy 168.1-net listOptions
The setLeaseTime command allows you to set the values of lease times and the getLeaseTime command to display the value of a lease time.
The syntax is:
client-class-policy client-class-name setLeaseTime valueThe lease time is the value of the dhcp-lease-time option. You should specify the time in seconds.
A client-class-policy contains two lease times: the lease time and the server lease time.
You might want to establish these two different lease times if you want to retain information about clients' DNS names and yet have them renew their leases frequently. When you use a single lease time and it expires, the server no longer keeps that client's DNS name. If, however, you use a short client lease time and a longer server lease time, the client information is retained even after the client's lease has expired.
The client-policy command allows you to configure DHCP embedded policies for clients. A client-policy is a policy object embedded within (and limited to) a client object. Each client may contain option data within its embedded policy, and may refer to a named policy with more option data, such as a router IP address.
Embedded client-policies are implicitly created and deleted when you create or delete the corresponding client. You manipulate the client-policy using the name of the client to which the embedded policy is attached.
You can enable, disable, or determine whether the feature has been set. You use the enable, disable, or get commands.
The syntax is:
client-policy client-name enable featureTable 2-6 lists and describes the client-policy features. For more information about lease time, see "Lease Times" section.
| Feature | Description |
|---|---|
Optional, default none. Clients may request a specific lease time. The server does not honor those requested lease times if this attribute is false. The server does not honor a client's lease time if the time is longer than the server's normal lease time. | |
Optional, default none. Specifies that leases for this client-policy should be permanently granted to requesting clients. | |
Optional, default none. Controls whether the server uses the value of the server-lease-time property to determine the length of a lease, rather than using the lease time returned to the client. |
Use the set and get commands to assign and retrieve values from the client-policy's properties.
The syntax is:
client-policy client-name get propTable 2-7 lists and describes the client-policy properties.
| Property | Description |
|---|---|
Optional, default none. A list of the names of options that should be returned in any replies to BOOTP clients. The options themselves do not have to have been configured in the same client-policy as the reply-options list. The server searches the hierarchy of client-policies for each option named in the list. For more information about this property, see the "Client-Policy Reply Options" section. | |
Optional, default none. Supplies the name of the executable file from which to boot or obtain configuration data. This property can also contain the following variable substitution values:
| |
Optional, default none A list of the names of options that should be returned in any replies to DHCP clients. The options themselves do not have to have been configured in the same client-policy as the reply-options list; the server searches the hierarchy of client-policies for each option named in the list. For more information about this property, see the "Client-Policy Reply Options" section. | |
Optional, default none. The length of time between the expiration of a lease and the time it is made available for re-assignment. | |
Optional, default none. If the server offers a lease to a client, but the offer is not accepted, the server waits the specified number of minutes before making the lease available again. | |
Optional, default none. The name of a boot file to be used in a client's boot process. The server returns this file name in the file field of its replies. The packet-file-name cannot be longer than 128 characters. This property can also contain the following variable substitution values:
| |
Optional, default none. The host name of a server to use in a client's boot process. The server returns this file name in the sname field of its replies. The packet-server-name field cannot be longer than 64 characters. | |
Optional, default none. The IP address of the next server in a client's boot process. For example, this might be the address of a TFTP server used by BOOTP clients. The server returns this address in the siaddr field of its reply. | |
Optional, default none. The time that the server believes the lease is valid. It may be useful to have the server consider leases leased for a longer period than the client to get more frequent client communication and the stability of long lease times. | |
vendor-class-identifier | Optional, default none. This property is used by clients and servers to exchange vendor-specific information. The information is an opaque object of n octets, presumably interpreted by vendor-specific code on the clients and servers.The vendor is indicated in the vendor-class-identifier option. |
To set the grace period to three days for client-policy 168.1-net, type:
nrcmd> client-policy 168.1-net set grace-period=3d
When the server is getting ready to return option data to a client, it examines up to seven policies: the client's embedded policy, the client's policy, the client's client-class's embedded policy, the client's client-class's policy, the client's lease's scope's embedded policy, the client's lease's scope's policy, and the system default policy, in that order.
Then the server looks through the policies for a reply-options list. It looks for bootp- or dhcp-reply-options depending on the client. The server uses the first list it finds. For each option in the list, the server looks through all of the policies, in order, and returns the data from the first policy that has a matching option. There is no requirement that the data that the server returns must come from the same policy that the reply-options list came from. If the server finds a reply-options list, it looks for each option in the list individually, and searches all of the related policies if necessary.
There is also no requirement that the options mentioned in a reply-options list be present in the client-policy that contains the list. The nrcmd program allows you to type in a string, and that string can name any option. The Network Registrar GUI, however, presents a special dialog box for adding a reply-options property to a client-policy. This dialog box restricts you to the options already configured in the client-policy. This is a GUI-only restriction; the server does not impose this restriction.
You can set individual option values with the setOption command, unset option values with the unsetOption command, and view option values with the getOption and listOptions commands. When you set an option value the DHCP server replaces any existing value or creates a new one, as needed, for the given option name.
The syntax is:
client-policy client-name listOptionsTable 2-8 lists and describes the client-policy options.
| Property | Description |
|---|---|
Lists the options in the named client-policy. | |
Sets the option name and value to the specified client-policy. The format is optname value. For example, dhcp-lease-time 3600. | |
Gets the value of the named option. | |
Removes the named option from the specified client-policy. |
To specify the lease time for a client, type:
nrcmd> client-policy 168.1-net setOption dhcp-lease-time 608400
To list the options in a client-policy, type:
nrcmd> client-policy 168.1-net listOptions
The setLeaseTime command allows you to set the values of lease times and the getLeaseTime command to display the value of a lease time.
The syntax is:
client-policy client-name setLeaseTime valueThe lease time is the value of the dhcp-lease-time option. You should specify the time in seconds.
A client-policy contains two lease times: the lease time and the server lease time.
You might want to establish these two different lease times if you want to retain information about clients' DNS names and yet have them renew their leases frequently. When you use a single lease time and it expires, the server no longer keeps that client's DNS name. If, however, you use a short client lease time and a longer server lease time, the client information is retained even after the client's lease has expired.
The custom-option command allows you to create, list, or delete a custom DHCP option.
You can also use the custom-option command to redefine any predefined DHCP options. The newly defined option's definition will override the original option. If you delete this option, its definition returns to its original value.
The syntax is:
custom-option name create optnum opttypeTable 2-9 lists and describes the custom-option properties.
| Property | Description |
|---|---|
Specifies the option number. Read-only. | |
Specifies the option type. It can be BOOL, BYTE, WORD, INT, UINT, STRING, IPADDR, BYTE_ARRAY, WORD_ARRAY, INT_ARRAY, UINT_ARRAY, or IPADDR_ARRAY. For more information about types, see the "Option Types" section. | |
Optional, default null-string. Use this property for a description. |
Table 2-10 lists the option types supported by the nrcmd program.
| Option Type | <opttype> | Definition |
|---|---|---|
boolean | TRUE or FALSE | |
byte | 8-bit unsigned integer | |
word | 16-bit unsigned integer | |
signed integer | 32-bit signed integer | |
unsigned integer | 32-bit unsigned integer | |
string | ASCII text string | |
IP address | IP address in the form of a.b.c.d | |
byte array | Binary string of the form xx[:xx] in which x is 0-9a-f | |
word array | Array of 16-bit unsigned integers | |
signed array | Array of 32-bit signed integers | |
unsigned array | Array of 32-bit unsigned integers | |
IP address array | Array of IP addresses |
To create a custom option called red, mapped to number 100, of type IPADDR, type:
nrcmd> custom-option red create 100 IPADDR
To create a custom option called blue, mapped to number 101, that is an array of bytes, type:
nrcmd> custom-option blue create 101 BYTE_ARRAY
To give custom-option blue a description, type:
nrcmd> custom-option blue set desc="this is another option called blue."
To create a custom-option that overlays pre-defined option 2 (time-offset), type:
nrcmd> custom-option green create 2 INT desc="Option green overlays time-offset."
To list the custom-options you have created, type:
nrcmd> custom-option list
To cause option 2 to revert to its original definition, type:
nrcmd> custom-option green delete
To redefine time-offset option to change the format of its user-printable name, type:
nrcmd> custom-option TimeOffset create 2 INT
To display the option's new definition, type:
nrcmd> custom-option TimeOffset show
Do not map numbers to custom options that are already used by DHCP or BOOTP options. For a complete list of pre-assigned numbers, see Table D-2.
The dhcp command allows you to configure the DHCP server in the cluster. Because there is only one DHCP server per cluster, you do not need to reference the server by name.
The syntax is:
dhcp disable featureTable 2-11 lists and describes the DHCP features.
| Feature | Description |
|---|---|
Controls whether the DHCP server uses the source address of the packet, if it is non-zero, in lieu of the giaddr field. Note that the DHCP server uses this feature only for DHCP packets, not BOOTP packets. The default is enabled. For more information about this feature, see the "Cisco DHCP Proxy" section. | |
Controls whether or not the DHCP server uses the client and client-class configuration objects to affect request processing. Default disabled. | |
Controls whether or not the DHCP server extends leases that are less than half expired. Default disabled, which means that the DHCP server will always extend leases (except in the first 30 seconds) to accommodate protocol retries. For more information about this feature, see the "Defer Lease Extensions" section. | |
Causes the DHCP server to find all the interface cards on the host and process DHCP requests that it receives from any of them. It will, however, only offer addresses to requests from subnets in which you have defined a valid scope with available addresses. If you do not enable this feature, the DHCP server uses only its list of configured interfaces. Default enabled. See the "Dhcp-interface" section. | |
Causes the server to drop a packet (if possible) when it encounters a failure in an extension. Default enabled. | |
Controls whether all scopes configured to use the server's failover configuration will be able to engage in failover. If disabled, only those scopes with failover explicitly enabled will do so. Default disabled. For more information, see the "Scope" section. | |
Forces the DHCP server to attempt a DNS update for each client that obtains or renews a lease, whether or not the DHCP server's state has recorded a successful update. This feature is useful when you need to restore a DNS server's database from a backup and have lost dynamic DNS records. Note that this command causes increased dynamic update load, which can adversely affect performance. If only a few DHCP clients' DNS names need to be refreshed, we recommend that you do not use force-dns-updates. Instead, request that DHCP clients individually release and renew their leases. | |
Controls whether the DHCP server sends unicast rather than broadcast responses when a client indicates that it can accept a unicast. This feature may not be available on all platforms. | |
If you enable this feature and you have configured the DHCP server to send ICMP ECHO (ping before offer) requests before offering addresses, the server will make unavailable any address for which it receives an ECHO reply within its configured timeout period. If you disable this feature, the DHCP server will also treat ICMP DEST_UNREACHABLE and TTL_EXPIRED error messages which it receives after sending ICMP ECHO requests as grounds for making an address unavailable. | |
Causes the DHCP server to recognize only packets generated from the nrcmd program's import leases command and ignore all others. You can use this property if you want to update your DHCP server and prevent clients from receiving addresses during this period. Default disabled. For more about import mode, see the "Import Mode" section. | |
Causes the DHCP server to use the client's MAC address as the only client identifier. The standard behavior, as specified in RFC 2132, is to use the client ID option (if it is present) as the unique client identifier. If you specify the mac-address-only argument, the DHCP server ignores the client's ID and uses its MAC address instead. You can use this argument to have a single, consistent way of identifying all clients that use your DHCP server. Default disabled. | |
Causes the DHCP server to release any other leases the client may have had on this server. Since the default behavior for the Network Registrar DHCP server is to store all the leases a client obtains, this command ensures that only one lease is stored. A client might obtain a number of leases if a user with a laptop traveled throughout the building and requested leases at different locations on the network. Default disabled. | |
If the server is replying to a BOOTP request, and is offering a lease from a scope that is configured for DNS updates, the DHCP server checks this property before beginning the update. You can use this feature to prevent DNS updates for BOOTP clients, while allowing updates for DHCP clients. | |
Controls whether the DHCP server attempts to read client-entry data through LDAP, that is, using the configuration supplied by the ldap command. Default disabled. For more information about the ldap command, see the "LDAP Features" section. | |
Controls whether the DHCP server saves the relay agent data for a particular IP address in the DHCP server's state when it writes the lease data for that IP address. Enable this feature if you expect the DHCP server to respond to leasequery messages. The default is disabled. |
The cisco-dhcp-proxy feature provides support for certain Cisco devices that implement a DHCP proxy function. The cisco-dhcp-proxy feature causes the DHCP server to use a non-zero IP source address as the giaddr (gateway address) of a DHCP packet when no giaddr is specified in the packet. This feature causes no change in the processing for DHCP clients that are not local or for any BOOTP clients. For locally connected DHCP clients (where the giaddr must be zero), the source address is normally zero (per the DHCP RFC), and so the subnet on which they belong is determined using the interface address on which the packet arrived---which is the correct behavior.
Because it might be possible that some locally connected clients might be affected by the cisco-dhcp-proxy feature, you can disable it. Such a client would have to send packets to the DHCP server using a non-zero source address (which they should not do), and this would cause them to be unable to get an IP address. If a client is having difficulty receiving an IP address, you can determine whether it is caused by the cisco-dhcp-proxy feature by checking the logs. Look for the phrase "with source IP address x.y.z.a" in the message that begins: "Server received a packet-type packet from... via: {Interface | Garrett} e.f.g.h" and that contains the client's MAC address or Client ID and hostname (if any). If you see such a message for a locally connected client, then you should consider disabling cisco-dhcp-proxy feature.
You might want to use the defer-lease extensions feature to reduce the number of writes to the Network Registrar database. These writes can occur because the Network Registrar DHCP server commits fresh information to the database any time it changes the duration of a client's lease. Since the DHCP server renews leases for the full lease interval every time the client contacts the server, these database writes may have a performance impact if the server is on a busy network.
Some database writes can be eliminated if the data being written is redundant, that is, the same as the old data. Instead of granting the full lease duration, the server can re-grant the lease with a new duration equal to the remaining time on the old lease. Since the absolute expiration time does not change, no database write is needed.
There are three cases of lease extensions to consider:
As a complication, the server also keeps track of the time at which it last heard from the client. Known as "last-transaction-time," this information is sometimes used by sites as a debugging aid (for example, "How long has it been since we've heard from Beth's PC?"). Maintaining this time robustly requires a write to the database on every client interaction. For more information about this property, see the "last-transaction-time-granularity" section.
Because the last-transaction-time is not integral to the protocol, it does not have to be updated synchronously. And since it is used primarily as a debugging aid, it does not have to be entirely accurate. Furthermore, because the in-memory copy is always accurate, you can use the export leases -server command to display the current information even if the data is not up-to-date in the database. For more information about the export leases command, see the "Export Leases" section.
You can put the DHCP server into import mode by enabling the import-mode feature and then restarting the server. You take the server out of import mode by disabling the feature and restarting the server. You can use import mode to exclude all DHCP lease requests except for the specially tagged ones that come from the nrcmd program during lease import. For more information about the import command, see the "Import Leases" section.
To enable the client-class facility for this DHCP server, type:
nrcmd> dhcp enable client-class
To disable import mode, type:
nrcmd> dhcp disable import-mode
To display whether discover-interface is enabled or disabled, type:
nrcmd> dhcp get discover-interfaces
Use the set, get, unset, and show commands to assign and retrieve values from the DHCP's name-value properties.
The syntax is:
dhcp get propTable 2-12 lists and describes the DHCP properties.
| Property | Description |
|---|---|
Controls the number of milliseconds the DHCP server will wait for a response before retrying a dynamic DNS request. Default 500. | |
Specifies a string that gets substituted with the %@docsis-vers% variable in the policy command's boot-file property. This substitution occurs if the DHCP request packet either does not contain a vendor-class-id option or if the option does not contain a docsis version id. Default is none. The string can contain 255 characters. | |
Is the default value of the extension trace level for every request object. You can override this value by setting the extension-trace-level in a user-written extension. Setting the level to zero causes very little tracing. Setting the level to three causes considerable tracing. For more information about DHCP extension creation, see the "Extension Properties" section. Default 0. | |
The percentage of currently available (unreserved) addresses that the main server should send to the backup server to be used for allocations to new DHCP clients when the main server is down. The value is only meaningful in the main server. If it is defined in a backup server, it is ignored (to enable copying of configurations). Default 10 percent. | |
If failover is enabled server-wide, this is the DNS name of the backup server associated with all scopes that do not have an explicit failover-backup-server value configured. If this DNS name resolves to the IP address of the current server, then this server operates as the backup server for all of these scopes. It is an error if both the main and backup server names resolve to IP addresses that reside on the same server. Default none. | |
The percentage of currently available (unreserved) addresses that the main server should send to the backup server for scopes on which dynamic BOOTP has been enabled. For more information, see the "Failover Backup Percentage" section. Default none. | |
Is the multiple of the desired lease period used to update the backup server when the main server informs it of a new DHCP client lease period. For more information, see the "Failover-Lease-Period-Factor" section. Default 1.50. | |
If failover is enabled server-wide, this is the DNS name of the main server associated with all scopes that do not have an explicit failover-main-server value configured. If this DNS name resolves to the IP address of the current server, then this server operates as the main server for all of these scopes. It is an error if both the main and backup server names resolve to IP addresses that reside on the same server. Default none. | |
This is maximum client lead time, in seconds. The MCLT controls how much ahead of the backup server the client's lease expiration can be. You must define it in the main server. If you define it in the backup server, it is ignored (to enable copying of configurations). Default 3600 seconds (one hour). | |
Failover partners will poll one another at this interval (in seconds) in order to confirm network connectivity. Default 15 seconds. | |
The interval (in seconds) after which failover partners, who cannot communicate, will know that they have lost network connectivity. Default 60 seconds. | |
Controls whether the server performs initialization and then goes into RECOVER state. If server A is running, server B issues this command to ask for the state of server A. This property takes a time argument. You enter the time as month (name or its first three letters), day, hour (24 hour) year (fully specified year or last two digits), all enclosed in double quotes. For example, "Jun 30 20:00:00 1998". | |
This is the safe period, in seconds. It does not have to be the same on both main and backup servers. It only has meaning if you have enabled the failover-use-safe-period property. You must define it in the main server. Default is 24 hours. For more information see the Network Registrar Concepts Guide. | |
If you have specified a failover-safe-period, you have to enable the failover-use-safe-period property to cause Network Registrar to go into the PARTNER-DOWN state automatically. If you do not enable failover-use-safe-period, Network Registrar will never go into the PARTNER-DOWN state automatically, you must use the server dhcp setPartnerDown command. For more information, see the "setPartnerDown" section. | |
Causes the DHCP server to search all relevant policies for a subnet mask option, when constructing a response to send to a client. Normally, the DHCP server retains the subnet mask configured in the scope containing the base being granted to the DHCP client. Available values are true and false. Default is false. The default is false. For more information, see the "Example" section and the Network Registrar User's Guide. | |
Specifies the number of seconds Network Registrar guarantees that the last transaction time is accurate. The default is 30 seconds. Do not set it lower than 30 seconds. For optimal performance set it to a value that is greater than half your lease interval. For more about this property, see the "Defer Lease Extensions" section. | |
Controls whether the DHCP server logs additional detail about the events listed in the log-settings. This can be helpful when you are analyzing a problem, but leaving it enabled for a long period can cause the log files to fill up. Default incoming-packets, missing options. For more information about the different log settings, see the "Log Settings" section. | |
Controls the size of buffers DHCP allocates for responding to DHCP clients. At least 100 buffers of each type should be allocated, and perhaps as many as several thousand would be reasonable in some installations. Default 500. | |
Controls the size of buffers DHCP allocates for receiving packets from DHCP clients. At least 100 buffers of each type should be allocated, and perhaps as many as several thousand would be reasonable in some installations. Default 500. | |
Controls the size of buffers DHCP allocates for communication with DNS servers. You can reduce the DHCP server's memory requirement by reducing the number of DNS packets, at the risk of missing updates. Dafault none. | |
Controls the number of times the DHCP server can try to add a host into DNS even if it detects that the host's name is already present in DNS. This field controls the number of times the DHCP server will attempt to modify a host's name in order to resolve a conflict. Default 2. | |
Controls the number of times the DHCP server attempts to send dynamic DNS updates to a DNS server. Default 3. | |
Sets the Time To Live (TTL) ceiling, in seconds, for DNS records added through dynamic DNS. When the DHCP server adds a DNS record, it sets the TTL to less than one-third of the lease time, or this ceiling value. Note that the DNS record's effective TTL may be determined by the DNS zone's minimum TTL. Default 86400. | |
The number of buffers the server will allocate for sending and receiving ICMP ping messages. Default none. For more information, see the scope's ping-client's feature, see the "Scope Features" section. | |
Specifies whether the server saves the lease renewal time. If 1 is specified, the server saves the lease renewal time (i.e., the minimum time in which the client is expected to issue a lease renewal) as part of the lease in persistent memory. The default is 0 (no saving of the lease renewal time). | |
Specifies whether the server saves the vendor-class-identifier. If 1 is specified, the server saves the vendor-class-identifier as offered in the DHCP request's vendor-class-identifier option as part of the lease in persistent memory. The default is 0. (Do not save the vendor-class-identifier.) | |
The list of scope selection tags associated with this server property. In this context the term tags refers to a named entity that is used to control matching client and client-class entries with candidate scopes. Default none. |
To set the value of the get-subnet-mask-from-policy property, type:
nrcmd> dhcp set get-subnet-mask-from-policy=true
For all servers or scopes for which you have enabled failover, you need to set the failover-backup-percentage. This is the number of currently available (not reserved) leases that the backup server can use for allocations to new DHCP clients when the main server is down. You can use the default, which is 10 percent, or specify another value.
For scopes on which you have enabled dynamic BOOTP, you need to use the failover-dynamic-bootp-backup-percentage rather than the failover-backup-percentage property. The failover-dynamic-bootp-backup-percentage is the percentage of available addresses that the main server should send to the backup server for use with BOOTP clients.
The failover-dynamic-bootp-backup-percentage is distinct from failover-backup-percentage property, because if dynamic BOOTP is enabled on a scope, a server will never, even in PARTNER-DOWN state, grant leases on addresses that are available to the other server. Network Registrar will not grant leases because they may be given out by the partner using dynamic BOOTP, and can never safely be assumed to be available again.
In order to properly support dynamic BOOTP while using the failover protocol, do the following on every LAN segment in which you want BOOTP support:
For more information, see the Network Registrar Concepts Guide and the Network Registrar CLI User's Guide.
The failover-lease-period-factor controls how much ahead of the client the backup server's idea of the lease expiration can be. Whereas, the failover-maximum-client-lead-time controls how much ahead of the backup server the client's lease expiration can be.
The larger the value, the more independent the main server is of the operation of the backup and the less performance impact the failover protocol has on the main server. However, the larger the value, the longer the backup will have to wait to time-out an expired lease and re-use it for a different client in the event that the main fails and the backup takes over DHCP functions.
You must define this property for the scope in the main server. If it is defined in a backup server, it is ignored (to enable duplicating the configurations through scripts). The default is 1.5 which is a good value for most sites.
The lease period interacts with the lease renewal period. If you increase the lease renewal period to a value greater than 50 percent, you need to also increase the lease factor. There should be a ratio of 2:1 between the renewal and lease factor. For example if you increase the renewal time to 80 percent the lease factor should be 1.8.
You can set the following flags:
To suppress warning messages for unconfigured or missing options, type:
nrcmd> dhcp set log-settings=default,incoming-packets
To turn on client and client-class debugging for the DHCP server, type:
nrcmd> dhcp set log-settings=client-detail nrcmd> server dhcp reload
To turn off debugging for the DHCP server, type:
nrcmd> dhcp set log-settings=default nrcmd> server dhcp reload
As an additional aid to troubleshooting your configuration, you can use the example extension, dextrace, distributed on the Network Registrar CD. It looks for a particular MAC address in every input packet. When it finds that MAC address, it enables packet sniffing for just that input and any corresponding output packet. You can configure this extension using the CLI, and the configuration commands are in the example source file for dexextension.c. This extension places only a very small load on the server, and is suitable for long-term use when trying to diagnose some DHCP problem in which a troublesome MAC address is known, but it is not possible (or perhaps not convenient) to manually stimulate that DHCP client directly in order to find the problem.
Use the method commands attachExtension, detachExtension, and listExtensions to configure the extensions points in the server you have defined. You can name each extension point and associate one extension with it. For more information about extensions, see the "Extension" section.
The syntax is:
dhcp attachExtension extension-point extension-nameAfter you have defined an extension, use the attachExtension command to add the test extension at the extension point post-packet-decode by typing:
nrcmd>dhcpattachExtension post-packet-decode test
To remove the extension test from the extension point post-packet-decode, type:
nrcmd> dhcp detachExtension post-packet-decode
To list all the extensions points and any extensions associated with them, type:
nrcmd> dhcp listExtensions
The dhcp-interface command allows you to add, remove, and list the IP addresses of your server's hardware card (such as Ethernet or Token Ring), also called the Interface card. Interfaces are named with the IP address and net mask for the physical device.
You can list the interfaces to provide either an explicit list of interfaces that the DHCP server should listen on, or an explicit list of interfaces that the DHCP server should not listen on.
The dhcp-interface command provides more functionality than that is provided through the GUI, and in a different form:
The syntax is:
dhcp-interface ipaddr / maskbits create [prop=value]The maskbits parameter defined for scopes can be specified as 24 (for a 24-bit network, such as a 2.255.255.255.0 netmask) or 16 ( for a 16-bit network, such as a 255.255.00 netmask).
Table 2-13 lists and describes the DHCP interface properties.
| Property | Description |
|---|---|
The IP address of the interface. | |
Indicates that the server should ignore this interface, which might be the case if you had several interfaces. Use this property to temporarily disable a specific interface in a list of interfaces. | |
The subnet number. |
To create two different interface configurations, type:
nrcmd> dhcp-interface 192.168.1.12/24 create nrcmd> dhcp-interface 10.1.2.3/24 create
To cause Network Registrar not to look at one interface, type the following. Note that you must have created the interface specification before you can set it to be ignored.
nrcmd> dhcp-interface 10.1.2.3/24 set ignore=true
To delete the interface specification 10.1.2.3/24, type:
nrcmd> dhcp-interface 10.1.2.3/24 delete
To list all the specified interfaces, type:
nrcmd> dhcp-interface list
The dns command allows you to enable or disable DNS server features. Note that in Network Registrar there is only one DNS server per cluster, hence you do not need to reference the server by name.
The syntax is:
dns disable featureTable 2-14 lists and describes the DNS features.
| Feature | Description |
|---|---|
Required, default disabled. Configures the server to hide information about the subzone hierarchy for all zones delegated from this server. This feature collapses a portion of the domain namespace into one virtual zone. | |
Required, default enabled. Controls the incremental transfer behavior for zones for which you have not configured a specific behavior. For more information about incremental transfer, see the "Incremental Transfer" section. | |
Required, default disabled. Controls whether you want Network Registrar to notice and log when a DNS server listed in a parent-zone's delegation of subzones does not know that it is authoritative for the zone. | |
Required, default disabled. Controls whether you want the DNS server, when composing a response to a query, to fetch missing glue records. Glue records are DNS A records that specify the address of a domain's authoritative name server. Normal DNS responses include NS records and their A records related to the name being queried. | |
Required, default disabled. Controls whether you want to disable forwarding client queries to other name servers when your DNS server is not authoritative for data being queried. If you disable recursive queries, you make your name server a noncaching server. | |
Required, default enabled. Controls NOTIFY sending notification for zones for which you have not configured a specific behavior. For more information about NOTIFY, see the "NOTIFY" section. | |
Required, default enabled. Controls whether you want round-robin cycling of equivalent records in responses to queries. Equivalent records are records of the same name and type. Because clients often only look at the first record of a set, enabling this feature can help balance loads and keep clients from forever trying to talk to an out-of-service host. | |
Required, default disabled. Controls whether you want this server to be a slave server, which is a server that relies entirely on forwarders for data that is not in its cache. This command has no effect unless you also specify the corresponding forwarders. Note that you can override slave-mode for specific domains with the DNS exception method. For more information about the exception method, see the "Exception Method" section. | |
Required, default disabled, as implemented in BIND 4.9.7. Specifies whether you want the address records in responses to queries to be reordered based on the subnet of the client. Because clients often only look at the first record of a set, enabling this feature can help localize network traffic onto a subnet. This feature only applies on answers to queries from clients located on the same subnet as the DNS server. | |
Required, default disabled. Enables relaxation of the RFC 2136 restriction on the zone name record in dynamic updates. This feature allows updates to specify a zone name, which is any name within an authoritative zone, rather than the exact name of the zone. |
The incremental transfer feature (ixfr-enable) allows you to control how your DNS server handles incremental transfer. If you enable incremental transfer, you need to set or accept the default value of the ixfr-expire-interval property.
If you enable incremental transfer, you need to set or accept the defaults for the following property.
Table 2-15 lists and describes the incremental transfer property.
| Property | Description |
|---|---|
Required, default 604800 seconds (7 days). Indicates the longest interval to allow a secondary zone to be maintained solely with incremental transfers. After this period, the server requests a full zone transfer. Validation: 0 <= x <= 2147483647. |
To enable incremental transfer for all your zones, type:
nrcmd> dns enable ixfr-enable
To disable incremental transfer for the single secondary zone example.com, type:
nrcmd> zone example.com disable ixfr
To disable incremental transfer for the single remote-dns server (or subnet) 128.103.1.1, type:
nrcmd> remote-dns create 128.103.1.1 set ixfr=false
For more information about setting incremental transfer on specific zones or remote DNS servers, see the "Zone" section or the "Remote-Dns" section.
Because a master server for a zone does not know specifically which slaves transfer from it, Network Registrar notifies all registered name servers for the zone (name servers listed in the NS Resource Records) when the zone changes. The sole exception to this policy is that Network Registrar does not notify the server named in the SOA mname field (the primary master). For more information about NOTIFY, see RFC 1996.
If you enable NOTIFY, you need to set or accept the defaults for the following properties.
| Property | Description |
|---|---|
Required, default 100. The maximum number of changes you want to accumulate during the notify-wait period. If this number is exceeded, Network Registrar sends notification before the notify-wait period has passed. | |
Required, default 2 seconds. The minimum interval required before sending notification of consecutive changes on the same zone to a particular server. Validation: 0 <= x <= 2147483647. | |
Required, default 5 seconds. For secondary zones, the minimum amount of time between the completion of processing of one notification (serial number testing and/or zone transfer), and the start of processing of another notification. Validation: 0 <= x <= 2147483647. | |
Required, default 1 second. The interval to stagger notification of multiple servers of a particular change. Validation: 0 <= x <= 2147483647. | |
Required, default 5 seconds. The period of time to delay, after an initial zone change, before sending change notification to other name servers. This property allows you to accumulate multiple changes, and thus limit the number of times the serial number advances. Validation: 0 <= x <= 2147483647. |
To disable NOTIFY for all the zones, type:
nrcmd> dns disable notify
You can use IXFR and NOTIFY together, but you do not have to. You might want to disable NOTIFY for a quickly changing zone for which immediate updates on all secondaries does not warrant the constant NOTIFY traffic. Such a zone might benefit from having a short refresh time and a disabled NOTIFY.
nrcmd>zone example.com set refresh=30m nrcmd>zone example.com disable notify
For more information about setting zone properties, see the "Zone" section.
Use the set, get, and unset commands to assign and retrieve values from the DNS server's name-value properties.
The syntax is:
dns get propTable 2-17 lists and describes the DNS properties.
| Property | Description |
|---|---|
Required, default 53. Specifies the UDP and TCP port number on which the DNS server listens for queries. Validation: [1, 65535]. | |
Required, default 7 days. Indicates the maximum amount of time that you want Network Registrar to retain cached information. Validation: 0 <= x <= 2147483647. | |
Required, default 200 KB. Indicates the size of the in-memory record cache, in kilobytes. Validation: 0 <= x <= 2147483647. | |
Required, default 10 minutes. Indicates how long information learned from other name servers about non-existent names or data should be cached. Validation: 0 <= x <= 2147483647. | |
Required. Specifies the UDP and TCP port to which the DNS server sends queries to other servers. Validation: [1, 65535]. |
The dns method commands let you add, list or remove specific servers for dealing with root-hint servers, exception servers, forwarding servers, and flushing the cache.
The syntax is:
dns addRootHint name addr [addr]To add the root name server a.root-servers.net, type:
nrcmd> dns addRootHint a.root-servers.net 198.41.0.4
To remove the root name server a.root-servers.net, type:
nrcmd> dns removeRootHint a.root-servers.net
To list the root name servers, type:
nrcmd> dns listRootHints
The syntax is:
dns addException name addr [addr]For example, the sample company, QuickExample, has four subsidiaries: red, blue, yellow, and green. Each of them has its own domain under the.com domain. But when users at red.com. want to use resources at blue.com, their DNS server knows that it is not authoritative for blue.com., and thus attempts to locate blue.com. by asking the root name servers.
To use exception handling, the administrator at red.com. lists all the domains that users might want to access, and at least one corresponding name server. In this case, the administrator would list the three other domains for the QuickExample company.
To add the exception server blue.com., type:
nrcmd> dns addException blue.com. 192.168.1.4
To remove the name server blue.com., type:
nrcmd> dns removeException blue.com.
To list the name servers, type:
nrcmd> dns listExceptions
The syntax is:
dns addForwarder addr [addr]To add the forwarder server 192.168.1.4, type:
nrcmd> dns addForwarder 192.168.1.4
To remove the name server 192.168.1.4, type:
nrcmd> dns removeForwarder 192.168.1.4
To list the forwarder servers, type:
nrcmd> dns listForwarders
Use the dns flushCache command to stop the disk cache file from growing, but the actual behavior depends on whether your DNS server is running or stopped.
To completely clear a cache that has grown too large, stop the server, type the command, and restart the server.
The syntax is:
dns flushCacheUse the dns rebuildRR-Indexes command if you need to rebuild your resource records indexes. You might need to rebuild your resource records indexes, if you observe resource or host list data that appears inconsistent or if data appears to be missing.
Rebuilding your resource records should correct any inconsistencies.
The syntax is:
dns rebuildRR-IndexesThe exit command allows you to exit the current nrcmd program session. Network Registrar writes all your unsaved changes to the database. If Network Registrar is unable to save your changes, it displays the same error code as if you had used the save command.
The syntax is:
exitTo quit Network Registrar's command line interface when you are in interactive mode, type:
nrcmd> exit
The export command allows you to export Network Registrar DHCP and DNS server information.
The syntax is:
export addresses {file=CSV text file | database=data source name user=db user name password=db user password [config=config file] [table=table name} [mask-bits=integer] [dhcp-only] [time-ascii | time-numeric]The export addresses command allows you to export all active IP addresses into a specified database or CSV (comma-separated value) text file.
The syntax is:
export addresses [file=<CSV text file> | { database=<data source name>To specify the clusters that you want the export command to query, use the .nrconfig configuration file. This is the same configuration file that the report command uses. If there is an [export-addresses] section in the configuration file, the export command uses the clusters specified in that section instead of the default cluster.
When you run the export addresses command, its output depends on what you specify:
The time-ascii and time-numeric options specify how date/time fields are output to a CSV text file or when the timestamp data type is not supported by the target database. The default is time-ascii.
Each line of the file must either begin with the character # (comment), a section header enclosed in square brackets, or a parameter=value pair or its continuation.
[export addresses] clusters=machine1 username password, machine2 username password
Network Registrar strips leading white space from each line and ignores blank lines.
You can specify cluster in a variety of ways and Network Registrar follows a precedence order. Any of the specific cluster specifications can override the default specification or previous specification.
# Cluster information for export addresses[export addresses] # clusters=<clustername> <username> <password>,...clusters=host1 admin, host2,
host3 admin3 passwd3You should separate the three-cluster arguments with spaces. For long lines you can use continuation lines, that is, you do not need to use continuation escape indicators.
You can optionally specify a user name and password for the cluster. If you do not provide a user name or password for a particular cluster, Network Registrar uses the last user name or password listed. If you do not provide user names or passwords, Network Registrar uses the information from the command line -N and -P arguments, and then the NT Registry or environment variables AIC_NAME and AIC_PASSWORD.
If Network Registrar cannot find a user name or password or the supplied user name and password are incorrect, the lease-notification command issues a warning for that cluster.
The export addresses command attempts to establish communication with the clusters you have specified. It reports an error in the following cases:
The export addresses command writes the database output to the ip_addresses table or to the specified table name. Table 2-18 shows the columns in the ip_addresses table.
| Column | Data Type | May Be Null? | Description |
|---|---|---|---|
ip_address | unsigned integer | no | 32-bit IP address |
ip_text | varchar(15) | no | IP address in dotted decimal notation |
type | varchar(20) | no | STATIC, DYNAMIC, or RESERVED |
state | varchar(20) | no | Available, Assigned, Unavailable, Leased, Expired, de-activated, Released, |
cluster_name | varchar(256) | no | Cluster name from which the information came |
scope_pool_name | varchar(256) | yes | Scope name address (DHCP) from which the address was allocated |
failover-role | varchar(64) | yes | Failover role, if any, of leases |
subnet_bits | integer | yes | Number of bits in subnet mask for the scope |
dns_name | varchar(256) | yes | Fully qualified DNS name for assigned addresses |
requested_name | varchar(64) | yes | UNIX or WINS host name (DHCP) |
mac_address | varchar(256) | yes | MAC address as text |
client_id | varchar(256) | yes | Client ID for the lease (DHCP) |
client_class | varchar(256) | yes | Client-class name (DHCP) |
lease_state_change_time | timestamp | yes | Date/time when the lease last changed state (DHCP) |
lease_expiration_time | timestamp | yes | Date/time when the lease expires (DHCP) |
lease_transaction_time | timestamp | yes | Date/time of the last transaction (DHCP) |
The fields listed as "May be NULL" are null if the specified information is not available:
The mac_address field is a text field of the form type-length-hex:hex:hex..., such as "1,6,06:44:40:26:f5:0f". The type and length are both in decimal whereas the data is in hexadecimal.
Field data types that are not supported by the target database are replaced with text (varchar) fields with the formats listed in Table 2-19:
| Field Data Type | Text Replacement |
|---|---|
ip_address | varchar(10) in hexadecimal, such as "0x1234abcd" |
other integers | varchar(11) in decimal, such as "28" |
timestamp | varchar(26) as either a string of the form "Wed Jan 02 02:03:55 1980" if time-ascii is specified or an unsigned integer string of seconds since midnight GMT Jan 01 00:00:00 1970 if time-numeric is specified. Times are always in UTC. |
NULL | varchar(1) "" |
Column names that exceed the target database's supported maximum name width are truncated to the allowable width.
If you specify writing the output to a CSV text file, the export addresses command writes each line in the file as one row in the database. The export addresses command outputs each field to the text file in the order listed in Table 2-18. Each field is terminated by a comma, except for the last. The first line in the file is not a table row, but instead contains a "#" followed by the text of each of the column names separated by commas. All fields that require text substitution are handled as described in the previous section.
The export addresses command reports every address configured in every server that is specified in the config file. This includes addresses specified in DHCP scope ranges, DNS static addresses, and explicitly reserved addresses both for DNS and DHCP servers. Addresses in DHCP scope ranges that are not in use (allocated or reserved) however, do not appear in the table.
The report displays multiple entries for an address if the address is served by more than one server, in more than one scope, or has multiple DNS names. Thus you cannot use a unique column as a key, but you can generate a unique key from a set of columns such as ip_address, type, cluster_name, scope_pool_name, or dns_name.
The export leases command writes the state of the leases to a file. It has two modes: client-side and server-side.
The syntax is:
export leases [-server | -client] filename [time-ascii | time-numeric]The filename is the name of output file or "-" for standard out for client-side exports. You cannot use the dash with the -server option. In addition, the server-side export does not permit filenames with any non-alphanumeric character, such as "." for example.
The time-ascii and time-numeric options control which date/time format the export command uses. The default is time-ascii.
To export the client leases to the output file leaseOut, type:
nrcmd> export leases -client leaseOut
The export leases -client command writes out the lease time as a string, which is the day, month, date, time, year format, such as Apr 13 16:35:48 1998.
To export all the currently held and expired leases to the output file leaseOut, type:
nrcmd> export leases -server leaseOut
The export leases -server command writes out the lease times as integers, which are the number of seconds since midnight GMT Jan 1, 1970. For example, 903968580.
The export zone command writes the specified DNS zone into a file in the BIND format.
The syntax is:
export zone zone-name arguments output-fileFor example, to write the contents of the Example domain, type:
nrcmd> export zone example.com static hosts.local
The export zonenames command exports the names of the zones in the server. You can specify forward, reverse, or both to cause the command to export the forward zones, reverse zones, or all the zones, respectively.
The syntax is:
export zonenames {forward|reverse|both} output-fileThe export hostfile command creates a hostfile, in UNIX hostfile format, from all the zones in the server. It ignores reverse zones. It creates hostfile records from A records, CNAME records, and HINFO records. The hostfile record consists of the IP Address, the FQDN, aliases created from the A records and CNAME records, and comments created from HINFO records.
The syntax is:
export hostfile output-fileThe extension command allows you to configure and integrate user-written DHCP extensions into the DHCP server.
To extend the DHCP server with an extension, do the following:
1. Write the extension in either Tcl, C or C++, and install it in the server extensions directory.
UNIX:
For Tcl this is /opt/nwreg2/extensions/DHCP/tcl.
For C or C++ this is /opt/nwreg2/extensions/DHCP/dex
Windows NT:
For Tcl this is \program files\network registrar\extensions\dhcp\tcl
For C or C++ this is \program files\network registrar\extensions\dhcp\dex
It is best to place these extensions in the appropriate directory for TCL or C/C++ extensions. Then, when configuring the file name, just type the file name itself (with no "/" or "\").
If you want to place extensions in subdirectories, you must enter the file name with a path separator. These are different depending on the operating system on which your DHCP server is running.
When entering a file name that contains a "\" character on NT, you must enter it with a "\" (because "\" is an escape character for the CLI). For example, to enter the file name "debug\myextension.tcl."
2. Configure the DHCP server to recognize this extension, using the extension command.
3. Attach the configured extension to one or more DHCP extension points using the dhcp attachExtension command. For more information about the command, see the "DHCP Extension Commands" section. For more information about choosing extensions points and writing extensions, see "Using Extension Points."
4. Reload the server.
The syntax is:
extension name create lang file entry [prop=value]To configure a Tcl extension, type:
nrcmd> extension mytclext create Tcl mytclfile.tcl mytclentry
The contents of mytclfile.tcl might be:
proc mytclentry{request response environ}{
$environ log LOG_INFO "helloworld"
{
Use the set, get, and unset commands to assign and retrieve values from the extension's properties.
The syntax is:
extension name get propTable 2-20 lists and describes the extension properties.
| Property | Description |
|---|---|
Required (set by create), default none. The name of the entry point for the module. This function is called from any extension point to which this module is bound. The arguments for this function are server-implementation specific. | |
Required (set by create), default none.This file name is relative to the directory extensions in the installation. It cannot be a absolute pathname, nor can it contain any sequence of two dots (..). | |
Optional, default none.The arguments that should be passed to the init-entry point function. For more information about how the DHCP server parses this information, see the "The Init-Entry Entry Point" section. | |
Optional, default none.The name of the init-entry point. If you set it, Network Registrar calls this function when the server loads the module and when the server shuts down. For more information about this entry point, see "The Init-Entry Entry Point" section. | |
Required (set by create), default none. The language in which the extension or module is implemented. Tcl indicates that the module is a Tcl extension (tcl7.5). Dex indicates that the module is a shared object with C calling interfaces. | |
Required (set by create), default none. The name of the extension or module. Network Registrar uses this name to assign extensions or modules to extension points. Changing this property renames the extension. |
The nrcmd program uses the same locking mechanism as Network Registrar. When you execute a command, the program attempts to get an exclusive lock for the cluster to which it is connected. If it is unable to get an exclusive lock, it displays a warning. You can only issue the following commands: client, lease, zone add, help, and force-lock.
The force-lock command obtains an exclusive lock. Use this command with caution, because running more than one program that updates the Network Registrar database can cause database corruption.
If you use the force-lock command to unlock a cluster, the command writes the warning to the log file on the client machine not on the cluster.
To force an exclusive lock, type:
nrcmd> force-lock
The help command allows you to display the nrcmd program's online help.
You can select the sections of the man page output by specifying the section names after the help cmd command. The section names are:
The syntax is:
helpTo print the list of commands, type:
-> help 100 Ok
To print the contents of the help man page, type:
-> help help 100 Ok
To print the contents of the help command's synopsis, type:
-> help help synopsis
100 Ok
SYNOPSIS
help
help <cmd> [<section>...]
The import command allows you to import lease information into the DHCP server configuration or import the contents of a BIND named.boot file into the DNS server configuration.
Before you can import leases, you need to perform several configuration steps:
1. Configure scopes in the DHCP server for the leases that you plan to import. For more information, see the "Scope" section.
2. If the host names for the leases are to be dynamically entered into DNS as part of the import, configure zones in the DNS server to allow dynamic updates. For more information, see the "Zone" section.
3. Set the DHCP server to import mode so that it will not respond to other lease requests during the lease importing. For more information, see the "Dhcp" section.
After you have imported the leases, take the DHCP server out of import mode so that it can respond to other lease requests.
The syntax is:
import leases fileTo import the file LeaseIn to the DHCP server, type:
nrcmd> import leases LeaseIn
If the lease time in the import file is greater than the lease time the client would have received if it were to acquire a lease, the client is given the lesser lease time. In other words, suppose it is 2 p.m. and your scope is configured for a one hour lease. According to the file you are importing, the lease time will not expire until 5 p.m. After you import the file, the lease will expire at 3 p.m., not 5 p.m.
If your import file specifies a zone name, the zone name will not be used when DNS is updated. If it specifies a host name, the host name will be used when DNS is updated, unless overridden by a host-name specification in a client or client-class entry.
The only way to indicate to the DHCP server that the client's host name should be placed in a zone other than the default associated with the scope, is to specify that zone in a client or client-class entry.
The syntax is:
import named.boot fileTo import the file /etc/named.boot to the DNS server, type:
nrcmd> import named.boot /etc/named.boot
You should use "UNIX style" paths even when running the import command on Windows NT. The previous example on Windows NT might look like this:
nrcmd> import named.boot c:/etc/named.boot
There is one known incompatibility between the way BIND loads named.boot configurations and the way the nrcmd command loads named.boot configurations.
When a zone file contains an $INCLUDE directive, BIND searches for the include file relative to the directory specified by the directory directive in the named.boot file, whereas the nrcmd program searches for the include file relative to the directory containing the zone file being processed.
You can avoid this problem completely if your BIND configuration uses absolute paths whenever specifying an include file in a zone file. If your zone files contain relative paths when specifying include files and the directory containing the zone file is not the same as the directory specified by the directory directive in the named.boot file, your configuration will not load properly. You will need to convert the relative paths in your zone files to absolute paths to import your BIND configuration into Network Registrar. An example of a configuration and how it might be fixed follows.
/etc/named.boot
/usr/local/domain/primary/db.example
/usr/local/domain/primary/db.include
/usr/local/domain/secondary
/etc/named.boot:
# BIND searches for zone files and include files relative to
# /usr/local/domain
directory /usr/local/domain
# BIND finds zone file in /usr/local/domain/primary primary
example.com primary/db.example
# end of /etc/named.boot
# BIND searches for include file relative to /usr/local/domain
$INCLUDE primary/db.include
# end of /usr/local/domain/primary/db.example
To make the configuration loadable, change the relative path in the file db.example to an absolute path.
$INCLUDE primary/db.include
$INCLUDE /usr/local/domain/primary/db.include
Table 2-21 lists and describes the boot file directives that are supported by the BIND 4.9.6 distribution and the corresponding nrcmd command syntax that is generated. Directives that Network Registrar does not support are marked with the word unsupported, and the directives that require no action from Network Registrar are marked with the word none.
Table 2-21 lists the BIND to nrcmd commands.
| BIND | Nrcmd |
|---|---|
directory new-directory | None supported within the named.boot file parser |
include file | None supported within the named.boot file parser |
primary domain-name-of-zone file | zone create domain-name-of-zone primary file=file |
secondary domain-name-of-zone ip-addr-list [backup-file] | zone create domain-name-of-zone secondary ip-addr [,ip-addr...] |
forwarders ip-addr-list | dns addForwarder ip-addr [ip-addr...] |
slave | dns enable slave-mode |
tcplist ip-addr-or-network-list | zone domain-name-of-zone enable restrict-xfer zone domain-name-of-zone set restricted-set=ip-addr [,ip-addr...] |
xfernets ip-addr-or-network-list | zone domain-name-of-zone enable restrict-xfer zone domain-name-of-zone set restricted-set=ip-addr [,ip-addr...] |
max-fetch number | dns set xfer-client-concurrent-limit=number |
domain local-domain-name | unsupported |
cache domain-name file | unsupported |
sortlist network-list | unsupported |
stub domain ip-addr-list [backup-file] | unsupported |
bogusns ip-addr-list | unsupported |
check-names primary/secondary/response fail/warn/ignore | unsupported |
options forward-only | dns enable slave-mode |
options no-recursion | dns enable no-recurse |
options no-fetch-glue | dns enable no-fetch-glue |
options fake-iquery | None---Network Registrar only supports fake iquery |
options query-log | unsupported |
limit transfers-in number | dns set xfer-client-concurrent-limit=number |
limit transfers-per-ns number | unsupported |
limit datasize number | unsupported |
limit files number | unsupported |
The ldap command allows you to associate remote LDAP servers with Network Registrar, and then set their attributes.
The syntax is:
ldap name create hostname [prop=value]To create an LDAP server object myserver with a host name of myserver.mycompany.com, type:
nrcmd> ldap myserver create myserver.mycompany.com
To delete an ldap server object myserver, type:
nrcmd> ldap myserver delete
To list the ldap server objects, type:
nrcmd> ldap list
Use the enable, disable, or get commands to enable, disable, or determine whether the feature has been set.
The syntax is:
ldap name disable featureTable 2-22 lists and describes the LDAP features. After you enable a feature you can set its properties.
| Feature | Description |
|---|---|
Optional, default false. Enables you to create entries for the LDAP server. When you enable can-create, you must enable can-update as well. | |
Optional, default false. Enables you to define queries to the LDAP server. | |
Optional, default false. Enables you to specify the types of updates to the LDAP server. | |
Optional, default false. Enables you to limit the number of outstanding queries to the LDAP server. If you enable this feature you can set the maxprequest property. |
Use the set, get, and unset commands to assign and retrieve values from the LDAP server's properties.
The syntax is:
ldap name get propTable 2-23 lists and describes the LDAP properties.
| Property | Description |
|---|---|
The number of connections that the server should make to a particular LDAP server. This is primarily a performance-tuning parameter. In some cases, more than one connection can improve overall throughput. | |
Specifies the names of the object classes that a newly created entry inherits. | |
Creates a separate string dictionary to contain attributes that with values not in the lease object. This allows the addition of attributes containing an arbitrary text string. | |
Allows you to specify a string that is assigned to any LDAP attributes, listed in the create or update dictionaries, that do not have their matching lease attribute present. These LDAP attributes can be listed in the create update dictionaries. If you specify no value, Network Registrar uses the string <default>. | |
If the dn (distinguished name) of the LDAP object to update (or create) can be constructed from one of the lease attributes, the specified dn-attribute is formatted using the dn-format string to construct the object filter that specifies the LDAP server to be modified. | |
Specifies the dn (distinguished name) for entry creation. A %s is required and is replaced with the value of the dn-attribute. | |
Formats the dn-attribute. A %s is required and is replaced with the value of the dn-attribute. | |
The host name of the server to connect to. Network Registrar needs the host name for LDAP servers. | |
The limit on the number of LDAP referrals Network Registrar will follow when querying. A value of zero means "don't follow referrals." | |
Limits any single LDAP connection to this number of outstanding queries. You may choose to limit the number of outstanding queries to improve performance. The DHCP server uses this configuration information when preparing client-entry queries. | |
The password of a user with access to the parts of the directory that DHCP will use. (LDAP servers can be configured to allow anonymous access, so this is optional.) | |
The port to connect to. (There is a default.) | |
A positive integer. LDAP servers can be used in preference order: 1 is the highest preference value. | |
The name of the LDAP attribute that may indicate that an LDAP response is a referral. The referral may or may not contain the dn to query for. If the dn is present (the current server assumes this), it is used as the search path along with a wildcard search scope in the query that follows the referral. If not, the search path is built by formatting the data in the referral attribute with the referral filter, and the existing search scope is used. | |
If the referral attribute does not contain a dn, the referral-attribute's data is formatted with this filter expression to build a search path, and the existing search scope for the LDAP server is used. | |
The filter to be applied in the query. A %s is required and is replaced by the value of the dn attribute. | |
The name of an object in the directory to use as a query's starting-point. The path and the scope together control the portion of the directory that are searched. | |
The scope can be SUBTREE (all children of the search path will be searched), ONELEVEL (only one the immediate children of the base object will be searched), or BASE (only the base object will be searched). | |
The number of seconds the DHCP server should wait for a response to an individual query. After a query times out, the server may re-try another LDAP server connection, or drop it. | |
The interval (in milliseconds) at which each LDAP client connection polls for results, if it has outstanding queries or updates. | |
If the LDAP object's dn cannot be determined directly, the DHCP server must issue a query to retrieve the dn. In that case, the DHCP server uses these parameters to extract the data from a lease attribute (specified by the search-attribute, and format it using the search-filter expression). | |
Formats the update-search-attribute. A %s is required and is replaced with the value of the dn-attribute. | |
The search filter (built using either the dn attribute or the search attribute) is used along with the path and scope to specify the LDAP object that should be updated. | |
The search scope is used to specify the LDAP object that should be updated. | |
The distinguished name of an object with access to the parts of the directory that DHCP will use. (Because you can configure LDAP servers to allow anonymous access, this property is optional.) |
The create-string-dictionary can contain multiple pairs of LDAP attributes. To assign different string values to the attributes givenname and carlicense, type:
nrcmd> ldap test-server setEntry create-string-dictionary givenname="abcdefg" nrcmd> ldap test-server setEntry create-string-dictionary carlicense="123-456"
Use the setEntry, getEntry, and unsetEntry commands to set, query, and clear elements of the various dictionary properties in the LDAP server configuration. These dictionary properties provide a convenient mapping from strings keys to string values.
The syntax is:
ldap name setEntry prop key=valueTable 2-24 lists and describes the LDAP dictionary properties.
| Properties | Description |
|---|---|
Creates a dictionary that maps LDAP attributes to DHCP lease attributes. This property describe a set of attributes to be written for entry creation and may contain lease attribute references. | |
Creates a string dictionary of attributes with literal values not contained in the DHCP lease object. You can then assign arbitrary text strings to these attributes. This property is useful if you want to search for the attributes using the text string. | |
Controls whether additional LDAP attributes are retrieved along with client-entry attributes. If any of these are present in a query's results, their values are made available to scripts through the request's environment dictionary. The LDAP value is keyed by the value in the LDAP query env-dictionary. | |
Controls the mapping between the names of LDAP attributes and client-entry attributes. The server attempts to retrieve all of the LDAP attributes specified in the dictionary. When a query succeeds, the values for any LDAP attributes that it returns are set in the corresponding client-entry attributes. This property 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 more information, see Chapter 11 of the Network Registrar User's Guide. | |
The dictionary that maps LDAP attributes to DHCP lease attributes. When an LDAP object is modified, each LDAP attribute that is present in this dictionary is set to the value of its corresponding DHCP lease attribute. |
To configure a query-dictionary to search for the surname (sn) and use its data to specify the client's DHCP host name, type:
nrcmd> ldap dirserver setEntry query-dictionary sn=host-name
To configure a query-dictionary to search for the first name (givenname) to use for the specific client-class name, type:
nrcmd> ldap myserver setEntry query-dictionary givenname=client-class-name
To configure a query-dictionary to search for the localityname to use for the domain name, type:
nrcmd> ldap myserver setEntry query-dictionary localityname=domain-name
To create a string-dictionary with an attribute named myattribute assigned to the string my string, type:
nrcmd> ldap myserver setEntry create-string-dictionary myattribute="my string"
The lease command allows you to view and manipulate the current DHCP leases in the cluster.
The syntax is:
lease listTable 2-25 lists and describes the lease command actions.
| Action | Description |
|---|---|
Removes the de-activate flag from the lease, but does not change the status of a lease marked as unavailable. | |
Prevents the lease from being given out or renewed, but does not change the state of the lease. | |
Makes a currently held lease available, even a lease marked as unavailable. Because using the force-available action may compromise the integrity of your IP address allocations, make sure that before you use the command the client holding the lease has stopped using the lease. | |
Displays the most recent MAC address associated with this lease. If no MAC address was ever associated with this lease (or if the lease has become unavailable), then Network Registrar displays the error message, "302 Not Found." | |
Displays the lease attributes for a specific address. | |
Lists all leases that are associated with the specified MAC address. |
All lease command actions take effect immediately. You do not need to reload the server.
To activate lease 192.168.1.9, type:
nrcmd> lease 192.168.1.9 activate
Use get to display the values from the lease properties. These properties are read-only.
The syntax is:
lease name get propTable 2-26 lists and describes the lease command properties.
| Properties | Description |
|---|---|
The IP address of this lease. | |
The DHCP server attempted (possibly successfully) to enter this name into the DNS server for this client. It is related to the client-host-name, but may not be identical due to name collisions in the DNS server database. | |
The domain name specified (if any) into which to put the client's DNS name. | |
A variety of flags relating to the client. For more information about these flags, see the "Client Flags" section. | |
The DNS name that the client requested the DHCP server place into the DNS server. | |
The client-id specified by the client, or one synthesized by the DHCP server for this client (if client-id-created-from-mac-address is set in the client-flags). | |
The time at which the client most recently contacted the DHCP server. | |
The MAC address which the client presented to the DHCP server. | |
The time at which the lease will expire. | |
Flags for the lease are either "reserved" or "de-activated." The lease is reserved for some MAC address or the lease is de-activated, which means that it should not be used. Any clients that are using de-activated leases will be NAK'ed on their next renewal. | |
The minimal time in which the client is expected to issue a lease renewal. | |
The time at which the state last changed to its current value. Use this property to determine when the lease was made unavailable. | |
The current state of the lease. |
Use the following client flags:
The following flags are for internal use only: client-valid, client-fqdn-present, client-updates-name, clear-host-name, host-name-has-changed, and domain-name-has-changed.
The lease-notification command allows you to receive notification when the number of available addresses in a scope is exceeded. You can specify the notification limit either as the number of free addresses or the percentage of free addresses. You can also specify who will receive e-mail notification.
The syntax is:
lease-notification available=number|percentage%Although you can use the lease-notification command interactively, its primary use is as an automated command. For more information, see the "Running Lease-notification Automatically on UNIX" section and the "Running Lease-notification Automatically on NT" section.
To specify scope 1 with an available value of 10% and e-mail recipients billy, joe, and jane, type:
nrcmd> lease-notification available=10% scopes=scope1 recipients=billy,joe,jane mail-host=mailhost
To specify the range of scopes 192.32.1.0-192.32.1.255, the config file .nrNotification, the recipients admin, an available value of 13 leases, and the NT mail host as mailhost, type:
nrcmd> lease-notification scopes=192.32.1.0-192.32.1.255
config=/home/bob/.nrNotification recipients=admin@comco.com available=13
mail-host=mailhost
Table 2-27 lists and describes the lease-notification command properties.
| Property | Description |
|---|---|
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. | |
Specify a configuration file. If you do not specify a configuration file, Network Registrar searches for the default .nrconfig file. For more information about the search order, see the "Specifying the Config File" section. | |
If you specify a mail-host, you may also specify the e-mail address of the sender of the e-mail in order to provide a return path for bounced e-mail. The default value is postmaster. | |
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 the following conditions applies:
|
On NT, 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. | |
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. | |
Specify the scopes either by their names or as a range or ranges of addresses. Network Registrar checks any scope containing any address that falls within the range of address. If you do not list any scopes or addresses, Network Registrar checks all scopes managed by the specified cluster. |
Each line of the file must either begin with the character # (comment), a section header enclosed in square brackets, or a parameter=value pair or its continuation. Network Registrar strips leading white space from each line and ignores blank lines.
You can specify cluster in a variety of ways and Network Registrar follows a precedence order. Any of the specific cluster specifications can override the default specification or previous specification:
# Cluster information for lease notification[lease-notification] # clusters=<clustername> <username> <password>...clusters=host1 admin, host2,
host3 admin3 passwd3Note that you should separate the three-cluster arguments with spaces. For long lines you can use continuation lines, that is, you do not need to use continuation escape indicators.
You can optionally specify a user name and password for the cluster. If you do not provide a user name or password for a particular cluster, Network Registrar uses the last user name or password listed. If you do not provide user names or passwords, Network Registrar uses the information from the command line -N and -P arguments, and then the NT Registry or environment variables AIC_NAME and AIC_PASSWORD.
If Network Registrar cannot find a user name or password or the supplied user name and password are incorrect, the lease-notification command issues a warning for that cluster.
You can run the lease-notification command periodically by means of the cron(1) command by supplying crontab(1) with the command to run. For example, to run the lease-notification command at 00:15 and 12:15 (15 minutes after midnight and noon) Monday through Friday, specify the following command to crontab:
15 0,12 * * 1-5 . .profile; /opt/nwreg2/usrbin/nrcmd lease-notification available=10\% config=/home/jsmith/.nrconfig addresses=192.32.1.0-192.32.128.0 recipients=jsmith,jdoe@example.com >/dev/null 2>&1 You can perform crontab editing by running the UNIX crontab -e command. Set your EDITOR environment variable before running the command, unless you want to use ed(1). See the crontab(1) man page for additional details.
Note that you must supply the nrcmd command's full path name on the crontab command line. You can determine the full path name in your environment with the UNIX which nrcmd command.
Also note that when you run the nrcmd lease-notification command by means of crontab, the user environment variables AIC_CLUSTER, AIC_NAME, and AIC_PASSWORD are ignored. Because the command being run could be viewed by others, for security reasons you should not provide the password through the -P option on the command line.
The cluster name, user, and password information for the cluster you want the nrcmd command to run from should be supplied in a .profile or other file in the home directory of the user running crontab -e, as shown in the following example:
AIC_CLUSTER=host1 export AIC_CLUSTER AIC_NAME=admin1 export AIC_NAME AIC_PASSWORD=passwd1 export AIC_PASSWORD
The file must be read explicitly in the crontab entry with . .profile specification. Note that the first "." is the shell command that causes the file to be read and must be followed by white space. For notification on a different cluster, or clusters, than the one on which ncrmd is running, you need to specify the following information:
You can prevent others from examining or changing the contents of the .profile and the configuration file you create by changing its permissions with the UNIX command chmod go-rw config_file.
Use the Scheduled Tasks service available in Windows NT Explorer under My Computer to schedule the nrcmd lease-notification command. If you do not find a Scheduled Tasks folder under My Computer, you will need to add this optional component from Microsoft Internet Explorer 4.0 or later, or use some third-party task scheduler. You can also use the at command to schedule the nrcmd lease-notification command. Put multiple entries into the at queue, one for each time of day at which you want to run the job.
The license command allows you to specify the license key for a cluster, or to view the license key or the license's expiration date.
Your license key is located on the back of the Cisco Network Registrar 3.0 CD case. You need to enter your license the first time you configure any cluster.
The syntax is:
license set prop=valueTable 2-28 lists and describes the license command properties.
| Properties | Description |
|---|---|
The expiration date of the license. Note that the date is read-only. | |
The license key |
To set the license, you must run the nrcmd program in interactive mode, then exit and rerun the nrcmd program. To set the license to key 1234 abcd 5678 efgh, type:
nrcmd -C cluster1 -N admin -P aicuser nrcmd> license set key=1234-abcd-5678-efgh 100 Ok nrcmd> exit
The listaddr command provides the address utilization reporting functionality of the listaddr.bat command available in earlier versions of Network Registrar. Because the output from this command was designed for analysis tools such as spreadsheets, the formatting is not ideal for end-users.
In future releases of Network Registrar, the listaddr command will no longer be supported. You should instead use the export addresses command. For more information, see the "Export Addresses" section.
The output for the listaddr command is a series of eight-column, comma-separated rows. There is one row for each known address. Thus, the total output can be quite verbose. A column may be empty if the usage of that column does not apply to the address. Table 2-29 lists and describes the meanings of the columns.
| Column | Description |
|---|---|
1 | IP address in unsigned hexadecimal format. |
2 | IP address in the canonical dotted format. |
3 | Type of the address. These types are defined as follows: |
STATIC---assigned to a host through DNS. | |
DYNAMIC---assigned to a host through a DHCP lease. | |
UNALLOCATED---the address is in the range of a DHCP scope, but is not in use. | |
RESERVED---the address is reserved for a host through DHCP. | |
4 | DNS name of host, for assigned addresses only. |
5 | State of the address. This field is blank for any address other than those assigned through DHCP leases. The values for such addresses are: Available, Unavailable, Leased, Expired, de-activated. |
6 | Native host name, for addresses assigned through a DHCP lease. This is usually the Windows or UNIX name for the host. |
7 | MAC address, for addresses assigned through a DHCP lease. |
8 | Expiration time, for DHCP dynamic addresses. |
The syntax is:
listaddrTo run listaddr, type:
nrcmd> listaddr
The policy command allows you to configure DHCP policy configurations. A policy is a collection of DHCP option values that can be associated with a range of addresses in a scope, or with a specific client or client-class configuration.
The syntax is:
policy name create [prop=value]To create the policy CompanyB, type:
nrcmd> policy CompanyB create
You can enable, disable, or determine whether the feature has been set. You use the enable, disable, or get commands.
The syntax is:
policy name enable featureTable 2-30 lists and describes the policy features. For more information about lease time, see "Lease Times" section.
| Feature | Description |
|---|---|
Optional, default true Clients may request a specific lease time. The server will not honor those requested lease times if this attribute is false. The server will not honor a client's lease time if the time is longer than the server's normal lease time. | |
Optional, default false. Specifies that leases for this client should be permanently granted to requesting clients. | |
Optional, default false. Controls whether the server uses the value of the server-lease-time property to determine the length of a lease, rather than using the lease time returned to the client. |
Use the set and get commands to assign and retrieve values from the policy's properties.
The syntax is:
policy name get propTable 2-31 lists and describes the policy properties.
| Property | Description |
|---|---|
Optional, default none. A list of the names of options that should be returned in any replies to BOOTP clients. The options themselves do not have to have been configured in the same policy as the reply-options list; the server will search the hierarchy of policies for each option named in the list. For more information about this property, see the "Policy Reply Options" section. | |
Optional, default none. Supplies the name of the executable file from which to boot or obtain configuration data. This property can also contain the following variable substitution values:
| |
Optional, default none A list of the names of options that should be returned in any replies to DHCP clients. The options themselves do not have to have been configured in the same policy as the reply-options list; the server will search the hierarchy of policies for each option named in the list. For more information about this property, see the "Policy Reply Options" section. | |
Optional, default 5 minutes. The length of time between the expiration of a lease and the time it is made available for re-assignment. | |
Optional, default 2 minutes. If the server offers a lease to a client, but the offer is not accepted, the server will wait the specified number of minutes before making the lease available again. | |
Optional, default none. The name of a boot file to be used in a client's boot process. The server returns this file name in the 'file' field of its replies. The packet-file-name cannot be longer than 128 characters. This property can also contain the following variable substitution values:
| |
Optional, default none. The host name of a server to use in a client's boot process. The server returns this file name in the sname field of its replies. The packet-server-name field cannot be longer than | |
Optional, default none. The IP address of the next server in a client's boot process. For example, this might be the address of a TFTP server used by BOOTP clients. The server returns this address in the siaddr field of its reply. | |
Optional, default none. The time that the server believes the lease is valid. It may be useful to have the server consider leases leased for a longer period than the client in order to get more frequent client communication along with the stability of long lease times. | |
vendor-class-identifier | Optional, default none. This property is used by clients and servers to exchange vendor-specific information. The information is an opaque object of n octets, presumably interpreted by vendor-specific code on the clients and servers. The vendor is indicated in the vendor-class-identifier option. |
To set the grace period to three days for policy 168.1-net, type:
nrcmd> policy 168.1-net set grace-period=3d
When the server is getting ready to return option data to a client, it examines up to seven policies: the client's embedded policy, the client's policy, the client's client-class's embedded policy, the client's client-class's policy, the client's lease's scope's embedded policy, the client's lease's scope's policy, and the system default policy, in that order.
Then the server looks through the policies for a reply-options list. It looks for bootp- or dhcp-reply-options depending on the client. The server uses the first list it finds. For each option in the list, the server looks through all of the policies, in order, and returns the data from the first policy that has a matching option. There is no requirement that the data that the server returns must come from the same policy that the reply-options list came from. If the server finds a reply-options list, it looks for each option in the list individually, and searches all of the related policies if necessary.
There is also no requirement that the options mentioned in a reply-options list be present in the policy that contains the list. The nrcmd program allows you to type in a string, and that string can name any option. The Network Registrar GUI, however, presents a special dialog box for adding a reply-options property to a policy that restricts you to the options already configured in the policy. This is a GUI-only restriction; the server does not impose this restriction.
You can set individual option values with the setOption command, unset option values with the unsetOption command, and view option values with the getOption and listOptions commands. When you set an option value, the DHCP server replaces any existing value or creates a new one, as needed, for the given option name.
The syntax is:
policy name listOptionsTable 2-32 lists and describes the policy options.
| Property | Description |
|---|---|
Lists the options in the named policy. | |
Sets the option name and value to the specified policy. The format is optname value. For example, dhcp-lease-time 3600. | |
Gets the value of the named option. | |
Removes the named option from the specified policy. |
To specify the lease time in a scope, type:
nrcmd> policy 168.1-net setOption dhcp-lease-time 608400
To list the options in a policy, type:
nrcmd> policy 168.1-net listOptions
The setLeaseTime command allows you to set the values of lease times and the getLeaseTime command to display the value of a lease time.
The syntax is:
policy name setLeaseTime valueThe lease time is the value of the dhcp-lease-time option. You should specify the time in seconds.
A policy contains two lease times: the lease time and the server lease time.
You might want to establish these two different lease times if you want to retain information about clients' DNS names and yet have them renew their leases frequently. When you use a single lease time and it expires, the server no longer keeps that client's DNS name. If, however, you use a short client lease time and a longer server lease time, the client information is retained even after the client's lease has expired.
The remote-dns command allows you to control the behavior of the DNS server when it is communicating with other DNS servers. Use it to either control incremental transfer or to send multiple records per TCP packet.
The syntax is:
remote-dns create addr [ /maskbits] [prop=value]Table 2-33 lists and describes the remote-dns properties.
| Property | Description |
|---|---|
The address of the server or network to which this information applies. | |
The number of bits in the addr attribute that are significant. |
To create the remote server description 128.103.1.1 with the net mask of 255.255.255.255, type:
nrcmd> remote-dns create 128.103.1.1/16
You can enable, disable, or determine whether the feature has been set. You use the enable, disable, or get commands.
remote-dns name disable featureTable 2-34 lists and describes the remote DNS server description features.
| Feature | Description |
|---|---|
Optional, default false. Indicates whether or not a foreign server supports incremental transfer and should be queried for incremental (IXFR) before full (AXFR) when asking for zone transfers. Although unwittingly setting this to true is generally harmless, doing so may result in additional transactions to accomplish a zone transfer. | |
Optional, default false. Indicates whether or not a remote server can be sent zone transfers (AXFR) with multiple records in one TCP packet. Older DNS servers will crash when receiving such transfers, despite being allowed by the protocol. |
When you enable or disable incremental transfer, Network Registrar looks for the most specific match, that is, it matches the machine with the longest mask. Use this feature to specify a group of servers with a single command.
To enable all DNS servers on this network to perform incremental transfer, type:
nrcmd> remote-dns create 128.103.1.0/16 ixfr=true
To disable all DNS servers 128.103.1.1/32 from performing incremental transfers, type:
nrcmd> remote-dns create 128.103.1.1/32 ixfr=false
The report command allows you to produce a summary of dynamic and static IP address utilization for one or more clusters.
The syntax is:
report [config=config file][column-separator=character string] [dhcp-only][file=output file][leasing-only]Table 2-35 lists and describes the report properties.
| Property | Description |
|---|---|
Specifies the character string you want used between the columns in the report. The default is a single space. If you specify whitespace, you must escape it with a backslash (\) and if it is entered on the command line, use quotes. For example, =,\ or = ",\". | |
A file that allows you to specify multiple clusters. | |
Specifies a summary of just the DHCP information. | |
Specifies the file name to which the report command writes the output. If you do not specify a file name, the report command writes to standard out. Note that, because it can take a long time to collect DNS data, you should not run the report command interactively when requesting DNS summaries. | |
Specifies that only scopes that are able to offer leases appear in the report. If failover is enabled, this includes scopes for which one of the following conditions applies:
| |
Specifies the number of high-order bits set in the network mask that define a logical subnet for which the report command produces a summary. The default value is 16. If the value of the mask-bits is less than the default or less than the largest mask of any scope's mask in the report, the report command uses the default value. |
To create a report of static DNS addresses and dynamic DHCP addresses, type:
nrcmd> report
To create a report of only DHCP scopes, type:
nrcmd> report dhcp-only
You can specify cluster in a variety of ways and Network Registrar follows a precedence order. Any of the specific cluster specifications can override the default specification or previous specification.
# Cluster information for summary reports [report] # clusters= clustername username password, ...clusters=host1 admin, host2, host3 admin3 passwd3You should separate the three cluster arguments with spaces. For long lines use continuation lines, that is, you do not need to use continuation escape indicators.
You can optionally specify a user name and password for the cluster. If you do not provide a user name or password for a particular cluster, Network Registrar uses the last user name or password listed. If you do not provide user names or passwords, Network Registrar uses the information from the command line -N and -P arguments, and then the NT Registry or environment variables AIC_NAME and AIC_PASSWORD.
If Network Registrar cannot find a user name or password or the supplied user name and password are incorrect, the report command issues a warning for that cluster.
The report command displays a row of information for each subnet specified by scope or deduced from DNS static address assignments outside of scopes.
The report command displays subtotal rows when more than one scope shares a common subnet, and for addresses that share a common subnet as specified by their address and mask. Note that the report commands assumes that there is no overlap between static addresses and scope ranges.
For each scope or subnet, the report command displays the following information:
For each scope-specified subnet, the report command also displays the following values:
Addresses have both a current state and a pending state after their lease expires.The categories leased and unavailable represent current states. The categories dynamically leased, reserved, and de-activated may represent current or pending states. The category free represents the current state available minus addresses flagged reserved or de-activated. Note that, the leased category overlaps other categories and is not incorporated in the scope total.
For each subtotal row, the report command provides summaries of any scope values in the subnet, and additionally, displays the following values:
The grand total, at the end of the report a total that summarizes all the data in the subnets
The rows and columns in Table 2-36 represent potential states and flags that an address within a DHCP scope can possess. The cells within the table indicate the category into which Network Registrar places addresses with a given state and flag. When multiple flags are set, de-activated takes priority over reserved, and reserved takes priority over any remaining flags for reporting purposes.
Table 2-36 lists and describes the potential states and flags for IP Addresses.
| Flags | None | Reserved | de-activated | Reserved and de-activated |
|---|---|---|---|---|
State |
|
|
|
|
available | free | reserved | de-activated | de-activated |
offered | dynamically leased, leased | dynamically leased, leased | de-activated, | de-activated, |
leased | dynamically leased, leased | dynamically leased, leased | de-activated | de-activated, |
expired | dynamically leased, leased | dynamically leased, leased | de-activated, | de-activated, |
pending- | dynamically leased, leased | dynamically leased, leased | de-activated, | de-activated, |
other- | other available | reserved | de-activated | de-activated |
unavailable | unavailable | unavailable | unavailable | unavailable |
The save command allows you to validate and save your changes to the database.
The syntax is:
saveThe nrcmd program performs validation when you create objects or modify their properties. It checks that you have supplied the required properties and that their values are valid. It also checks the validity of property values when you set them.
When you issue the save command, Network Registrar performs three levels of validation:
All nrcmd commands return a status code as the first line of output. The status codes are affected by SMTP and other line-oriented protocols. The first word on the line is a three-digit status code, and the remaining output is the descriptive text. The first digit of the status code determines the class of the status.
Table 2-37 lists and describes the save command error codes.
| Error Code | Description |
|---|---|
Indicates a successful save. | |
Indicates an error in processing the command. | |
Indicates an error in communicating with the cluster database server. | |
Indicates an internal error in the command. |
For more information about error codes, see "Error Codes."
The scope command allows you to create and edit DHCP scopes.
The syntax is:
scope name create addr mask [prop=value]To create a scope, type:
nrcmd> scope testScope create 192.168.1.0 255.255.255.0
To delete a scope, type:
nrcmd> scope testScope delete
To list scopes, type:
nrcmd> scope list
The scope command allows you to enable, disable, or determine whether the feature has been set. You use the enable, disable, or get commands. Note that the get command displays the value of the feature.
The syntax is:
scope name disable featureTable 2-38 lists and describes the scope features.
| Feature | Description |
|---|---|
Optional, default disabled. Controls whether the server accepts BOOTP requests. If you want clients to always receive the same addresses, you need to reserve IP addresses for all your BOOTP clients. For information about how to reserve address, see Scope Reservations. | |
Optional, default enabled. Controls whether the DHCP server will accept DHCP requests for this scope. You would only disable DHCP for a scope to cause the scope to be used for BOOTP exclusively, or to temporarily de-activate a scope. | |
Optional, default disabled. Controls whether the server will accept dynamic BOOTP requests for this scope. Dynamic BOOTP requests are BOOTP requests that do not match a reservation, but can be satisfied from the available lease pool. To use this feature, you must also enable bootp. | |
Optional, default disabled. Controls whether the DHCP server should attempt to update a DNS server with the name and address information from leases that are granted to requesting clients. | |
failover | See scope properties. |
Optional, default disabled. Controls whether the server should attempt to ping an address. | |
Optional, default none. Controls whether to allow existing clients to re-acquire their leases, but not to offer any leases to new clients. Note that a renew-only scope will not change the client associated with any of its leases, other than to allow a client currently using an available IP address to continue to use it. | |
Optional, default disabled. Controls whether the DHCP server automatically creates DNS host names for DHCP clients who do not provide names. The server can synthesize unique names for clients based on the synthetic-name-stem property. | |
Optional, default disabled. Controls whether you set a trap on the scope to alert you when the number of free addresses gets high. For more information, see the "Trap" section. | |
Optional, default disabled. Controls whether you set a trap on the scope to alert you when the number of free addresses gets low. For more information, see the "Trap" section. | |
Optional, default disabled. Controls whether the DHCP server is updated before the lease is granted. |
To enable dynamic DNS update, type:
nrcmd> scope testScope enable dynamic-dns
To disable dynamic BOOTP, type:
nrcmd> scope testScope disable dynamic-bootp
Use the set and get commands to assign and retrieve values from the scope's properties.
The syntax is:
scope name get prop=valueTable 2-39 lists and describes the scope properties.
| Property | Description |
|---|---|
Optional, default none. The address of the subnet for which this scope contains addresses. (Read-only) | |
Optional, default none. A scope that does not extend leases to clients. It treats all of the addresses in its ranges as if they were individually de-activated. | |
Optional, default none. The address of the reverse DNS server for the zone into which the server should add PTR records. | |
Optional, default none. The name of the inverse (in.addr.arpa) zone that is updated with PTR and TXT records. | |
Optional, default none. The IP address of the primary DNS server on which the forward zone resides. | |
Optional, default none. The name of the DNS zone to which a DHCP client's host name should be added (A record). | |
Controls whether the server uses failover. It has three possible states. For more information, see the "Failover Property States" section. | |
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 backup-server is not configured on this scope or in the server-wide default, then this server is considered to be the main server for this scope. | |
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 the main-server is not configured on this scope or in the server-wide default, then this server is considered to be the main server for this scope. | |
Optional, default none. The mask associated with the scope's network address. (Read-only) | |
Optional, default none. The number of milliseconds the DHCP server should wait for ping responses. If you make this value too large, you will slow down the lease offering processes. If you make this value too small, you will reduce the effectiveness of pinging addresses before offering them. | |
Optional, default none. The name of the policy associated with this scope. | |
Optional, default none. The IP address of the primary scope for this (secondary) scope. | |
Optional, default none. The subnet mask of this scope's primary scope (if this is a secondary scope). | |
Optional, default none. The primary scope for this (secondary) scope. Use the distinguished name none to indicate no primary scope. You need to specify a primary scope if you have multiple logical subnets on the same physical network segment, and if you allow DHCP to offer addresses from any of the subnets. | |
Optional, default none. The list of selection criteria associated with a scope. The scope compares a client's selection criteria to this list in order to determine whether the client can obtain a lease from the scope. | |
Optional, default none. The prefix of the default host name to use if clients do not supply host names. | |
Optional, default none. Sets the number or percentage of the reset value for the free-address trap on this scope. For more information, see the "Trap" section. | |
Optional, default none. Sets the number or percentage threshold for the free-address trap on this scope. For more information, see the "Trap" section. | |
Optional, default enabled. If the server is replying to a BOOTP request, and is offering a lease from a scope that is configured to perform DNS updates, it will check this property before beginning the DNS update. This property allows you to prevent DNS updates for BOOTP clients, while allowing updates for DHCP clients. |
The failover over property has three possible states:
To set the name of the reverse zone, type:
nrcmd> scope testScope set dns-reverse-zone-name=10.in-addr.arpa.
To get the DNS zone name, type:
nrcmd> scope testScope get dns-zone-name
The scope method commands allow you to add, remove, show, and list ranges and reservations.
You can specify the start and end values as host numbers or IP addresses. Note that the start and end values must fall within the network addresses as defined by the scope's addr and the network mask attributes.
The syntax is:
scope name addRange start endTable 2-40 lists and describes the scope range methods.
| Method | Description |
|---|---|
Adds a range of addresses to the named scope. | |
Lists the leases in the named scope. | |
Lists the available addresses in the named scope. | |
Removes the range of available addresses in the named scope. |
To add a range, type:
nrcmd> scope testScope addRange 192.168.1.10 192.168.1.20
To delete a range, type:
nrcmd> scope testScope removeRange 192.168.1.10 192.168.1.15
The scope command, with the name argument allows you to add, delete, or list the reservations on the named scope.
The syntax is:
scope name addReservation ipaddr macaddrTable 2-41 lists and describes the scope reservation methods.
| Method | Description |
|---|---|
Adds the reservation to the named scope. | |
Lists the reservations in the named scope. | |
Deletes a reservation from the named scope. |
To add a reservation, type:
nrcmd> scope testScope AddReservation 192.168.1.10 1,6,00:a0:24:2e:9c:20
To remove a reservation, type the following, specifying either the client's MAC or IP address:
nrcmd> scope testScope removeReservation 192.168.1.10
The scope-policy command allows you to configure 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.
Embedded scope-policies are implicitly created and deleted when you create or delete the corresponding scopes. You manipulate the scope-policy using the name of the scope to which the embedded policy is attached.
You can enable, disable, or determine whether the feature has been set. You use the enable, disable, or get commands.
The syntax is:
scope-policy scope-name enable featureTable 2-42 lists and describes the scope-policy features. For more information about lease time, see "Lease Times" section.
| Feature | Description |
|---|---|
Optional, default none. Clients may request a specific lease time. The server does not honor those requested lease times if this attribute is false. The server does not honor a client's lease time if the time is longer than the server's normal lease time. | |
Optional, default none. Specifies that leases for this scope-policy should be permanently granted to requesting clients. | |
Optional, default none. Controls whether the server uses the value of the server-lease-time property to determine the length of a lease, rather than using the lease time returned to the client. |
Use the set and get commands to assign and retrieve values from the scope-policy's properties.
The syntax is:
scope-policy scope-name get propTable 2-43 lists and describes the scope-policy properties.
| Property | Description |
|---|---|
Optional, default none. A list of the names of options that should be returned in any replies to BOOTP clients. The options themselves do not have to have been configured in the same scope-policy as the reply-options list; the server will search the hierarchy of client-policies for each option named in the list. For more information about this property, see the "Scope-Policy Reply Options" section. | |
Optional, default none. Supplies the name of the executable file from which to boot or obtain configuration data. This property can also contain the following variable substitution values:
| |
Optional, default none A list of the names of options that should be returned in any replies to DHCP clients. The options themselves do not have to have been configured in the same scope-policy as the reply-options list; the server will search the hierarchy of client-policies for each option named in the list. For more information about this property, see the "Scope-Policy Reply Options" section. | |
Optional, default none. The length of time between the expiration of a lease and the time it is made available for re-assignment. | |
Optional, default none. If the server offers a lease to a client, but the offer is not accepted, the server will wait the specified number of minutes before making the lease available again. | |
Optional, default none. The name of a boot file to be used in a client's boot process. The server returns this file name in the 'file' field of its replies. The packet-file-name cannot be longer than 128 characters. This property can also contain the following variable substitution values:
| |
Optional, default none. The host name of a server to use in a client's boot process. The server returns this file name in the sname field of its replies. The packet-server-name field cannot be longer than | |
Optional, default none. The IP address of the next server in a client's boot process. For example, this might be the address of a TFTP server used by BOOTP clients. The server returns this address in the siaddr field of its reply. | |
Optional, default none. The time that the server believes the lease is valid. It may be useful to have the server consider leases leased for a longer period than the client in order to get more frequent client communication along with the stability of long lease times. | |
vendor-class-identifier | Optional, default none. This property is used by clients and servers to exchange vendor-specific information. The information is an opaque object of n octets, presumably interpreted by vendor-specific code on the clients and servers.The vendor is indicated in the vendor-class-identifier option. |
To set the grace period to three days for scope-policy 168.1-net, type:
nrcmd> scope-policy 168.1-net set grace-period=3d
When the server is getting ready to return option data to a client, it examines up to seven policies: the client's embedded policy, the client's policy, the client's client-class's embedded policy, the client's client-class's policy, the client's lease's scope's embedded policy, the client's lease's scope's policy, and the system default policy, in that order.
Then the server looks through the policies for a reply-options list. It looks for bootp- or dhcp-reply-options depending on the client. The server uses the first list it finds. For each option in the list, the server looks through all of the policies, in order, and returns the data from the first policy that has a matching option. There is no requirement that the data that the server returns must come from the same policy that the reply-options list came from. If the server finds a reply-options list, it looks for each option in the list individually, and searches all of the related policies if necessary.
There is also no requirement that the options mentioned in a reply-options list be present in the scope-policy that contains the list. The nrcmd program allows you to type in a string, and that string can name any option. The Network Registrar GUI, however, presents a special dialog box for adding a reply-options property to a scope-policy that restricts you to the options already configured in the scope-policy. This is a GUI-only restriction; the server does not impose this restriction.
You can set individual option values with the setOption command, unset option values with the unsetOption command, and view option values with the getOption and listOptions commands. When you set an option value the DHCP server replaces any existing value or creates a new one, as needed, for the given option name.
The syntax is:
scope-policy scope-name listOptionsTable 2-44 lists and describes the scope-policy options.
| Property | Description |
|---|---|
Lists the options in the named scope-policy. | |
Sets the option name and value to the specified scope-policy. The format is optname value. For example, dhcp-lease-time 3600. | |
Gets the value of the named option. | |
Removes the named option from the specified scope-policy. |
To specify a router on a scope-policy, type:
nrcmd> scope-policy 168.1-net setOption routers 168.1.96.180
To list the options in a scope-policy, type:
nrcmd> scope-policy 168.1-net listOptions
The setLeaseTime command allows you to set the values of lease times and the getLeaseTime command to display the value of a lease time.
The syntax is:
scope-policy scope-name setLeaseTime valueThe lease time is the value of the dhcp-lease-time option. You should specify the time in seconds.
A scope-policy contains two lease times: the lease time and the server lease time.
You might want to establish these two different lease times if you want to retain information about clients' DNS names and yet have them renew their leases frequently. When you use a single lease time and it expires, the server no longer keeps that client's DNS name. If, however, you use a short client lease time and a longer server lease time, the client information is retained even after the client's lease has expired.
The scope-selection-tag command allows you to define tags that are added to the scope selection tag list. After you have defined scope selection tags you can associate them with scopes, clients, and client-classes.
The syntax is:
scope-selection-tag name createTo create the scope selection tag internal, type:
nrcmd> scope-selection-tag internal create
To delete the scope selection tag internal, type:
nrcmd> scope-selection-tag internal delete
To list the scope selection tags, type:
nrcmd> scope-selection-tag list
Network Registrar limits you to a total of 30 scope selection tags. When the DHCP server configures itself, it checks the number of scope selection tags defined for any network. A network in this context is the aggregation of all of the scopes that are related to a particular subnet. This includes all of the scopes that belong together (because they share a common network number and subnet mask) and all of the scopes that are related to one of these through the use of the primary scope reference. Thus, within all of the scopes that make up a network, there can be no more than 30 scope selection tags.
When the DHCP server reads a client entry (from the local database or from LDAP), the server checks its scope selection inclusion and exclusion criteria against the scope selection tags defined for the scopes on this network. If the client entry references tags that are not present in any scope in the network, then how the server handles the tags depends on whether the reference is to included or excluded tags. If the reference is for excluded tags, then the tag will have no effect. If the reference is for included tags, then the server determines that there is no acceptable scope on that network for this client.
The server command allows you to affect the behavior of the server. After you have used the server command or any other time you have changed the server's configuration, you need to reload the server. Use the server command or the Network Registrar GUI to reload the server.
The syntax is:
server [DNS|DHCP|TFTP] cmdTable 2-45 lists and describes the arguments to the server commands.
| Command | Description |
|---|---|
Disables the server. | |
Enables the server. | |
Gets the specified server's current health. | |
Reports the status of the connection between the server and its DNS, LDAP, or failover servers. For more information, see the "getRelatedServers" section. | |
Gets the specified server's current statistics. | |
Causes the specified server to be stopped and then immediately restarted. When the server restarts it re-reads all of its configuration information and its previously saved state information and then begins operating. | |
Sets the debugging level and the location of the debug messages. You can specify either MLOG or WINDOW as locations. The default location is MLOG. | |
Notifies one DHCP server that another DHCP is down and moves all appropriate scopes into the PARTNER-DOWN state. For more information, see the "setPartnerDown" section. | |
Starts the specified server (DNS, DHCP, or TFTP). | |
Stops the specified server (DNS, DHCP, or TFTP). | |
Turns off debugging output. |
To stop the DNS server, type:
nrcmd> server DNS stop
To start the DHCP server, type:
nrcmd> server DHCP start
To display the health of the DHCP server, type:
nrcmd> server DHCP getHealth
The getRelatedServers command allows you to create a report on the connection status of the other servers associated with this DHCP server. Information is reported for DNS, LDAP, and failover-associated DHCP servers.
Table 2-46 displays the columns in the report.
| Column | Description |
|---|---|
Type | Main, Backup, DNS, or LDAP |
Name | DNS host name |
Address | IP address in dotted octet format |
Requests | Number of outstanding requests or two dashes (--) if not applicable |
Communications | OK or INTERRUPTED. Information about DHCP and DNS servers that a DHCP server has tried to update |
localhost State | Failover state of this server or two dashes (--) |
Partner State | Failover state of the associated failover server or two dashes (--) |
Network Registrar displays the columns sorted by type, name, and IP address.
The setPartnerDown command allows you to notify a DHCP server that a failover server associated with the DHCP server has been verified to be down. When you run the setPartnerDown command all of the scopes in this server, which are running failover with the partner server, move into PARTNER-DOWN state.
When you use the setPartnerDown command, you can specify a date and time, which represents a value equal to or later than the last known data and time the partner server could have been operational. If you do not specify a value, Network Registrar uses the current date and time.
You might want to specify a value on this command to shorten the waiting period associated with entering PARTNER-DOWN state. In particular, IP addresses that were available in the partner server cannot be allocated to different DHCP clients until a waiting period equal to the maximum client lead time has passed. For more information about the maximum-client-lead-time, see the "failover-maximum-client-lead- time" section.
 | Caution Make sure that the partner server is really down before issuing the setPartnerDown command. |
The following are valid values:
If you specify 98 or 99, Network Registrar assumes 1998 or 1999. If you specify a lower number, such as 05 or 10, Network Registrar assumes 2005 or 2010.
To notify the backup server that its main server is down now, type:
nrcmd> server DHCP setPartnerDown backup.mycompany.com
To notify the backup server that its main server went down at 12 midnight on October 31, 1998 type:
nrcmd> server DHCP setPartnerDown backup.mycompany.com Oct 31 24:00:00 1998
The server features allow you to enable or disable a feature. You use the enable or disable commands to affect the following feature.
The syntax is:
server [DNS | DHCP | TFTP] enable featureTable 2-47 lists and describes the server argument.
| Argument | Description |
|---|---|
Controls whether the server is started by the AIC server agent when you reboot. You might want to disable this feature for clusters that want to provide a single protocol service. By default, both the DNS and DHCP servers are enabled, while TFTP is disabled. |
To disable the DNS server from automatically restarting on reboot, type:
nrcmd> server DNS disable start-on-reboot
Table 2-48 lists and describes the server property.
| Property | Description |
|---|---|
The version string for the server. This property is useful when describing version information to Technical Support. |
The session command allows you to set session control parameters on your nrcmd command session. You can control the visibility level that determines which properties are displayed, and the default output format.
The syntax is:
session set prop=valueTable 2-49 lists and describes the session command arguments.
| Property | Description |
|---|---|
An enumerated string that can have the following values: | |
script---show objects in script-suitable format, that is, one attribute per line. | |
user---show objects in a user-readable format, that is, one object per line. | |
The name of the current cluster. This is a read-only property. | |
The name of the current user. This is a read-only property. | |
Controls which properties are displayed. The default visibility is 5. |
To set the output so that it is suitable for script processing, type:
nrcmd> session set default-format=script
The tftp command allows you to enable or disable TFTP server features. Since there is only one TFTP server per cluster within Network Registrar, you do not need to refer to the server by name.
The syntax is:
tftp disable featureTable 2-50 lists and describes the TFTP features.
| Feature | Description |
|---|---|
Required, default disabled. Specifies how the TFTP server should respond to DOCSIS file requests from TFTP clients. If this feature is disabled, the TFTP server refuses DOCSIS file requests and sends an access violation error to the client. | |
Required, default disabled. Specifies whether the TFTP server should log generated DOCSIS files to disk. If this feature is enabled, the TFTP server will log each generated DOCSIS configuration file to a tftp subdirectory within the server logs directory. | |
Required, default enabled. Specifies how the TFTP server should respond to file read requests from TFTP clients. If this feature is disabled, the TFTP server refuses file read requests and sends an access violation error to the client. | |
Required, default disabled. Specifies whether or not the TFTP server will use SSL when communicating with a LDAP server. If this feature is disabled, the TFTP server does not use SSL when communicating with LDAP. | |
Required, default disabled. Specifies how the TFTP server should respond to file write requests from TFTP clients. If this feature is disabled, the TFTP server refuses file write requests and sends an access violation error to the client. | |
Required, default disabled. Specifies whether or not the TFTP server treats pathnames contained within TFTP requests as if the paths were rooted at the specified home directory. If this feature is enabled, the TFTP server attempts to resolve both absolute and relative pathnames to paths located beneath the specified home directory. |
Use the set, get, and unset commands to assign and retrieve values from the DNS server's name-value properties.
The syntax is:
tftp get propTable 2-51 lists and describes the TFTP properties.
| Property | Description |
|---|---|
Required, default none. Specifies the name of an active directory domain that the TFTP server uses to provide dynamic configuration file support. | |
Required, default none. Specifies the name of the default disk device the TFTP server uses when none is specified in the pathname contained in the TFTP request. This property is designed for use on NT to specify a default drive letter. | |
Required, default 100. Specifies the maximum number of DOCSIS configuration log files the TFTP server maintains in the TFTP subdirectory within the server logs directory. Once this limit is reached, the TFTP server removeS one DOCSIS log file for each new log file it creates. | |
Required, default: /docsis. Specifies a pathname prefix the TFTP server recognizes as the trigger to create a DOCSIS configuration file. This prefix must match the one the DHCP server is using to generate the DOCSIS filename that DHCP sends to the TFTP client. | |
Required, default none. Specifies a path to a home directory the TFTP server uses to resolve TFTP requests. If use-home-directory-as-root is disabled, the the value of home-directory is used in conjunction with the paths specified in the search-list to resolve TFTP requests. | |
Required, default 5 seconds. Specifies the initial length of time 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 localhost. Specifies the hostname or IP address of a LDAP server the TFTP server uses to provide dynamic configuration file support. | |
Required, default 10 seconds. Specifies the initial length of time the TFTP server wait after sending a request to a LDAP server before declaring that request timed-out and sending a retransmission to the server. | |
Required, default 60 seconds. Specifies the maximum length of time the TFTP server waits after transmitting the initial LDAP request before giving up retrying on that request. | |
Required, default none. Specifies the password the TFTP server uses when connecting to a LDAP server. | |
Required, default 389. Specifies the port number the TFTP server uses when communicating with a LDAP server. | |
Required, default none. Specifies the root distinguished name the TFTP server uses to locate the root of the directory tree for dynamic configuration file support. | |
Required, default none. Specifies the user name the TFTP server uses when connecting to a LDAP server. | |
Required, default 4 files. Specifies the number of log files the TFTP server will maintain in the server logs directory. | |
Required, default 1 megabyte. Specifies the size of each log file that the TFTP server will maintain in the server logs directory. | |
Required, default: 3. Specifies the level of verbosity the TFTP server will employ when writing log messages to the TFTP server log file. Each integer value from zero through four enables the following log levels:
| |
Required, default 1 megabye. Specifies the maximum file size limit the TFTP server will enforce for a file written to the TFTP server. | |
Required, default 65536. Specifies the minimum socket buffer size the TFTP server uses for the well known port on which it is listening for TFTP requests. | |
Required, default 0. Specifies the level of verbosity the TFTP server will employ when writing messages to the server trace file. Each integer value from 0 through 4 enables the following log levels:
Note that you should only turn on packet tracing if instructed to do so by technical support. Packet tracing has a significant impact upon performance level. | |
Required, default 69. Specifies the UDP port number the TFTP server uses to listen for TFTP requests. | |
Required, default none. Specifies a comma-separated list of paths the TFTP server uses to resolve TFTP requests. If you enable use-home-directory-as-root, the paths in the search list are ignored and the home directory is used to resolve all TFTP requests. | |
Required, default 60. Specifies the maximum length of time the TFTP server will wait 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. |
Use the setTraceLevel and getTraceLevel commands to specify and report the trace levels for the TFTP server.
The syntax is:
tftp getTraceLevelTable 2-52 describes these TFTP commands.
| Command | Description |
|---|---|
getTraceLevel | Optional, default none. Reports the trace level that the TFTP server is currently using. Enable TFTP server tracing only when investigating server problems. For normal server operation the trace level should be zero. |
Optional, default 0. Specifies the level of tracing used for the TFTP server. Trace output is written to the file file_tftp_1_trace in the server logs directory. Trace levels are cumulative and defined as follows:
|
Using the enable, disable, and get commands you can activate, de-activate, and list the state of the traps:
The syntax is:
trap disable featureTable 2-53 describes the trap command's features and the corresponding SNMP notification name.
| Feature | SNMP Notification | Description |
Indicates that an address conflict has been detected with another DHCP server. | ||
ciscoNetRegFailover | Indicates that a DHCP server has detected a configuration mismatch with a failover peer. | |
Indicates whether Network Registrar has detected the DNS server queue has become too large. | ||
Indicates whether Network Registrar has detected a duplicate IP address. | ||
free-address-high | Indicates that the number of free IP addresses is no longer too low. | |
Indicates that the number of free IP addresses is too low. | ||
Indicates the Network Registrar DHCP or DNS server is not responding. | ||
other-server-responding | Indicates that the other Network Registrar DHCP or DNS server is responding. | |
Indicates whether the Network Registrar DHCP or DNS server has been started | ||
Indicates whether the Network Registrar DHCP or DNSserver has been stopped. |
You can use the set, unset, get, and show commands to assign and retrieve values from the various name-value properties associated with traps.
The syntax is:
trap set prop=value [prop=value ...]Table 2-54 describes the trap command properties.
| Property | Description |
|---|---|
free-address-low-threshold | A string representation of an integer or percentage indicating the threshold value for the free-address-low trap. Valid values are digits [0-9] and optionally a single trailing % character. 0-2147483647 and percentages must lie within the range 0-100 inclusive. |
free-address-high-threshold | A string representation of an integer or percentage indicating the reset value for the free-address trap. Valid values are digits [0-9] and optionally a single trailing % character. 0-2147483647 and percentages must lie within the range 0-100 inclusive. |
Threshold traps are throttled through the use of a hysteresis mechanism. At any time either the free-address-low trap or the free-address-high trap may be armed, but not both. The free-address-low trap is armed when the DHCP process starts. If a free-address-low event occurs, Network Registrar generates the free-address-low trap and unarms it, and then arms the free-address-high trap.
The occurrence of one condition is used to arm the trap for the opposite condition---even if one trap is disabled through the nrcmd command, its opposite will still be sent as needed. You need to specify both the low and high values in the same manner, that is, if you specify the low threshold as a percentage, then you must also specify the high threshold as a percentage, and vice-versa. The high value must be greater than or equal to the low threshold value.
The low and high values are always expressed as units of resource free in which the units are either numeric or percent. In the case of the free-address trap, the resource being measured is the number of free addresses available in a scope.
The DHCP server issues a trap when the number of free addresses is equal to or less than the trap low value, after which the server automatically disables the trap. By default, both the trap low and high threshold values are set to 20 percent.
To set the free-address-low-threshold to 12 percent and the free-address-high-threshold to 22 percent, type:
nrcmd> trap set free-address-low-threshold=12% nrcmd> trap set free-address-high-threshold=22%
To set the free-address-low-threshold to 100 and the free-address-high-threshold to 130, type:
nrcmd> trap set free-address-low-threshold=100 free-address-high-threshold=30
You can use the methods addRecipient, removeRecipient, and listRecipients in conjunction with the trap command to define a list of trap recipients that are shared by all of the traps.
The syntax is:
trap addRecipient recipient-name host-name [community] [port-number]Table 2-55 lists and describes the trap method arguments.
| Argument | Description |
|---|---|
community | An optional community string that you can specify as part of the trap PDU for authentication purposes. Note that the default community string is public. |
host-name | A string representation of the host name or IP address of the recipient platform. |
port-number | An optional port number parameter to which Network Registrar directs the trap. The default port number is 162. |
recipient-name | A unique (cluster-wide) identifier for the recipient. |
The Network Registrar DNS and DHCP servers reference the trap recipients through aliases in order to allow multiple recipients at the same address, but at different ports. You can add or delete a particular trap recipient from the list, but you cannot modify the recipients.
The zone command allows you to create and edit DNS zones, as well as force transfer zones.
The syntax is:
zone name create primary file=BINDfileTo create a zone, type:
nrcmd> zone QuickExample.com create primary file=host.local
To create both an SOA record with values (ns.test.org. andy.test.org.) and an NS record with value ns.test.org, type:
nrcmd> zone test.org create primary ns andy
Both of these records will have the name of the zone ("test.org." or "@"). Because the name ns.test.org. is within the test.org. zone, you have to provide an A record for ns.test.org:
nrcmd> zone test.org. addRR ns A 24.10.2.2
To have the primary server initiate a forced zone transfer to one or more secondary servers, use the forceXfer primary argument. To have a secondary server force a zone transfer from the primary, use the forceXfer secondary argument. For example, to force a zone transfer to the secondary server test.org from the primary, type:
nrcmd> zone test.org forceXfer secondary
You can enable, disable, or determine the feature that has been set with the enable, disable, or show commands.
The syntax is:
zone name disable featureTable 2-56 lists and describes the zone features.
| Feature | Description |
|---|---|
Required, default enabled. (Primary server only) Enables or disables RFC 2136 dynamic updates to the zone. The most typical source of these updates is a DHCP server. | |
Required, default disabled. Restricts zone transfers to a specific set of hosts. If you restrict zone transfers, you need to use the restricted-set property to list the servers that are allowed to perform zone transfers. | |
Optional, default none. Applies to secondary zones only. Enables requesting incremental transfer for this zone. When set, (to either to true or false) it overrides the global ixfr-enable value for this zone. | |
Optional, default none. Enables the notification of other authoritative servers when this zone changes. When set, (to either true or false) it overrides the global notify value for this zone. |
Using the server global value (not setting this value per-zone) gives you an easy way of globally turning IXFR on or off, or setting a general policy for your zones and specific exceptions to the server global value.
Use the set and get commands to assign and retrieve values from the zone's properties. These properties depend on the type of zone that you are creating.
The syntax is:
zone name set prop=value [prop=value ...]Table 2-57 lists and describes the zone properties.
| Property | Description |
|---|---|
(Secondary-only). The list of servers from which Network Registrar will transfer data for this zone. | |
The set of IP addresses from which dynamic updates will be accepted, when you have enabled the dynamic feature. The nrcmd program treats addresses with zeroes in the least significant octets as network numbers, with implicit masks in octet multiples. | |
Optional, default: 604800. The expire interval, in seconds, of the zone. The length of time a secondary can continue to serve zone data without confirmation that it is still current. Validation: refresh < x < 2147483647. | |
Optional, default: 86400. The minimum TTL value to expose in resource records for this zone. Records with lower TTL values will be published with this value. Validation: 0 <= x <= 2147483647. | |
An optional list of additional servers to notify when this zone changes. All servers listed in NS records for the zone with the exception of the server described by the ns property of the zone (the mname field of the SOA record) will receive notifications. Servers listed in the notify-set will also be notified. | |
Required, default: none.The fully-qualified domain name of the primary for this zone. This host is the original or primary source of data for this zone. | |
Required, default: none. A domain name which specifies the mailbox of the person responsible for this zone. The first label is a user or mail alias, the rest of the labels are a mail destination. A mailbox of hostmaster@test.com would be represented as hostmaster.test.com. | |
Optional, default: 10800. The refresh interval, in seconds, of the zone. Used by secondaries as the period of polling for zone changes. Validation: 1 <= x <= 2147483647. | |
The set of IP addresses that may request zone transfers when you have enabled the restrict-xfer feature. | |
Optional, default: 3600. The retry interval, in seconds, of the zone. Used by secondaries as the period of retrying when polling for changes, or attempting zone transfer after encountering errors. Validation: < (expire - refresh) | |
Optional, default: 1. The current serial number of the zone. Maintained automatically by the DNS server. Validation: 0 <= x <= 4294967295. |
You use the following commands to add, remove, and list the hosts for the zone.
The syntax is:
zone name addHost name addr [alias]Table 2-58 lists and describes the host properties.
| Property | Description |
|---|---|
name | The host's domain name. |
addr | The list of addresses assigned to the host. |
aliases | An optional list of alias domain names for this host. |
To add a host to the QuickExample zone, type:
nrcmd> zone QuickExample.com addHost bethpc 192.168.1.10
You use the following commands to add, remove, and list the resource records in the zone or to delete a zone's unused or obsolete resource records.
The syntax is:
zone name addRR name [ttl] [class] type [preference] dataTable 2-59 lists and describes the resource record properties.
| Property | Description |
|---|---|
The class of resource record, which is always IN (for Internet) in DNS. | |
The resource record's domain name (owner name). | |
preference | Prevents mail routing loops. Is an unsigned 16 bit number (between 0 and 65535) that indicates the mail exchanger's priority. [...] Mailers attempt delivery to the mail exchangers with the lowest preference values first. |
The resource record time to live (in seconds). The length of time the record the client may cache the resource record. | |
The type of resource record, such as PTR or A. |
The addRR command adds a resource record of the type that you specify.
If you are adding an MX record, you can specify a preference to determine the order of mail servers. The system will try the mail server with the lowest number and if that server is not available it will try the next lowest number. You can have two mail servers with the same number, and the system will randomly try either one
The cleanRR command deletes zone records that are left after you have deleted a zone. It uses the DNS server's historical zone data to determine what part of this data can be removed. Use the cleanRR command if you periodically delete and reimport zones, which can cause your database to grow.
The behavior of the cleanRR command depends on whether there is a new zone:
The cleanRR command does not print out a list of records to be deleted or prompt you for confirmation. You can safely run it at any time.
The listRR command displays resource records in the named zone. You can display all the resource records, or just the static or the dynamic resource records.
The removeDynRR command removes all specified dynamic resource records. You can specify resource records by name or name and type. To use the command, the DNS server must be running. Changes take effect immediately; you do not need to reload the server.
The removeRR command removes all specified static resource records. You can specify resource records by name, name and type, or name, type, and data (in which the specified data is in BIND-style format). Note that for the removal to take effect, you need to reload the server.
To add a name server resource record, type:
nrcmd> zone QuickExample.com addRR green ns green.QuickExample.com
You can specify the name as either the relative name (if the server is within the same domain), as an absolute name (by supplying the fully qualified domain name), or the same name as the zone name (by using the @ symbol).
To delete a zone's unused or obsolete resource records, type:
nrcmd> zone QuickExample.com cleanRR
Posted: Thu Nov 18 13:20:46 PST 1999
Copyright 1989-1999©Cisco Systems Inc.