Upload
others
View
25
Download
0
Embed Size (px)
Citation preview
Network Registrar CLI Reference GuideSoftware Release 5.5
Corporate HeadquartersCisco Systems, Inc.170 West Tasman DriveSan Jose, CA 95134-1706 USAhttp://www.cisco.comTel: 408 526-4000
800 553-NETS (6387)Fax: 408 526-4100
Customer Order Number: DOC-7812875=Text Part Number: 78-12875-01
THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS.
THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY.
The following information is for FCC compliance of Class A devices: This equipment has been tested and found to comply with the limits for a Class A digital device, pursuant to part 15 of the FCC rules. These limits are designed to provide reasonable protection against harmful interference when the equipment is operated in a commercial environment. This equipment generates, uses, and can radiate radio-frequency energy and, if not installed and used in accordance with the instruction manual, may cause harmful interference to radio communications. Operation of this equipment in a residential area is likely to cause harmful interference, in which case users will be required to correct the interference at their own expense.
The following information is for FCC compliance of Class B devices: The equipment described in this manual generates and may radiate radio-frequency energy. If it is not installed in accordance with Cisco’s installation instructions, it may cause interference with radio and television reception. This equipment has been tested and found to comply with the limits for a Class B digital device in accordance with the specifications in part 15 of the FCC rules. These specifications are designed to provide reasonable protection against such interference in a residential installation. However, there is no guarantee that interference will not occur in a particular installation.
Modifying the equipment without Cisco’s written authorization may result in the equipment no longer complying with FCC requirements for Class A or Class B digital devices. In that event, your right to use the equipment may be limited by FCC regulations, and you may be required to correct any interference to radio or television communications at your own expense.
You can determine whether your equipment is causing interference by turning it off. If the interference stops, it was probably caused by the Cisco equipment or one of its peripheral devices. If the equipment causes interference to radio or television reception, try to correct the interference by using one or more of the following measures:
• Turn the television or radio antenna until the interference stops.
• Move the equipment to one side or the other of the television or radio.
• Move the equipment farther away from the television or radio.
• Plug the equipment into an outlet that is on a different circuit from the television or radio. (That is, make certain the equipment and the television or radio are on circuits controlled by different circuit breakers or fuses.)
Modifications to this product not authorized by Cisco Systems, Inc. could void the FCC approval and negate your authority to operate the product.
The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB’s public domain version of the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.
NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED “AS IS” WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE.
IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
CCIP, the Cisco Powered Network mark, the Cisco Systems Verified logo, Cisco Unity, Fast Step, Follow Me Browsing, FormShare, Internet Quotient, iQ Breakthrough, iQ Expertise, iQ FastTrack, the iQ Logo, iQ Net Readiness Scorecard, Networking Academy, ScriptShare, SMARTnet, TransPath, and Voice LAN are trademarks of Cisco Systems, Inc.; Changing the Way We Work, Live, Play, and Learn, Discover All That’s Possible, The Fastest Way to Increase Your Internet Quotient, and iQuick Study are service marks of Cisco Systems, Inc.; and Aironet, ASIST, BPX, Catalyst, CCDA, CCDP, CCIE, CCNA, CCNP, Cisco, the Cisco Certified Internetwork Expert logo, Cisco IOS, the Cisco IOS logo, Cisco Press, Cisco Systems, Cisco Systems Capital, the Cisco Systems logo, Empowering the Internet Generation, Enterprise/Solver, EtherChannel, EtherSwitch, GigaStack, IOS, IP/TV, LightStream, MGX, MICA, the Networkers logo, Network Registrar, Packet, PIX, Post-Routing, Pre-Routing, RateMUX, Registrar, SlideCast, StrataView Plus, Stratm, SwitchProbe, TeleRouter, and VCO are registered trademarks of Cisco Systems, Inc. and/or its affiliates in the U.S. and certain other countries.
All other trademarks mentioned in this document or Web site are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (0201R)
Network Registrar CLI Reference Guide Copyright © 2002, Cisco Systems, Inc. All rights reserved.
78-12875-01
C O N T E N T S
Preface 15
Who Should Read This Guide 15
How This Guide Is Organized 15
Document Conventions 16
Obtaining Documentation and Submitting a Service Request 16
Open Source License Acknowledgements 16
OpenSSL/Open SSL Project 17
License 1: 17
License 2: 17
C H A P T E R 1 About the nrcmd Program 1
Invoking the nrcmd Command 1
Command Organization 2Command Usage 3
Create Keyword 3Set Keyword 3Enable Keyword 4Attribute Flags 4
Saving Your Changes 4
Command Line Navigation Keys 5
nrcmd Commands 5
C H A P T E R 2 Using the nrcmd Commands 1
address-block 2Virtual Private Network Configuration Example 4
address-block-policy 5address-block-policy Reply Options 5Lease Times 5Specifying Arrays in Vendor Specific Options 5
admin 6Passwords 7
client 8Specifying MAC Addresses 10
3Network Registrar CLI Reference Guide
Contents
Reloading the Server 10
Using the one-shot Action 10
Using the authenticate-until Attribute 11
Values for the host-name Attribute 12
Client Caching 12
client-class 13
client-class-policy 15
client-policy 16
custom-option 17
dhcp 20
Deferring Lease Extensions 36
Putting the Sever in Import Mode 37
Configuring the sms-library-path Attribute 37
Setting the Failover Backup Percentage 37
Setting the Maximum Client Lead Time 38
Setting the Failover Lease Period Factor 38
Enabling DHCP Forwarding 39
Troubleshooting MAC Addresses 40
Enabling SMS Network Discovery 40
dhcp-interface 41
Listing DHCP Interfaces 42
dns 43
NOTIFY 48
Resolution Exception Domain 49
Flushing the Cache 49
Rebuilding Resource Records Indexes 50
Handling Rogue Address Records 50
exit 51
export 52
Specifying Clusters for the export addresses Command 53
Specifying a Namespace on Export 54
Command Keywords for the export addresses Command 54
Error Reports for the export addresses Command 54
Database Output Format of the export addresses Command 55
Text File Output Format of the export addresses Command 56
Addresses Reported by the export addresses Command 56
Considerations of the export leases Command 56
extension 57
4Network Registrar CLI Reference Guide
78-12875-01
Contents
force-lock 60
help 61
import 62
Import File 63
Specifying the Namespace on Import 63
Named.boot File 63
Mapping BIND 4 Boot File Directives to nrcmd 64
ldap 65
Dictionary Examples 70
Using the create-string-dictionary Attribute 70
lease 71
Using the send-reservation Keyword 75
Using the delete-reservation Keyword 76
Reserving an Address That Is Currently Leased 76
Setting a Lease to Unavailable 77
lease-notification 79
Running the lease-notification Command Automatically on UNIX 80
Running the lease-notification Command Automatically on Windows 81
Specifying the Configuration File 81
Specifying Clusters 81
license 83
namespace 84
option-datatype 87
policy 90
Policy Reply Options 94
Lease Times 95
Specifying Arrays in Vendor-Specific Options 95
remote-dns 96
report 98
Specifying Clusters 99
Displaying the Summary 99
save 102
Validation 102
Status Codes 102
scope 103
Changing the Mask of a Scope 109
Failover Attribute States 109
scope-policy 110
5Network Registrar CLI Reference Guide
78-12875-01
Contents
scope-policy Reply Options 110
Lease Times 110
Specifying Arrays in Vendor Specific Options 110
scope-selection-tag 111
Inclusion and Exclusion Criteria 111
server 112
Getting Related Servers 114
Setting Partner Down 114
Updating the System Management Server 115
session 116
Session Asserts 117
subnet 119
tftp 121
trap 127
Free Address Traps 129
vendor-option 130
Defining Vendor-Specific DHCP Options 131
zone 133
Owner Names 138
Default TTL Responses 138
Server Records 139
Enabling Incremental Zone Transfers by Server or Zone 139
Removing Resource Records 139
Cleaning Resource Records 139
Logging Checkpoint Files and Scavenging 140
TTL in Zone File Exports and Imports 140
C H A P T E R 3 Using the nrcmd Program As an API 1
Connecting to Network Registrar 1
Performing Authentication 1
Choosing Scripting Techniques 2Using Nrcmd Batch Files 2Command Syntax 2Adding Program Control 2
C H A P T E R 4 Using Extension Points 1
Creating Extensions 1Determining the Task 1
6Network Registrar CLI Reference Guide
78-12875-01
Contents
Deciding on the Approach 2Choosing the Extension Point 2Choosing the Extension Language 2
Language-Independent API 2Routine Signature 3Dictionaries 3Utility Methods 4Init-Entry Extension Point 4Configuration Errors 4Recognizing Extensions 4
TCL Extensions 5TCL API 5Dealing with TCL errors 5Handling Boolean Variables 5Configuring TCL Extensions 6Init-Entry Extension Point in TCL 6
C/C++ Extensions 6C/C++ API 6Using Types 7Building C/C++ Extensions 7Using Thread-Safe Extensions 7Configuring C/C++ Extensions 8Debugging C/C++ Extensions 8
Pointers into DHCP Server Memory 8Init-Entry Entry Point in C/C++ 9
DHCP Request Processing Using Extensions 9Receiving a Packet 10
Using post-packet-decode When Decoding the Packet 10
Using pre-client-lookup and post-client-lookup for Client-Class Processing 10
Building a Response Template 11
Determining the Network 11
Finding a Lease for the Client 11
Serializing Requests for the Same IP Address 12
Determining If the Lease Is Acceptable 12
Using the pre-packet-encode Extension to Gather Response Packet Information 13
Encoding the Response Packet 14
Updating Stable Storage 14
Using the post-send-packet Extension to Send the Packet 14
Using the pre-dns-add-forward Extension to Process DNS Requests 14
7Network Registrar CLI Reference Guide
78-12875-01
Contents
Extension Dictionaries 15
Environment Dictionary 15
Request and Response Dictionaries 16
Decoded DHCP Packet Data Items 17
Using the dhcp-parameter-request-list Option 18
Extension Point Descriptions 18
Environment Dictionary 18
post-packet-decode 19
pre-client-lookup 19
Environment Dictionary 20
Client-Class Data Input 20
Request Dictionary 21
post-client-lookup 22
Environment Dictionary 22
Request Dictionary 22
check-lease-acceptable 24
Environment Dictionary 24
Request Dictionary 24
Response Dictionary 24
pre-packet-encode 24
Request Dictionary 24
Response Dictionary 25
pre-dns-add-forward 27
Environment Dictionary 28
A P P E N D I X A Codes and Formats 1
Status Returns 1
Network Registrar Error Codes 1
Import and Export File Formats 5
A P P E N D I X B DHCP Extension Dictionary API 1
Tcl Attribute Dictionary API 1Attribute Dictionary Methods 1Tcl Environment Dictionary Methods 2
DEX Attribute Dictionary API 3Attribute Dictionary Methods 4DEX Environment Dictionary API 6DEX Environment Dictionary Methods 6
8Network Registrar CLI Reference Guide
78-12875-01
Contents
A P P E N D I X C DHCP Extension Dictionary Entries 1
Decoded DHCP Packet Data Items 1
Request Dictionary 5
Response Dictionary 10
I N D E X
9Network Registrar CLI Reference Guide
78-12875-01
Contents
10Network Registrar CLI Reference Guide
78-12875-01
F I G U R E S
Figure 4-1 Extensions Request and Response Dictionaries 17
11Network Registrar CLI Reference Guide
78-12875-01
Figures
12Network Registrar CLI Reference Guide
78-12875-01
T A B L E S
Table 1-1 General Options to nrcmd Command 1
Table 1-2 nrcmd Navigation Key Combinations 5
Table 1-3 nrcmd Commands 5
Table 2-1 CLI Commands 1
Table 2-2 address-block Command Attributes 3
Table 2-3 client Command Attributes 9
Table 2-4 Option Data Types 18
Table 2-5 dhcp Command Attributes 22
Table 2-6 DHCP Log Flags 33
Table 2-7 dhcp Command Extension Points 35
Table 2-8 dns Command Attributes 45
Table 2-9 DNS Log Flags 48
Table 2-10 export addresses Database Output 55
Table 2-11 Field Data Types 56
Table 2-12 extension Command Attributes 58
Table 2-13 BIND 4 to nrcmd Command Mappings 64
Table 2-14 ldap Command Attributes 67
Table 2-15 lease Command Attributes 72
Table 2-16 lease-notification Command Keywords 80
Table 2-17 namespace Command Attributes 85
Table 2-18 Option Data Types 88
Table 2-19 type-policy Command Attributes 92
Table 2-20 report Command Keywords 98
Table 2-21 Categories of Address States 100
Table 2-22 Potential States and Flags for IP Addresses 101
Table 2-23 save Command Status Codes 102
Table 2-24 scope Command Attributes 105
Table 2-25 getRelatedServers Report 114
Table 2-26 subnet Command Attributes 120
Table 2-27 tftp Command Attributes 122
Table 2-28 trap Command Traps 128
13Network Registrar CLI Reference Guide
78-12875-01
Tables
Table 2-29 zone Command Attributes 136
Table 4-1 Extensions Points and Dictionaries 15
Table 4-2 post-packet-decode Data Items 19
Table 4-3 pre-client-lookup Request Information Data Items 21
Table 4-4 Pre-client-lookup Client Information Data Items 21
Table 4-5 pre-client-lookup Client Understanding Data Items 22
Table 4-6 post-client-lookup Request Information Data Items 23
Table 4-7 post-client-lookup Client Information Data Items 23
Table 4-8 Post-Client-Lookup Client Understanding Data Items 23
Table 4-9 pre-packet-encode Request Information Data Items 24
Table 4-10 pre-packet-encode Client Information Data Items 25
Table 4-11 pre-packet-encode Client Understanding Data Items 25
Table 4-12 pre-packet-encode Response Dictionary Data Items 25
Table 4-13 pre-packet-encode Client Information Data Items 26
Table 4-14 pre-packet-encode Lease Information Data Items 26
Table 4-15 pre-packet-encode Scope Address Information Data Items 27
Table 4-16 pre-packet-encode Scope Acceptability Information Data Items 27
Table 4-17 pre-packet-encode Scope DNS Information Data Items 27
Table A-1 Status Information 1
Table A-2 Error Codes 1
Table B-1 Tcl Attribute Dictionary Methods 1
Table B-2 Tcl Environment Dictionary Methods 2
Table B-3 DEX Attribute Dictionary Methods 4
Table B-4 DEX Environment Dictionary Methods 7
Table C-1 DHCP and BOOTP Fields 1
Table C-2 DHCP and BOOTP Options 2
Table C-3 Decoded Packet Field 5
Table C-4 Request Dictionary Specific Data Items 6
Table C-5 Response Dictionary Specific Data Items 10
14Network Registrar CLI Reference Guide
78-12875-01
Preface
This chapter describes who should read this guide, how it is organized, and the document conventions in the Network Registrar CLI Reference Guide.
Cisco documentation and additional literature are available in a CD-ROM package, which ships with your product. The Documentation CD-ROM, a member of the Cisco Connection Family, is updated monthly. Therefore, it might be more up to date than printed documentation. To order additional copies of the Documentation CD-ROM, contact your local sales representative or call customer service. The CD-ROM package is available as a single package or as an annual subscription. You can also access Cisco documentation on the World Wide Web at http://www.cisco.com, http://www-china.cisco.com, or http://www-europe.cisco.com.
If you are reading Cisco product documentation on the World Wide Web, you can submit comments electronically. Click Feedback on the toolbar, and then select Documentation. After you complete the form, click Submit to send it to Cisco. We appreciate your comments.
Who Should Read This GuideThe Network Registrar CLI Reference Guide is written for system administrators. It assumes you understand how your site is configured, and are familiar with TCP/IP networking. The intent of the manual is to provide you information about how to use Network Registrar’s command-line program, nrcmd, and how to use the DHCP extension points to write your own extensions.
How This Guide Is OrganizedThis guide is intended to be used after you have installed and have Network Registrar running. The major sections of this guide are as follows:
Chapter 1 About the nrcmd Program Provides instructions on how to use the Network Registrar nrcmd program.
Chapter 2 Using the nrcmd Commands Describes all of the nrcmd commands.
Chapter 3 Using the nrcmd Program As an API Provides suggestions on how to create batch files to execute nrcmd commands.
15Network Registrar CLI Reference Guide
78-12875-01
PrefaceDocument Conventions
Document ConventionsNetwork management interfaces use the following conventions:
Caution Means reader be careful. In this situation, you might do something that could result in equipment damage or loss of data.
Note Means reader take note. Notes contain helpful suggestions or references to material not covered in the publication.
Tip Helpful hint. The description can present an optimum action to take in the context.
Obtaining Documentation and Submitting a Service RequestFor information on obtaining documentation, submitting a service request, and gathering additional information, see the monthly What’s New in Cisco Product Documentation, which also lists all new and revised Cisco technical documentation, at:
http://www.cisco.com/en/US/docs/general/whatsnew/whatsnew.html
Subscribe to the What’s New in Cisco Product Documentation as a Really Simple Syndication (RSS) feed and set content to be delivered directly to your desktop using a reader application. The RSS feeds are a free service and Cisco currently supports RSS version 2.0.
Open Source License AcknowledgementsThe following acknowledgements pertain to this software license.
Chapter 4 Using Extension Points Provides descriptions of the DHCP extension points.
Appendix A Codes and Formats Describes the status and error codes and the dump and load formats.
Appendix B DHCP Extension Dictionary API Describes the dictionary method calls you can use when accessing dictionaries from Tcl extensions and from shared libraries.
Appendix C DHCP Extension Dictionary Entries Describes the data items available in the request and response dictionaries.
16Network Registrar CLI Reference Guide
78-12875-01
PrefaceOpen Source License Acknowledgements
OpenSSL/Open SSL Project© 1998-2008 The OpenSSL Project. All rights reserved.
© 1995-1998 Eric Young ([email protected]). All rights reserved.
This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/).
This product includes cryptographic software written by Eric Young ([email protected]).
This product includes software written by Tim Hudson ([email protected]).
License 1:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. All advertising materials mentioning features or use of this software must display the following acknowledgment: “This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/).”
4. The names “OpenSSL Toolkit” and “OpenSSL Project” must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact [email protected].
5. Products derived from this software may not be called “OpenSSL” nor may “OpenSSL” appear in their names without prior written permission of the OpenSSL Project.
6. Redistributions of any form whatsoever must retain the following acknowledgment: “This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/).”
THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT “AS IS'” AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License 2:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions, and the following disclaimer in the documentation and/or other materials provided with the distribution.
17Network Registrar CLI Reference Guide
78-12875-01
PrefaceOpen Source License Acknowledgements
3. All advertising materials mentioning features or use of this software must display the following acknowledgement: “This product includes cryptographic software written by Eric Young ([email protected]).”
THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABL FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOOD OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
18Network Registrar CLI Reference Guide
78-12875-01
Ne78-12875-01
C H A P T E R 1
About the nrcmd ProgramYou can use either the graphical user interface (GUI) or the nrcmd command line interface (CLI) to configure and manage your DNS, DHCP, and TFTP servers. This chapter describes how to use the nrcmd command line interface.
It specifically describes:
• Invoking the nrcmd command
• Using the nrcmd command arguments
• Listing the nrcmd commands
Invoking the nrcmd CommandYou can use the nrcmd command in batch mode by executing scripts that use the commands or by using the interactive mode in which you enter commands at the nrcmd command prompt.
Note The nrcmd command is located in \Program Files\Network Registrar\bin on Windows and in /opt/nwreg2/usrbin on Solaris.
The command syntax is as follows:
nrcmd [general_options] [command] [specific_options]
Table 1-1 describes the general options. Chapter 2, “Using the nrcmd Commands,” describes the commands and their specific options.
Table 1-1 General Options to nrcmd Command
Option Description
-C cluster cluster is the name of the machine on which the Network Registrar servers are running. If not specified, the cluster name defaults to localhost.
-N user user is the Network Registrar user name.
-P password password is the password of the Network Registrar user.
-h prints help text.
1-1twork Registrar CLI Reference Guide
Chapter 1 About the nrcmd ProgramCommand Organization
If you omit the general options, Network Registrar gets them from the Registry or environment variables. If Network Registrar cannot find values for these parameters, it prompts you for them. If you omit the cluster name on a system where Network Registrar servers are installed, the nrcmd program assumes access to localhost and does not prompt you.
The Registry and environment variables are AIC_NAME for the name, AIC_PASSWORD for the password, and AIC_CLUSTER for the cluster name. The Solaris and Linux Registry keys are in a file with the user’s login name in the var/nwreg2/data/registry directory, with the file contents in the form name=value. The Windows Registry path is Software\American Internet\Network Registrar\2.0 and the key is HKEY_CURRENT_USER.
To execute the command line interface in interactive mode, enter:
nrcmd [-C cluster] [-N user] [-P password]
Typing this command displays the interactive prompt nrcmd> to which you enter:
nrcmd> command [optional-parameters]
To specify a series of items, use commas between the items. Do not add a space after the comma. For example:
nrcmd> zone example.com. set dynupdate-set=192.168.1.1,127.0.0.1
To terminate an interactive session, enter the exit command.
To view the online help, enter the help command.
Command OrganizationThe nrcmd commands specify a class of object, which you can create, delete, or list. Each of these objects in turn has attributes, which you can enable, disable, set, get, and unset, depending on data type. These objects may also have common methods, which are specific to the type of object, and that let you perform operations on groups of attributes.
When you use the nrcmd commands to configure Network Registrar, you manipulate the following:
• Classes of objects—these are things that you can create, delete, show or list, such as scopes, policies, or zones.
– create—creates an entry. If the entry already exists, this command overwrites it with the new information.
– delete—removes an entry.
– list—displays all the objects of a given type, including all attributes.
– listnames—displays only the names of all objects of a given type.
– show—displays the values of all the attributes.
-r logs in as a read-only user.
-b filename.txt filename is the name of a file of nrcmd commands that run in batch mode; reading a line at a time and printing a new line after the prompt.
Table 1-1 General Options to nrcmd Command (continued)
Option Description
1-2Network Registrar CLI Reference Guide
78-12875-01
Chapter 1 About the nrcmd ProgramCommand Organization
• Attributes of objects—these are things that you can enable or disable, or whose value you can set or display using the following common methods:
– enable—enables a Boolean type of attribute.
– disable—disables a Boolean type of attribute.
– set—sets the value of an attribute.
– get—displays the value of an attribute.
– unset—makes an attribute have no value. You cannot unset required attributes.
• Other custom methods—these are specific operations that you can perform on an object, beyond editing its attributes. Examples are adding a range of IP addresses to a scope, or removing hosts from a zone.
Command UsageHow you specify a series of arguments depends on the type of command you are using. The following shows the differences when using the create, set, and enable commands.
Create Keyword
When you use the create keyword and there are required arguments, you must supply them. You can also supply additional arguments. You must supply the required arguments in the specified order; however, you can specify the optional arguments in any order with the syntax attribute=value.
For example, the syntax for creating a scope is as follows:
scope name create ipaddress mask [attribute=value]
This means that you must supply an IP address and mask when you create a scope, and you can optionally specify other attributes of the scope.
The following example creates the scope testScope with the IP address of 128.103.1.1 and a mask of 255.255.255.0:
nrcmd> scope testScope create 128.103.1.1 255.255.255.0
For example, if you want to create a scope and also specify the name of the DNS zone to which a DHCP client’s host name should be added, enter:
nrcmd> scope testScope create 128.103.1.1 255.255.255.0 dns-zone-name=example.com.
After the create keyword creates and assigns all specified parameters to the object, it checks that all the required attributes have values (either defaults or user-specified). If you neglect to supply the required attributes, Network Registrar reports an error.
Set Keyword
You use the set keyword to set the value of a attribute. If you want to set a list of things, such as DNS servers, or IP addresses, you can separate them with commas. You can also use the set keyword to set several attributes on a single line—just specify the attribute and its value followed by a space and the next attribute and value pair.
1-3Network Registrar CLI Reference Guide
78-12875-01
Chapter 1 About the nrcmd ProgramCommand Organization
For example, to specify the name of the DNS zone to which a DHCP client’s host name should be added, enter:
nrcmd> scope testScope set dns-zone-name=QuickExample.com
For example, to specify the list of IP addresses that you will allow to perform zone transfers, enter:
nrcmd> zone QuickExample.com set auth-servers=196.68.1.10,196.68.1.20
For example, to set the client’s client-class and domain-name, enter:
nrcmd> client 1,6,02:02:02:02:02:02 set client-class-name=internal domain-name=QuickExample.com
The unset keyword places an attribute in the undefined state. The get keyword displays the value for an attribute.
Enable Keyword
You use the enable keyword to enable a boolean attribute. After you enable one boolean attribute, you may need to set its associated attributes. Use the disable keyword to disable a boolean attribute. You can use the unset keyword to remove the enabled or disabled state of the boolean attribute.
For example, to enable incremental transfer processing for the DNS server, enter:
nrcmd> dns enable ixfr-enable
To change the incremental transfer expiration interval, enter:
nrcmd> dns set ixfr-expire-interval=10d
Note You cannot add set keywords to an enable command line. You need to first enable the boolean attribute, and then, on the next command line, set the associated attributes.
Attribute Flags
Command attributes are described as follows:
• Required—The attribute is required for the object. You must set the attribute or accept its default, and you can modify the value. You cannot use the unset keyword to set a required attribute to undefined. Trying to do so returns the error message “386 - Required attribute cannot be deleted.”
• Optional—The attribute is optional and does require a value. You can set and reset the attribute, and you can use the unset keyword to make it undefined.
• Read-only—The attribute is immutable and read-only. You can use the get keyword with the attribute, but you cannot set or unset it. Trying to set or unset a read-only attribute returns the error message “385 - Read-only attribute cannot be modified.”
Saving Your ChangesThe CLI waits for one of the following events to occur before it saves your changes to the database:
• Invoking the save command
• Exiting from nrcmd
1-4Network Registrar CLI Reference Guide
78-12875-01
Chapter 1 About the nrcmd ProgramCommand Line Navigation Keys
• Reloading a server
• Adding a resource record or a host to a zone
Note Network Registrar saves resource records immediately.
Command Line Navigation KeysTable 1-2 lists keyboard navigation key combinations that are useful when entering nrcmd commands.
nrcmd CommandsTable 1-3 lists the nrcmd commands, alphabetically. You can use these commands on the command line or insert them into scripts.
Table 1-2 nrcmd Navigation Key Combinations
Key Combination Action
Control-a Go to the beginning of the line
Control-b Back one character
Control-d Delete one character
Control-e Go to the end of the line
Control-f Forward one character
Control-k Kill to the end of the line
Control-l Redraw the line
Control-n Next line in the history
Control-p Previous line in the history
Control-t Shift an individual character left
Control-u Delete the line and move the cursor to the beginning of the line
Control-w Delete one word backwards
Esc-b Back one word
Esc-f Forward one word
Table 1-3 nrcmd Commands
Command Description
address-block Creates and sets properties for address blocks
address-block-policy Configures DHCP embedded policies for address blocks
admin Creates administrators and assigns them passwords
client Creates clients and assigns them to client-classes
client-class Creates client-classes
1-5Network Registrar CLI Reference Guide
78-12875-01
Chapter 1 About the nrcmd Programnrcmd Commands
client-class policy Sets embedded client-class policies
client-policy Sets embedded client policies
custom-option Creates a custom DHCP option
dhcp Specifies the DHCP server attributes
dhcp-interface Specifies the IP address of the DHCP server’s hardware card
dns Specifies the DNS server attributes
exit Quits the nrcmd command
export Writes the state of the lease or a zone to a file
extension Integrates user-written DHCP extensions into the Network Registrar DHCP server
force-lock Obtains an exclusive lock for the nrcmd command session
help Provides online help
import Loads configuration information from a file
ldap Specifies the LDAP remote server attributes
lease Retrieves information about DHCP leases
lease-notification Notifies you when you run out of available leases in a scope
license Views and updates license information
namespace Creates and sets properties for namespaces
option-datatype Defines data types for use in defining vendor-supplied DHCP options
policy Specifies the policy information
remote-dns Specifies information about remote DNS servers
report Creates a summary of the dynamic and static IP address utilization for one or more clusters
save Saves the current configuration changes
scope Specifies scope attributes
scope-policy Sets embedded scope attributes
scope-selection-tag Creates scope selection tags
server Affects server behavior
session Configures session parameters
subnet Retrieves information about subnets
tftp Specifies the Trival File Transport Protocol (TFTP) server attributes
trap Activates Simple Network Management Protocol (SNMP) traps
vendor-option Defines vendor-supplied DHCP options
zone Specifies DNS zone attributes
Table 1-3 nrcmd Commands (continued)
Command Description
1-6Network Registrar CLI Reference Guide
78-12875-01
Ne78-12875-01
C H A P T E R 2
Using the nrcmd CommandsThis chapter contains descriptions for all the nrcmd commands and their attributes, alphabetically arranged in sections by command. The command syntax appears at the beginning of each section, followed by the syntax descriptions, attribute descriptions, and any usage guidelines. See the “Attribute Flags” section on page 1-4 for the types of attributes—required, optional, and read-only.
Attributes with time values are described with a default unit of time. However, you can append the characters “w,” “d,” “h,” “m,” or “s” immediately after the time value to translate the unit into weeks, days, hours, minutes, or seconds, respectively, if it fits in the allowed range of values. You can also mix time units in a single value, such as “1d6h” and “1d360m” (which are equivalent to “30h” and “1800m”).
Note If you use the get keyword to get the value of a valid attribute, but its value is not defined, Network Registrar returns the unexpected error “308 Unknown parameter.” However, using the show or list keyword shows the attribute in the resulting list.
Table 2-1 lists all the nrcmd commands.
Table 2-1 CLI Commands
Command Command Command
address-block, page 2-2 extension, page 2-57 report, page 2-98
address-block-policy, page 2-5 force-lock, page 2-60 save, page 2-102
admin, page 2-6 help, page 2-61 scope, page 2-103
client, page 2-8 import, page 2-62 scope-policy, page 2-110
client-class, page 2-13 ldap, page 2-65 scope-selection-tag, page 2-111
client-class-policy, page 2-15 lease, page 2-71 server, page 2-112
client-policy, page 2-16 lease-notification, page 2-79 session, page 2-116
custom-option, page 2-17 license, page 2-83 subnet, page 2-119
dhcp, page 2-20 namespace, page 2-84 tftp, page 2-121
dhcp-interface, page 2-41 option-datatype, page 2-87 trap, page 2-127
dns, page 2-43 policy, page 2-90 vendor-option, page 2-130
exit, page 2-51 remote-dns, page 2-96 zone, page 2-133
export, page 2-52
2-1twork Registrar CLI Reference Guide
Chapter 2 Using the nrcmd Commandsaddress-block
address-blockThe address-block command creates and sets attributes for Network Registrar address blocks.
An address block is a contiguous range of IP address space that is delegated to the DHCP server for assignment. The DHCP server expects to subdivide these address blocks for delegation to some other server or device, or for its own use in interaction with DHCP clients.
Address blocks can parent one or more subnets. Subnets are also contiguous ranges of IP address space that are bound to a specific client, usually a router or another DHCP server. Address blocks and subnets are similar to scopes in that they contain address ranges and other attributes necessary to configure the DHCP client-server interaction. Unlike scopes, address blocks and subnets do not have the address ranges available for assignment to DHCP clients and do not contain reserved addresses.
In a virtual private network (VPN) deployment where multiple VPNs use the same private address space, you can use logically identical address blocks simultaneously on multiple VPNs. See the “Virtual Private Network Configuration Example” section on page 2-4.
address-block name create address=netaddr [attribute=value...]
address-block name delete
address-block name set attribute=value [attribute=value...]
address-block name unset attribute
address-block name get attribute
address-block name [show]
address-block list
address-block listnames
address-block listsubnets
Syntax Description See Table 2-2 on page 2-3 for the address-block command attributes and their descriptions.
address-block name create address=netaddr [attribute=value...]
Creates an address block with a certain network address (including netmask prefix), and optionally adds attributes. See Table 2-2 on page 2-3 for the attributes to use with this command. The policy is the only required attribute, which defaults to the default policy if omitted.
nrcmd> address-block red create address=10.1.0.0/16 policy=Policy1
address-block name delete
Deletes an address block.
address-block name set attribute=value [attribute=value...]
Sets one or more attributes for the address block. The policy is the only required attribute, which defaults to the default policy if omitted.
nrcmd> address-block red set namespace=vpn-red
2-2Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsaddress-block
address-block name unset attribute
Unsets an optional address block attribute. You cannot unset the policy attribute.
address-block name get attribute
Gets the value for an address block attribute.
address-block name [show]
Shows the values of all attributes of the address block.
address-block list
Lists all address blocks and their attributes.
address-block listnames
Lists only the names of all address blocks.
address-block listsubnets
Lists the subnets created from the address block.
Attributes Table 2-2 describes the address-block command attributes and their values and defaults, if any.
Table 2-2 address-block Command Attributes
Attribute Usage Description
address create set
IP address of the address block. Use the set command to rename the address block.
embedded-policy get The embedded policy object for this address-block. Read-only. Gets its value from the address-block-policy command.
initial-subnet set= get unset
Initial subnet size of the address block, as a number of mask bits. Optional, no default.
nrcmd> address-block red set initial-subnet=16
namespace set= get unset
Namespace containing the address block. If set, it sets the both namespace and namespace-id attribute values. If you get the namespace value, it derives from the namespace-id value. Required, default is the default namespace.
namespace-id set= get unset
Namespace in which the address block resides. You must define the namespace using the namespace name create namespace-id command See the “namespace” section on page 2-84. Network Registrar actually uses the namespace-id value. If unset, the global namespace is used. Optional, default is to use the current namespace as set by the session set current-namespace command, or, if undefined there, the global namespace.
nrcmd> address-block red set namespace-id=99
policy set= get
Name of the policy associated with the address-block. See the policy command to create the policy. Required, default is default policy.
nrcmd> address-block red set policy=Policy1
2-3Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsaddress-block
Usage Guidelines Virtual Private Network Configuration Example
This sample configuration provisions an address block for a VPN called vpn-red. Once provisioned, the DHCP server allocates and manages subnets in the block according to client requests for subnets.
First create a new namespace for the VPN. Network Registrar uses the vpn-id from incoming request messages to determine the namespace to use when processing requests from the VPN. See the “namespace” section on page 2-84.
nrcmd> namespace vpn-red create
Create an address block that Network Registrar will manage as it processes subnet allocation requests for vpn-red.
nrcmd> address-block red create 10.1.0.0/16 policy=Policy1 nrcmd> address-block red set namespace-id=99 nrcmd> address-block red set initial-subnet=24 nrcmd> address-block red set subnet-increment=16
Related Commands address-block-policy, namespace, subnet
segment-name set= get
A label for the LAN that this block is part of. To group multiple, logical IP subnets on a single, physical LAN, give each block the same segment-name string. The server ignores character case when comparing segment-name strings. Optional, no default.
selection-tags set= get
A list of tag strings that are compared with incoming allocation requests’ selection tags. All of a request’s tags must match a block’s selection tags in order for the block to be used to satisfy the request. Separate multiple tags with a comma. Do not include commas within a tag. Optional, no default.
Table 2-2 address-block Command Attributes (continued)
Attribute Usage Description
2-4Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsaddress-block-policy
address-block-policyThe address-block-policy command configures DHCP embedded policies for address blocks. An address-block-policy is a policy object embedded within (and limited to) an address-block object. Each address block may contain option data within its embedded policy, and may refer to a named policy with more option data, such as a router IP address. For the priority of what option data the server returns to a subnet, see the “Policy Reply Options” section on page 2-94.
The DHCP server implicitly creates and deletes embedded address-block-policies when you create or delete the corresponding address blocks. You manipulate the address-block-policy using the name of the corresponding address-block.
For the syntax and descriptions, see the policy command.
Attributes See Table 2-19 on page 2-92 in the policy command section for the attribute descriptions. Except where noted in the table, many policy command attributes also apply to address block policies.
Usage Guidelines address-block-policy Reply Options
When the server is getting ready to return option data to a client, it examines up to seven policies. See the “Policy Reply Options” section on page 2-94 in the policy command.
Lease Times
An address block policy contains two lease times: the client lease time and the server lease time. The server controls these in the same way as it does with the policy command. See the “Lease Times” section on page 2-95 in the policy command.
Specifying Arrays in Vendor Specific Options
The address-block-policy command accepts data in vendor-specific options in the same way as the policy command. See the “Specifying Arrays in Vendor-Specific Options” section on page 2-95 in the policy command.
Related Commands address-block, client-policy, client-class, client-class-policy, policy, scope
2-5Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsadmin
adminThe admin command configures administrators for the cluster. You can choose any string for the administrator’s name. Network Registrar uses a password to authenticate each administrator.
admin name create password=password
admin name delete
admin name set password=password
admin name unset password
admin name get password
admin name enterPassword
admin name [show]
admin list
admin listnames
Syntax Description For the usage of passwords, see the “Passwords” section on page 2-7.
admin name create password=password
Creates an administrator (and optionally sets the password). If an entry already exists, the command overwrites it. Note that adding a password exposes it as plain text during entry. If you do not want to expose the password, use the admin name enter password command.
admin name delete
Deletes an administrator.
admin name set password=password
Sets or changes an administrator password. Note that this exposes the password as plain text.
admin name unset password
Unsets an administrator password, which appears as blank (without asterisks).
admin name get password
Gets an administrator password, if it exists, and displays it as asterisks.
admin name enterPassword
Returns entry and confirmation prompts for a password, which is not echoed on the screen.
admin name [show]
Shows an administrator name and password as asterisks.
admin list
Lists all administrators and their passwords, as asterisks.
admin listnames
Lists just the administrators’ names.
2-6Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsadmin
Usage Guidelines Passwords
Network Registrar uses the password to authenticate the administrator. If you create an administrator without a password, Network Registrar cannot authenticate the name and denies that administrator access to the cluster.
The admin user has the predefined changeme password, but you should change this password as soon as you can after installing Network Registrar.
Because the password is sensitive information, Network Registrar displays its value as asterisks in output from the admin list, admin name show, and admin name get password commands. However, specifying a password on the command line exposes it as plain text to viewers. To prevent this, omit the password when you create the account, then use the admin name enterPassword command. Keep track of the password you enter at the “password” and “verify password” prompts, because it does not display on the screen.
nrcmd> admin bob create password=bob-pwd 100 Okbob: password = ********nrcmd> admin bob create 314 Duplicate object - admin 'bob' already existsnrcmd> admin bob enterPassword password: verify password: 100 Ok
2-7Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsclient
clientThe client command assigns attributes to a specific client entry. These attributes determine what type of IP address or policy Network Registrar assigns to the requesting host. Network Registrar always stores the client identifier (MAC address or default) in lowercase characters.
client {macaddress | default} create [attribute=value…]
client {macaddress | default} delete
client {macaddress | default} set attribute=value [attribute=value…]
client {macaddress | default} unset attribute
client {macaddress | default} get attribute
client {macaddress | default} [show]
client list
client listnames
Syntax Description See Table 2-3 on page 2-9 for the client command attribute descriptions.
client macaddress create [attribute=value…] client default create [attribute=value…]
Creates the client identifier as a MAC address or the word default (and optionally defines its attributes). See the “Specifying MAC Addresses” section on page 2-10. The default client configuration applies to all clients that do not have an explicit configuration. If an entry for the client already exists, the command overwrites it. If you modify the default client configuration, you must reload the server. See the “Reloading the Server” section on page 2-10.
nrcmd> client 1,6,00:d0:ba:d3:bd:3b create client-class-name=external
client macaddress delete client default delete
Deletes the client entry.
client macaddress set attribute=value [attribute=value…] client default set attribute=value [attribute=value…]
Sets one or more attributes for the client.
client macaddress unset attribute client default unset attribute
Unsets the value of an attribute for the client.
client macaddress get attribute client default get attribute
Gets the value of an attribute for the client.
client macaddress [show] client default [show]
Shows the values of all attributes assigned to the client.
2-8Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsclient
client list
Lists all clients and any attributes assigned to them.
client listnames
Lists just the client identifiers.
Attributes Table 2-3 describes the client command attributes and their values and defaults, if any.
Table 2-3 client Command Attributes
Attribute Usage Description
action set= get unset
Action to take for the client. Optional, no default. Use one or more of the following comma-delimited tokens:
• exclude—Server ignores all communication from this client. If you use the command on the default client (client default action=exclude), only a client specifically registered through the client command can communicate with the server.
• one-shot—Server does not renew or re-offer any lease made to the client (either directly or in a client-class entry). See the “Using the one-shot Action” section on page 2-10.
• use-release-grace-period—Server delays the effect of DHCPRELEASE messages that the client sends. A release-grace-period for the policy specifies the delay time. During the grace period, the client’s lease is not available for any other client.
• none—No action.
authenticate-until set= get unset
Limits the authentication time to the duration that you specify, in a date format or the forever keyword. See the “Using the authenticate-until Attribute” section on page 2-11. Optional, no default.
client-class-name set= get unset
For clients only, the client-class to which the client belongs. If the client is not in a client-class, the DHCP server uses the default client-class. Optional, no default.
domain-name set= get unset
Domain name of the zone to use when performing dynamic DNS updates. The server places the client’s address (A) resource record in this zone. For the domain-name string to have an effect, you must use the scope name enable dynamic-dns command (the default) for the scope that allocated the address. Optional, no default.
embedded-policy get Embedded policy as set by the client-policy command. Read-only, but you can unset all the embedded policy attributes (while retaining the policy name).
host-name set= get unset
Client hostname. Use this string to replace any host-name DHCP option the DHCP client sends. See the “Values for the host-name Attribute” section on page 2-12. For the host-name string to have an effect, you must set scope name enable dynamic-dns (the default) in the scope that includes the address. Optional, no default.
policy-name set= get unset
Policy to add to the Network Registrar DHCP policy search list for this client. Optional, no default.
2-9Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsclient
Usage Guidelines Specifying MAC Addresses
Identify a client by its MAC addresses or by the word default. Specify the MAC address in the form hardware,length,address (including the commas). A sample Ethernet MAC address is 1,6,00:d0:ba:d3:bd:3b.
• hardware—Usually 1 (Ethernet) or 6 (Token Ring), but can be any number from 1 through 255.
• length—Octets in the MAC address (usually 6, but can be any number from 1 through 16).
• address—MAC address itself, with octets separated by colons, and each octet having a two-character hex value from 00 through FF (case-insensitive).
Reloading the Server
The DHCP server reads the client configuration data each time it receives a request for an IP address. If you modify a client that a MAC address identifies, you do not have to reload the server. However, if you modify the default client configuration, you must reload the server.
Using the one-shot Action
Use the one-shot action to allocate provisional addresses. This is useful when you want a client to have an address for only a short time. Configure the default client (or the client-class that the default client specifies) with the one-shot action.
nrcmd> client default set action=one-shot
The server then gives a lease to an unknown client, but when the lease expires, the server does not respond to that client during the lease grace period. After this period expires, the server does not respond to the client until another client gets the lease. This final period could be short or long, depending on the number of leases in the scope and clients using them. Newly available leases go on the end of a queue. Because the server allocates leases from the beginning of the queue, it might be quite some time before another client gets the lease.
You can allow the client a relatively short lease time, such as one day, and specify a long grace period, such as two weeks. This way you can offer an incentive to the client to register with some authority and become a known client, while not re-allocating the lease to another client. After the lease expires, the
selection-criteria set= get unset
Scope-selection tag or (comma-separated) tags to build the scope inclusion list. See the “scope-selection-tag” section on page 2-111 for how to create scope-selection tags. Optional, no default.
selection-criteria- excluded
set= get unset
Scope-selection tag or (comma-separated) tags to exclude when building the scope exclusion list. See the “scope-selection-tag” section on page 2-111 for how to create scope-selection tags. Optional, no default.
unauthenticated- client-class-name
set= get unset
For clients only, the name of the client-class to use if the client is no longer authenticated. Optional, no default.
user-defined set= get unset
User-defined string, such as a foreign key in a separate authorization database. This attribute has no effect on server operation. Optional, no default.
Table 2-3 client Command Attributes (continued)
Attribute Usage Description
2-10Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsclient
client cannot get another address for the two-week grace period. When another client gets the lease, the first client, whose use of the lease is no longer on record, can get another lease as an unknown client and have another opportunity to register.
You can configure the lease and grace period differently for each scope, so that provisional leases can have different lease and grace periods than nonprovisional ones. Provisional addresses are less restrictive if you use multiple DHCP servers, because each server operates its one-shot capabilities independently. With the approach described and two DHCP servers, an unregistered client can get two days of provisional address use every two weeks.
Using the authenticate-until Attribute
By default, client entries apply to clients for an unlimited time period. Using the authenticate-until attribute, you can limit a client entry by specifying an expiration time.
When a client entry is no longer valid, the DHCP server uses the unauthenticated-client-class- name attribute value for the name of the client-class entry to use in answering this DHCP request. If this attribute is not set or if there is no client-class entry in it, the DHCP server ignores the request and does not provide the client an address. The following are the valid authentication values:
• +num unit—Time in the future, where num is a decimal number and unit is s, m, h, d, or w for seconds, minutes, hours, days or weeks, respectively. For example, “+3w” is three weeks in the future.
• date—Month, day, 24-hour, and 2-or-4-digit-year. For example: “Jun 30 20:00:00 2002.” Enter the time that is local to the nrcmd process. If the server runs in another time zone, disregard the time zone and use local time instead.
• forever—The authentication for this client does not expire.
The following steps give an example of using the authenticate-until attribute to distinguish between clients that are authenticated and those that are not authenticated.
1. Create two scope-selection tags to tie the authenticated and unauthenticated clients to a scope.
nrcmd> scope-selection-tag AuthSelectionTag create nrcmd> scope-selection-tag UnauthSelectionTag create
2. Create an authenticated and an unauthenticated client-class. Set the selection criteria for each as appropriate.
nrcmd> client-class AuthClientClass create nrcmd> client-class AuthClientClass set selection-criteria=AuthSelectionTag nrcmd> client-class UnauthClientClass create nrcmd> client-class UnauthClientClass set selection-criteria=UnauthSelectionTag
3. Create the client and include the authenticate-until expiration time. Set the client-class-name and unauthenticated-client-class-name attributes as appropriate.
nrcmd> client 01:02:03:04:05:06 create authenticate-until=+10m nrcmd> client 01:02:03:04:05:06 set client-class-name=AuthClientClass nrcmd> client 01:02:03:04:05:06 set unauthenticated-client-class-name=UnauthClientClass
4. Create the authenticated and unauthenticated scopes, define their address ranges, and tie them to their respective scope-selection tags.
nrcmd> scope AuthScope create 192.168.2.0 255.255.255.0 nrcmd> scope AuthScope addRange 192.168.2.1 192.168.2.50 nrcmd> scope AuthScope set selection-tags=AuthSelectionTag nrcmd> scope UnauthScope create 192.168.2.0 255.255.255.0 nrcmd> scope UnauthScope addRange 192.168.2.51 192.168.2.100 nrcmd> scope UnauthScope set selection-tags=UnauthSelectionTag
2-11Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsclient
5. Enable client-class processing for the server.
nrcmd> dhcp enable client-class
6. Save the settings and reload the server.
nrcmd> save nrcmd> dhcp reload
After the authentication expires and the client requests another address, the DHCP server assigns the client an address from the range defined in the UnauthScope scope.
Values for the host-name Attribute
The host-name attribute value can be in one of two general forms. The first is simply the hostname string, which overrides the DHCP client request hostname. When you enter a valid name, the DHCP server ignores the actual value of the host-name option in the client’s DHCP packet and uses the client-entry option instead. The second form is a keyword that starts with the (@) symbol.
• hostname—The server uses this hostname to override the DHCP client request host name. This name can be any valid DNS name, but cannot include underscores.
• @host-name-option—The server uses whatever host-name option the client sends. This is the default behavior if there is no entry for the hostname in the client or client-class.
• @no-host-name-option—The server drops the host-name option that the client sends and does not replace it. If you disable DNS name synthesis, the client does not place a name in DNS.
• @use-macaddress—The server synthesizes a hostname for the client based on its MAC address. This ensures that the client has a valid, unique, and predictable name in DNS. The form that the resulting hostname takes is, for example, x1-6-00-d0-ba-d3-bd-3b.
Client Caching
The DHCP server maintains a memory cache of client data so that the server does not need to read the database to get this information for each client transaction. This is particularly useful for LDAP. However, the server does not keep this data indefinitely in cache because it is bound to change over time and the server should have updated data. The cached value is not expected to last until the next request cycle or across client reboots. The server has a limit on the number of entries it caches, as well as the amount of time it holds onto each cached entry. You can adjust both of these parameters. Keep the time short to allow the number of entries that you expect to arrive during the time that you set as the time to live (TTL). Moreover, the server has limited memory. You can, therefore, set a limit on the number of clients that the server keeps in the client cache by using the dhcp set client-cache-count command.
nrcmd> dhcp set client-cache-count=1000
The client cache, called the cache-time-to-live (TTL), is valid only for a short time (typically a few seconds). You can also configure this TTL using the dhcp set client-cache-ttl command. After the TTL expires, the server reads the client information from the database.
nrcmd> dhcp set client-cache-ttl=10
When the client cache count reaches the specified maximum, the server cannot cache any more clients until the TTL expires, after which it reads from the database and begins caching again.
The values you set for these two parameters depend on the expected client requests over time. You should balance the values so that the server should refer to the client cache item only once before the cache expires and the server refreshes the information directly from the database.
Related Commands client-policy, client-class, client-class-policy, policy, scope, scope-policy, scope-selection-tag
2-12Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsclient-class
client-classThe client-class command applies a set of attributes to a group or class of DHCP client configurations. Unlike most client configurations, the DHCP server reads the client-class configurations at server startup time. Therefore, you must reload the server for changes to take effect.
client-class name create [attribute=value…]
client-class name delete
client-class name set attribute=value [attribute=value…]
client-class name unset attribute
client-class name get attribute
client-class name [show]
client-class list
client-class listnames
Note You must enable client-class processing for the server before Network Registrar can recognize client-classes. nrcmd> dhcp enable client-class
Syntax Description See Table 2-3 on page 2-9 for the client command attribute descriptions. Except where noted in the table, many client command attributes also apply to the client-class command.
client-class name create [attribute=value…]
Creates the client-class (and optionally defines its attributes). Client-class names are case-sensitive. You must enable client-class processing for this to go into effect.
nrcmd> dhcp enable client-classnrcmd> client-class internal create nrcmd> dhcp reload
client-class name delete
Deletes the client-class.
client-class name set attribute=value [attribute=value…]
Sets one or more attributes for the client-class. See Table 2-3 on page 2-9 for the attributes.
client-class name unset attribute
Unsets a client-class attribute.
client-class name get attribute
Gets an attribute value for the client-class.
client-class name [show]
Shows the values of all attributes assigned to the client-class.
2-13Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsclient-class
client-class list
Lists all client-classes and any attributes assigned to them.
client-class listnames
Lists just the client-class names.
Attributes See Table 2-3 on page 2-9 in the client command for the attribute descriptions.
Usage Guidelines See the “Usage Guidelines” in the “client” section on page 2-8.
Related Commands client, client-policy, client-class-policy, dhcp, ldap, policy, scope-policy
2-14Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsclient-class-policy
client-class-policyThe client-class-policy command configures embedded policies for client-classes. Each client-class can contain option data in its embedded policy and can refer to a named policy with more option data, such as a router IP address. Network Registrar implicitly creates and deletes an embedded client-class policy when you create and delete the corresponding client-class. You manipulate the client-class policy using the name of the client-class to which the embedded policy is attached.
For the syntax and descriptions, see the “policy” section on page 2-90.
Attributes See Table 2-19 on page 2-92 in the policy command section for the attribute descriptions. Except where noted in the table, many policy command attributes also apply to client-class policies.
Related Commands client, client-policy, client-class, policy, scope-policy
2-15Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsclient-policy
client-policyThe client-policy command configures embedded policies for clients. Each client can contain option data in its embedded policy and can refer to a named policy with more option data, such as a router IP address. Network Registrar implicitly creates and deletes an embedded client policy when you create or delete the corresponding client. You manipulate the client policy using the name of the client to which the embedded policy is attached.
For the syntax and descriptions, see the “policy” section on page 2-90.
Attributes See Table 2-19 on page 2-92 in the policy command section for the attribute descriptions.
Related Commands client-class, client-class-policy, policy, scope-policy
2-16Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandscustom-option
custom-optionThe custom-option command creates and deletes custom DHCP options. You can also use this command to redefine any predefined DHCP options. If you delete this option, its definition returns to its original value.
custom-option name create number type [desc=“string”]
custom-option name delete
custom-option name set attribute=value [attribute=value…]
custom-option name unset attribute
custom-option name get attribute
custom-option name [show]
custom-option list
custom-option listnames
Syntax Description custom-option name create number type [desc=“string”]
Creates a custom option with a name, maps it to an option number, defines the data type, and optionally sets an attribute value. The positional attributes (in their correct order) are:
• name—Name of the custom option. Be consistent in naming the options in lowercase.
• number—Option number. Creating custom options that use the site-specific numbers 128 through 254 avoids conflicting with public DHCP options (see RFC2489). Optional, no default. Table C-2 on page C-2 lists public option numbers.
• type—Valid data type. Table 2-4 on page 2-18 lists the option data types. Optional, no default. See the Network Registrar User’s Guide for more information.
• desc=string—Description string. Optional, no default. Includes quotation marks if there are spaces between words.
nrcmd> custom-option red create 100 IPADDR nrcmd> custom-option blue create 101 BYTE_ARRAY
The following example creates a custom option that overlays the public time-offset option with a new definition.
nrcmd> custom-option green create 2 INT desc=”Option green overlays time-offset”
Note As shown in the example, you can create custom options that override public DHCP or BOOTP options. Cisco Systems highly recommends not doing this. Also, do not give the custom option a name in the form “option-number,” unless number is a numeric value from 1 through 254 that is not defined. See Table C-2 on page C-2 for the list of predefined option numbers. The following entry will generate a “duplicate object – option already exists” message. nrcmd> custom-option option-192 create 192 INT
2-17Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandscustom-option
custom-option name delete
Deletes a custom option. If the custom option is an overlay of a public option, the option reverts to its previous definition.
custom-option name set attribute=value [attribute=value…]
Sets or resets one or more attributes for a custom option.
• name=name—Changes the name of the custom option, preferably in lowercase.
• number=number—Changes the option number. Numbers 128 through 254 are reserved for site-specific options. Optional, no default. Table C-2 on page C-2 lists the public option numbers that you should avoid.
• type=type—Changes the valid data type (see Table 2-4). Optional, no default. See the Network Registrar User’s Guide for more information about option validation types.
• desc=string—Adds or changes the description string. Optional, no default.
nrcmd> custom-option blue set desc="this is an option called blue"
custom-option name unset attribute
Unsets the value of a custom option attribute.
custom-option name get attribute
Gets the value of an attribute for a custom option.
custom-option name [show]
Shows the attributes of a custom option.
custom-option list
Lists all custom options and any attributes assigned to them.
custom-option listnames
Lists just the names of the custom options.
Option Data Types Table 2-4 lists the option data types that the nrcmd program supports.
Table 2-4 Option Data Types
Option Data Type Type Name (Number) Definition
boolean BOOL (1) TRUE or FALSE.
byte BYTE (7) 8-bit unsigned integer.
byte array BYTE_ARRAY (8) Sequence of bytes represented in the form xx[:xx…] in which x is a hex character 0 through 9 or a through f. For example, to enter a series of four bytes containing the values 192, 168, 73 and 144, enter their hex values as “c0:a8:49:90.” Enter the ASCII string “ABCijk123” as “41:42:43:69:6a:6b:31:32:33.”
IP address IPADDR (5) IP address in the form of a.b.c.d.
IP address array IPADDR_ARRAY (6) Array of IP addresses.
signed array INT_ARRAY (3) Array of 32-bit signed integers.
signed integer INT (2) 32-bit signed intege.r
string STRING (4) ASCII text string.
2-18Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandscustom-option
Related Commands option-datatype, vendor-option
unsigned array UINT_ARRAY (12) Array of 32-bit unsigned integers.
unsigned integer UINT (11) 32-bit unsigned integer.
word WORD (9) 16-bit unsigned integer.
word array WORD_ARRAY (10) Array of 16-bit unsigned integers.
Table 2-4 Option Data Types (continued)
Option Data Type Type Name (Number) Definition
2-19Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdhcp
dhcpThe dhcp command configures the DHCP server in the cluster. Because there is only one DHCP server in a cluster, you do not need to reference the server by name.
dhcp enable attribute
dhcp disable attribute
dhcp set attribute=value [attribute=value…]
dhcp unset attribute
dhcp get attribute
dhcp trimIPHist date [-namespace name] [-logfile filename]
dhcp [show]
dhcp attachExtension extension-point extension-name [sequence-number]
dhcp detachExtension extension-point [sequence-number]
dhcp listExtensions
dhcp setPartnerDown partner-server [date]
dhcp getRelatedServers column-separator=string
dhcp updateSMS [all]
Note See also the “server” section on page 2-112 for other server control commands.
Syntax Description See Table 2-5 on page 2-22 for the dhcp command attribute descriptions.
dhcp enable attribute
Enables an attribute for the DHCP server.
nrcmd> dhcp enable client-class
dhcp disable attribute
Disables an attribute for the DHCP server.
nrcmd> dhcp disable import-mode
dhcp set attribute=value [attribute=value…]
Sets one or more attributes for the DHCP server.
nrcmd> dhcp set failover-maximum-client-lead-time=60
dhcp unset attribute
Unsets the value of a DHCP server attribute.
2-20Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdhcp
dhcp get attribute
Gets the value of an attribute for the DHCP server.
nrcmd> dhcp get discover-interfaces
dhcp trimIPHist date [-namespace name] [-logfile filename]
Supplies the DHCP server with a cutoff time to apply to the history records. When you reload the server, it examines the history database and deletes any records with an expiration time older than the date value.
nrcmd> dhcp trimIPHist “Tue Dec 31 19:00:00 2002” 101 Reload Needed
The effect of this command is not persistent; it only affects the next reload, not all subsequent reloads. You can specify to trim data in a specific namespace only. You can also redirect output to a log file, mainly for debugging purposes. Enter the date-string based on the local CLI time and date, in relative or fixed format:
• -numunit—Relative date in the form of a hyphen followed by a num digit, and unit as one of s (seconds), m (minutes), h (hours), d (days), or w (weeks). For example, -12d indicates “twelve days ago.”
• day-of-week month day hour:minute[:second] year—Enclose this format in quotes, since it includes space characters. Abbreviate the day of week and month to the first three characters; the hour is on a 24-hour clock; seconds are optional; and the year is the fully specified year or a two-digit representation in which 98 = 1998, 99 = 1999, and all other two digit values are in 20xx. For example, “Tue Dec 31 19:00:00 02”.
For more information on trimming, refer to the chapter on configuring DHCP scopes and leases in the Network Registrar User’s Guide.
dhcp [show]
Shows the values of the DHCP server attributes.
dhcp attachExtension extension-point extension-name [sequence-number]
Sets the specified extension point to call an extension. The following example adds an extension named test to the extension point post-packet-decode.
nrcmd> dhcp attachExtension post-packet-decode test 1
If the extension point is already configured to call an extension, use the sequence number to specify the order in which Network Register is to execute the extensions (1, 2, 3,...). If you omit a sequence number, Network Registrar overwrites the existing extension with the new value. See Table 2-7 on page 2-35 for descriptions of the extension-point values.
dhcp detachExtension extension-point [sequence-number]
Detaches extensions from an extension point. The following example removes the test extension from the post-packet-decode extension point. Network Registrar removes the extension at the specified sequence number. If you omit the sequence number, Network Registrar removes the extension at sequence number 1.
nrcmd> dhcp detachExtension post-packet-decode test 1
dhcp listExtensions
Lists the currently configured extensions and their sequence numbers (if you configure multiple extensions) at each extension point. Cisco recommends that you run listExtensions for an extension point before attaching a new one. Check the results to ensure that the new extension has a different sequence number than an existing one.
2-21Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdhcp
dhcp setPartnerDown partner-server [date]
Notifies the DHCP server that its partner DHCP server is down and moves all appropriate scopes into the PARTNER-DOWN state. Optionally, you can specify the date and time when the partner was last known to operate. The default is the current date. This command is the equivalent of the server dhcp setParnterDown command. For more information, see the “Setting Partner Down” section on page 2-114.
Caution Confirm that the partner server is completely down before issuing the setPartnerDown keyword.
dhcp getRelatedServers column-separator=string
Gets the status of the connection between the DHCP server and its DNS, LDAP, or failover servers. You can optionally specify that the report use string for separating columns. This command is the equivalent of the server dhcp getRelatedServers command. For more information, see the “Getting Related Servers” section on page 2-114.
dhcp updateSms [all]
Causes the DHCP server to perform System Management Server (SMS) network discovery. Optionally, including all sends out all leased addresses from the DHCP server to SMS. If you do not include this parameter, the server sends only those addresses leased since the last time you used this command. This command is the equivalent of the server dhcp updateSMS command. For more information, see the “Updating the System Management Server” section on page 2-115.
Attributes Table 2-5 describes the dhcp command attributes and their values and defaults, if any.
Table 2-5 dhcp Command Attributes
Attribute Usage Description
activity-summary-interval set= get unset
Time, in seconds, between activity summary log messages if enabled in the activity-summary setting in log-settings. Optional, default 300 seconds (five minutes).
addr-blocks-default- selection-tags
set= get unset
Specifies the default selection tag (or list of tags) to be associated with incoming subnet-allocation requests that do not contain any subnet name data. Optional, no default.
addr-blocks-use-client- affinity
enable disable unset
The DHCP server tries to allocate subnets to clients using address blocks that they already used. Disabling this attribute causes the server to supply subnets from any suitable address block, based on other selection data in the clients’ messages. Optional, default enable.
addr-blocks-use-lan- segments
enable disable unset
Controls whether DHCP subnet-allocation uses the lan-segment attribute when configured on address blocks. Optional, default disable.
addr-blocks-use-selection- tags
enable disable unset
Controls whether the server compares the incoming subnet-allocation requests’ subnet name data with each address block’s selection tags. An address block will only be considered if the two match. Optional, default enable.
2-22Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdhcp
append-user-class-id-to- selection-tag
enable disable unset
Meaningful only if dhcp set map-user-class-id=1 (map the user class ID to the scope-selection tag). If you set this attribute to true (the default), Network Registrar appends the user class ID to existing scope-selection tags. If set to false, the user class ID replaces any existing tags. See the “scope-selection-tag” section on page 2-111. Optional, default enable.
client-cache-count set= get unset
Allocates the specified maximum number of clients to the client cache. The DHCP server allocates the amount at startup and frees it up at shutdown. See the “Client Caching” section on page 2-12. Optional, default 1000 clients.
nrcmd> dhcp set client-cache-count=1000
client-cache-ttl set= get unset
Time to live for the client cache, in seconds. The DHCP server removes the entries in memory after this period. See the “Client Caching” section on page 2-12. Optional, default 10 seconds.
nrcmd> dhcp set client-cache-ttl=10
client-class enable disable unset
Controls whether the DHCP server uses the client and client-class configuration objects to affect request processing. Optional, default disable.
cnr-5-0-upgraded get Shows whether the DHCP server was upgraded for Network Registrar Release 5.0. Read-only.
collect-performance- statistics
enable disable unset
Controls whether the DHCP server collects statistics for performance monitoring. Optional, default disable.
dbsn get Minor serial number of the specified server, which gets incremented after every set of configuration changes. Useful with the session assert commands. See the “Session Asserts” section on page 2-117. Read-only.
defer-lease-extensions enable disable unset
Controls whether the server renews a client’s lease that is less than halfway to its expiration. By default, the server defers the lease extension—does not renew the lease, but grants another one while keeping the lease period. This way, the server can avoid extra database updates. However, if a client is more than halfway to expiration, this setting has no effect, and the server extends the lease to the full configured lease period. See the “Deferring Lease Extensions” section on page 2-36. Optional, default enable.
Table 2-5 dhcp Command Attributes (continued)
Attribute Usage Description
2-23Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdhcp
delete-orphaned-leases enable disable unset
Leases that are in the lease state database can have a namespace-id recorded with them, or they can be orphaned. When the DHCP server initializes its cache from the lease state database, it expects every lease with a namespace-id to match a configured namespace. If the server finds a lease whose namespace-id does not match a configured namespace, this property controls whether to delete that lease from the database or to ignore that entry (the default), assuming that at some point the server is configured with the appropriate namespace. In either case, the server cannot use the lease. Optional, default disable.
delete-orphaned-subnets enable disable unset
As the DHCP server starts up, it tries to locate the parent namespace and address block of each subnet. If a subnet refers to a namespace that is no longer configured in the server, or if the server cannot locate a parent address block that contains the subnet, the server uses this attribute to decide whether to keep the subnet entry in the state database (the default) or to delete it permanently. Optional, default disable.
discover-interfaces enable disable unset
Controls whether the DHCP server looks at all the interface cards on the host and processes DHCP requests that it receives from any of them. However, it only offers addresses to requests from subnets defined with a valid scope with available addresses. If disabled, the DHCP server uses only its list of configured interfaces. See the “dhcp-interface” section on page 2-41. Optional, default enable.
dns-timeout set= get
Time, in milliseconds, that the DHCP server waits for a response before retrying a dynamic DNS request. Required, default 60000 milliseconds.
docsis-version-id-missing set= get unset
String (maximum 255 characters) that gets substituted with the %@docsis-vers% variable in the policy command’s boot-file attribute. This substitution occurs if the DHCP request packet does not contain a vendor-class-id option or the option does not contain a DOCSIS version id. Optional, no default.
drop-old-packets set= get unset
Time, in seconds, that a packet can age and still be processed. If the server is very busy, this could delay processing packets in the UDP input queue. The DHCP protocol allows clients to retry packets that are not processed in a few seconds. Therefore, allowing the server to process packets that are older than a few seconds could increase the congestion. If the age of a packet is greater than the value of this attribute when the server processes it, the server drops the packet. Optional, default 8 seconds.
drop-packet-on-extension- failure
enable disable unset
Controls whether the server drops a packet (if possible) when it encounters a failure in an extension. Optional, default enable.
Table 2-5 dhcp Command Attributes (continued)
Attribute Usage Description
2-24Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdhcp
extension-trace-level set= get unset
Default value of the extension trace level for every request object. See the “extension” section on page 2-57. You can override this value by setting the extension-trace-level in a user-written extension. Setting the level to 0 (the default) causes very little tracing. Setting the level to 3 causes considerable tracing. Optional, default 0.
failover enable disable unset
Controls whether all scopes that use the server’s failover configuration can engage in failover. See the “Failover Attribute States” section on page 2-109. If disabled (the default), those scopes with failover explicitly enabled for the scope are still available for failover. Optional, default disable.
failover-backup-percentage set= get unset
With failover enabled, the percentage of currently available (unleased) addresses that the main server should send to the backup server to allocate to new DHCP clients when the main server is down. The value is only meaningful for the main server. Optional, default 10 percent.
failover-backup-server set= get unset
With failover enabled, the DNS name of the backup server associated with all scopes if you did not use the scope name set failover-backup-server command. If this DNS name resolves to the IP address of the current server, this server operates as the backup server for all of these scopes. It is an error if both the main and backup server names resolve to addresses on the same server. Optional, no default.
failover-bulking enable disable unset
With failover enabled, controls whether a failover bind update (BNDUPD) contains multiple lease state updates. Affects only the lease state updates that DHCP client activity generates. Optional, no default.
failover-dynamic-bootp- backup-percentage
set= get unset
With failover enabled, the percentage of currently available (unreserved) addresses that the main server should send to the backup server for scopes set with scope name enable bootp. See the “Setting the Failover Backup Percentage” section on page 2-37. Optional, no default.
failover-lease-period-factor set= get unset
With failover enabled, 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. See the “Setting the Failover Lease Period Factor” section on page 2-38. Optional, default factor of 1.5.
failover-main-server set= get unset
With failover enabled, the DNS name of the main server associated with all scopes where scope name set failover-main-server is not set. If this DNS name resolves to the IP address of the current server, this server operates as the main server for all of these scopes. It is an error if both the main and backup server names resolve to addresses on the same server. Optional, no default.
Table 2-5 dhcp Command Attributes (continued)
Attribute Usage Description
2-25Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdhcp
failover-maximum-client- lead-time
set= get unset
With failover enabled, the maximum client lead time (MCLT), in seconds. The MCLT is the maximum time that one server can extend a client’s lease beyond what its partner knows it to be. You must define the MCLT on the main server, which communicates it to its partner. It is ignored on a backup server. See the “Setting the Maximum Client Lead Time” section on page 2-38. Optional, default 3600 seconds (60 minutes).
failover-poll-interval set= get unset
With failover enabled, the polling interval of the failover partners (in seconds) to confirm network connectivity. Optional, default 15 seconds.
failover-poll-timeout set= get unset
With failover enabled, the interval (in seconds) after which failover partners who cannot communicate know that they lost network connectivity. Optional, default 60 seconds.
failover-recover set= get unset
With failover enabled, time at which the server performs initialization and goes into RECOVER state. If server A is running, server B issues this command to ask for the state of server A. 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 2002.” Optional, default zero (0).
failover-safe-period set= get unset
With failover enabled and the failover-use-safe-period attribute set, the safe period, in seconds. You must define it in the main server. The safe period can differ on the main and backup servers. See the Network Registrar User’s Guide for more information. Optional, default 86400 seconds (24 hours).
failover-use-safe-period enable disable unset
With failover enabled and the failover-use-safe-period attribute set, you must enable the failover-use-safe-period attribute to cause Network Registrar to go into the PARTNER-DOWN state automatically. If you disable this attribute (the default), Network Registrar never goes into the PARTNER-DOWN state automatically. You must then use the dhcp setPartnerDown command. See the “Setting Partner Down” section on page 2-114. Optional, default disable.
get-subnet-mask-from- policy
enable disable unset
Controls whether the DHCP server searches all relevant policies for a subnet mask option when constructing a response to send to a client. Normally, the DHCP server retains the subnet mask configured in the scope containing the base being granted to the DHCP client. Optional, default disable.
hardware-unicast enable disable unset
Controls whether the DHCP server sends unicast rather than broadcast responses when a client indicates that it can accept a unicast. This attribute is only available on the following operating systems: Solaris, Windows 2000, and Windows NT. Optional, default enable.
Table 2-5 dhcp Command Attributes (continued)
Attribute Usage Description
2-26Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdhcp
ignore-icmp-errors enable disable unset
With this attribute enabled (the default), if you configured the DHCP server to send ICMP ECHO (ping-before-offer) requests, the server makes unavailable any address for which it receives an ECHO reply within its configured timeout period. If you disable this attribute, the DHCP server also treats ICMP DEST_UNREACHABLE and TTL_EXPIRED error messages that it receives after sending ICMP ECHO requests as grounds for making an address unavailable. Optional, default enable.
ignore-requests-for-other- servers
enable disable unset
Controls whether to prevent the normal DHCP server response to client requests for other servers. Normally, if the DHCP server sees a client requesting a lease from another server for an address that this server is configured to control, it sets the lease to unavailable. However, some clients could send request packets with bad server ID options (rather than packets actually directed to other servers) that the server could wrongly interpret as the address being unavailable. You can set this attribute to prevent this from occurring. See also the “Setting a Lease to Unavailable” section on page 2-77. Optional, no default.
import-mode enable disable unset
Controls whether to have the DHCP server recognize only packets generated from the import leases command and to ignore all others. See the “Putting the Sever in Import Mode” section on page 2-37. You can use this attribute if you want to update your DHCP server and prevent clients from receiving addresses during this period. Optional, default disable.
inhibit-busy-optimization enable disable unset
Controls whether to prevent the server from using optimization to recover from periods of congestion. By default, the DHCP server determines that it is heavily loaded when the number of request packets reaches two-thirds of the total allocated. It logs a message and attempts to recover from the congestion by performing several optimizations. For example, it relaxes the requirement to keep the client’s last transaction time updated to the granularity specified by the last-transaction-time-granularity attribute.
When the number of request packets drops to one-third of the total allocated, the server logs a message and returns to normal operation. If you enable the inhibit-busy-optimization attribute, the server does not use the optimizations or log the messages when it gets congested. Optional, default disable.
ip-history enable disable unset
Controls recording IP history data for the IP history database. See the Configuring DHCP Scopes and Leases chapter of the Network Registrar User's Guide. Default, disable.
Table 2-5 dhcp Command Attributes (continued)
Attribute Usage Description
2-27Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdhcp
ip-history-dir set= get unset
Path to the directory of the database containing the IP (lease) history. It is best to store the history files on a different disk partition from the server’s lease state database. Because of this, use absolute paths if possible. Relative paths are relative to the server logs directory. The server default logs directory is, on Solaris and Linux, in the /var/nwreg2/logs directory; on Windows, in the C:\Program Files\Network Registrar\Logs folder. Use forward slashes (“/”) as path separators and quote paths containing space characters. Then, use the default statement.
Absolute paths are allowed for putting the IP history database on a separate file system from the logs or configuration directory.
You must set this attribute if you also use the dhcp enable ip-history command. Optional, default is the logs directory.
last-transaction-time- granularity
set= get unset
Time, in seconds, that Network Registrar guarantees that the last transaction time is accurate. Do not set this lower than the default of 60 seconds). For optimal performance, set it to a value that is greater than half of your lease interval. See the “Deferring Lease Extensions” section on page 2-36. Optional, default 60 seconds.
ldap-mode set= get unset
Determines the preference for using LDAP servers if more than one LDAP server is configured. Optional, no default. There are two possible values:
• round-robin—The DHCP server ignores the servers’ preferences. It treats all LDAP servers (those configured to handle client queries and those configured to accept lease-state updates) equally.
• failover—The DHCP server uses the active LDAP server with the lowest preference. If the preferred server loses its connection or fails, the DHCP server uses the next LDAP server in preference order. The DHCP server uses servers with equal preference in round-robin order.
log-settings set= get unset
Determines which events to log in the log files. See Table 2-6 on page 2-33. Logging additional detail about events can help analyze a problem. However, leaving detailed logging enabled for a long period can fill up the log files. Optional, the default flags are default, incoming-packets, and missing-options.
mac-address-only enable disable unset
Controls whether the DHCP server uses the client’s MAC address as the only client identifier. The standard behavior, as specified in RFC 2132, is to use the client ID option (if it is present) as the unique client identifier. You can use this argument to identify all clients that use the server. Optional, default disable.
Table 2-5 dhcp Command Attributes (continued)
Attribute Usage Description
2-28Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdhcp
map-user-class-id set= get unset
Determines the handling of user class-id. This attribute is global and is set for all DISCOVER packets. Optional, default 0. The values are:
0—Ignore the user class-id option (default). 1—Map the user class-id option to the scope-selection tag. See the “scope-selection-tag” section on page 2-111. 2—Map the user class-id option to the client-class.
max-dhcp-requests set= get
Number of buffers that the DHCP server allocates for receiving packets from DHCP clients and failover partners. You should allocate at least 100 buffers; perhaps as many as several thousand is reasonable in some installations. Required, default 500 buffers.
max-dhcp-responses set= get
Number of buffers that the DHCP server allocates for responding to DHCP clients and communicating with failover partners. The number of buffers allocated should be at least two times the number allocated for the max-dhcp-requests attribute. Perhaps as many as several thousand is reasonable in some installations. Required, default 1000 buffers (if failover is configured, the server configures additional responses).
max-dns-packets set= get
Number of DNS packet buffers that the DHCP server allocates for sending dynamic updates to the DNS server. You can reduce the DHCP server’s memory requirement by reducing the number of DNS packets, at the risk of missing updates. Required, default 100 buffers.
max-dns-renaming-retries set= get
Number of times that the DHCP server can try to add a host in DNS even if it detects that the host’s name is already present. This controls the number of times the DHCP server tries to modify a host’s name to resolve a conflict on each failed update. Required, default 2 retries.
max-dns-retries set= get
Number of times that the server tries to send dynamic updates to a DNS server. Required, default three retries.
max-dns-ttl set= get
Time to live (TTL) ceiling, in seconds, for DNS records added through dynamic DNS. When the DHCP server adds a DNS record, it sets the TTL to less than one-third of the lease time, or this ceiling value. Note that the DNS record’s effective TTL could actually be the zone’s minimum TTL. Required, default 86400 seconds.
max-ping-packets set= get unset
Number of buffers that the server allocates for sending and receiving ICMP ping messages, if you use the scope name enable ping-clients command. See Table 2-24 in the “scope” section on page 2-103. Optional, no default.
Table 2-5 dhcp Command Attributes (continued)
Attribute Usage Description
2-29Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdhcp
max-waiting-packets set= get unset
Number of packets that can wait for processing for an address. The server queues only the most recently received n packets (of an address) for processing. If an additional packet associated with that address arrives and n packets are already queued, the server drops the oldest packet and queues the new one. See the dropped-waiting-packets log setting attribute in Table 2-6 on page 2-33. It also drops duplicate packets (whose XID, client-id, and MAC address are the same as one already queued). If you accept the default of 0, the server processes all packets. Optional, default 0.
mcd-blobs-per-bulk-read set= get unset
Number of blob objects for a bulk read. Use this attribute to tune DHCP start and reload times. Generally, a higher value results in faster server start and reload times, at the cost of using more memory. Optional, values from 1 through 2500, default 256 blobs.
one-lease-per-client enable disable unset
Controls whether to have the DHCP server release any other leases that the client may have had on this server. Because the default behavior for the Network Registrar DHCP server is to store all the leases that a client obtains, this command ensures that the DHCP server only stores one lease. A client might obtain a number of leases if a user with a laptop travels throughout the building and requests leases at different locations on the network. Optional, default disable.
return-client-fqdn-if-asked enable disable unset
Controls whether the system returns the client-fqdn (fully qualified domain name) option to the client in the outgoing packet if the client requests it in the parameter request list. For example, the client may want to know the status of the DNS activity. Optional, default enable.
The system always sets the flags in the option to 0x3 and the RCODE1 and RCODE2 to 255. It also sends back whatever string was sent in, even if the use-client-fqdn attribute is turned off and no matter what the actual name is (or may ultimately be) in DNS.
save-lease-renewal-time enable disable unset
If set to true, the server saves the lease renewal time (the minimum time in which the client is expected to issue a lease renewal) as part of the lease in persistent memory. Optional, default disable.
save-relay-agent-data set= get unset
The lease state database in Network Registrar 5.5 saves all relay agent data. Therefore, any changes to this attribute have no effect. Optional, no default.
save-vendor-class-id enable disable unset
Controls whether the server saves the value of the vendor-class-identifier DHCP option (60) in memory. This affects what you can store in an LDAP directory. Optional, default disable.
Table 2-5 dhcp Command Attributes (continued)
Attribute Usage Description
2-30Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdhcp
scope-selection-tags set= get unset
List of scope-selection tags associated with the server. In this context, refers to a named entity that controls matching client and client-class entries with candidate scopes. See the “scope-selection-tag” section on page 2-111. Optional, no default.
skip-client-lookup enable disable unset
If enabled, causes the DHCP server to skip looking up the client entry for client-class processing. If disabled (the default), the DHCP server looks up the client entry first. Optional, default disable.
sms-lease-interval set= get unset
Sets the time interval, in milliseconds, between sending addresses to the System Management Server (SMS). After you install a future release of Microsoft BackOffice Resource Kit (which contains an enhanced version of smsrsgen.dll), reduce this interval or set it to 0. Optional, default 1100 milliseconds.
sms-library-path set= get unset
Overrides the internal default value for the name of the SMS dll. The default is the empty string. If you specify an empty string, the system defaults to the internal server default of smsrsgen.dll. Optional, no default.
sms-network-discovery set= get unset
Causes the DHCP server to generate SMS network discovery records. To enable this attribute, set it to 1; to disable it, set it to 0 (the default). Use this attribute in conjunction with the dhcp updateSms command. See the “server” section on page 2-112. Optional, default 0.
sms-site-code set= get unset
Specifies the site code of the SMS server that receives discovery records when you issue the updateSms keyword. You must initialize this attribute to the appropriate SMS site code for the updateSms keyword to operate. See the “server” section on page 2-112. Optional, no default.
update-dns-for-bootp enable disable unset
If the server replies to a BOOTP request and offers a lease from a scope that is configured for DNS updates, the DHCP server checks this attribute before beginning the update. You can use this attribute to prevent DNS updates for BOOTP clients, while allowing updates for DHCP clients. Optional, default enable.
use-client-fqdn enable disable unset
Controls whether the system examines the client-fqdn (fully qualified domain name) option for the hostname. If there are characters after the first dot in a client-fqdn option, the server ignores them because it determines the domain from the scope. Set this attribute to false if you do not want the server to determine a hostname from this option, possibly because the client is sending unexpected characters. Optional, default enable.
Table 2-5 dhcp Command Attributes (continued)
Attribute Usage Description
2-31Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdhcp
DHCP Log Settings See Table 2-6 for the log flags that you can set using the dhcp command. The log setting that is enabled by default is incoming-packets.
You can modify the logging behavior of the DHCP server by setting flags on the log-settings attribute. For example, you can suppress warning messages for unconfigured or missing options.
nrcmd> dhcp set log-settings=default,incoming-packets nrcmd> dhcp reload
You can turn on client and client-class debugging for the DHCP server.
nrcmd> dhcp set log-settings=client-detail nrcmd> dhcp reload
You can also turn off debugging entirely for the DHCP server.
nrcmd> dhcp set log-settings=default nrcmd> dhcp reload
use-client-fqdn-first enable disable unset
Controls whether the system examines the client-fqdn option on incoming packets first, before the host-name option, when determining a hostname for a client. If there is a client-fqdn option with a hostname specified, the system uses that hostname. If the system finds no client-fqdn option in the incoming packet, the system uses the host-name option.
If the use-client-fqdn-first parameter is set to false, the system examines the host-name option first and uses any name found in that option. If that option does not appear, it examines the client-fqdn option for a hostname. Optional, default enable.
use-dns-update-prereqs enable disable unset
By default, the DHCP server uses prerequisites in its DNS update messages when it is performing DNS updates on behalf of clients. If disabled, the server does not include prerequisites. Without them, the server associates the last client who uses a given domain name with that name, even if another client was already associated with it. Optional, default enable.
use-host-name enable disable unset
Controls whether the system examines the host-name option for the hostname. Disable this attribute if you do not want the server to determine a hostname from this option, possibly because the client is sending unexpected or “junk” characters. Optional, default enable.
use-ldap-client-data enable disable unset
Controls whether the DHCP server attempts to read client-entry data using the configuration supplied by the ldap command. See the “ldap” section on page 2-65. Optional, default disable.
vpn-communication enable disable unset
If enabled (the default), the DHCP server can communicate with DHCP clients on a different virtual private network (VPN) from that of the DHCP server by using an enhanced DHCP relay agent capability. This enhanced capability is signalled by the appearance of the server-id-override sub-option in the relay-agent-information-option (DHCP option 82). Optional, default enable.
Table 2-5 dhcp Command Attributes (continued)
Attribute Usage Description
2-32Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdhcp
Table 2-6 DHCP Log Flags
Flag Messages Logged to name-dhcp-1-log
activity-summary Every five minutes. This is useful when you enable many of the no-xxx log settings because it provides some indication of the activity in the server without imposing the load required for a log message corresponding to each DHCP message. Configure the frequency for these messages using the dhcp set activity-summary-interval command.
client-criteria- processing
When the server examines a scope to find an available lease or to determine if a lease is still acceptable for a client who already has one. This setting can be useful when configuring or debugging client-class scope criteria processing. It logs a moderate amount of data, so you should not leave it enabled for long.
client-detail After every client-class client lookup operation. This line shows all the data found for the client as well as the data found in the client’s client-class. This is useful when setting up a client-class configuration and for debugging problems in client-class processing.
default At a low level in several parts of the DHCP server. This flag is on by default. If you reconfigure the default, this logging does not appear.
dns-update-detail Additional log messages for all DNS operations. This flag is helpful in diagnosing problems in dynamic DNS operations.
dropped-waiting- packets
If the system drops packets due to the setting of the max-waiting-packets DHCP attribute. The server may drop packets if the queue length for any IP address exceeds the value of the max-waiting-packets attribute. If the dropped-waiting-packets attribute is enabled, the server logs a message whenever it drops a waiting packet from the queue for an IP address.
failover-detail Concerning failover protocol operations and state transitions. Setting this does not place a significant load on the server.
incoming-packets As a single line for every incoming packet. This setting is especially useful when you initially configure a DHCP server or BOOTP relay, in that an immediate positive indication exists that the DHCP server receives packets. Default enabled.
incoming-packet- detail
With the contents of every DHCP packet received by the DHCP server in human readable form. This setting enables the built-in DHCP packet sniffer for input packets. The log files fill up (and turn over) very rapidly when you enable this setting. It also causes a significant performance impact on the DHCP server, so that you should not leave it enabled for long.
ldap-create-detail When the DHCP server sends a request creating a lease state entry to an LDAP server, receives a response from an LDAP server, or retrieves a result or error message from an LDAP server.
ldap-query-detail When the DHCP server initiates a query to an LDAP server, receives a response from an LDAP server, or retrieves a query result or an error message from an LDAP server.
ldap-update-detail When the DHCP server sends a lease update request to an LDAP server, receives a response from an LDAP server, or a retrieves a result or error message from an LDAP server.
2-33Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdhcp
leasequery When processing leasequery packets without internal errors, and when a lease query results in an acknowledgement (ACK) or negative acknowledgement (NAK) message.
minimal-config-info Reduces the number of configuration messages that Network Registrar logs when the server starts or reloads. In particular, the server does not log a message for every scope when this flag is set.
missing-options When a policy does not include an option a DHCP client requests, to that the DHCP server cannot supply it. This flag is on by default.
no-dropped-bootp- packets
Prevents logging the single line message normally logged for every dropped BOOTP packet.
no-dropped-dhcp- packets
Prevents logging the single line message normally logged for every DHCP packet dropped due to DHCP configuration. See the no-invalid-packets flag for messages associated with packets dropped because they are invalid.
no-failover-activity Prevents logging normal activity messages and some warning messages logged for failover. Serious error log messages continue to appear independently of this log setting.
no-failover-conflict Prevents logging warnings about potential conflicts between failover partners, but still logs errors. Setting this log setting can greatly reduce the amount of logging produced by a failover without losing the errors.
no-invalid-packets Prevents logging the single line message normally logged for every DHCP packet dropped for being invalid. See the no-dropped-dhcp-packets flag for messages associated with packets dropped because of the DHCP server configuration.
no-reduce-logging- when-busy
When the server is very busy. Normally, the DHCP server reduces logging when it becomes very busy, such as when it uses over two-thirds of the available receive buffers (which is itself a configurable value). To do this, it sets the no-success-messages, no-dropped-dhcp-packet, no-dropped-bootp-packets, no-failover-activity, and no-invalid-packet flags and clears everything else except the activity-summary flag. When it is no longer very busy, such as when only one-third of the available receive buffers used, the server restores the previous settings. Setting this flag prevents Network Registrar from taking these actions.
no-success-messages Prevents logging the single line message normally logged for every successful outgoing DHCP response packet. This affects logging for only successful outgoing DHCP response packets. This log setting can greatly increase server performance.
no-timeouts Prevents logging messages associated with the timeout of leases or offers.
outgoing-packet- detail
Contents of every DHCP packet transmitted by the DHCP server in a human readable form. Enables the built-in DHCP packet sniffer for output packets. The log files fill up (and turn over) very rapidly when this setting is enabled. Enabling this setting also causes a performance impact on the DHCP server because of the volume of outgoing packets so you should not leave it enabled for long.
Table 2-6 DHCP Log Flags (continued)
Flag Messages Logged to name-dhcp-1-log (continued)
2-34Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdhcp
Extension Points Table 2-7 summarizes the extension points available for controlling the DHCP server (in general sequential order). See Chapter 4, “Using Extension Points.”
unknown-criteria As a single-line when the DHCP server finds a client entry that specifies a selection-criteria or selection-criteria-excluded that is not found in any scope appropriate for that client’s current network location.
Table 2-6 DHCP Log Flags (continued)
Flag Messages Logged to name-dhcp-1-log (continued)
Table 2-7 dhcp Command Extension Points
Extension Point Purpose
check-lease- acceptable
Reached immediately after the server determines that the current lease is acceptable for this client. The extension can examine the results of that operation and can cause the routine to return different results.
Caution Use this extension point with extreme care. Incorrect usage can create an infinite loop in the server.
post-client-lookup Examines the results of the entire client-class processing operation and acts based on those results, such as rewriting the results or dropping the packet. You can use this extension point to place data items in the environment dictionary to affect the processing of an extension running at the pre-packet-encode extension point. Note that you cannot change the client-class at this point, but you can override certain values determined by the client or client-class already examined.
post-packet-decode First extension point encountered when a request arrives. It immediately follows the decoding of the input packet and precedes any processing on the data in the packet. The primary activity for an extension at this point is to read information from an input packet and act on it, for example, to rewrite the input packet.
post-send-packet Updates an external process or database with information about a request or response.
pre-client-lookup Runs only if you set dhcp enable client-class for the server. This extension point allows an extension to perform any or all of the following:
• Modify the client that is looked up during client-class processing.
• Specify individual data items to override any data items found from the client entry or the client-class that it specifies.
• Instruct the server to skip the client lookup altogether. In this case, the only client data used is that specified.
• Drop the packet.
pre-packet-encode Rewrites information in the response packet that the DHCP server sends to the user. This extension point comes after the response packet is ready for encoding into a packet sent to the DHCP client. Typically, you can add options to the packet at this extension point. The server can also drop the packet at this point, but the server already recorded its values in its internal database.
2-35Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdhcp
Usage Guidelines Deferring Lease Extensions
You can enable the defer-lease-extensions attribute to reduce the number of writes to the Network Registrar database. These writes can occur because the Network Registrar DHCP server commits fresh information to the database any time it changes the duration of a client’s lease. Because the DHCP server renews leases for the full lease interval every time the client contacts the server, these database writes may impact performance if the server is on a busy network.
You can eliminate some database writes if the data being written is the same as the old data. Instead of granting the full lease duration, the server can regrant the lease with a new duration equal to the remaining time on the old lease. Because the absolute expiration time does not change, there is no need to write to the database.
There are three cases of lease extensions to consider:
• Client retries—When the server gets behind, it is possible for a client to retransmit requests. The DHCP server does not maintain enough information to recognize these as retransmissions, and processes each to completion, regranting a full lease duration and updating the database. When the server is already behind, doing extra work worsens the situation. To prevent this, the DHCP server does not extend leases that are less than 30 seconds old, regardless of the state of the defer-lease-extensions attribute.
• Client reboots—The effective renew time for a client’s lease is really the minimum of the configured renew time and the time between client reboots. In many installations this may mean that clients get fresh leases one (in a typical enterprise) or two (in a typical cable network) times per day, even if the renew time is set for many days. Setting the defer-lease-extensions attribute can prevent these early renews from causing database traffic.
• Artificially short renewal times—Because there is no way for a DHCP server to proactively contact a DHCP client with regard to a lease, you might configure fairly short client renewals to provide a means of doing network renumbering, address re-allocation, or network reconfiguration (for example, a change in DNS server address) in a timely fashion. The goal is to allow you to do this without incurring unacceptable database update overhead.
As a complication, the server also keeps track of the time when it last heard from the client. Known as the last transaction time, sites sometime use this information as a debugging aid. Maintaining this time robustly requires a write to the database on every client interaction. See the last-transaction-time-granularity attribute in Table 2-5 on page 2-22. Because the last transaction time is not integral to the protocol, you need not update it synchronously. Also, because it is primarily a debugging aid, it need not 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. See the “Considerations of the export leases Command” section on page 2-56.
pre-dns-add-forward Chooses the name and affects the number of DNS retries during update operations. Network Registrar might call this extension point multiple times for a single DNS update operation.
Table 2-7 dhcp Command Extension Points (continued)
Extension Point Purpose
2-36Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdhcp
Putting the Sever in Import Mode
You can put the DHCP server into import mode by enabling the import-mode attribute and then restarting the server. You take the server out of import mode by disabling the attribute 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. See the “Usage Guidelines” for the “import” section on page 2-62.
Configuring the sms-library-path Attribute
When you install the Microsoft BackOffice Resource Kit, the system path is not updated to reflect the location of the SMS dll. Use one of the following methods to configure this attribute.
• Set the attribute to the relative path.
To set the attribute to relative path, add the following line to the system path on the machine that has DHCP server:
sms-install-directory\diagnose
Then, set this attribute to the name of the dll:
nrcmd> dhcp set sms-library-path “smsrsgen.dll”
You can also accept the system default:
nrcmd> dhcp unset sms-library-path
• Set the attribute to the absolute path.
If you do not want to change the system path, enter the following command to set this attribute to the absolute path of the dll location:
nrcmd> dhcp set sms-library-path ”\\Program Files\\Resource Kit\\sms\\diagnose\\smsrsgen.dll”
Setting the Failover Backup Percentage
For all servers or scopes for which you set dhcp enable failover or scope enable failover, you must set the failover-backup-percentage. This is the number of currently available (not reserved) leases that the backup server can use for allocations to new DHCP clients when the main server is down. You can use the default, which is 10 percent, or specify another value.
For scopes for which you set scope enable dynamic-bootp, use the failover-dynamic-bootp-backup-percentage attribute rather than the failover-backup-percentage attribute. The failover-dynamic-bootp-backup-percentage is the percentage of available addresses that the main server should send to the backup server for use with BOOTP clients.
Note You must define this percentage on the main server. If you define it on the backup server, Network Registrar ignores it (to enable duplicating configuration through scripts). If you do not define it, Network Registrar uses the default or specified failover-backup-percentage.
The failover-dynamic-bootp-backup-percentage is distinct from the failover-backup-percentage attribute, because if scope name enable bootp is set on a scope, a server never, even in PARTNER-DOWN state, grants leases on addresses that are available to the other server. Network Registrar does not grant leases because the partner might give them out using dynamic BOOTP, and you can never safely assume that they are available again.
2-37Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdhcp
To properly support dynamic BOOTP while using the failover protocol, do the following on every LAN segment in which you want BOOTP support:
• Create one scope for dynamic BOOTP
• Enable BOOTP and dynamic BOOTP
• Disable DHCP for that scope
For more information about dynamic BOOTP, see the Network Registrar User’s Guide.
Setting the Maximum Client Lead Time
The failover-maximum-client-lead-time (MCLT) attribute is a key factor in failover. The MCLT adds a certain fixed amount to the client’s expiration time as known by the backup server, as an insurance that the backup server does not give out the lease prematurely to another client in case the main server is down. By default, the MCLT extends the lease period by one hour. Failover requires the MCLT because the servers uses the failover lazy update feature. With this feature, a server can allocate an IP address or extend a lease without having first to notify its failover partner each time. It can notify its partner in batches of updates later as time permits, a performance advantage.
However, with lazy update, when a server fails before updating its partner about having updated a client’s lease, the partner may consider the lease expired and allocate it to another client prematurely. The added MCLT period avoids this problem. Every time the partners reconnect, the main server sends its partner the MCLT extension period. The partner cannot give a lease to a client until after this short waiting period, which gives the client a chance to apply to the partner for a renewal while still maintaining the lease. If the period expires and the main server is still down, the partner can still give the client another address.
Setting the Failover Lease Period Factor
The client and the backup server can have different information about a lease expiration. The failover-lease-period-factor attribute controls how much ahead of the client’s lease expiration the main server tells its partner that the expiration is.
The larger the lease period factor, the more independent the main server is of the operation of its partner, and the less performance impact the failover protocol has on the main server. However, the larger the factor, the longer the partner must wait to time out an expired lease and re-use it for a different client in the event that the main fails and the partner takes over DHCP functions. Possible values are:
• 1.0—Same as the lease period that the main server gives the DHCP client. The main server can then never offer any client a lease time or lease extension of more than the MCLT.
• 1.5—The default and optimized factor. It is the lease period itself plus half again the lease, best used if the renewal period is 50% of the lease.
• 2.0—Twice the lease period the main server gives the client.
You must define this attribute for the main DHCP server. If it is defined in a backup server, the main server ignores it (to enable duplicating the configurations through scripts).
The lease period interacts with the lease renewal period. If the lease renewal period is more than 50% of the lease, you must also increase the lease period factor. The calculation is as follows: lease factor (1) + renewal time percentage = renewal factor. The usual renewal time of 50% would require a (1 + .5 =) 1.5 renewal factor. A renewal time of 80% would require a (1 + .8 =) 1.8 renewal factor.
2-38Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdhcp
Enabling DHCP Forwarding
You can forward DHCP traffic from one DHCP server to another under the control of a Network Registrar extension. The DHCP forwarding attribute is important in situations where the other server is not one that you manage. This is most likely to occur in environments where multiple vendors supply DHCP services for clients on the same virtual LAN.
The DHCP forwarding attribute works in the following way:
1. When DHCP is initialized, the server opens a UDP socket, which it uses to send forwarded packets. To support servers with multiple IP addresses, the socket address pair consists of INADDR_ANY and any port number. This enables clients to use any one of the server’s IP addresses.
2. When the DHCP server receives a request from a client, it processes these extension point scripts:
– post-packet-decode
– pre-client-lookup
– post-client-lookup
As the DHCP server processes these scripts, it checks the environment dictionary for the following string:
cnr-forward-dhcp-request
3. When it finds that string and it has the value true (enabled), the server calls its forwarding code.
4. The forwarding code checks the environment dictionary for a string with the following key:
cnr-request-forward-address-list
It expects a list of comma-separated IP addresses with an optional colon-delimited port number, as in the following example:
192.168.168.15:1025,192.168.169.20:1027
By default, the server forwards to port 67. It sends a copy of the entire client request to each IP address and port in turn. If any element in the list is invalid, the server stops trying to parse the list.
5. After the forwarding code returns, the server stops processing the request. In the post-client-lookup extension point script, however, this might create an optional log message with client-entry details.
The following example of a portion of a TCL extension script tells the DHCP server to forward a request to another server based on the information in the request. You can use such a script if there are multiple device provisioning systems in the same environment. In this case, you would run the extension script on the DHCP server to which routers forward broadcast requests. The script would determine which (if any) other server or servers should handle the request, and tell the original server to forward the request.
The sample script uses a static mapping of MAC address prefix to send modems from a specific vendor to a specific system.
proc postPktDecode {req resp env} { set mac [$req get chaddr] set addrs "" ;# Very simple, static classifier that forwards all requests from devices ;# with a vendor-id of 01:0c:10 to the DHCP servers at 10.1.2.3 and 10.2.2.3: switch -glob -- $mac {
01:0c:10* { set addrs "10.1.2.3,10.2.2.3" }
} ;# If we decide to forward the packet, the $addrs var will have the IP addresses ;# where to forward the packet: if {$addrs != ""} {
;# Tell the DHCP server to forward the packet...
2-39Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdhcp
$env put cnr-forward-dhcp-request true ;# ...and where to forward it: $env put cnr-request-forward-address-list $addrs ;# No more processing is required. return
} }
A more flexible script could use a per-client configuration object, such as the Network Registrar client entry, to indicate which DHCP server should get the request. See also the “extension” section on page 2-57.
Troubleshooting MAC Addresses
As an additional aid to troubleshooting your configuration, you can use the example extension, dextrace, distributed on the Network Registrar CD-ROM. It looks for a particular MAC address in every input packet. When it finds that MAC address, it enables packet sniffing for just that input and any corresponding output packet. You can configure this extension using the CLI; the configuration commands are in the example source file for dexextension.c. This extension places only a very small load on the server and is suitable for long-term use when trying to diagnose a DHCP problem in which a troublesome MAC address is known, but it is not possible (or perhaps not convenient) to manually stimulate that DHCP client directly to find the problem.
Enabling SMS Network Discovery
To enable SMS network discovery and specify the site code of the SMS server as “aic,” enter these commands:
nrcmd> dhcp set sms-network-discovery 1 nrcmd> dhcp set sms-site-code aic nrcmd> dhcp reload nrcmd> dhcp updateSms
Related Commands dhcp-interface, lease, policy, scope, server
2-40Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdhcp-interface
dhcp-interfaceThe dhcp-interface command adds, removes, and lists Network Registrar DHCP interfaces.
In Network Registrar, a DHCP interface is a logical representation of the hardware interface (such as a server’s Ethernet or Token Ring network interface card) that the DHCP server uses. DHCP interfaces get the name of the address and subnet mask of the physical device they represent. Additionally, Network Registrar uses the interface named default to provide configurable default values for interfaces that the DHCP server discovers automatically. If you delete the default interface, the DHCP server uses hardcoded default values for port numbers and socket buffer sizes for the interfaces that it autodiscovers.
dhcp-interface ipaddress/maskbits create
dhcp-interface {ipaddress/maskbits | default} delete
dhcp-interface ipaddress/maskbits set {mask=value | ignore=true | false}
dhcp-interface {ipaddress/maskbits | default} get {addr | mask | ignore}
dhcp-interface {ipaddress/maskbits | default} [show]
dhcp-interface list
dhcp-interface listnames
Syntax Description dhcp-interface ipaddress/maskbits create [attribute=value...]
Creates a DHCP interface specification named by the IP address and network prefix bits of the physical interface. You can specify the mask bits as 24 (for a 24-bit network, such as a 255.255.255.0 netmask) or 16 (for a 16-bit network, such as a 255.255.0.0 netmask).
dhcp-interface {ipaddress/maskbits | default} delete
Deletes a DHCP interface. If you delete the default interface, the DHCP server uses hardcoded default values for port numbers, and socket buffer sizes for the interfaces that it autodiscovers.
nrcmd> dhcp-interface 10.1.2.3/24 delete
dhcp-interface ipaddress/maskbits set {mask=value | ignore=true | false}
Sets the subnet mask or ignore attribute, or both.
The ignore attribute enables or disables the server to ignore this interface, which might be the case if you had several interfaces. You can disable to temporarily disable a specific interface in a list. To change the interface address, delete and recreate the interface. Optional, no default.
nrcmd> dhcp-interface 10.1.2.3/24 set ignore=true
dhcp-interface {ipaddress/maskbits | default} get {addr | mask | ignore}
Gets the value of an attribute for the DHCP interface.
dhcp-interface {ipaddress/maskbits | default} [show]
Shows the values of all attributes assigned to the DHCP interface.
nrcmd> dhcp-interface 10.1.2.3/24 show
2-41Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdhcp-interface
dhcp-interface list
Lists all DHCP interfaces and any attributes assigned to them. See the “Listing DHCP Interfaces” section on page 2-42.
dhcp-interface listnames
Lists just the DHCP interface names.
Usage Guidelines Listing DHCP Interfaces
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.
• dhcp enable discover-interfaces (the default)—DHCP server uses the operating system platform support to enumerate all of the active interfaces on the machine, and (unless there is an interface configuration with the ignore attribute enabled) attempts to listen on each of these.
• dhcp disable discover-interfaces—DHCP server consults the interface list for all interfaces that do not have the ignore attribute enabled, and attempts to listen on each of these.
Related Commands dhcp
2-42Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdns
dnsThe dns command sets and enables or disables DNS server attributes. Note that in Network Registrar there is only one DNS server per cluster, hence you do not need to reference the server by name.
dns enable attribute
dns disable attribute
dns set attribute=value [attribute=value…]
dns unset attribute
dns get attribute
dns [show]
dns addRootHint name ipaddress [ipaddress…]
dns removeRootHint name
dns listRootHints
dns addException name ipaddress [ipaddress…]
dns removeException name
dns listExceptions
dns addForwarder ipaddress [ipaddress…]
dns removeForwarder ipaddress
dns listForwarders
dns flushCache
dns rebuildRR-Indexes
dns forceXfer secondary
dns scavenge
Note See also the “server” section on page 2-112 for other server control commands.
Syntax Description See Table 2-8 on page 2-45 for a list of the dns command attribute descriptions.
dns enable attribute
Enables a DNS server attribute.
2-43Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdns
dns disable attribute
Disables a DNS server attribute, such as to disable NOTIFY for all the zones.
nrcmd> dns disable notify
dns set attribute=value [attribute=value…]
Sets one or more attributes of the DNS server.
dns unset attribute
Unsets the value of a DNS attribute.
dns get attribute
Gets the value of an attribute for the DNS server.
dns [show]
Shows all the DNS server attributes.
dns addRootHint name ipaddress [ipaddress…]
Adds the named root server at a specific IP address using the root hint method. After you specify these servers, Network Registrar queries them for their root name server records that resolve other names. These values need not be exact, but should be accurate enough for the DNS server to retrieve the correct information.
nrcmd> dns addRootHint a.root-servers.net 198.41.0.4
dns removeRootHint name
Removes a root name server.
nrcmd> dns removeRootHint a.root-servers.net
dns listRootHints
Lists a root name server.
dns addException name ipaddress [ipaddress…]
Adds an exception server at a specific IP address. See the “Resolution Exception Domain” section on page 2-49.
nrcmd> dns addException blue.com. 192.168.1.4
dns removeException name
Removes an exception server.
dns listExceptions
Lists all the exception name servers.
dns addForwarder ipaddress [ipaddress…]
Adds the IP address of any name servers that you want your Network Registrar DNS server to use as forwarders. Network Registrar forwards recursive queries to these servers before forwarding queries to the Internet-at-large. Note that you can use the exception method to override forwarding for specific domains.
nrcmd> dns addForwarder 192.168.1.4
dns removeForwarder ipaddress
Removes a forwarder server at the IP address.
2-44Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdns
dns listForwarders
Lists all the forwarder servers.
dns flushCache
Flushes the cache file to stop it from growing. The behavior depends on whether your DNS server is running or stopped. See the “Flushing the Cache” section on page 2-49.
dns rebuildRR-Indexes
Rebuilds the resource records indexes. See the “Rebuilding Resource Records Indexes” section on page 2-50.
dns forceXfer secondary
Forces full zone transfers for every secondary zone, regardless of the SOA serial numbers, to synchronize DNS data store. If a normal zone transfer is already in progress, the command schedules a full zone transfer for that zone immediately after the normal zone transfer finishes.
dns scavenge
Causes scavenging on all zones that have enabled the scvg-enabled attribute.
Attributes Table 2-8 describes the dns command attributes and their values and defaults, if any.
Table 2-8 dns Command Attributes
Attributes Usage Description
checkpoint-interval set= get unset
Interval (in seconds) at which to checkpoint zones (take the latest snapshot in the zone checkpoint database). The zone checkpoint interval overrides anything set at this level for a particular zone. See the “Logging Checkpoint Files and Scavenging” section on page 2-140. Required, range 3600-604800 seconds (1-168 hours), default 19800 seconds or three hours.
fake-ip-name- response
enable disable
Controls whether the server, if queried for a domain name that resembles an IP address (for example, an A record like 192.168.40.40), automatically responds with a NXDOMAIN status without even trying to query (or forward to) other servers. See the “Handling Rogue Address Records” section on page 2-50. Required, default enable.
hide-subzones enable disable
Causes the server to provide recursion even when queried without recursion. Do not use on servers queried for nonauthoritative data.
ixfr-enable enable disable
Controls the incremental transfer behavior for zones for which you did not configure a specific behavior. If incremental transfer is enabled, then you must also set the value of the ixfr-expire-interval attribute or accept the default value. Required, default enable.
ixfr-expire-interval set= get
Longest interval to maintain a secondary zone solely with incremental transfers. After this period, the server requests a full zone transfer. Required, default 604800 seconds (7 days), range 0 through 2147483647 seconds.
lame-deleg-notify enable disable
Controls whether you want Network Registrar to 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 disable.
local-port-num set= get
UDP and TCP port number on which the DNS server listens for queries. Required, default port 53, range 1 through 65535.
2-45Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdns
log-settings set= get
Determines which events to log, as set using a bit mask. See Table 2-9 on page 2-48. Logging additional details about events can help analyze a problem. However, leaving detailed logging enabled for a long period can fill the log files. Required, default is all settings except scavenge-detailed.
max-cache-ttl set= get
Maximum amount of time to retain cached data. Required, default 604800 seconds (7 days), range 0 through 2147483647 seconds.
mem-cache-size set= get
Size of the in-memory record cache, in kilobytes. Required, default 200 KB, range 1 through 4194303 KB.
neg-cache-ttl set= get
How long to cache information learned from other name servers about nonexistent names or data, in seconds. Required, default 600 seconds (10 minutes), range 0 through 2147483647 ms.
no-fetch-glue enable disable
Controls whether you want the DNS server, when composing a response to a query, to fetch missing glue records. Glue records are A records with the address of a domain’s authoritative name server. Normal DNS responses include NS records and their A records related to the name being queried. Required, default disable.
no-recurse enable disable
Controls whether you want to disable forwarding client queries to other name servers when your DNS server is not authoritative for data being queried. If you enable no-recurse queries, you make your name server a noncaching server. Required, default disable.
notify enable disable
Controls sending notification for zones for which you did not configure a specific behavior. See the “NOTIFY” section on page 2-48. You must also set the other notify-xxx attributes or accept their defaults. Required, default enable.
notify-defer-cnt set= get
With NOTIFY enabled, the maximum number of UPDATE changes to accumulate during the notify-wait period. If this number is exceeded, Network Registrar sends notification before the notify-wait period passes. Required, default 100 changes.
notify-min-interval set= get
With NOTIFY enabled, the minimum interval required before sending notification of consecutive changes on the same zone to a particular server. Required, default 2 seconds, range 0 through 2147483647 seconds.
notify-rcv-interval set= get
With NOTIFY enabled, for secondary zones, the minimum amount of time between the completion of processing of one notification (serial number testing or zone transfer) and the start of processing of another notification. Required, default 5 seconds, range 0 through 2147483647 seconds.
notify-send-stagger set= get
With NOTIFY enabled, the interval to stagger notification of multiple servers of a particular change. Required, default 1 second, range 0 through 2147483647 seconds.
notify-wait set= get
With NOTIFY enabled, the period of time to delay, after an initial zone change, before sending change notification to other name servers. Use this attribute to accumulate multiple changes. Required, default 5 seconds, range 0 through 2147483647 seconds.
Table 2-8 dns Command Attributes (continued)
Attributes Usage Description
2-46Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdns
remote-port-num set= get
UDP and TCP port to which the DNS server sends queries to other servers. Required, default port 53, range 1 through 65535.
round-robin enable disable
Controls whether to round-robin equivalent records in responses to queries. Equivalent records are records of the same name and type. Because clients often only look at the first record of a set, enabling this attribute can help balance loads and keep clients from forever trying to talk to an out-of-service host. Required, default enable.
save-negative- cache-entries
enable disable
Controls whether to have the server store negative-query-results cache entries in its cache.db file. If disabled, the server discards negative cache entries evicted from the in-memory cache instead of storing them in the cache.db file. See the “Handling Rogue Address Records” section on page 2-50. Required, default enable.
scvg-ignore- restarts-interval
set= get
Interval, in seconds, for which a server restart does not recalculate a start scavenging time. Required, default 7200 seconds (two hours).
scvg-interval set= get
With scavenging enabled, the interval, in seconds, at which the zone is scheduled for scavenging. The zone setting of the same attribute overrides this setting. See the “Logging Checkpoint Files and Scavenging” section on page 2-140. Range 3600 (one hour) through 31536000 seconds. Required, default 604800 seconds (seven days).
scvg-no-refresh- interval
set= get
With scavenging enabled, the interval, in seconds, during which actions, such as dynamic updates, do not refresh the timestamp on a record. The zone setting of the same attribute overrides this setting. Range 3600 (one hour) through 31536000 seconds. Required, default 604800 seconds (seven days).
scvg-refresh- interval
set= get
With scavenging enabled, the interval, in seconds, during which the record can have a timestamp refreshed. The zone setting of the same attribute overrides this setting. Range 3600 (one hour) through 31536000 seconds. Required, default 604800 seconds (seven days).
slave-mode enable disable
Controls whether the server should be a slave server that relies entirely on forwarders for data not in its cache. This attribute has no effect unless you also specify the corresponding forwarders. Note that you can override slave mode for specific domains with the DNS exception method. See the “Resolution Exception Domain” section on page 2-49. Required, default disable.
subnet-sorting enable disable
Controls whether to re-order address records in responses to queries based on the subnet of the client. Because clients often only look at the first record of a set, enabling this attribute can help localize network traffic onto a subnet. This attribute applies only to answers to queries from clients located on the same subnet as the DNS server. Required, default disable (as implemented in BIND 4.9.7).
update-relax-zone- name
enable disable
Controls relaxing of the RFC 2136 restriction on the zone name record in dynamic updates. This attribute allows updates to specify a zone name, which is any name within an authoritative zone, rather than the exact name of the zone. Required, default disable.
Table 2-8 dns Command Attributes (continued)
Attributes Usage Description
2-47Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdns
DNS Log Settings Table 2-9 describes the flags you can set with the log-settings attribute, along with their numerical equivalents. All the settings are enabled by default except the scavenge-details setting. If you make changes to the settings, reload and restart the server.
Usage Guidelines NOTIFY
Using NOTIFY, a Network Registrar DNS master server can inform its slave servers that changes occurred to its zone. It does not communicate the changes themselves in the NOTIFY packet. Instead, the slave servers respond with a zone transfer request.
Because a master server for a zone does not know specifically which slave servers transfer from it, Network Registrar notifies all registered name servers for the zone (name servers listed in the NS Resource Records) when the zone changes. The sole exception to this policy is that Network Registrar does not notify the server named in the SOA mname field (the primary master). For more information about NOTIFY, see RFC 1996.
Table 2-9 DNS Log Flags
Flag Flag Number Logs
config 1 Server configuration and de-initialization (unconfiguration).
datastore 8 Datastore processing that provides insight into various events in the server’s embedded databases.
ddns 2 High level dynamic update messages.
ddns-details 17 Resource records added or deleted due to dynamic DNS updates.
ddns-refreshes 15 Dynamic DNS update refreshes for Widows 2000 clients.
ddns-refreshes- details
16 Resource records refreshed during dynamic DNS updates for Windows 2000 clients.
forward 12 Outbound forwarding queries.
lame-delegation 13 Lame delegation events, although enabled by default. Disabling this flag could prevent the log from getting filled with frequent lame delegation encounters.
notify 5 NOTIFY transactions.
packet 7 General packet processing.
query 6 Query requests.
root-query 14 Queries and responses from root servers.
scavenge 9 Zones scavenged of dynamic resource records.
scavenge-details 10 More detailed scavenged zone output (disabled by default).
server-operations 11 General high server events, such as those pertaining to sockets and interfaces.
xfr-in 3 Inbound full and incremental zone transfers.
xfr-out 4 Outbound full and incremental zone transfers.
2-48Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdns
You can use IXFR and NOTIFY together, but this is not necessary. You can 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. For example:
nrcmd> zone example.com set refresh=30m nrcmd> zone example.com disable notify
For more information about setting zone attributes, see the “zone” section on page 2-133.
Resolution Exception Domain
Use the dns addException name ipaddress [ipaddress…] command only if you do not want your DNS server to use the standard name resolution for names outside the local authoritative zone. The exception method allows you to specify the resolution exception domains and the associated servers’ IP addresses.
The resolution exception covers subzone delegations. If the global forwarding is set and a subzone is in the resolution exception list, the query for that subzone goes to the name server that appears in the exception list and not to the forwarder. To achieve subzone queries, both the subzone delegation and the resolution exception must be defined.
Note In the absence of specific resolution exception, when the global forwarding option is set, any query for the subzone delegation goes to the forwarder, and not to the server that is authoritative for that subzone.
For example, the sample company, example.com, has four subsidiaries—red, blue, yellow, and green. Each of them has its own domain in the .com domain. However, 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.configures exceptions for all the domains that require special resolution handling, and at least one corresponding name server for each. In this case, the administrator would list the three other domains for the example.com company.
To remove an exception, use the dns removeException name command. To replace the server address to which the extension points, remove the extension and re-add it. You must also stop the DNS server, flush the cache, and restart the server. See the following “Flushing the Cache” section.
Flushing the Cache
Use the dns flushCache command to stop the disk cache file from growing, but the actual behavior depends on whether your DNS server is running or stopped.
• DNS server running—Network Registrar clears all entries from the cache database file. Flushing the cache does not shrink its size, due to the nature of the database, but does create free space within it. Because the memory cache is unaffected by this operation, this does not lose the recently in-use cache entries and does not significantly affect performance.
• DNS server stopped—Network Registrar interprets the request as being a request to flush all entries and thus removes the cache database file. Network Registrar re-initializes the database when you restart the server.
To clear a cache that grew too large, or when changing a resolution exception, stop the server, enter the command, and restart the server. Stopping the server does not terminate the server process, but stops it from handling further requests. For details on resolution exception, see the “Resolution Exception Domain” section on page 2-49.
2-49Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsdns
Rebuilding Resource Records Indexes
Use the dns rebuildRR-Indexes command if you need to rebuild the resource records indexes used by the user interface. For example, if you observe inconsistent resource or host list data or missing data, then rebuild the resource record indexes. Rebuilding the resource record indexes should correct any inconsistencies that the user interface displays. It may not correct inconsistencies that the command line interface displays. This index rebuild does not affect the DNS server, except that Network Registrar removes duplicate records detected during the process.
Note In the user interface, the dns rebuildRR-Indexes command removes any duplicate resource records that it finds in the user interface cache. A subsequent reload of the DNS server may produce the following diagnostic message: 101 Ok, with warnings Error Protocol Error removing record for name host_name, zone zone_name while loading config changes. This warning is normal and you can safely ignore it.
Handling Rogue Address Records
You may become victim of a suspicious denial-of-service attack where a rogue host targets Address (A) resource record queries to a caching DNS server. These queries are for names that resemble IP addresses. To avoid overloading the DNS server’s CACHE.db file with negative responses from the root, the server will not try to resolve these queries. The fake-ip-name-response DNS attribute is enabled by default to affect this. When the server receives a query (for a nonauthoritative name), it consults its in-memory cache and, if it cannot resolve the query there, queries its cache.db file. If the server cannot resolve the query in either place, it examines the queried name and, if that resembles an IP address (four octets, each separated by a dot with no trailing or preceding characters), does not forward the query. Instead, the server responds with a NXDOMAIN status and does not include the negative response in its caches.
Another control over having the CACHE.db fill with negative entries is the save-negative-cache-entries attribute. The server acts on the save-negative-cache-entries attribute when it saves entries from in-memory cache to the cache.db file. It typically saves positive and negative query responses from in-memory cache when that cache is full and the server needs to make room for a new entry—the server evicts the least-recently-used entry. If you disable save-negative-cache-entries, the server does not store evicted negative entries in the cache.db file; the server simply discards them.
Related Commands server, zone
2-50Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsexit
exitThe exit command writes all unsaved changes to the database and then terminates the current nrcmd session. If Network Registrar cannot save your changes, it displays an error code. See the “save” section on page 2-102 for descriptions of save error messages.
To quit the Network Registrar command line interface while in interactive mode, enter:
nrcmd> exit
Related Commands save
2-51Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsexport
export The export command exports Network Registrar DHCP and DNS server information.
export addresses file=CSV-text-file [namespace=name] [config=config-file] [dhcp-only] [time-ascii | time-numeric]
export addresses database=db-name user=username password=password [table=name] [namespace=name] [config=config-file] [dhcp-only] [time-ascii | time-numeric]
export hostfile [file]
export leases {-client | -server} [-namespace name] [-time-ascii | -time-numeric] file
export zone name {static | dynamic | both} file
export zonenames {forward | reverse | both} file
Syntax Description export addresses file=CSV-text-file [namespace=name] [config=config-file] [dhcp-only] [time-ascii | time-numeric]
Exports all active IP addresses into a comma-separated value (CSV) text file, if specified. If you omit the file, it writes the output in CSV format to the standard output. See the “Specifying Clusters for the export addresses Command” section on page 2-53. For the namespace usage, see the “Specifying a Namespace on Export” section on page 2-54.
export addresses database=db-name user=username password=password [table=name] [namespace=name] [config=config-file] [dhcp-only] [time-ascii | time-numeric]
Exports all active IP addresses into a database table. See the “Database Output Format of the export addresses Command” section on page 2-55. For the namespace usage, see the “Specifying a Namespace on Export” section on page 2-54.
export hostfile [file]
Creates a host file, in UNIX host file format, from all the zones in the server, ignoring reverse zones. It creates hostfile records from A records, CNAME records, and HINFO records. Each host file record consists of the IP address, FQDN, aliases created from the A and CNAME records, and comments created from HINFO records.
export leases {-client | -server} [-namespace name] [-time-ascii | -time-numeric] file
Writes the state of all the current leases to the output file. The export leases -client command writes out the lease time as a string in the month, day, time, year format, such as Apr 15 16:35:48 2002.
nrcmd> export leases -client leaseout.txt
2-52Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsexport
The export leases -server command writes out the state of all current and expired leases to the DHCP server’s log directory using the output file that you specify. It writes lease times as integers representing the number of seconds since midnight GMT Jan 1, 1970, for example, 903968580.
nrcmd> export leases -server leaseout.txt
The file is either the name of the output file or a dash (–) for the standard output for client-side exports. You cannot use the dash with the -server keyword. In addition, the server-side export does not permit any nonalphanumeric character such as a dot (.) in filenames. See the “Considerations of the export leases Command” section on page 2-56. For the syntax of the entries in the output file, see the Network Registrar User’s Guide.
For the namespace usage, see the “Specifying a Namespace on Export” section on page 2-54.
export zone name {static | dynamic | both} file
Writes the specified DNS zone into a file in the BIND format, where name is the domain whose data you want to write to a file. The following example exports the contents of the example.com domain to the hosts.local file.
nrcmd> export zone example.com. static hosts.local
export zonenames {forward | reverse | both} file
Exports just the zone names for a particular zone type—forward, reverse, or both—to a file.
Usage Guidelines Specifying Clusters for the export addresses Command
The export addresses command exports all active IP addresses into a specified database or CSV text file. You can determine which clusters the command pertains to in many ways. Network Registrar follows a precedence order, as follows. Any of the specific cluster specifications can override the default specification or previous specification.
• Default cluster (localhost).
• UNIX environment or Windows Registry variable AIC_CLUSTER.
• -C flag on the command line allows you to specify a single cluster.
• clusters attribute in the configuration file. This allows you to specify a group of clusters. The following example specifies clusters in a .nrconfig file, the default configuration file, or in a file that you specify with the config keyword:
Cluster information for export addresses [export addresses] clusters=machine1 username password, machine2 username password [...] clusters=host1 admin, host2, host3 admin3 passwd3
Separate cluster specifications with commas. Within each cluster specification, separate the three arguments with spaces. For long lines you can use continuation lines. You can embed carriage returns; you do not need to use continuation escape indicators.
You can optionally specify a username and password for the cluster. If you omit a username or password for a particular cluster, Network Registrar uses the last username or password listed. If you omit usernames or passwords, Network Registrar uses the information from the command line -N and -P arguments, and then the Windows Registry or environment variables AIC_NAME and AIC_PASSWORD. See the “Invoking the nrcmd Command” section on page 1-1.
If Network Registrar cannot find a username or password or the supplied username and password are incorrect, the command issues a warning for that cluster.
2-53Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsexport
Specifying a Namespace on Export
The output of the export command can include the namespace specification. The value can be any valid, predefined namespace name, or the reserved words global and all. Global indicates all addresses not in any of the defined namespaces. All indicates all namespaces, including the global one. If you omit the namespace, the current one applies, as set by the session set current-namespace command. If the current namespace is undefined, the global namespace applies. Network Registrar adds the ID of the namespace at the end of each output line in the export file.
Command Keywords for the export addresses Command
Use the following conventions for export addresses keywords.
• Configuration file—If it exists, .nrconfig is the default configuration file. To use a configuration file other than the default file, use the config keyword to identify your configuration file. If there is an [export-addresses] section in the configuration file, the export command uses the clusters that the section specifies instead of the default cluster. If you omit a configuration file, the export addresses command looks for a default .nrconfig file. This is the same configuration file that the report command uses. Network Registrar looks for the file first in your current directory, then in your home directory, and finally in the AIC_INSTALL_PATH/conf directory. It uses the first file it encounters.
Each line of the configuration file must begin with the character # (comment), a section header enclosed in square brackets, or a parameter=value pair or its continuation. For example:
[export addresses] clusters=machine1 username password, machine2 username password [...]
Network Registrar strips leading white space from each line and ignores blank lines.
• dhcp-only—This keyword causes the command to output only DHCP information and not DNS information.
• Database tables—The table keyword specifies the database table to which the command exports address information. If you omit this keyword, Network Registrar writes to the default table name ip_addresses. If the table already exists in the specified database when you run the export command, Network Registrar clears (and resets the columns) before writing the new data. Network Registrar does not provide a warning or confirmation if it clears an existing table.
• Date and time—The optional time-ascii and time-numeric keywords specify how to output date/time fields to a CSV text file and when the target database does not support the timestamp data type. The default is time-ascii.
Error Reports for the export addresses Command
The export addresses command attempts to establish communication with the clusters you specify. It reports an error in the following cases:
• If the export addresses command cannot establish communication with any of the selected clusters, it issues messages on each cluster it could not reach and exits with “101 Ok, with warnings.”
• If the export addresses command cannot connect to the database or manipulate the table, it reports “326 Database access error:” followed by the text that ODBC reports.
• If ODBC is not installed on the system, it reports “340 ODBC 3.x or higher required. ODBC not installed.” If there is an incompatible version of ODBC present, it issues the message, “340 ODBC 3.x or higher required. ODBC.y installed.”
2-54Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsexport
Note If successful, the export addresses command prints “100 Ok” both before and after Network Registrar lists the addresses. The first “100 Ok” means that the command is processing (without rejection because of existing locks, licensing problems, or command syntax errors). The second “100 Ok” indicates that the command successfully completed its processing.
Database Output Format of the export addresses Command
The export addresses command writes the database output to the ip_addresses table or to the specified table name. Table 2-10 shows the columns in the ip_addresses table.
Table 2-10 export addresses Database Output
Column Data Type Null? Description
client_id varchar(256) yes Client ID for the lease (DHCP).
client_class varchar(256) yes Client-class name (DHCP).
cluster_name varchar(256) no Cluster name from which the information came.
dns_name varchar(256) yes Fully qualified DNS name for assigned addresses. If Null, the DCP lease is not bound to a DNS name.
failover-role varchar(64) yes Failover role, if any, of leases.
ip_address unsigned integer no 32-bit IP address.
ip_text varchar(15) no IP address in dotted decimal notation.
lease_expiration_time timestamp yes Date and time when the lease expires (DHCP).
lease_state_change_time timestamp yes Date and time when the lease last changed state (DHCP).
lease_transaction_time timestamp yes Date and time of the last transaction (DHCP).
mac_address varchar(256) yes MAC address text field in the form.type,length,hex:hex:hex..., such as “1,6,00:d0:ba:d3:bd:3b.” The type and length are both in decimal, whereas the data is in hexadecimal.
namespace-name varchar(256) yes Namespace name. If Null, the current namespace, as set by the session set current namespace command.
requested_name varchar(64) yes UNIX or WINS hostname (DHCP).
scope_pool_name varchar(256) yes Scope name address (DHCP) from which the address was allocated.
state varchar(20) no Available, Assigned, Unavailable, Leased, Expired, De-activated, Released, Other Available, Pending Available.
subnet_bits integer yes Number of bits in subnet mask for the scope.
type varchar(20) no STATIC, DYNAMIC, or RESERVED.
2-55Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsexport
If the target database does not support the data type of a field, the export command replaces it with a text (varchar) field as listed in Table 2-11. Column names that exceed the target database’s supported maximum name width get truncated to the allowable width.
Text File Output Format of the export addresses Command
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-10 on page 2-55. The first line in the file is not a table row, but instead contains a hash (#) symbol followed by the text of each of the column names separated by commas. The command handles all fields that require text substitution as the previous section describes.
Note The output is not in a guaranteed order. The order depends on the data in the system. Therefore, if order is important to you, use a tool to sort the data.
Addresses Reported by the export addresses Command
The export addresses command reports every address configured in every server that is specified in the configuration file. This includes addresses specified in DHCP scope ranges, DNS static addresses, and explicitly reserved addresses both for DNS and DHCP servers. However, unused (unallocated and unreserved) addresses in DHCP scope ranges do not appear in the table.
The report displays multiple entries for an address if the address is served by more than one server, is 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.
Considerations of the export leases Command
When you use the export leases -client command, Network Registrar reads the database. If the servers are running, executing this command may affect system performance.
When you use the export leases -server command, Network Registrar does not read the database, so it is significantly faster. You can execute the command only if the server is running. Because the server is doing some extra work while it is building the export file, it may slow down somewhat. However, the time involved is usually so short that you may not notice the performance impact.
Related Commands import, report
Table 2-11 Field Data Types
Field Data Type Text Replacement
ip_address varchar(10) in hexadecimal, such as “0x1234abcd”
Null varchar(1) “”
other integers varchar(11) in decimal, such as “28”
timestamp varchar(26) as either a string of the form “Mon Apr 1502:03:55 2002” 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
2-56Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsextension
extensionThe extension command configures and integrates user-written DHCP extensions into the DHCP server.
extension name create language file entry [init-args=value init-entry=value]
extension name delete
extension name set attribute=value [attribute=value…]
extension name unset attribute
extension name get attribute
extension name [show]
extension list
extension listnames
Note The DHCP server reads extensions only when you reload the server. So if you change an extension, you must reload the DHCP server.
Syntax Description See Table 2-12 on page 2-58 for the extension command attribute descriptions.
extension name create language file entry [init-args=value init-entry=value]
Creates a client and optionally assigns initial entry point attributes. The command line attributes are:
• language—Language in which the extension or module is implemented, either Tcl or Dex. Required, no default.
• file—Filename relative to the directory extensions in the installation, as an absolute pathname, but cannot contain a sequence of two dots (..). Required, no default.
• entry—Name of the entry point for the module. This function is called from any extension point to which this module is bound. The arguments for this function are server-implementation-specific. Required, no default.
• For the initial entry point attributes, see Table 2-12 on page 2-58.
The following example configures an extension named ext1 using the Tcl file tclfile1.tcl having the entry mytclentry.
nrcmd> extension ext1 create Tcl tclfile1.tcl mytclentry
extension name delete
Deletes an extension.
extension name set attribute=value [attribute=value…]
Sets one or more attributes for the extension.
extension name unset attribute
Unsets the value of an extension attribute.
2-57Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsextension
extension name get attribute
Gets the value of an attribute for the extension.
extension name [show]
Shows the values of all attributes assigned to the extension identified by name.
extension list
Lists all extensions and any attributes assigned to them.
extension listnames
Lists just the extension names.
Attributes Table 2-12 describes the extension command attributes and their values and defaults, if any.
Usage Guidelines To extend the DHCP server, do the following:
Step 1 Write the extension in 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—For Tcl this is \program files\network registrar\extensions\dhcp\tcl For C or C++ this is \program files\network registrar\extensions\dhcp\dex
It is best to place these extensions in the appropriate directory for TCL or C/C++ extensions. Then, when configuring the filename, just enter the filename itself, without slash (/) or backslash (\).
Table 2-12 extension Command Attributes
Attribute Usage Description
entry set= get
Name of the entry point for the module. This function is called from any extension point to which this module is bound. Required, no default.
file set= get unset
Filename relative to the directory extensions in the installation, or as an absolute pathname, but cannot contain a sequence of two dots (..). Required, no default.
init-args set= get unset
Arguments to pass to the init-entry point function. See Chapter 4, “Using Extension Points.” Optional, no default.
init-entry set= get unset
Name of the init-entry point. If you set it, Network Registrar calls this function when the server loads the module and when the server shuts down. See Chapter 4, “Using Extension Points.” Optional, no default.
lang set= get
Language in which the extension or module is implemented:
• Tcl—Module is a Tcl extension (tcl7.5)
• Dex—Module is a shared object with C calling interfaces
Required, no default.
2-58Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsextension
If you want to place extensions in subdirectories, enter the filename with a path separator. These are different depending on the operating system on which your DHCP server is running.
Note When entering a filename that contains a backslash (\) character on Windows NT, you must enter it with a double-backslash (\\), because backslash (\) is an escape character in the CLI. For example, enter the filename debug\myextension.tcl as debug\\myextension.tcl.
Step 2 Use the extension command to configure the DHCP server to recognize this extension.
Step 3 Attach the configured extension to one or more DHCP extension points using the dhcp attachExtension command. For more information about choosing extension points and writing extensions, see Chapter 4, “Using Extension Points.”
Step 4 Reload the server.
Related Commands dhcp
2-59Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsforce-lock
force-lockWhen you execute a nrcmd command, it tries to get an exclusive lock for the cluster to which it is connected. If it cannot get an exclusive lock, it displays a warning.
Without an exclusive lock, you can issue only these commands:
• client
• lease
• zone add
• help
• force-lock
Caution Use the force-lock command carefully, because running more than one program that updates the Network Registrar database can cause database corruption. Always check with the other user that currently has the lock. Do not use the force-lock command if the other user exits nrcmd during the time you receive the lock notification, or the command will fail and you will have to restart the session. Instead, the session will become available and you can simply continue with the normal commands.
If you use the force-lock command to unlock a cluster, the command writes the warning to the log file on the client machine, not on the cluster.
To force an exclusive lock, enter:
nrcmd> force-lock
2-60Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandshelp
helpThe help command displays the nrcmd program online help.
help
help command [section…]
Syntax Description help
If you enter the help command without any arguments, Network Registrar displays a list of all the commands.
help command [section…]
If you specify the help command with a command name, Network Registrar displays the help page for the command of that name. Optionally, you can use the section attribute to limit the response to a specified section of the command message.
The section names are:
• synopsis—Valid syntax for the command
• description—Textual description of the command behavior
• examples—Examples of the command usage
• attributes—Descriptions of the attributes
• status—Description of the status codes that this command returns
The following example prints the synopsis section of the help file for the help command.
nrcmd> help help synopsis 100 Ok SYNOPSIS help help <cmd> [<section>...]
Usage Guidelines You can set the screen buffer size and window size to view the entire content of the help item.
2-61Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsimport
importThe import command imports DHCP lease data or a BIND named.boot file into the DNS server configuration.
import leases file
import named.boot file
Syntax Description import leases file
Imports the leases in the file to the DHCP server. See the “Import File” section on page 2-63. For the namespace usage, see the “Specifying the Namespace on Import” section on page 2-63.
nrcmd> import leases LeaseIn
import named.boot file
Imports the BIND 4.x.x named.boot file. This points the server to its database files, such as the /etc/named.boot file on UNIX or Windows. See the “Named.boot File” section on page 2-63.
nrcmd> import named.boot /etc/named.boot
Note Use UNIX style pathnames even when running the import command on Windows. If successful, the import command prints “100 Ok” both before and after Network Registrar imports the file. The first “100 Ok” means that the command is being processed (without rejection because of existing locks, licensing problems, or command syntax errors). The second “100 Ok” indicates that the command successfully completed its processing.
Usage Guidelines Before you can import leases, you must perform several configuration steps:
Step 1 Configure scopes in the DHCP server for the leases that you plan to import. See the “scope” section on page 2-103.
Step 2 If you want the hostnames for the leases dynamically entered into DNS as part of the import, configure zones in the DNS server to allow dynamic updates. See the “zone” section on page 2-133.
Step 3 Set the DHCP server to import mode so that it does not respond to other lease requests during the lease importing. See the “dhcp” section on page 2-20.
For all the time fields, use either the number of seconds since midnight GMT January 1, 1970, or day, month, date, time, year format (Mon Apr 15 16:35:48 2002).
Step 4 After you import the leases, take the DHCP server out of import mode so that it can respond to other lease requests.
Note Importing permanent leases will fail if you disable the permanent leases option, so keep this option enabled using, for example, the policy name enable permanent-leases command.
2-62Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsimport
Import File
The client is given the lesser of the lease times:
• In the import file, or
• That the client would receive if it were to acquire a lease using the existing configuration of the DHCP server.
For example, it is 2:00 p.m. and your scope is configured for a one-hour lease. According to the file that you import, the lease time does not expire until 5:00 p.m. After you import the file, the lease expires at 3:00 p.m. and not at 5:00 p.m.
If your import file specifies a DNS zone name, the server does not use the zone name when it updates DNS. If the file specifies a hostname, then the server uses the hostname when updating DNS, unless the hostname was overridden by a host-name specification in a client or client-class entry.
The only way to indicate to the DHCP server that the client’s hostname should be in a zone other than the default associated with the scope is to specify that zone in a client or client-class entry.
Specifying the Namespace on Import
You can specify the namespace for imported leases at the end of each lease entry in the import file. The namespace must be predefined. See the “namespace” section on page 2-84. All leases without explicit namespace entries are assigned to the current (or global) namespace.
Named.boot File
BIND 4.x.x uses a boot file, called named.boot, to point the server to its database files. You can import your entire BIND 4.x.x configuration using the import command.
When a BIND file contains an $INCLUDE directive, BIND searches for the include file relative to the directory that the directory directive in the named.boot file specifies. In contrast, the nrcmd program searches for the include file relative to the directory containing the zone file being processed.
To avoid this problem, ensure that the BIND configuration uses absolute paths whenever specifying an include file in a zone file. If your zone files contain relative paths when specifying include files, and the directory containing the zone file is not the same as the directory that the directory directive in the named.boot file specifies, your configuration cannot load properly. You need to convert the relative paths in your zone files to absolute paths so that you can import your BIND configuration into Network Registrar. Here is an example of a configuration and how to fix paths in directory hierarchy, configuration files, and zone files:
• Directory hierarchy:
/etc/named.boot/usr/local/domain/primary/db.example/usr/local/domain/primary/db.include/usr/local/domain/secondary
• Configuration file (/etc/named.boot):
#BIND searches for zone files and include files relative to /usr/local/domaindirectory /usr/local/domain#BIND finds zone file in /usr/local/domain/primary primary example.com primary/db.example end of /etc/named.boot
• Incorrect zone file (/usr/local/domain/primary/db.example):
#BIND searches for include file relative to /usr/local/domain$INCLUDE primary/db.include#end of /usr/local/domain/primary/db.example
2-63Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsimport
To make the configuration loadable, change the relative path ($INCLUDE primary/db.include) in the file db.example to an absolute path ($INCLUDE /usr/local/domain/primary/db.include).
Mapping BIND 4 Boot File Directives to nrcmd
Table 2-13 describes the named.boot file directives that the BIND 4.9.6 distribution supports and the corresponding nrcmd command syntax that is generated. Network Registrar marks the directives it does not support with the word Unsupported, and marks the ones that require no action with the word None.
Related Commands dhcp, export, scope, zone
Table 2-13 BIND 4 to nrcmd Command Mappings
BIND 4 nrcmd
bogusns ip-addr-list Unsupported
cache domain-name file Unsupported
check-names primary/secondary/ response fail/warn/ignore
Unsupported
directory new-directory Unsupported in the named.boot file parser
domain local-domain-name Unsupported
forwarders ip-addr-list dns addForwarder ip-addr[,ip-addr...]
include file Unsupported in the named.boot file parser
limit datasize number Unsupported
limit files number Unsupported
limit transfers-in number dns set xfer-client-concurrent-limit=number (set session visibility to 3)
limit transfers-per-ns number Unsupported
options fake-iquery None—Network Registrar supports only fake iquery
options forward-only dns enable slave-mode
options no-fetch-glue dns enable no-fetch-glue
options no-recursion dns enable no-recurse
options query-log Unsupported
primary domain-name-of-zone file zone create name primary file=file
secondary domain-name-of-zone ip-addr-list [backup-file]
zone create name secondary ip-addr [,ip-addr...]
slave dns enable slave-mode
sortlist network-list Unsupported
stub domain ip-addr-list [backup-file] Unsupported
tcplist ip-addr-or-network-list zone name enable restrict-xfer
zone name set restricted-set=ip-addr[,ip-addr...]
xfernets ip-addr-or-network-list zone name enable restrict-xfer
zone name set restricted-set=ip-addr[,ip-addr...]
2-64Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsldap
ldapThe ldap command associates remote Lightweight Directory Access Protocol (LDAP) servers with Network Registrar and sets their attributes.
ldap server create hostname [attribute=value…]
ldap server delete
ldap server enable attribute
ldap server disable attribute
ldap server set attribute=value [attribute=value…]
ldap server unset attribute
ldap server get attribute
ldap server setEntry dictionary-attribute-key=value
ldap server unsetEntry dictionary-attribute-key
ldap server getEntry dictionary-attribute-key=value
ldap server [show]
ldap list
ldap listnames
Syntax Description See Table 2-14 on page 2-67 for the ldap command attributes and their descriptions.
ldap server create hostname [attribute=value…]
Creates a name entry for the LDAP server at the hostname (and optionally assigns values to its attributes). The following example creates the LDAP server object myserver with a hostname of myserver.mycompany.com.
nrcmd> ldap myserver create myserver.mycompany.com
ldap server delete
Deletes the entry for an LDAP server.
nrcmd> ldap myserver delete
ldap server enable attribute
Enables an LDAP server attribute. After you enable an attribute, you can set its values.
ldap server disable attribute
Disables an LDAP attribute.
ldap server set attribute=value [attribute=value…]
Sets one or more attributes for the LDAP server.
2-65Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsldap
ldap server unset attribute
Unsets the value of an LDAP attribute.
ldap server get attribute
Displays the value of an attribute of the LDAP server.
ldap server setEntry dictionary-attribute-key=value
Use the setEntry, getEntry, and unsetEntry commands to set, query, and clear elements of the various dictionary properties in the LDAP server configuration. These dictionary properties provide a convenient mapping from string keys to string values. The dictionary values are as follows. See also the “Dictionary Examples” section on page 2-70:
create-dictionary—Maps LDAP attributes to dhcp lease attributes. If an entry does not exist, this sets entries in this dictionary to the value of its corresponding DHCP lease attribute. Optional, no default.
create-string-dictionary—Maps LDAP attributes to user specified strings. If an entry does not exist, this sets entries in this dictionary to the matching string. Optional, no default. See the “Using the create-string-dictionary Attribute” section on page 2-70.
env-dictionary—The server can retrieve additional LDAP attributes along with client-entry attributes. If any of these are in a query’s results, their values are made available to scripts through the request’s environment dictionary. This keys the LDAP value by the value in the query env-dictionary. Optional, no default.
query-dictionary—Mapping between the names of LDAP attributes and DHCP attributes. The server tries to retrieve all the LDAP attributes specified in the dictionary. When a query succeeds, the server sets the values for any LDAP attributes that it returns in the corresponding client-entry attribute. Optional, no default.
This attribute also controls the mapping of an LDAP attribute name to the embedded policy. The LDAP attribute name associated with the embedded-policy value is used to create an embedded policy. If the server finds the particular LDAP attribute name, it decodes the attribute data as if it were an encoding of the client-embedded policy. For details about LDAP configuration, see the Network Registrar User’s Guide.
update-dictionary—Maps LDAP attributes to DHCP lease attributes. When an LDAP object is modified, each LDAP attribute present in this dictionary is set to the value of its corresponding DHCP lease attribute. Optional, no default.
ldap server unsetEntry dictionary-attribute-key
Unsets the value of a dictionary attribute. See the setEntry syntax description and the “Dictionary Examples” section on page 2-70.
ldap server getEntry dictionary-attribute-key=value
Retrieves information from various dictionaries in the LDAP server configuration. See the setEntry syntax description and the “Dictionary Examples” section on page 2-70.
ldap server [show]
Shows the values of the attributes of the named LDAP server.
ldap list
Lists the names of the remote LDAP servers and any attributes assigned to them.
ldap listnames
Lists just the names of the remote LDAP servers.
2-66Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsldap
Attributes Table 2-14 describes the ldap command attributes and their values and defaults, if any.
Table 2-14 ldap Command Attributes
Attribute Usage Description
can-create enable disable unset
Controls whether an LDAP server can create new entries to store lease state updates. Optional, default disable.
can-query enable disable unset
Controls whether to use an LDAP server for client queries. Optional, default disable.
can-update enable disable unset
Controls whether to use an LDAP server to store lease state updates. Optional, default disable.
connections set= get unset
The Network Registrar LDAP facility is multithreaded. Each LDAP object has a configurable number of connections associated with it. Network Registrar creates one thread for each connection configured in an LDAP object, and each thread can have a maximum of LDAP requests associated with its request queue (by enabling the limit-requests attribute and setting a max-requests attribute value). The connections attribute is primarily a performance tuning parameter. In some cases, more than one connection can improve overall throughput. The amount depends on the load on the LDAP server. With many applications using LDAP, five connections would be appropriate; with just Network Registrar using LDAP, 25 would be appropriate. Optional, default one connection.
create-object- classes
set= get unset
With the can-create attribute enabled, Network Registrar names of the object classes inherited by a newly-created entry in the directory. Optional, no default.
default-attribute- value
set= get unset
String assigned to any LDAP attributes, listed in the create or update dictionaries, that do not have matching lease attributes. You can list these LDAP attributes in the create update dictionaries. If you omit a value, Network Registrar uses the string <default>. Optional, default <default>.
dn-attribute set= get unset
If the server can construct the distinguished name (DN) of the LDAP object to update (or create) from one of the lease attributes, it formats the specified dn-attribute using the dn-format string to construct the object filter that specifies the LDAP server to modify. Optional, no default.
dn-create-format set= get unset
Distinguished name (DN) for entry creation. A %s is required at the entry level and is replaced by the value of the dn-attribute. If you can construct the DN of the LDAP object created from one of the lease’s attributes, the server formats the specified dn-attribute using the dn-format string. Optional, no default.
dn-format set= get unset
Formats the dn-attribute for entry modification. A %s is required at the entry level and is replaced by the value of the dn-attribute. If you can construct the DN of the LDAP object updated from one of the lease’s attributes, the server formats the specified dn-attribute using the dn-format string to construct the query filter. Optional, no default.
2-67Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsldap
hostname set= get unset
Hostname of the LDAP server. Required for creation, no default.
limit-requests enable disable unset
Controls whether to limit the number of outstanding queries on each LDAP client connection. Optional, default enable.
max-referrals set= get unset
Limits the number of LDAP referrals the server follows when querying. A value of zero (the default) means “do not follow referrals.” Optional, default 0 referrals.
max-requests set= get unset
With ldap enable limit-requests, limits the number of outstanding queries of a single LDAP connection. You can improve performance (and avoid swamping the LDAP server) by limiting the number of outstanding queries. For example, if the LDAP server can handle only 100 requests, setting max-requests=20 with connections=5 might be appropriate. Adjust the parameters one at a time and monitor the results. Optional, default 20 requests.
password set= get unset
Password of a user with access to the parts of the directory that DHCP uses. (You can configure LDAP servers to allow anonymous access, so this is optional.) Optional, no default.
port set= get unset
Port on the remote LDAP server. Optional, no default.
preference set= get unset
Preferential order of LDAP servers, specified as a positive integer. 1 is the highest preference value. Optional, default value of 1.
referral-attr set= get unset
Name of the LDAP attribute that may indicate that an LDAP response is a referral. Optional, no default. The referral may or may not contain the DN for which to query:
• If the DN is present (the current server assumes this), it is used as the search path along with a wildcard search scope in the query that follows the referral.
• If the DN is not present, the search path is built by formatting the data in the referral attribute with the referral filter, and the existing search scope is used.
referral-filter set= get unset
If the referral-attr attribute does not contain a DN, the referral attribute’s data is formatted with this filter expression to build a search path, and the existing search scope for the LDAP server is used. Optional, no default.
search-filter set= get unset
Search filter to apply in the client-entry query. The server formats the client’s MAC address using the filter to specify the object that contains the client-entry data. An optional %s at the entry level is replaced by the value of the dn-attribute. Optional, no default.
Table 2-14 ldap Command Attributes (continued)
Attribute Usage Description
2-68Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsldap
search-path set= get unset
Name of an object in the directory to use as a query’s starting point. Together, the search-path and search-scope attributes control the portion of the directory that the server searches. An optional %s at the entry level is replaced by the value of the dn-attribute. Optional, no default.
search-scope set= get unset
Scope of the search. Optional Can be one the following values:
• subtree—Server searches all the children of the search-path (default)
• onelevel—Server only searches the immediate children of the base object
• base—Server only searches the base object itself
threadwaittime set= get unset
If there are outstanding queries or updates, the interval (in milliseconds) at which each LDAP connection polls for results and processes queries, updates and creates. Optional, default 100 ms.
timeout set= get unset
Seconds that the DHCP server should wait for a response to an individual query. After a query times out, the server may retry another LDAP server connection or drop the query if there is no other connection. Note that timeout values for queries are smaller than those for updates. Optional, default 10 seconds.
update-search- attribute
set= get unset
If the DHCP server cannot directly determine the DN of the object to update, it must issue a query to retrieve the DN. In that case, the server uses data in the lease’s search-attribute attribute and formats it using the update-search-filter attribute. Optional, no default.
update-search- filter
set= get unset
Formats the update-search-attribute attribute. A %s is required and is replaced with the value of the DN attribute. Optional, no default.
update-search- path
set= get unset
Starting point for the portion of the directory that contains the LDAP objects that the server updates. The update-search-path and the update-search-scope together control the portion of the directory that contains the objects to update. Optional, no default.
update-search- scope
set= get unset
The update-search-path and the update-search-scope together control the portion of the directory that contains the objects to update. Optional, no default. The scope can be:
• subtree—Server searches all the children of the search-path
• onelevel—Server only searches the immediate children of the base object
• base—Server only searches the base object itself
username set= get unset
DN of a user with access to the parts of the directory that DHCP uses. (You can configure LDAP servers to allow anonymous access, so this is optional). Optional, no default.
Table 2-14 ldap Command Attributes (continued)
Attribute Usage Description
2-69Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsldap
Usage Guidelines Dictionary Examples
Configure a query-dictionary to search for the surname (sn) and use its data to specify the client’s DHCP hostname.
nrcmd> ldap ldapserver setEntry query-dictionary sn=host-name
Configure a query-dictionary to search for the first name (givenname) to use for the specific client-class name:
nrcmd> ldap ldapserver setEntry query-dictionary givenname=client-class-name
Configure a query-dictionary to search for the locality name to use for the domain name:
nrcmd> ldap ldapserver setEntry query-dictionary localityname=domain-name
Create a string-dictionary with an attribute named myattribute assigned to a string named my string:
nrcmd> ldap ldapserver setEntry create-string-dictionary myattribute="my string"
Using the create-string-dictionary Attribute
The dictionary associated with the create-string-dictionary attribute can contain multiple pairs of LDAP attributes. Each pair is set using a separate setEntry keyword. The following examples assign different string values to the attributes givenname and carlicense.
nrcmd> ldap ldapserver setEntry create-string-dictionary givenname=abcdefg nrcmd> ldap ldapserver setEntry create-string-dictionary carlicense=123-456
Note An LDAP attribute can appear only once in each dictionary. A second ldap name setEntry command that supplies an existing key replaces that key.
Related Commands dhcp
2-70Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandslease
leaseUse the lease command to view and manipulate the current DHCP leases in the cluster. All lease command attributes are read-only, and all actions take effect immediately. The ipaddress value can be a simple IP address or can include the namespace, in the syntax namespacename/ipaddress. See the “namespace” section on page 2-84. You do not need to reload the server with this command.
lease ipaddress activate
lease ipaddress deactivate
lease ipaddress send-reservation
lease ipaddress delete-reservation
lease ipaddress force-available
lease ipaddress get-scope-name
lease ipaddress macaddr
lease ipaddress get attribute
lease ipaddress [show]
lease list
lease list –lansegment ipaddress mask
lease list –macaddr macaddress
lease list –subnet ipaddress mask
Syntax Description See Table 2-15 on page 2-72 for the lease command attribute descriptions.
lease ipaddress activate
Activates a lease, but does not change the state of a lease marked as unavailable. The ipaddress value can include the address’ namespace, in the following slash-separated format:
namespacename/ipaddress
If there is no namespace prefix for the address, the value set by the session set current-namespace applies. See the “session” section on page 2-116, or the global namespace if the current namespace is not set.
nrcmd> lease 192.168.1.9 activate
lease ipaddress deactivate
De-activates a lease from being given out or renewed, but does not change the state of the lease.
lease ipaddress send-reservation
Sends an existing reservation to the server immediately without having to reload the server. Use this keyword in conjunction with the scope name addReservation command.
2-71Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandslease
lease ipaddress delete-reservation
Deletes an existing reservation from the DHCP server immediately without requiring a server reload. To delete the lease from the internal nrcmd database, follow this command with the scope name removeReservation command.
lease ipaddress force-available
Makes a currently held lease available, even a lease marked as unavailable. Because using the force-available action may compromise the integrity of your IP address allocations, ensure that, before you use the keyword, the client holding the lease stopped using the lease.
lease ipaddress get-scope-name
Shows the scope to which a lease belongs.
lease ipaddress macaddr
Shows the most recent MAC address associated with a lease. If no MAC address was ever associated with this lease (or if the lease became unavailable), then Network Registrar displays the error message, “302 Not Found.”
lease ipaddress get attribute
Gets the value of an attribute for a lease.
lease ipaddress [show]
Shows the lease attributes for a specific address.
lease list
Lists all the leases in all namespaces. Note that there is no namespace modifier for this command.
lease list –lansegment ipaddress mask
Lists all leases in a LAN segment, including all leases in primary scopes for the address and mask. It also includes all leases in secondary scopes whose primary scope matches the address and mask.
lease list –macaddr macaddress
Lists all leases associated with the specified MAC address. Examples of acceptable formats for the MAC address are:
• 1,6,00:d0:ba:d3:bd:3b
• 00:d0:ba:d3:bd:3b
• 00d0bad3bd3b
lease list –subnet ipaddress mask
Lists all leases in a subnet for the network address and mask.
Attributes Table 2-15 describes the lease command attributes and their values. They are all read-only attributes.
Table 2-15 lease Command Attributes
Attribute Usage Description
address get IP address of the lease.
client-binary-client- id
get Binary form of the client’s MAC address, if any.
2-72Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandslease
client-dns-name get The DHCP server attempted (possibly successfully) to enter this name into the DNS server for this client. It is related to the client-host-name, but may not be identical due to name collisions in the DNS server database.
client-domain-name get Domain (if any) to which the client’s DNS name belongs.
client-flags get The client-flags attribute value can be any of the following flags:
• client-dns-name-up-to-date—The client DNS name (A record) is current in the DNS server database.
• client-id-created-from-mac-address—The client-id was created for internal use from the client-supplied MAC address. If this is true, the server does not report it.
• dns-update-pending—DNS operation is pending for this client.
• reverse-dns-up-to-date—The reverse (PTR record) DNS entry is current in the DNS database.
client-host-name get DNS name that the client requested the DHCP server place into the DNS server.
client-id get Client ID that the client specifies, or one that the DHCP server for this client synthesizes (if client-id-created-from-mac-address is set in the client-flags).
client-last- transaction-time
get Date and time when the client most recently contacted the DHCP server.
client-mac-addr get MAC address that the client presented to the DHCP server.
client-os-type get Operating system of the leased client. This attribute is used only by the updateSms keyword and has no other purpose. If you enable failover, the main server transmits this value to the backup server. The syntax of this attribute’s value is OS-name major.minor.
Other examples are: LANMAN Server, LANMAN Workstation, MAC OS, Microsoft Windows, Microsoft Windows 2000 Professional, Microsoft Windows 95, Microsoft Windows 9x, Microsoft Windows for Workgroups, Microsoft Windows NT Advanced Server, Microsoft Windows NT Server, Microsoft Windows NT Workstation 3.51, Microsoft Windows NT Workstation 4.0, Netware, and OS/2.
expiration get Date and time when the lease expires.
Table 2-15 lease Command Attributes (continued)
Attribute Usage Description
2-73Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandslease
flags get Flags for the lease are backup, deactivated, dynamic, or reserved:
• backup—The state for this lease was recorded by a server whose role was backup with respect to this lease.
• deactivated—The lease is de-activated, which means that you should not use it. Any client that uses de-activated leases receives a NAK on its next renewal attempt.
• dynamic—The lease was last written by a server that knew only about the lease because it was created by a send-reservation command.
• reserved—The lease is reserved for some MAC address. The table that relates MAC addresses to leases is in the scope.
Flags can also include initialized, valid, and failover-updated.
lease-renewal-time get Minimal time in which the client is expected to issue a lease renewal.
namespace-id get Identifier for the namespace, if any.
relay-agent-circuit- id
get Accesses and manipulates the relay-agent circuit id data as stored with a response’s lease.
relay-agent-option get Contents of the relay agent information option from the most recent client interaction.
relay-agent-remote- id
get Accesses and manipulates the relay-agent-remote-id data as stored with a response’s lease.
relay-agent-server- id-override
get IP address in the server-id-override suboption of the relay agent information option.
relay-agent-subnet- selection
get IP address in the subnet selection suboption of the relay agent information option.
relay-agent-vpn-id get Contents of the vpn-id suboption of the relay agent information option. For a description of the VPN ID format, see Table 2-17 on page 2-85.
start-time-of-state get Date and time when the state last changed to its current value. Use this attribute to determine when the lease was made unavailable.
Table 2-15 lease Command Attributes (continued)
Attribute Usage Description
2-74Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandslease
Usage Guidelines Using the send-reservation Keyword
When using the send-reservation keyword:
• Ensure that the reservation already exists (at least in the nrcmd internal database).
• While the scope in which the reservation exists in nrcmd must already exist in the DHCP server, the particular IP address need not appear in the ranges for that scope.
• If you use failover on the scope in which the reservation resides, issue the send-reservation keyword first to the backup and then to the main server. (Ensure that you issued the scope add-reservation keyword to both systems first.)
The following example creates a reservation for IP address 192.168.1.9 and adds it to the open cluster’s database without reloading the DHCP server.
nrcmd> scope myscope addReservation 192.168.1.9 1,6,00:d0:ba:d3:bd:3b nrcmd> save nrcmd> lease 192.168.1.9 send-reservation
state get Current state of the lease. This can be any of the following:
• available—Not currently leased by any client. Any client information is from the most recent client-to-lease or be-offered this lease.
• expired—The client did not renew the lease and it expired. Upon expiration, the DHCP server schedules the removal of the client’s DNS information.
• leased—Currently leased to the client whose information appears in the lease.
• offered—Offered to the associated client. In many cases, the database is not written with information concerning offering a lease to a client, because there is no requirement to update stable storage with this information.
• other-available—Used only when failover is enabled. A lease in this state is available for allocation by the other server in the failover pair, but not available for allocation by this server.
• released—The client released the lease, but the server was configured to apply a release-grace-period. The lease is not available until the grace-period expires.
• pending-available—Used only when failover is enabled. A lease in this state is available as soon as this server can synchronize its available state with the other server.
• unavailable—The lease is unavailable. It was made unavailable because of some conflict. A ping attempt might show that the IP address was already in use by another client, or the DHCP server might notice another DHCP server handing out this lease. See the “Setting a Lease to Unavailable” section on page 2-77.
vendor-class-id get Client ID specified by the client.
Table 2-15 lease Command Attributes (continued)
Attribute Usage Description
2-75Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandslease
Note You should save the reservation (the second command in the example) to ensure that it is preserved across server reload because issuing the send-reservation keyword alone affects only the server’s internal memory.
For more information about the scope name addReservation command, see the “scope” section on page 2-103.
Using the delete-reservation Keyword
When using the delete-reservation keyword:
• Ensure that the reservation was already removed from the nrcmd internal database.
• If you use failover on the scope in which the reservation resides, issue:
a. The delete-reservation keyword to the backup server.
b. The delete-reservation keyword to the main server.
c. A scope removeReservation command to both systems.
The following example creates a reservation and sends it to server 192.168.1.9.
nrcmd> lease 192.168.1.9 delete-reservation nrcmd> scope myscope removeReservation 192.168.1.9 1,6,00:d0:ba:d3:bd:3b nrcmd> save
Note You should save the results of this operation to ensure that it is preserved across server reload because issuing the delete-reservation keyword alone affects only the server’s internal memory.
For details about the scope name removeReservation command, see the “scope” section on page 2-103.
Reserving an Address That Is Currently Leased
It is possible to delete a reservation for one client and send a reservation for a second client, even though the first client still has the lease. The following example describes how Network Registrar behaves in this situation.
Assume that you set up a reservation and lease, as follows:
nrcmd> scope my-scope addReservation 192.168.96.180 1,6,00:d0:ba:d3:bd:3b nrcmd> save nrcmd> lease 192.168.96.180 send-reservation nrcmd> lease 192.168.96.180 activate nrcmd> save
Client 1,6,00:d0:ba:d3:bd:3b does a DHCPDISCOVER and gets an offer for 192.168.96.180. The client then does a DHCPREQUEST and gets an ACK message for the same IP address.
As time passes, client 1,6,00:d0:ba:d3:bd:3b does several DHCPREQUESTs that are renewals, which the server acknowledges. Then, at some time prior to the expiration time of the lease by client 1,6,00:d0:ba:d3:bd:3b on 192.168.96.180, you terminate the reservation as follows:
nrcmd> lease 192.168.96.180 de-activate nrcmd> scope my-scope removeReservation 192.168.96.180 nrcmd> save nrcmd> lease 192.168.96.180 delete-reservation
2-76Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandslease
Next you add a reservation for a different client for that IP address, even though the address is still leased to the first client:
nrcmd> scope my-scope addReservation 192.168.96.180 1,6,02:01:02:01:02:01 nrcmd> save nrcmd> lease 192.168.96.180 send-reservation nrcmd> lease 192.168.96.180 activate nrcmd> save
Now you have an IP address that is leased to one client, but reserved for another. If the new client (1,6,02:01:02:01:02:01) does a DHCPDISCOVER prior to the original client (1,6,00:d0:ba:d3:bd:3b) doing a DHCPDISCOVER, it does not get 192.168.96.180. Instead, it receives a random IP address from the dynamic pool.
When the original client (1,6,00:d0:ba:d3:bd:3b) sends its next DHCPREQUEST to renew the lease on 192.168.96.180, it gets a NAK message. Generally, upon receipt of the not-acknowledged message, the client immediately sends a DHCPDISCOVER. On receipt of that DHCPDISCOVER, the DHCP server cancels the remaining lease time on its lease for 192.168.96.180.
After this, the server gives client 1,6,00:d0:ba:d3:bd:3b whatever lease is appropriate for it—some reservation other than 192.168.96.180, some dynamic lease (if one is available), or nothing, if no dynamic leases are available.
When the new client 1,6,02:01:02:01:02:01 does a DHCPDISCOVER, it gets 192.168.96.180.
You could force the availability of a lease, as follows:
nrcmd> lease 192.168.96.180 force-available
However, that does not stop the original client (1,6,00:d0:ba:d3:bd:3b) from using 192.168.96.180. Also, it does not prevent the new client (1,6,02:01:02:01:02:01) from getting 192.168.96.180.
In other words, this means that making a reservation for a client is independent of the lease state (and actual lease client) of the IP address for which the reservation is made. This is as true of reservations made by the send-reservation keyword as it is of reservations made solely in nrcmd in the configuration database. Thus, making a reservation for one client does not cause another client to lose that lease right away, although that client receives a NAK response the next time it contacts the DHCP server (which could be seconds or days). Additionally, the client that reserved the IP address does not get it if some other client already has it. Instead, it gets some other IP address until the:
• IP address it is supposed to receive is free.
• Client sends a DHCPREQUEST as a renewal and receives a NAK response.
• Client sends a DHCPDISCOVER.
Setting a Lease to Unavailable
While the DHCP server is running, it can set an address to the unavailable state for any of the following three reasons:
• The server is configured for a ping before an offer, and the ping (ICMP echo) message is returned successfully—This indicates that there is a currently active client using that IP address. The DHCP server marks that IP address as unavailable.
• The server receives a DHCPDECLINE message from a DHCP client to which it leased what it thought was a good IP address—The client does an ARP request for the IP address on its local LAN segment to see if anyone else is using it, and some system responds to that request. The client then, in effect, returns the IP address to the DHCP server with a DHCPDECLINE, and then does another DHCPDISCOVER operation to get a new IP address. The server marks the IP address that the client returns as unavailable.
2-77Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandslease
• The server receives “other server” requests from the client—Because all DHCPREQUEST messages are broadcast as part of the DISCOVER-OFFER-REQUEST-ACK cycle, the DHCP server can see messages directed to other servers. A server knows that a message is directed to it by the contents of the server-id option in the packet. If the server sees a message that is directed to another server (its own IP address does not appear in the server-id option), but the address to which this message refers is one that the local server controls, it marks that address as unavailable, because it believes that two DHCP servers must be trying to manage the same address simultaneously.
If you have reason to believe that the client is sending “bad” server-id options (rather than packets actually directed to other servers), you can prevent addresses from being marked unavailable by enabling the ignore-requests-for-other-servers attribute at the DHCP server level.
nrcmd> dhcp enable ignore-requests-for-other-servers
Related Commands dhcp, lease-notification, namespace, scope, session
2-78Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandslease-notification
lease-notificationUse the lease-notification command to receive notification about the number of available addresses in a scope. You can specify the notification limit either as the number of free addresses or the percentage of free addresses. You can also specify who should receive e-mail notification.
lease-notification available={number | percentage%} [config=config file] [leasing-only] [recipients=recipient[,recipient] [mail-host=name [errors-to=recipient]]] [scopes={{scopename | address-range}[,scopename | address-range,....]}] [namespace=name]
Although you can use the lease-notification command interactively, its primary use is as an automated command. See the “Running the lease-notification Command Automatically on UNIX” section on page 2-80 or the “Running the lease-notification Command Automatically on Windows” section on page 2-81.
Syntax Description lease-notification available={number | percentage%} [config=config file] [leasing-only] [recipients=recipient[,recipient] [mail-host=name [errors-to=recipient]]] [scopes={{scopename | address-range}[,scopename | address-range,...]}] [namespace=name]
Table 2-16 describes the lease-notification keywords. Note that keywords and attributes associated with the recipients and scopes keywords apply only in connection with those keywords. The following example specifies scope 1 with an available value of 10% and e-mail recipients billy, joe, and jane.
nrcmd> lease-notification available=10% scopes=scope1 recipients=billy,joe,jane mail-host=mailhost
To specify the range of scopes 192.68.1.0 to 192.68.1.255, the configuration file .nrNotification, the recipients administrator, an available value of 13 leases, and the Windows mail host as mailhost, enter:
nrcmd> lease-notification scopes=192.68.1.0-192.68.1.255 config=/home/bob/.nrNotification [email protected] available=13 mail-host=mailhost
Note If successful, the lease-notification command prints “100 Ok” both before and after Network Registrar lists the addresses. The first “100 Ok” means that the command is being processed (without rejection because of existing locks, licensing problems, or command syntax errors). The second “100 Ok” indicates that the command successfully completed its processing.
2-79Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandslease-notification
Usage Guidelines Running the lease-notification Command Automatically on UNIX
You can run the lease-notification command periodically by means of the cron(1) command by supplying crontab(1) with the command to run. The following example, specified to crontab, runs the lease-notification command at 00:15 and 12:15 (15 minutes after midnight and noon), Monday through Friday.
15 0,12 * * 1-5 . .profile; /opt/nwreg2/usrbin/nrcmd lease-notification available=10\% config=/home/jsmith/.nrconfig addresses=192.32.1.0-192.32.128.0 recipients=jsmith,[email protected] >/dev/null 2>&1
Table 2-16 lease-notification Command Keywords
Keyword Description
available Specify either a number or percentage of available addresses. If the number or percentage of available addresses is equal to or less than the specified value for the scopes being checked, Network Registrar generates a report listing information about the scopes that reach or exceed the available value.
config Specify a configuration file. If you omit a configuration file, Network Registrar searches for the default .nrconfig file. See the “Specifying the Configuration File” section on page 2-81.
errors-to If you specify a mail-host, you can also specify the e-mail address of the sender of the e-mail to provide a return path for bounced e-mail. The default value is postmaster.
leasing-only If you specify leasing-only, Network Registrar displays only the scopes that can offer leases. If failover is enabled, this includes scopes for which one of the following conditions applies:
• The role is main and the failover state is NORMAL, COMM-INTERRUPTED, or PARTNER DOWN.
• The role is backup and the failover state is COMM-INTERRUPTED or PARTNER DOWN.
mail-host On Windows, you must specify a mail-host.
On UNIX, the mail host is generally already configured for the sendmail program. You can verify that your UNIX system is properly configured by issuing the command date | mail your-email-address and observing whether or not the date is e-mailed to you. If mail is not configured, you must specify a mail-host.
namespace If you specify a namespace, you can enter the namespace name or the keywords all or global. The all keyword notifies of addresses in all the configured namespaces. The global keyword notifies of all addresses not in any specific namespace.
recipients If you specify the e-mail addresses of one or more recipients, Network Registrar sends an e-mail report to those addresses. Otherwise, Network Registrar directs the report to standard output.
scopes Specify the scopes either by their names or as a range or ranges of addresses. Network Registrar checks any scope containing any address that falls within the range of addresses. If you omit any scopes or addresses, Network Registrar checks all scopes that the specified cluster manages.
2-80Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandslease-notification
You can perform crontab editing by running the UNIX crontab -e command. Set your EDITOR environment variable before running the command, unless you want to use ed(1). See the crontab(1) man page for additional details.
Note that you must supply the nrcmd command’s full pathname on the crontab command line. You can determine the full pathname in your environment with the UNIX which nrcmd command.
Also, note that when you run the nrcmd lease-notification command by means of crontab, the server ignores the user environment variables AIC_CLUSTER, AIC_NAME, and AIC_PASSWORD. Because other viewers can view the command being run, do not provide the password through the -P option on the command line, for security reasons.
You should supply the cluster name, user, and password information for the cluster you want the nrcmd command to run from in a .profile or other file in the home directory of the user running crontab -e, as shown in the following example:
AIC_CLUSTER=host1 export AIC_CLUSTER AIC_NAME=admin1 export AIC_NAME AIC_PASSWORD=passwd1 export AIC_PASSWORD
The . .profile specification in the crontab entry explicitly reads the file. The first dot (.) is the shell command that reads the file and you must follow it with whitespace. For notification on a different cluster, or clusters, than the one on which ncrmd is running, specify the following information:
• Clusters to check in a config file, as described in the “Specifying the Configuration File” section on page 2-81.
• Fully specified pathname as in sample crontab entry at the beginning of this section.
You can prevent others from examining or changing the contents of the .profile and the configuration file that you create by changing its permissions with the chmod go-rw config_file UNIX command.
Running the lease-notification Command Automatically on Windows
Use the Scheduled Tasks service available in Windows Explorer under My Computer to schedule the nrcmd lease-notification command. If you do not find a Scheduled Tasks folder under My Computer, you need to add this optional component from Microsoft Internet Explorer 4.0 or later, or use some third-party task scheduler. You can also use the at command to schedule the nrcmd lease-notification command. Put multiple entries into the at queue, one for each time of day at which you want to run the job.
Specifying the Configuration File
If you omit a config file, the lease-notification command looks for a default .nrconfig file in your current directory, then in your home directory, and finally in the AIC_INSTALL_PATH/conf directory. Network Registrar uses the first file it encounters.
Each line of the file must either begin with the character # (comment), a section header enclosed in square brackets, or a parameter=value pair or its continuation. Network Registrar strips leading white space from each line and ignores blank lines.
Specifying Clusters
You can specify clusters in different ways. Network Registrar follows a precedence order:
1. Default cluster (localhost).
2. UNIX environment or Windows Registry variable AIC_CLUSTER.
2-81Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandslease-notification
3. -C flag on the command line allows you to specify a single cluster.
4. Clusters attribute in the config file, with which you can specify a group of clusters. The following example specifies clusters in the .nrconfig file or some other specified configuration file:
Cluster information for lease notification [lease-notification] clusters=clustername username password...clusters=host1 admin, host2, host3 admin3 passwd3
Separate the three cluster arguments with spaces. For long lines, you can use continuation lines without using escape indicators. You can optionally specify a username and password for the cluster. If you omit a username or password, Network Registrar uses the last one listed. Network Registrar uses the information from the command line -N and -P arguments, and then the Windows Registry or environment variables AIC_NAME and AIC_PASSWORD.
If Network Registrar cannot find a username or password, or the supplied username and password are incorrect, the lease-notification command issues a warning for that cluster.
Related Commands lease
2-82Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandslicense
licenseThe license command specifies the license key for a cluster or allows you to view the license key or the license’s expiration date. Your license key is located on the back of the Cisco Network Registrar CD-ROM case. You must enter your license key the first time you configure any cluster.
• Permanent license—You do not see the license message again unless you move your cluster to another machine.
• Evaluation copy of Network Registrar—You have a license that expires.
• Invalid or missing licensing key—You cannot configure or manage the Network Registrar servers. However, the servers themselves continue to function normally.
• License expires in seven or fewer days—You see a warning when you start Network Registrar.
license set key=value
license get {expiration | key}
license [show]
Syntax Description license set key=value
Sets the key value for the license. To set the license, you must run the nrcmd program in interactive mode, then exit and rerun the nrcmd program. The following example sets the license to key 1234 abcd 5678 efgh.
nrcmd -C cluster1 -N admin -P changeme nrcmd> license set key=1234-abcd-5678-efgh 100 Ok nrcmd> exit
license get {expiration | key}
Gets the expiration or key values for the license.
license [show]
Shows the values of the attributes assigned to the license.
Related Commands admin
2-83Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsnamespace
namespaceThe namespace command creates, deletes, sets, and lists attributes for namespaces. A namespace distinguishes a set of DHCP server objects that are independent of otherwise identical objects in other namespaces. The DHCP server groups address blocks and their associated subnets, and scopes and their associated leases by namespace. A namespace has a descriptive name.
There are two ways to use namespaces:
• Through address blocks—By creating subnets
• Through scopes—By creating leases
In virtual private network (VPN) deployments, for example, you can create a namespace for each VPN, based on the vpn-id. The namespaces allow the DHCP server to distinguish among multiple instances of a single logical IP subnet when that subnet is used in multiple independent VPNs. The server also groups each lease in the subnet by namespace, so that the server can interact with clients on VPNs that use the same IP address space. See the “Virtual Private Network Configuration Example” section on page 2-4.
namespace name create id=id [attribute=value]
namespace name delete
namespace name set attribute=value
namespace name unset attribute
namespace name get attribute
namespace name [show]
namespace list
namespace listnames
Syntax Description namespace name create id=id [attribute=value]
Creates a namespace using a unique name and unique namespace identifier. The namespace requires the name and an id. You cannot use the reserved words all or global for the namespace name.
The namespace can take two attributes, the VPN Routing and Forwarding instance (VRF) name and the VPN identifier (See Table 2-17). Network Registrar associates an incoming packet with the namespace if either the VRF name or VPN ID appears in the vpn-id option or vpn-id suboption (each can carry only one at a time in the packet).
You can change the namespace name using the set command, unless the namespace is the current namespace defined by the session set current-namespace command or the new name is not unique. You cannot change the namespace-id value. See the “session” section on page 2-116.
namespace name delete
Deletes a namespace.
namespace name set attribute=value
Changes the namespace name or sets one of the other attributes (see Table 2-17). You can change the namespace name only to another unique name. You cannot change the namespace-id value.
2-84Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsnamespace
namespace name unset attribute
Unsets the value of an attribute.
namespace name get attribute
Gets the value of an attribute.
namespace name [show]
Shows the values of all attributes assigned to the namespace.
namespace list
Lists the namespaces and their properties.
namespace listnames
Lists just the names of all the namespaces.
Attributes Table 2-17 describes the namespace command attributes and attribute=value pairs.
Table 2-17 namespace Command Attributes
Attribute Usage Description
addr-blocks- default-selection- tags
set= get unset
Specifies the default selection tag (or list of tags) that are associated with incoming subnet-allocation requests in this namespace that does not contain any subnet name data. Optional, no default.
addr-blocks-use- client-affinity
enable disable unset
The DHCP server attempts to allocate subnets to clients using address blocks that the clients have already used. Use this parameter to disable that behavior, in which case the server supplies subnets from any address block that is suitable (based on other selection data in the clients’ messages. Optional, default enable.
addr-blocks-use- lan-segments
enable disable unset
Controls whether DHCP subnet-allocation uses the lan-segment attribute when configured on address blocks. Optional, default disable.
addr-blocks-use- selection-tags
enable disable unset
Controls whether the server compares incoming subnet-allocation requests’ subnet name data with each address block’s selection tags. An address block is only considered if the two match. Optional, default enable.
description create set= get unset
Description for the namespace. Optional, no default.
id create get
Unique identifier for the namespace. Must be a positive number. Required, no default.
name create set= get
unset
Unique name string for the namespace; for example, Red or Blue. Required, no default.
2-85Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsnamespace
Related Commands address-block, scope, session, subnet
vpn-id create set= get
unset
Unique identifier for the VPN associated with the namespace. The VPN identifier is in the format oui:index, such as a1:3f6c. It consists of a three-octet VPN authority organizationally unique identifier (OUI), assigned by the IEEE organization (RFC 2685), that corresponds to the VPN owner or ISP, followed by a colon, and a four-octet index number corresponding to the VPN serviced by the authority. DHCP and the Remote Authentication Dial-In User Service (RADIUS) use the VPN ID to identify a VPN. RADIUS can use it to assign dial-in users to the proper VPN, based on each user’s authentication information. Optional, no default.
vrf-name create set= get
unset
Unique virtual routing forwarding (VRF) name, as derived from the relay agent router configuration. Optional, no default.
Table 2-17 namespace Command Attributes (continued)
Attribute Usage Description
2-86Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsoption-datatype
option-datatypeThe option-datatype command allows you to define DHCP option data types as required to accommodate devices from a variety of vendors. You can create a collection of standard DHCP option data types, such as IPADDR, BYTE and IPADDR_ARRAY, to support requirements for complex data types.
Note The option datatype name is case-insensitive.
option-datatype name create
option-datatype name delete
option-datatype name defineField field position datatype [flags]
option-datatype name undefineField field
option-datatype name listFields
option-datatype name enable read-only
option-datatype name disable read-only
option-datatype name [show]
option-datatype list
option-datatype listnames
Syntax Description option-datatype name create
Creates an option data type.
option-datatype name delete
Deletes an option data type.
option-datatype name defineField field position datatype [flags]
Defines a field of an option data type. Specifies the field name, numeric position among other fields, data type, and optional formatting flags. The attributes of this command are as follows:
• field—Name of the field to define or undefine in the option data type definition. Required, no default.
• position—Position number of the field being defined in the option data type definition. Required, no default.
• datatype—Currently supported DHCP option data type. This specifies the data type of the field being defined in the new option data type definition. It can be BOOL, BYTE, WORD, INT, UINT, STRING, IPADDR, BYTE_ARRAY, WORD_ARRAY, INT_ARRAY, UINT_ARRAY, or IPADDR_ARRAY. See Table 2-18. Required, no default.
2-87Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsoption-datatype
• flags—One or more comma-separated strings specifying formatting of the data type. Optional, no default.
The supported flags are:
• little-endian—Lower-byte-first ordering, such as for Intel devices.
• counted-array—Data in an array field is preceded by a byte that gives the length of the array. This is valid only for an array type, such as IPADDR_ARRAY. See the “Specifying Arrays in Vendor Specific Options” section on page 2-110.
• exclude-from-dhcp-packet—Data to exclude in this field from the packet that the DHCP server sends the DHCP client.
option-datatype name undefineField field
Undefines a field name for an option data type.
option-datatype name listFields
Lists any fields defined for an option data type.
option-datatype name enable read-only
Prevents further changes to the definition of an option data type.
Note You should enable the read-only attribute for an option data type before using it in a vendor-option command.
option-datatype name disable read-only
Allows you to make changes to the definition of an option data type (the default).
option-datatype name [show]
Shows the attributes for an option data type.
option-datatype list
Lists the DHCP option data types and any attributes assigned to them.
option-datatype listnames
Lists just the names of the DHCP option data types.
Option Data Types Table 2-18 lists the data type values that Network Registrar supports.
Table 2-18 Option Data Types
Option Data Type Datatype (Number) Definition
boolean BOOL (1) TRUE or FALSE.
byte BYTE (7) 8-bit unsigned integer.
byte array BYTE_ARRAY (8) Sequence of bytes represented in the form xx[:xx…] in which x is a hex character 0 through 9 or a through f. For example, to enter a series of four bytes containing the values 192, 168, 73 and 144, enter their hex values as c0:a8:49:90. Enter the ASCII string ABCijk123 as 41:42:43:69:6a:6b:31:32:33.
IP address IPADDR (5) IP address in the form of a.b.c.d.
2-88Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsoption-datatype
Usage Guidelines See the “Defining Vendor-Specific DHCP Options” section on page 2-131.
IP address array IPADDR_ARRAY (6)
Array of IP addresses.
signed array INT_ARRAY (3) Array of 32-bit signed integers.
signed integer INT (2) 32-bit signed integer.
string STRING (4) ASCII text string.
unsigned array UINT_ARRAY (12) Array of 32-bit unsigned integers.
unsigned integer UINT (11) 32-bit unsigned integer.
word WORD (9) 16-bit unsigned integer.
word array WORD_ARRAY (0) Array of 16-bit unsigned integers.
Table 2-18 Option Data Types (continued)
Option Data Type Datatype (Number) Definition
2-89Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandspolicy
policyThe policy command configures DHCP policy configurations. A policy is a collection of DHCP option values to associate with a range of addresses in a scope, or with a specific client or client-class configuration. Network Registrar considers policy reply options in a hierarchy of options. See the “Policy Reply Options” section on page 2-94.
The policy command can stand alone. However, there are four additional policy object types that you indicate as hyphenated prefixes to the policy command:
• address-block
• client
• client-class
• scope
policy name create [attribute=value…]
[type-]policy name delete
[type-]policy name enable attribute
[type-]policy name disable attribute
[type-]policy name set attribute=value [attribute=value…]
[type-]policy name unset attribute
[type-]policy name get attribute
[type-]policy name [show]
policy list
policy listnames
[type-]policy name setOption option value
[type-]policy name unsetOption option
[type-]policy name getOption option
[type-]policy name listOptions
[type-]policy name setVendorOption vendoroption suboption-syntax field value
[type-]policy name unsetVendorOption vendoroption suboption-syntax field
[type-]policy name getVendorOption vendoroption suboption-syntax field
[type-]policy name listVendorOptions [vendoroption]
[type-]policy name setLeaseTime value
2-90Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandspolicy
Syntax Description See Table 2-19 on page 2-92 for the policy command attribute descriptions.
policy name create [attribute=value…]
Creates a policy (and optionally assigns attribute values).
nrcmd> policy CompanyB create
[type-]policy name delete
Deletes a policy.
[type-]policy name enable attribute
Enables the attribute for a policy.
[type-]policy name disable attribute
Disables the attribute for a policy.
[type-]policy name set attribute=value [attribute=value…]
Sets an attribute to a value for a policy.
nrcmd> policy default set grace-period=3d nrcmd> address-block-policy 10.10.0.0/16 set offer-timeout=2m nrcmd> client-policy 1,6,00:d0:ba:d3:bd:3b set server-lease-time=5d nrcmd> client-class-policy CableModem set dhcp-reply-options=all-subnets-local nrcmd> scope-policy testScope set bootp-reply-options=time-offset nrcmd> dhcp reload
[type-]policy name unset attribute
Unsets the value of an attribute for a policy. You cannot unset required attributes.
[type-]policy name get attribute
Gets the value of an attribute for a policy.
[type-]policy name [show]
Shows the values of all attributes assigned to a policy.
policy list
Lists all policies and any attributes assigned to them.
policy listnames
Lists just the names of all policies.
[type-]policy name setOption option value
Sets the value of a standard DHCP option name to a value for a policy.
nrcmd> policy default setOption dhcp-lease-time 608400
For a list of all the DHCP options that you can configure, enter the nrcmd program help dhcp-option command.
[type-]policy name unsetOption option
Unsets the value of an option for a policy.
[type-]policy name getOption option
Gets the value of an option for the policy.
2-91Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandspolicy
[type-]policy name listOptions
Lists the standard options in a policy.
nrcmd> policy default listOptions (51)dhcp-lease-time: 604800
[type-]policy name setVendorOption vendoroption suboption field value [type-]policy name setVendorOption vendoroption {suboption[index]} field value
Associates a vendor-supplied DHCP option (vendoroption) and its suboption with the policy and assigns a value to a field of the suboption. Use the suboption-index syntax when a suboption is an array that requires braces and square brackets. See the “Specifying Arrays in Vendor-Specific Options” section on page 2-95. See also the “Defining Vendor-Specific DHCP Options” section on page 2-131.
You must create the name of the vendor option using the option-datatype and vendor-option commands before you can use it in the policy command.
[type-]policy name unsetVendorOption vendoroption suboption field [type-]policy name unsetVendorOption vendoroption {suboption[index]} field
Deletes the association between the specified policy and a vendor-supplied DHCP option suboption field. Use the suboption-index syntax for arrays. See the “Specifying Arrays in Vendor-Specific Options” section on page 2-95.
[type-]policy name getVendorOption vendoroption suboption-syntax field [type-]policy name getVendorOption vendoroption {suboption[index]} field
Gets vendor-specific option data for the policy.
[type-]policy name listVendorOptions [vendoroption]
Lists data for all vendor options in a policy or, optionally, lists data for a specific vendor option.
nrcmd> policy 168.1-net listVendorOptions
[type-]policy name setLeaseTime value
Sets the client lease time to value for a policy. The lease time is the value of the dhcp-lease-time DHCP option. See the “Lease Times” section on page 2-95.
To view the lease time value, use the [type-]policy name listOptions command. The time is displayed in seconds.
Attributes Table 2-19 describes the [type-] policy command attributes.
Table 2-19 type-policy Command Attributes
Attribute Usage Description
allow-client-a- record-update
enable disable unset
Allows the client to update the A record. If the client sets the flags in the FQDN option to indicate an A record update in the request, and if this attribute is enabled, the server allows the client to do the A record update. Otherwise, the server does the A record update based on other server configurations. Optional, default enable.
2-92Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandspolicy
allow-dual-zone- dns-update
enable disable unset
If enabled, the DHCP server returns the client-fqdn option (81) so that the client can perform an A record update itself. Also, the server performs an A record update on the client’s behalf. This is required to support certain DHCP deployments that represent their clients in two DNS zones. If both the allow-client-a-record-update and allow-dual-dns-update attributes are enabled, the latter takes precedence. Optional, default disable.
allow-lease-time- override
enable disable unset
Clients can request a specific lease time. The server does not honor requested lease times if this attribute is false, or if the time is longer than the server’s normal lease time. Optional, default enable.
bootp-reply- options
set= get unset
List of names of options to return in any replies to BOOTP clients. You do not need to configure the options themselves in the same policy as the reply-options list; the server searches the hierarchy of policies for each option named in the list. See the “Policy Reply Options” section on page 2-94. Optional, no default.
dhcp-reply- options
set= get unset
List of names of options to return in any replies to DHCP clients. You do not need to configure the options themselves in the same policy as the reply-options list; the server searches the hierarchy of policies for each option named in the list. See the “Policy Reply Options” section on page 2-94. Optional, no default.
grace-period set= get unset
Time, in seconds, between the expiration of a lease and the time it is made available for re-assignment. Optional, default 300 seconds (five minutes).
offer-timeout set= get unset
The time, in seconds, that the server waits to re-offer a lease if a client does not accept it. Optional, default 120 seconds (two minutes).
packet-file-name set= get unset
Name of the boot file for a client’s boot process. The server returns this filename in the file field of its replies. Optional, no default, but cannot be longer than 127 characters. This attribute can also contain the following variable substitution values:
• %@docsis-vers%—If you specify the DOCSIS version value, the server substitutes it with the version presented in the DHCP request packet’s vendor-class-identifier option. This version can be either docsis1.0 or docsis1.1. If the vendor-class-id option is missing or does not contain a DOCSIS version string, the server substitutes the docsis-version-id-missing string. See Table 2-5 on page 2-22.
• %@mac-addr%—If you specify the MAC address value, the server substitutes this string with the source MAC address as presented in the DHCP request packet.
packet-server- name
set= get unset
Hostname of a server to use in a client’s boot process. The server returns this hostname in the sname field of its replies. Optional, no default, but cannot be longer than 64 characters.
packet-siaddr set= get unset
IP address of the next server in a client’s boot process. For example, this might be the address of a TFTP server BOOTP clients use. The server returns this address in the siaddr field of its reply. Optional, no default.
Table 2-19 type-policy Command Attributes (continued)
Attribute Usage Description
2-93Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandspolicy
Usage Guidelines Policy Reply Options
When the server is getting ready to return option data to a client, it examines up to seven policies in the following order:
1. Client embedded policy
2. Client assigned policy
3. Client-class embedded policy
4. Client-class assigned policy
5. Scope embedded policy for clients, or address block embedded policy for subnets
6. Scope assigned policy for clients, or address block assigned policy for subnets
7. System default policy
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 from the server must come from the same policy as the reply-options list. If the server finds a reply-options list, it looks for each option in the list individually, and searches all the related policies if necessary.
Also, you do not need to have the options mentioned in a reply-options list present in the policy containing the list. You can enter a string that can name any option. The Network Registrar GUI, however, presents a special dialog box for adding a reply-options attribute 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.
permanent-leases enable disable unset
When enabled, grants permanent leases to clients. Optional, default disable.
server-lease-time set= get unset
Time that the server believes the lease is valid. It may help for the server to consider leasing for a longer period than the client requests so as to get more frequent client communication, along with the stability of long lease times. This value is not used unless it is longer than the lease time in the dhcp-lease-time option found through the normal traversal of policies. See the “Lease Times” section on page 2-95. Optional, no default.
split-lease-times enable disable unset
Controls whether the server uses the value of the server-lease-time attribute to determine the length of a lease, rather than using the lease time returned to the client. Optional, default disable.
Table 2-19 type-policy Command Attributes (continued)
Attribute Usage Description
2-94Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandspolicy
Lease Times
A policy contains two lease times—the client lease time and the server lease time.
• Client—You set the client lease time through the setLeaseTime keyword. This lease time determines how long the client believes its lease is valid.
• Server—You set the server lease time through server-lease-time attribute. This lease time determines how long the server considers the lease valid. Note that the server lease time is independent of the lease’s grace period. The server does not allocate the lease to another client until after the lease time and grace period expire.
You can 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. However, if you use a short client lease time and a longer server lease time, then the client information is retained even after the client’s lease expires.
Caution Although Network Registrar supports the use of two lease times for special situations, Cisco Systems generally recommends that you not use the server-lease-time attribute.
Specifying Arrays in Vendor-Specific Options
The following example sets data for the boot_server_type field in array index 0 of the suboption named suboption_8. Include the braces and square brackets as part of the suboption and index specification. Enter the 200 as a string and not in hexidecimal.:
nrcmd> policy 168.1-net setVendorOption IntelPXE_vso {suboption_8[0]} boot_server_type 200
If the data type of the option field (in this example, boot_server_IP_list) is an array, use comma-separated values, such as the two IP addresses in the following example, as a string and not in hexidecimal.
nrcmd> policy network-1.2.3 setVendorOption IntelPXE_vso {suboption_8[0]} boot_server_IP_list 192.168.25.4,192.168.25.5
See the “Defining Vendor-Specific DHCP Options” section on page 2-131.
Related Commands admin, client-class, client-class-policy, client-policy, dhcp, scope, scope-policy, vendor-option
2-95Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsremote-dns
remote-dnsThe remote-dns command controls the behavior of the DNS server when it is communicating with other DNS servers. Use it either to control incremental transfer or to send multiple records per transmission control protocol (TCP) packet.
remote-dns ipaddress[/maskbits] create [ixfr={true | false} | multirec={true | false}]
remote-dns ipaddress[/maskbits] delete
remote-dns ipaddress[/maskbits] enable {ixfr | multirec}
remote-dns ipaddress[/maskbits] disable {ixfr | multirec}
remote-dns ipaddress[/maskbits] unset {ixfr | multirec}
remote-dns ipaddress[/maskbits] [show]
remote-dns list
remote-dns listnames
Syntax Description remote-dns ipaddress[/maskbits] create [ixfr={true | false} | multirec={true | false}]
Creates a remote DNS server description. See the enable syntax description for the optional attributes. The following example creates the remote server description 192.168.1.1 with the net mask of 255.255.0.0.
nrcmd> remote-dns create 192.168.1.1/16
Note Each net mask octet is composed of 8 bits. In the previous example, the first two octets are significant, thus the netmask is 16. If the first three octets are significant, the net mask is 24.
remote-dns ipaddress[/maskbits] delete
Deletes a remote DNS server description.
remote-dns ipaddress[/maskbits] enable {ixfr | multirec}
Enables incremental zone transfers (IXFRs), multiple records, or both for a remote DNS server.
• ixfr—Whether a foreign server supports incremental transfer and to query it for incremental (IXFR) before full (AXFR) when asking for zone transfers. Although unwittingly setting this to true is generally harmless, doing so may result in additional transactions to accomplish a zone transfer. Optional, initial default disable.
• multirec—Whether to send a remote server zone transfers (AXFR) with multiple records in one TCP packet. Older DNS servers crash when they receive such transfers, despite being allowed by the protocol. Optional, initial default disable.
When you enable or disable incremental transfer, Network Registrar looks for the most specific match. That is, it matches the machine with the longest mask. You can use this attribute to specify a group of servers with a single command.
2-96Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsremote-dns
The following example enables all DNS servers on this network to perform incremental transfer.
nrcmd> remote-dns create 128.103.0.0/16 ixfr=true
The following example disables incremental transfers on all DNS servers on this network.
nrcmd> remote-dns create 128.103.1.0/24 ixfr=false
remote-dns ipaddress[/maskbits] disable {ixfr | multirec}
Disables incremental zone transfers or multiple records for a remote DNS server. See the enable syntax description.
remote-dns ipaddress[/maskbits] unset {ixfr | multirec}
Unsets the incremental zone transfers or multiple records attribute for the remote DNS server.
remote-dns ipaddress[/maskbits] [show]
Shows the attributes for the remote DNS server.
remote-dns list
Lists all remote DNS server descriptions and any attributes assigned to them.
remote-dns listnames
Lists just the names of the remote DNS servers.
Related Commands dns, server
2-97Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsreport
reportThe report command produces a summary of dynamic and static IP address utilization for one or more clusters.
report [config=config file] [column-separator=character-string] [dhcp-only] [file=output-file] [leasing-only] [mask-bits=value] [namespace=name]
Syntax Description report [config=config-file] [column-separator=character-string] [dhcp-only] [file=output-file] [leasing-only] [mask-bits=value] [namespace=name]
When you use the report command with no keywords, it creates a report of static DNS addresses and dynamic DHCP addresses for the cluster on which it is running and sends the report to the standard output. You can limit the report, redirect it to a file, and change its column delimiters by using the keywords. Table 2-20 describes the report command attributes.
Note If successful, the report command prints “100 Ok” both before and after Network Registrar lists the addresses. The first “100 Ok” means that the command is being processed (without rejection because of existing locks, licensing problems, or command syntax errors). The second “100 Ok” indicates that the command successfully completed its processing.
Table 2-20 report Command Keywords
Keywords Description
column- separator
Character string that you want the report to use between the columns. The default is a single space. If you specify whitespace, you must precede it with a backslash (\) and, if entering it on the command line, use quotation marks. For example: “\ ”.
config File in which you can specify multiple clusters.
dhcp-only Summary of just the DHCP information.
file Filename to which the report command writes the output. If you omit a filename, the report command appears on the screen. Because it can take a long time to collect DNS data, you should not run the report command interactively when requesting DNS summaries.
leasing-only Only scopes that can offer leases should appear in the report. If failover is enabled, this includes scopes for which one of the following conditions applies:
• The role is main and the failover state is NORMAL, COMMUNICATION-INTERRUPTED, or PARTNER DOWN.
• The role is backup and the failover state is COMM-INTERRUPTED or PARTNER DOWN.
mask-bits Number of high-order bits set in the network mask that define a logical subnet for which the report command produces a summary. The default value is 16.
If the value of the mask-bits is less than the default or less than the largest mask of any scope’s mask in the report, the report command uses the default value.
2-98Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsreport
Usage Guidelines Specifying Clusters
You can specify cluster in a variety of ways and Network Registrar follows a precedence order. Any of the cluster specifications can override the default specification or previous specification.
• The default cluster (localhost).
• The UNIX environment or Windows Registry variable AIC_CLUSTER.
• The -C flag on the command line allows you to specify a single cluster.
• The clusters attribute in the configuration file allows you to specify a group of clusters. The following example specifies clusters in the configuration file.
Cluster information for summary reports [report] clusters= clustername username password, ...clusters=host1 admin, host2, host3 admin3 passwd3
Note You should separate the three cluster arguments with spaces. For long lines, use continuation lines, that is, you do not need to use continuation escape indicators. You can optionally specify a username and password for the cluster. If you do not provide a username or password for a particular cluster, Network Registrar uses the last username or password listed. If you do not provide usernames or passwords, Network Registrar uses the information from the command line -N and -P arguments, and then the Windows Registry or environment variables AIC_NAME and AIC_PASSWORD.
If Network Registrar cannot find a username or password, or if the supplied username and password are incorrect, then the report command issues a warning for that cluster.
Displaying the Summary
The report command displays a row of information for each subnet specified by scope or deduced from DNS static address assignments outside of scopes.
The report command displays subtotal rows when more than one scope shares a common subnet, and when addresses share a common subnet as specified by their address and mask. Note that the report command assumes that there is no overlap between static addresses and scope ranges.
For each scope or subnet, the report command displays the following information:
• Network number, in hexadecimal
• Number of bits in the subnet mask
• Network number in canonical, dotted-octet format
For each scope-specified subnet, the report command also displays the following values:
• Cluster name
namespace If you specify a namespace, you can enter its name or the keyword global. This reports on addresses in a specific namespace, or those in the global, unspecific namespace.
Table 2-20 report Command Keywords (continued)
Keywords Description
2-99Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsreport
• Scope role (If using failover, the value is MAIN or BACKUP.)
• Scope name
• Addresses—Total addresses within the scope ranges: free + dynamically leased + reserved + unavailable + de-activated + other available
• Free—Free addresses within a range, in the available state, and not flagged as reserved or de-activated
• % free—Free addresses as a percentage of all addresses within scope ranges
• Reserved—Value is within a range and flagged reserved, unless unavailable
• Leased—Value is within a range and in the leased, offered expired, or released state, even if flagged reserved or de-activated
• Dynamically leased—Value is within a range and in the leased, offered, or expired state, unless flagged reserved or de-activated
• Unavailable—Within a range and marked as unavailable by the server, regardless of flags
• De-activated—Within a range and flagged deactivated, unless unavailable
• Other available—Leases set aside for the failover partner to lease when communication is interrupted
• Other reservations—Addresses marked reserved which are not in a scope range
Addresses have both a current state and a pending state after their leases expire. Table 2-21 summarizes address states.
For each subtotal row, the report command provides summaries of any scope values in the subnet, and additionally, displays the following values:
• Total—All addresses in the subnet.
• Static—Addresses statically assigned.
• Unallocated—Addresses unallocated to DHCP scope ranges, otherwise reserved or statically assigned, and therefore available for static assignment or allocation to a scope range.
At the end of the report, a grand total summarizes all the data in the subnets.
The rows and columns in Table 2-22 represent potential states and flags that an address within a DHCP scope can possess. The cells within the table indicate the category into which Network Registrar places addresses with a given state and flag. When setting multiple flags, deactivated takes priority over reserved, and reserved takes priority over any remaining flags for reporting purposes.
Table 2-21 Categories of Address States
These categories Represent these states
deactivated current or pending
dynamically leased current or pending
free current state of available minus addresses flagged reserved or deactivated
leased current (The leased category overlaps other categories and is not incorporated in the scope total.)
reserved current or pending
unavailable current
2-100Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsreport
Table 2-22 lists and describes the potential states and flags for IP addresses.
Related Commands export
Table 2-22 Potential States and Flags for IP Addresses
States
Flags
None Reserved DeactivatedReserved and Deactivated
available free reserved deactivated deactivated
leased dynamically leased, leased
dynamically leased, leased
deactivated, leased
deactivated, leased
expired dynamically leased, leased
dynamically leased, leased
deactivated, leased
deactivated, leased
offered dynamically leased, leased
dynamically leased, leased
deactivated, leased
deactivated, leased
other- available
other available reserved deactivated deactivated
pending- available
dynamically leased, leased
dynamically leased, leased
deactivated, leased
deactivated, leased
unavailable unavailable unavailable unavailable unavailable
2-101Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandssave
saveThe save command validates and saves your changes to the database.
save
Usage Guidelines Validation
The nrcmd program performs validation when you create objects or modify their attributes. It checks that you supplied the required attributes and that their values are valid. It also checks the validity of attribute values when you set them.
When you issue the save command, Network Registrar ensures that:
• It made no other modifications to these objects since reading them from the database.
• All affected references are still valid.
• The proposed modifications result in a valid server configuration.
Status Codes
All nrcmd commands return a status code as the first line of output. The first word on the line is a three-digit status code. The remaining output is the descriptive text. The first digit of the status code determines the class of the status.
Table 2-23 lists the save command status codes.
For details about error codes, see Appendix A, “Codes and Formats.”
Related Commands server
Table 2-23 save Command Status Codes
Status Code Description
100 Ok Indicates a successful save.
3xx Indicates an error in processing the command.
4xx Indicates an error in communicating with the cluster database server.
5xx Indicates an internal error in the command.
2-102Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsscope
scopeThe scope command creates and edits DHCP scopes.
scope name create addr mask [attribute=value…]
scope name delete
scope name enable attribute
scope name disable attribute
scope name set attribute=value [attribute=value...]
scope name unset attribute
scope name get attribute
scope name [show]
scope list
scope listnames
scope name listLeases
scope name changeMask netmask
scope name clearUnavailable
scope name addRange start end
scope name removeRange start end
scope name listRanges
scope name addReservation ipaddr macaddr
scope name removeReservation {ipaddr | macaddr}
scope name listReservations
Syntax Description See Table 2-24 on page 2-105 for the scope command attribute descriptions.
scope name create ipaddress mask [attribute=value…]
Creates a scope (and optionally sets an attribute). Specify the scope mask in base-10 (such as 255.255.255.0), not in hexadecimal.
nrcmd> scope testscope create 192.168.1.0 255.255.255.0
scope name delete
Deletes a scope.
2-103Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsscope
scope name enable attribute
Enables an attribute for a scope.
nrcmd> scope testscope enable dynamic-dns
scope name disable attribute
Disables a attribute for a scope.
nrcmd> scope testscope disable dynamic-bootp
scope name set attribute=value [attribute=value...]
Sets one or more attributes for a scope.
nrcmd> scope testscope set dns-reverse-zone-name=10.in-addr.arpa.
scope name unset attribute
Unsets an attribute for a scope. You cannot unset required attributes.
scope name get attribute
Gets the value of an attribute for a scope. The following example gets the DNS zone name.
nrcmd> scope testscope get dns-zone-name
scope name [show]
Shows the values of all attributes assigned to a scope.
scope list
Lists all scopes and any attributes assigned to them.
scope listnames
Lists just the names of scopes.
scope name listLeases
Lists the leases in a scope. This list can be very long.
scope name changeMask netmask
Changes the network mask of a scope. See the “Changing the Mask of a Scope” section on page 2-109.
nrcmd> scope testScope changemask 255.255.254.0
scope name clearUnavailable
Clears the unavailability of leases in a scope to make them all available.
scope name addRange start end
Adds a range of addresses to a scope. The start and end values can be host numbers or IP addresses. However, they must fall within the network addresses that the scope address and mask define. If adding addresses to a scope creates a continuous set of addresses, Network Registrar merges the current list of ranges, if possible.
nrcmd> scope testScope addRange 192.168.1.10 192.168.1.20
scope name removeRange start end
Removes a range of available addresses in a scope, starting with a start address and ending with an end address. If removing a range creates a discontinuous set of addresses, Network Registrar modifies or splits the existing ranges.
nrcmd> scope testscope removeRange 192.168.1.10 192.168.1.15
2-104Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsscope
scope name listRanges
Lists the available addresses in a scope.
scope name addReservation ipaddr macaddr
Adds a reservation to a scope.
nrcmd> scope testScope AddReservation 192.168.1.10 1,6,00:d0:ba:d3:bd:3b
Tip You can use the lease name send-reservation command to send the reservation immediately to the server without reloading it. For more information, see the “lease” section on page 2-71.
scope name removeReservation {ipaddress | macaddress}
Removes a reservation from a scope. Specifying the MAC address or IP address of the client.
nrcmd> scope testscope removeReservation 192.168.1.10
scope name listReservations
Lists the reservations in a scope.
Attributes Table 2-24 describes the scope command attributes and their values and defaults, if any.
Table 2-24 scope Command Attributes
Attribute Usage Description
addr set= get unset
Address of the subnet for which this scope contains addresses (read-only). Optional, no default.
bootp enable disable unset
Controls whether the server accepts BOOTP requests. If you want clients to always receive the same addresses, you need to reserve IP addresses for all your BOOTP clients. Optional, default disable.
deactivated enable disable unset
A scope that does not extend leases to clients. It treats all of the addresses in its ranges as if they were individually de-activated. Optional, no default.
dhcp enable disable unset
Controls whether the DHCP server does accept DHCP requests for this scope. Disable DHCP for a scope to use the scope for BOOTP exclusively, or to temporarily de-activate it. Optional, default enable.
dns-reverse- zone-name
set= get unset
Name of the inverse (in.addr.arpa) zone that is updated with PTR and TXT records. Optional, no default.
dns-rev-server- addr
set= get unset
Address of the reverse DNS server for the zone into which the server should add PTR records. Optional, no default.
dns-server-addr set= get unset
IP address of the primary DNS server on which the forward zone resides. Optional, no default.
dns-zone-name set= get unset
Name of the DNS zone to which to add a DHCP client’s host (A record). Optional, no default.
2-105Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsscope
dynamic-bootp enable disable unset
Controls whether the server accepts dynamic BOOTP requests for this scope. Dynamic BOOTP requests are BOOTP requests that do not match a reservation, but can come from the available lease pool. To use this attribute, you must also enable bootp. Optional, default disable.
dynamic-dns enable disable unset
Controls whether the DHCP server should attempt to update a DNS server with the name and address information from leases granted to requesting clients. Optional, default disable.
embedded- policy
get Embedded policy for the scope. Read-only. The embedded policy attribute gets its value from the scope-policy command.
failover set= get unset
Controls whether the scope should participate in failover, with three possible values:
• scope-enabled
• scope-disabled
• use-server-settings (default)
See the “Failover Attribute States” section on page 2-109. Optional, default is use-server-settings (dhcp enable/disable failover).
failover-backup- percentage
set= get unset
Percentage of available addresses that the main server should send to the backup server. If defined for a scope, you must define it for the scope in the main server. If defined in a backup server, it is ignored (to enable copying of configurations). The value overrides the server values for failover-backup-percentage and failover-dynamic-bootp-backup- percentage, and the value defined here is used for this scope, whether or not this scope supports dynamic-bootp. If defined as zero (0), no addresses go to the backup server. Because zero is a significant value, once defined, you must unset this attribute for the scope to use the server default values for failover-backup-percentage or failover-dynamic-bootp-backup-percentage. Optional, no default.
failover-backup-server
set= get unset
String representing the DNS name of the backup server associated with this LAN segment. If the DNS name resolves to the IP address of the current server, then this server operates as the backup server for this scope. It is an error if the names of both the main and backup server resolve to the IP addresses that reside on the same server. If the failover- main-server is set to “local” or is not configured on this scope or in the server-wide default, this server is considered to be the main server for the scope. Optional, no default.
failover-main- server
set= get unset
String representing the DNS name of the main server associated with this LAN segment. If the DNS name resolves to the IP address of the current server, then this server operates as the main server for this scope. It is an error if the names of both the main and backup server resolve to the IP addresses that reside on the same server. If you do not configure the backup server on this scope or in the server-wide default, then this server is the main server for this scope. If the failover-backup-server is set to “local” or is not configured on this scope or in the server-wide default, this server is considered to be the main server for the scope. Optional, no default.
Table 2-24 scope Command Attributes (continued)
Attribute Usage Description
2-106Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsscope
mask set= get unset
Subnet mask associated with the scope’s network address. Optional, no default.
namespace set= get unset
Namespace in which the addresses in the scope reside. You must define the namespace using the namespace name create namespace-id command. See the “namespace” section on page 2-84. Network Registrar actually uses the namespace-id value. If unset, the global namespace is used. Optional, default is to use the current namespace as set by the session set current-namespace command, or, if undefined there, the global namespace.
namespace-id set= get unset
ID of the namespace in which the addresses in the scope reside. An alternative to specifying the namespace attribute. See the namespace attribute for details. If unset, the ID of the global namespace is used. Optional, default is the current namespace.
ping-clients enable disable unset
Controls whether the server should attempt to ping an address. If enabled, also indicate a ping timeout. Optional, default disable.
ping-timeout set= get unset
The number of milliseconds that the DHCP server should wait for ping responses. If you make this value too large, you slow down the lease offering process. If you make this value too small, you reduce the effectiveness of pinging addresses before offering them. Three hundred milliseconds is a frequent compromise. Optional, default 300 ms.
policy set= get unset
Name of the policy associated with the scope. Required, default is default policy. This means that the scope uses all the properties set in the default policy (including the lease time), unless specifically reset.
primary-addr get IP address of the primary scope for a secondary scope. Read-only.
primary-mask get Subnet mask of a secondary scope’s primary scope. Read-only.
primary-scope set= get unset
Primary scope for a secondary scope. Setting the value of the primary-scope attribute on a scope designates the scope as being secondary to another scope. You must specify a primary scope if you have multiple logical subnets on the same physical network segment and if you allow DHCP to offer addresses from any of the subnets. To remove the status of secondary from the scope (that is, promote it to being a primary scope), you must unset the primary-scope attribute. Optional, no default.
renew-only enable disable unset
Controls whether to allow existing clients to re-acquire their leases, but not to offer any leases to new clients. Note that a renew-only scope does not change the client associated with any of its leases, other than to allow a client currently using an available IP address to continue to use it. Optional, no default.
selection-tags set= get unset
Comma-separated list of selection criteria associated with a scope. The scope compares a client’s selection criteria to this list to determine whether the client can obtain a lease from the scope. Optional, no default.
Table 2-24 scope Command Attributes (continued)
Attribute Usage Description
2-107Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsscope
synthesize-name enable disable unset
Controls whether the DHCP server automatically creates DNS hostnames for DHCP clients who do not provide them. The server can synthesize unique names for clients based on the synthetic-name-stem attribute. Optional, default disable.
synthetic-name-stem
set= get unset
Prefix of the default hostname to use if clients do not supply hostnames. Optional, no default.
trap-free- address-high
enable disable unset
Controls whether you set a trap on the scope to alert you when the number of free addresses gets high. When a scope is created, the trap-free-address-high attribute is enabled. Also, the trap-free-address-low, trap-free-address-low-threshold and trap-free-address-high-threshold attributes are undefined. See the “trap” section on page 2-127. See also the trap-free-address-high-threshold attribute. Optional, default enable.
trap-free- address-high- threshold
set= get unset
Number or percentage threshold for the free-address trap on this scope. Percentages must be followed by a (%) sign.The high threshold must be greater than or equal to the low threshold. See the “trap” section on page 2-127. See also the trap-free-address-high attribute. Optional, no default.
trap-free- address-low
enable disable unset
Controls whether you set a trap on the scope to alert you when the number of free addresses gets low. See the “trap” section on page 2-127. See also the trap-free-address-low-threshold attribute. Optional, no default.
trap-free- address-low- threshold
set= get unset
Number or percentage threshold for the free-address trap on this scope. Percentages must be followed by a (%) sign. The low threshold must be less than or equal to the high threshold. See the “trap” section on page 2-127. See also the trap-free-address-low attribute. Optional, no default.
trap-free- address-reset
set= get unset
Number or percentage, followed by a (%) sign, of the reset value for the free-address trap on this scope. See the “trap” section on page 2-127. Optional, no default.
update-dns-first enable disable unset
Controls whether the DNS server is updated before the lease is granted. Optional, default disable.
update-dns-for- bootp
enable disable unset
If the server replies to a BOOTP request and offers a lease from a scope that is configured to perform DNS updates, it checks this attribute before beginning the DNS update. This attribute prevents DNS updates for BOOTP clients while allowing updates for DHCP clients. You can also control this attribute globally using the dhcp enable/disable update-dns-for-bootp command, but the scope setting overrides it. Optional, no default.
use-dns-update-prereqs
enable disable unset
By default, the DHCP server uses prerequisites in its DNS update messages when it is performing DNS updates on behalf of clients. If disabled, the server does not include prerequisites. Without them, the server associates the last client who uses a given domain name with that name, even if another client was already associated with it. The scope setting overrides the DHCP server setting. Optional, default enable.
Table 2-24 scope Command Attributes (continued)
Attribute Usage Description
2-108Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsscope
Usage Guidelines Changing the Mask of a Scope
The changemask action:
• Changes the mask on the specified scope.
• Changes the primary-mask attribute on any secondary scopes to the newly specified scope.
• Iterates over all reservations in the scope and displays any that now fall outside the scope. If reservations fall outside the scope, the command returns “101, Ok with warnings” instead of “100 Ok.”
• Iterates over all ranges in the scope and displays any that have endpoints that now fall outside the scope. If range endpoints fall outside the scope, the command returns “101, Ok with warnings” instead of “100 Ok.”
• When you next reload the DHCP server, deletes existing leases that fall outside the acceptable ranges for this scope and are not in the acceptable ranges of any other scope.
Failover Attribute States
The failover attribute has three possible states:
• scope-enabled—Indicates that this scope, and all scopes that are secondary to it or to which it is a secondary on this LAN segment, are enabled for failover. Scope parameters (not server parameters) should determine the main and backup servers.
If more than one scope on the same LAN segment is scope-enabled for failover, then the main and backup servers must be identical for each. An error occurs if one scope on a LAN segment is scope-enabled and another is scope-disabled, unless the other scope has failover enabled server-wide.
• scope-disabled—Disables a scope and all other scopes associated with it on a LAN segment from participating in failover. It only has meaning if failover is defined server-wide.
• use-server-settings—Indicates that this scope should use the settings for main and backup servers unless another scope associated with it on a LAN segment is either explicitly scope-enabled or scope-disabled. If one scope on a LAN segment is scope-enabled or scope-disabled, it overrides any scope for which use-server-settings is set on that LAN segment.
Note If you set the scope attribute failover-backup-percentage explicitly, Network Registrar uses it, even if the value of the failover attribute is use-server-settings.
Related Commands admin, client-class, client-class-policy, client-policy, dhcp, policy, scope-policy, scope-selection-tag
2-109Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsscope-policy
scope-policyThe scope-policy command configures DHCP embedded policies for scopes. A scope-policy is a policy object embedded within (and limited to) a scope object. Each scope may contain option data within its embedded policy, and may refer to a named policy with more option data, such as a router IP address.
The DHCP server implicitly creates and deletes embedded scope-policies when you create or delete the corresponding scopes. You manipulate the scope-policy using the name of the corresponding scope.
For the syntax and descriptions, see the policy command.
Attributes See Table 2-19 on page 2-92 in the policy command section for the attribute descriptions.
Usage Guidelines scope-policy Reply Options
When the server is getting ready to return option data to a client, it examines up to seven policies. See the “Policy Reply Options” section on page 2-94.
Lease Times
A scope policy contains two lease times—the client lease time and the server lease time. The server controls these the same as with the policy command. See the “Lease Times” section on page 2-95.
Specifying Arrays in Vendor Specific Options
The scope-policy command accepts data in vendor-specific options in the same way as the policy command. See the “Specifying Arrays in Vendor-Specific Options” section on page 2-95.
Related Commands client-policy, client-class, client-class-policy, policy, scope
2-110Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsscope-selection-tag
scope-selection-tagThe scope-selection-tag command defines the tags that you add for the scope selection criteria for scopes, clients, and client-classes.
scope-selection-tag name create
scope-selection-tag name delete
scope-selection-tag list
Syntax Description scope-selection-tag name create
Creates a scope-selection tag.
nrcmd> scope-selection-tag internal create
scope-selection-tag name delete
Deletes a scope-selection tag.
nrcmd> scope-selection-tag internal delete
Note When you delete a tag, Network Registrar removes it from the tag list, but does not remove it from any existing scope, client, or client-class configurations.
scope-selection-tag list
Lists all scope-selection tags.
nrcmd> scope-selection-tag list
Usage Guidelines Inclusion and Exclusion Criteria
When the DHCP server reads a client entry (from the local database or from LDAP), the server checks its scope-selection inclusion and exclusion criteria against the tags defined for the scopes on this network. If the client entry refers to tags that are not present in any scope in the network, the server handles the tags depending on whether the reference is to include or exclude tags. If the reference is for exclusion, the tags have no effect. If the tags are not present and the reference is for inclusion, the server determines that there is no acceptable scope on that network for this client.
Related Commands admin, client-class, client-class-policy, dhcp
2-111Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsserver
serverThe server command affects the behavior of the server. After you use the server command, or any other time you change the server configuration, use the server command or the Network Registrar GUI to reload the server.
Timesaver The server keyword is optional. You can enter all these commands starting with just the server type.
[server] {dns | dhcp | tftp} enable [start-on-reboot]
[server] {dns | dhcp | tftp} disable [start-on-reboot]
[server] {dns | dhcp | tftp} start
[server] {dns | dhcp | tftp} stop
[server] {dns | dhcp | tftp} get version
[server] {dns | dhcp | tftp} getHealth
[server] {dns | dhcp | tftp} getStats
[server] {dns | dhcp | tftp} reload
[server] dhcp getRelatedServers [column-separator=string]
[server] dhcp setPartnerDown partner-server [date]
[server] dhcp updateSms [all]
[server] {dns | dhcp | tftp} serverLogs nlogs=value logsize=value
[server] {dns | dhcp | tftp} serverLogs [show]
Syntax Description The syntax descriptions use the convention {dns | dhcp | tftp} to indicate that you can use the command with the DNS, DHCP, or TFTP servers. There are no attributes other than those specified in the syntax. You can omit the server keyword in each case.
[server] {dns | dhcp | tftp} enable [start-on-reboot]
Enables a server. With the additional start-on-reboot attribute, the AIC Server Agent starts the server when you reboot. You might want to disable this attribute for clusters that provide a single protocol service. By default, the DNS and DHCP servers are enabled, while the TFTP server is disabled, to start on reboot.
[server] {dns | dhcp | tftp} disable [start-on-reboot]
Disables a server or the optional start-on reboot attribute. You might want to disable this attribute for clusters that provide a single protocol service. By default, the DNS and DHCP servers are enabled, while the TFTP server is disabled, to start on reboot.
nrcmd> server DNS disable start-on-reboot
2-112Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsserver
[server] {dns | dhcp | tftp} start
Starts a server (DNS, DHCP, or TFTP).
[server] {dns | dhcp | tftp} stop
Stops a server (DNS, DHCP, or TFTP). Stopping the server does not terminate the server process, but stops it from handling further requests.
[server] {dns | dhcp | tftp} get version
Gets the version number of the server software. Useful when describing version information to the Cisco Technical Assistance Center (TAC).
[server] {dns | dhcp | tftp} getHealth
Gets the current health of a server. A return of 0 indicates that the server is not running. Values of 1 through 10 indicate how well the server is running. A value of 10 indicates the highest health, and 0 indicates that the server is not running. The DNS and TFTP server return values of either 10 or 0 only. If there is an incremental drop in the server health value, look at the log files for the particular server as the best indication of health.
[server] {dns | dhcp | tftp} getStats
Gets a server’s current statistics.
[server] {dns | dhcp | tftp} reload
Stops and immediately restarts the server. When the server restarts, it rereads all of its configuration information and its previously saved state information and then begins operating.
[server] dhcp getRelatedServers [column-separator=string]
Gets the status of the connection between the DHCP server and its DNS, LDAP, or failover servers. You can optionally specify that the report use string for separating columns. See the “Getting Related Servers” section on page 2-114.
[server] dhcp setPartnerDown partner-server [date]
Notifies the DHCP server that its partner DHCP server is down and moves all appropriate scopes into the PARTNER-DOWN state. Optionally, you can specify the date and time when the partner was last known to operate. The default is the current date. See the “Setting Partner Down” section on page 2-114.
Caution Ensure that the partner server is really down before issuing the setPartnerDown keyword.
[server] dhcp updateSms [all]
Causes the DHCP server to perform System Management Server (SMS) network discovery. Optionally, including all sends out all leased addresses from the DHCP server to SMS. If you do not include this parameter, the server sends only those addresses leased since the last time you used this command. See the “Updating the System Management Server” section on page 2-115.
[server] {dns | dhcp | tftp} serverLogs nlogs=value logsize=value
Sets or changes nlogs, the number of server logs, and logsize, the size of the server logs in bytes for a server. Valid values for nlogs are 2 through 100. The value of logsize is in bytes, and the optional K and M suffixes scale the specified value by 1000 or 1,000,000, respectively. Valid values for logsize are 10000 through 500000000 (or 10K through 500M) bytes. The following example sets the
2-113Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsserver
DNS server to generate up to seven log files of five million bytes each. Restart the AIC Server Agent for the changes to take effect.
nrcmd> server dns serverLogs nlogs=7 logsize=5M nrcmd> exit (UNIX)> /etc/init.d/aicservagt start (Windows)> net start "AIC Server Agent 2.0"
[server] {dns | dhcp | tftp} serverLogs [show]
Displays the number and size of log files.
Usage Guidelines Getting Related Servers
The getRelatedServers command allows you to create a report on the connection status of the other servers associated with this DHCP server. Network Registrar displays information for DNS, LDAP, and failover-associated DHCP servers sorted by type, name, and IP address. Table 2-25 describes the report output.
Setting Partner Down
The setPartnerDown command allows you to notify a DHCP server that a failover server associated with the DHCP server is down. When you run the setPartnerDown command, all of the scopes in this server that run failover with the partner server move into PARTNER-DOWN state.
Caution Ensure that the partner server is really down before issuing the setPartnerDown command.
You can specify a value on this command to shorten the waiting period associated with entering PARTNER-DOWN state. Network Registrar cannot allocate IP addresses that were available in the partner server to different DHCP clients until a waiting period equal to the maximum client lead time (MCLT) passed. See the failover-maximum-client-lead-time attribute in Table 2-5 on page 2-22.
Table 2-25 getRelatedServers Report
Column Description
Address IP address in dotted octet format.
Communications OK or INTERRUPTED. Information about DHCP and DNS servers that a DHCP server tried to update.
localhost State Failover state of this server or two dashes (--).
Name DNS hostname.
Partner State Failover state of the associated failover server or two dashes (--).
Requests Number of outstanding requests, or the failover recovery or DNS update status. In the failover RECOVER state, the Requests column shows the Percent of Failover Recovery yet-to-complete value, starting with 100 at the beginning of the recovery and decreasing to zero, when the partners are again in synch. If the server is in the failover NORMAL state, you can use the dhcp set log-settings=failover-detail command to show the Percent of Failover Bind-Update yet-to-complete value (the percent of configured leases not yet scanned) in the Requests column.
Type Main, Backup, DNS, or LDAP.
2-114Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsserver
When you use the setPartnerDown command, you can specify a date and time that are equal to or later than the last known date and time the partner server could have been operational. If you do not specify a value, Network Registrar uses the current date and time. The following example notifies the backup server that its main server is down.
nrcmd> server dhcp setPartnerDown main.mycompany.com
There are two conventions for specifying the date:
• Specify the date as –num unit (a time in the past), where num is a decimal number and unit is s, m, h, d, or w for seconds, minutes, hours, days or weeks respectively. For example, specify -3d for three days.
• Specify the date as month (name or its first three letters), day, hour (24-hour convention), year (fully specified year or last two digits). The following example notifies the backup server that its main server went down at 12 midnight on October 31, 2002.
nrcmd> server dhcp setPartnerDown main.mycompany.com Oct 31 00:00:00 2002
Note Wherever you specify a date and time using the nrcmd command, you should enter the time that is local to the nrcmd process. This means that, if the server is running in different time zone than your nrcmd process, you should disregard the timezone where the server is running and use local time instead.
Updating the System Management Server
When using the updateSms keyword, you must first set dhcp set sms-network-discovery=0 and set the sms-library-path and sms-site-code attributes. If you reload the DHCP server when updateSms is processing, it stops processing, and does not resume after the DHCP server comes back up again.
To use the updateSms command on Windows (NT and 2000), turn on “This Account” in the Startup tab of AIC Server Agent 2.0. Then, provide the name of the administrator account of the domain and the corresponding password, and start the services.
Related Commands dns, dhcp, tftp
2-115Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandssession
session The session command sets session control parameters on your CLI command session.
The session assert functionality allows a nrcmd batch script to assert that a given condition is true. If the condition is true, the command has no effect, but if it is not true, the nrcmd exits at that point. Some uses for the session assert functionality are to ensure that the nrcmd session has an exclusive lock on the Network Registrar database, or to ensure that server configuration data has or has not changed since a previous point.
session set default-format=user | script
session set current-namespace=name
session unset current-namespace
session set visibility={5 | 3 | 1}
session get {cluster | default-format | user-name | visibility}
session [show]
session assert server.dbsn == server-version-minor-serial-number
session assert server.dbsn != server-version-minor-serial-number
session assert locked
Syntax Description session set default-format=user | script
Sets the default format for the CLI session, either user or script:
• user—Show objects in a user-readable format, one attribute per line (the default)
• script—Show objects in script-suitable format, one object per line
The default is user format. The following example sets the output for script processing.
nrcmd> session set default-format=script
session set current-namespace=name
Sets the namespace for the session. Use this command to set the default namespace when there is a namespace expected for a CLI command, but that command does not have an explicit entry for the namespace, you cannot explicitly enter it for the command. If you do not use this command, Network Registrar uses the global namespace.The namespace value can either be a namespace name or its ID. Network Registrar reserves the namespace values all (refers to all namespaces, including global) and global (there is no namespace associated with the DHCP server objects). If the string matches an already defined namespace name, Network Registrar considers it a namespace name. Otherwise, Network Registrar considers it a namespace ID and the CLI tries to convert it into a namespace ID number. See the “namespace” section on page 2-84.
session unset current-namespace
Equivalent of the session set current-namespace="" command.
2-116Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandssession
session set visibility={5 | 3 | 1}
Sets the session visibility, or what verbosity of attributes you can set or display for the session. A value of 1 gives the highest visibility. The default session visibility is 5. You cannot unset the visibility attribute.
Caution Do not change the default session visibility of 5 unless directed to do so by the Cisco Technical Assistance Center (TAC).
session get {cluster | default-format | user-name | visibility}
Displays the cluster, default format, username, or visibility for the session.
session [show]
Shows the values of all attributes assigned to the CLI session.
session assert server.dbsn == server-version-minor-serial-number
Asserts that a specific server's configuration data has not changed. This is usually used by an external process that is maintaining a cache of the Network Registrar server configuration data and wants to discover if the cache is no longer valid. See the “Session Asserts” section on page 2-117.
nrcmd>session assert dhcp.dbsn == 42
session assert server.dbsn != server-version-minor-serial-number
Asserts that a specific server's configuration data has changed. Scripts use this command to get updates on changes to the Network Registrar server configuration data.
nrcmd>session assert dhcp.dbsn != 42
The following script emits the list of scopes, and the new DHCP server dbsn value only if the dbsn value changes from 110. It assumes that the output from this script will be parsed by an external process that is trying to keep the list of scopes up to date with Network Registrar. See the “Session Asserts” section on page 2-117.
session assert dhcp.dbsn != 110
session assert locked
Use this command before any CLI commands that require a lock on the session. If any of the commands that follow require a lock, the CLI session exits. See the “Session Asserts” section on page 2-117.
Usage Guidelines Session Asserts
The session assert commands can simplify interactions with external data management processes, and help in writing multi command batch scripts that stop processing if an asserted precondition fails. You generally use these commands with the script default-format, and possibly at a lower session visibility level. If the assertion passes, a “100 Ok” message appears. If it fails, a “107 Assertion Failed dhcp.dbsn (minor-serial-number) = value” message appears and the CLI exits.
The session assert locked command exits the CLI if it cannot lock the session. The following is a sample script for performing batch operations that require a lock.
nrcmd> session set default-format=script nrcmd> session assert locked nrcmd> commands-that-require-a-lock
2-117Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandssession
The session assert dhcp.dbsn commands exit the CLI session if the minor serial number for the DHCP server does not match (==) or does not exceed (!=) the value given. The minor serial number is incremented with each configuration change. Get its value using the dhcp get dbsn command. See the “dhcp” section on page 2-20. The following is a sample script for modifying a DHCP server based on configuration version 1234.
nrcmd> session set default-format=script nrcmd> dhcp get dbsn nrcmd> session assert dhcp.dbsn == 1234 nrcmd> scope scope-name create ipaddr mask policy=policy-name nrcmd> scope scope-name addRange start-ipaddr end-ipaddr
The following is a sample script for displaying DHCP configuration changes since version 1234.
nrcmd> session set default-format=script nrcmd> session assert dhcp.dbsn != 1234 nrcmd> scope list nrcmd> policy list nrcmd> client-class list
2-118Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandssubnet
subnetUse the subnet command to view and manipulate the current DHCP subnets the server creates with the address-block command. All subnet command actions take effect immediately. The ipaddress value can be a simple IP address or can include the namespace in the syntax namespacename/ipaddress. See the “namespace” section on page 2-84. You do not need to reload the server.
subnet ipaddress/mask activate
subnet ipaddress/mask deactivate
subnet ipaddress/mask force-available
subnet ipaddress/mask get attribute
subnet ipaddress/mask [show]
subnet list
Syntax Description See Table 2-26 on page 2-120 for the subnet command attributes and their descriptions.
subnet ipaddress/mask activate
Activates a subnet, but does not change the status of a subnet marked as unavailable. The ipaddress/mask value can include the namespace, in the following slash-separated format:
namespacename/ipaddress/mask
If there is no namespace prefix for the address, the value set by the session set current-namespace applies. See the “session” section on page 2-116.
nrcmd> subnet 192.168.1.9 activate
subnet ipaddress/mask deactivate
De-activates a subnet from being given out or renewed, but does not change the state of the subnet.
subnet ipaddress/mask force-available
Makes a currently held subnet available, even a subnet marked as unavailable. Because using the force-available action may compromise the integrity of your IP address allocations, ensure that before you use this command, the client assigned the subnet is no longer using it.
subnet ipaddress/mask get attribute
Gets the value of an attribute for a subnet. See Table 2-15 on page 2-72.
subnet ipaddress/mask [show]
Shows the subnet attributes for a specific address.
subnet list
Lists all the subnets.
Attributes Table 2-26 describes the subnet command attributes and their values. They are all read-only attributes.
2-119Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandssubnet
Related Commands address-block, namespace
Table 2-26 subnet Command Attributes
Attribute Usage Description
client-domain-name get Domain name that the client specifies in its messages (if any).
client-flags get The client-id-created-from-mac-address flag indicates that the client-id was created for internal use from the client’s MAC address. Optional, no default.
client-host-name get Hostname that the client specifies (if any).
client-id get Client ID of the subnet’s client. Optional, no default.
client-last- transaction-time
get Time that the client most recently contacted the DHCP server. Optional, no default.
client-mac-addr get MAC address that the client presents to the DHCP server. Optional, no default.
expiration get Expiration time of the subnet’s binding. Optional, no default.
high-water get Highest utilization level recorded since the last statistics. Optional, no default.
in-use-addresses get Number of addresses that the client currently uses. Optional, no default.
last-transaction- time
get The time at which the client last communicated with the server about the subnet. Optional, no default.
namespace-id get ID of the namespace that contains the subnet. Optional, no default.
relay-agent-option get Contents of the relay agent information option from the most recent client interaction. Optional, no default.
selection-tags get The selection-tag string that the client presented when it last leased or renewed the subnet binding.
2-120Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandstftp
tftpThe tftp command enables or disables TFTP server attributes. Because there is only one TFTP server per cluster within Network Registrar, you do not need to refer to the server by name.
tftp enable attribute
tftp disable attribute
tftp set attribute=value [attribute=value…]
tftp unset attribute
tftp get attribute
tftp [show]
tftp setTraceLevel value
tftp getTraceLevel
tftp reload
Note See also the “server” section on page 2-112 for other server control commands.
Syntax Description See Table 2-27 on page 2-122 for the tftp command attributes and their descriptions.
tftp enable attribute
Enables a TFTP server attribute. See Table 2-27 for the attributes with a usage of enable or disable.
nrcmd> tftp enable file-caching
tftp disable attribute
Disables a TFTP server attribute.
tftp set attribute=value [attribute=value…]
Sets one or more attributes of the TFTP server. See Table 2-27 for the attributes with a usage of set. The following command example enables caching:
nrcmd> tftp set file-cache-directory="CacheDir"
Note that if you use this command, you must set the cache directory and reload the server:
nrcmd> tftp set file-cache-directory="CacheDir" nrcmd> tftp reload
If file-caching is enabled, but file-cache-directory is not set, no files are cached. Also, if file-cache-directory is set, but file-caching is disabled, the files in the file-cache-directory are still accessible to clients, through normal methods, but are not cached.
tftp unset attribute
Unsets the value of an attribute of the TFTP server. You cannot unset required attributes.
2-121Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandstftp
tftp get attribute
Gets the value of an attribute for the TFTP server.
tftp [show]
Shows the TFTP server attributes.
tftp setTraceLevel value
Specifies the level of tracing that the TFTP server uses. Trace output is written to the file_tftp_1_log file in the server logs directory. Trace statements go to the file_tftp_1_log on Windows NT and to the file_tftp_1_trace file on Solaris. Each integer value from 0 through 4 enables another cumulative trace level:
• 0—Disables all server tracing (default).
• 1—Displays all server log messages in the trace file.
• 2—Also displays the client IP address and port for all TFTP packets.
• 3—Also displays header information for all TFTP packets.
• 4—Also displays the first 32 bytes of TFTP packet data.
Note Only enable packet tracing if the Cisco TAC instructs you to. Tracing has significant impact on the performance level of the server. Also, do not enable packet tracing for long periods of time.
tftp getTraceLevel
Reports the trace level that the TFTP server is currently using. Use this command only when investigating server problems.
tftp reload
Reloads the TFTP server and updates the files in cache.
nrcmd> tftp reload
Attributes Table 2-27 describes the tftp command attributes and their values and defaults, if any.
Table 2-27 tftp Command Attributes
Attribute Usage Description
active-directory- domain
set= get
Name of an active directory domain that the TFTP server uses to provide dynamic configuration file support. Required, no default.
csrc- configuration-file
set= get
Path to a configuration file the TFTP server uses when loading the Cisco Subscriber Registration Center (CSRC) version 1.0 library. The TFTP server can then generate dynamic DOCSIS modem configuration files. The location of the CSRC configuration file is typically /CSRC_INSTALL_DIR/conf/csrc.cfg. Required, no default.
default-device set= get
Name of the default disk device the TFTP server uses when none is specified in the pathname contained in the TFTP request. This attribute is designed for use on Windows to specify a default drive letter. Required, no default.
2-122Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandstftp
docsis-access enable disable
How the TFTP server should respond to dynamic DOCSIS file requests from TFTP clients. Relevant for users of CSRC 1.0 only. If this attribute is disabled, the TFTP server refuses dynamic DOCSIS file requests and sends an access violation error to the client. Required, default disable.
docsis-file- logging
enable disable
Whether the TFTP server should log generated DOCSIS files to disk. Relevant for users of CSRC 1.0 only. If this attribute is enabled, the TFTP server logs each generated DOCSIS configuration file to a tftp subdirectory within the server logs directory. Relevant for users of CSRC 1.0 only. Required, default disable.
docsis-log-file- count
set= get
Maximum number of DOCSIS configuration log files that the TFTP server maintains in the TFTP subdirectory within the server logs directory. Relevant for users of CSRC 1.0 only. Once this limit is reached, the TFTP server removes one DOCSIS log file for each new log file it creates. Required, default 100 log files.
docsis-pathname- prefix
set= get
Pathname prefix that the TFTP server recognizes as the trigger to create a DOCSIS configuration file. Relevant for users of CSRC 1.0 only. This prefix must match the one that the DHCP server is using to generate the DOCSIS filename that DHCP sends to the TFTP client. Required, default /docsis.
file-cache- directory
set= get
Path to an existing directory where the TFTP server finds the files to put into cache, if enabled by the file-cache attribute. The server loads all these files on startup and on reloading, up to the maximum set by the file-cache-max-memory-size attribute. Use absolute pathnames only. Network Registrar does not cache any files in this directory’s subdirectories. Required, no default, but the value is appended to the home directory path, as set by the home-directory attribute.
file-cache enable disable
Determines whether the TFTP server should perform file caching on files located in the directory that the file-cache-directory attribute specifies. File caching allows the server to run faster by loading the files into memory, up to the maximum set by the file-cache-max-memory size attribute. Upon reload, Network Registrar logs the name of each cached file, and skips any files it cannot load. It reads in all files as binary data and translates them as the TFTP client requests. Writing directly to cache is not allowed. Required, default disable.
file-cache-max- memory-size
set= get unset
Maximum memory size, in bytes, of the file cache. Network Registrar loads all files into cache that cumulatively fit this memory size. If set to 0, Network Registrar does not cache any data, even if you enable file caching. Required, default 32000 bytes.
home-directory set= get
Path to a home directory that the TFTP server uses to resolve TFTP requests. With the use-home-directory-as-root attribute disabled, Network Registrar uses the value of the home-directory attribute plus the paths specified in the search-list to resolve requests. Required, default is the /data/tftp subdirectory of the installation directory.
initial-packet- timeout
set= get
Initial time that the TFTP server waits after sending a response to a client before declaring that response timed-out and sending a retransmission to the client. Required, default 5 seconds.
Table 2-27 tftp Command Attributes (continued)
Attribute Usage Description
2-123Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandstftp
ldap-host-name set= get
Hostname or IP address of an LDAP server that the TFTP server uses to provide dynamic configuration file support. Relevant for users of CSRC 1.0 only. Required, default localhost.
ldap-initial- timeout
set= get
Initial time the TFTP server waits after sending a request to an LDAP server before declaring that request timed-out and sending a retransmission to the server. Relevant for users of CSRC 1.0 only. Required, default 10 seconds.
ldap-maximum- timeout
set= get
Maximum time that the TFTP server waits after transmitting the initial LDAP request before giving up retrying on that request. Relevant for users of CSRC 1.0 only. Required, default 60 seconds.
ldap-password set= get
Password that the TFTP server uses when connecting to an LDAP server. Relevant for users of CSRC 1.0 only. Required, no default.
ldap-port-number set= get
Port number that the TFTP server uses when communicating with an LDAP server. Relevant for users of CSRC 1.0 only. Required, default port 389.
ldap-root-dn set= get
Root distinguished name that the TFTP server uses to locate the root of the directory tree for dynamic configuration file support. Relevant for users of CSRC 1.0 only. Required, no default.
ldap-user-name set= get
Username of the TFTP server when connecting to an LDAP server. Relevant for users of CSRC 1.0 only. Required, no default.
ldap-use-ssl enable disable
Controls whether the TFTP server uses SSL when communicating with an LDAP server. Relevant for users of CSRC 1.0 only. If this attribute is disabled, the TFTP server does not use SSL when communicating with LDAP. Required, default disable.
log-file-count set= get
Number of log files that the TFTP server maintains in the server logs directory. Required, default 4 files.
log-file-size set= get
Size of each log file that the TFTP server maintains in the server logs directory. Required, default 1024 KB.
log-level set= get
Level of verbosity that the TFTP server employs when writing log messages to the TFTP server log file. Required, default level 3. Each integer value from zero through four enables the following cumulative log levels:
• 0—None: no log messages written.
• 1—Error: present condition inhibits the TFTP server operation, such as there is no LDAP server.
• 2—Warning: present condition can cause operational problems, such as connection timeouts. Also includes errors.
• 3—Information: provides normal server informational messages (default). Also includes warnings and errors.
• 4—Activity: normal server operation, such as client requests and replies. Also includes information, warnings, and errors.
Maintain the log level attribute at the default of information.
Table 2-27 tftp Command Attributes (continued)
Attribute Usage Description
2-124Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandstftp
log-settings set= get
The TFTP server allows control over additional details about the events listed in the log-settings.The additional detail can be very helpful when analyzing a problem, but can cause the log files to fill up quickly (and therefore to turn over frequently, possibly losing important information) if left enabled for a long period of time. Optional, default is default. The possible flags are:
• default—Causes the logging in the server to be active. Success messages print to the log for each successful transfer.
• no-success-messages—Causes the single line message that is normally logged for every successful read from the TFTP server to not appear. Affects logging only for successful file reads from the TFTP server.
max-inbound- file-size
set= get
Maximum file size that limit the TFTP server enforces for a file written to the TFTP server. Required, default 1024 KB.
min-socket- buffer-size
set= get
Minimum socket buffer size that the TFTP server uses for the well known port on which it is listening for TFTP requests. Required, default 65536 buffers.
packet-trace-level set= get
Specifies the level of verbosity that the TFTP server employs when writing messages to the server trace file. Each integer value from 1 through 4 enables increasing levels of tracing. Setting packet trace level to 0 disables tracing. Required, default 0 (disabled).
port-number set= get
UDP port number that the TFTP server uses to listen for TFTP requests. Required, default port 69.
read-access enable disable
How the TFTP server should respond to file read requests from TFTP clients. If this attribute is disabled, the TFTP server refuses file read requests and sends an access violation error to the client. Required, default enable.
search-list set= get
Comma-separated list of paths that the TFTP server uses to resolve TFTP requests. If you enable use-home-directory-as-root, the server ignores the paths in the search list and uses the home directory to resolve all TFTP requests. Required, no default.
session-timeout set= get
Maximum length of time that the TFTP server waits after transmitting the initial response before giving up retrying on that response. If no response is received from the client within this timeout period, the TFTP session is terminated. Required, default 60 seconds.
use-home- directory-as-root
enable disable
Whether the TFTP server treats pathnames contained in TFTP requests as if the paths were rooted at the specified home directory. If this attribute is enabled, the TFTP server attempts to resolve both absolute and relative pathnames to paths located beneath the specified home directory. Required, default disable.
Table 2-27 tftp Command Attributes (continued)
Attribute Usage Description
2-125Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandstftp
Related Commands server
write-access enable disable
How the TFTP server should respond to file write requests from TFTP clients. If this attribute is disabled, the TFTP server refuses file write requests and sends an access violation error to the client. Required, default disable. Limitations—If enabled, the client can only write to a file that already exists on the server. The max-inbound-file-size attribute dictates the incoming file size.
Table 2-27 tftp Command Attributes (continued)
Attribute Usage Description
2-126Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandstrap
trapThe trap command enables or disables Simple Network Management Protocol (SNMP) traps. You can use traps to warn of error conditions and possible problems with the Network Registrar DNS, DHCP, or TFTP servers. These conditions include depleting the DHCP server scope address pools and communication loss with other servers.
trap enable trap
trap disable trap
trap set {free-address-low-threshold=value | free-address-high-threshold=value}
trap unset {free-address-low-threshold | free-address-high-threshold}
trap get {free-address-low-threshold | free-address-high-threshold}
trap [show]
trap addRecipient recipient host [community] [port]
trap removeRecipient recipient
trap listRecipients
Syntax Description trap enable trap
Activates a trap. See Table 2-28 on page 2-128 for the traps and their corresponding SNMP notification names. The default trap name is trap.
trap disable trap
De-activates a trap.
trap set {free-address-low-threshold=value | free-address-high-threshold=value}
Sets either or both of the two free address threshold attributes. In both cases, the valid values are digits and optionally a single trailing percent (%) character; the integer range is 0 through 2147483647 and percentages must be 0 through 100:
• free-address-low-threshold—Threshold value for the free-address-low trap; default is 20%
• free-address-high-threshold—Reset value for the free-address trap; default is 20%
See the “Free Address Traps” section on page 2-129 for restrictions. The following example sets the free-address-low-threshold to 12 percent and the free-address-high-threshold to 22 percent.
nrcmd> trap set free-address-low-threshold=12% nrcmd> trap set free-address-high-threshold=22%
trap unset {free-address-low-threshold | free-address-high-threshold}
Unsets the values of one of the free address threshold attributes.
trap get {free-address-low-threshold | free-address-high-threshold}
Gets the value of the free address threshold.
2-127Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandstrap
trap [show]
Shows the values of the free address thresholds. See the “Free Address Traps” section on page 2-129.
trap addRecipient recipient host [community] [port]
Adds the trap recipient to the cluster’s trap recipient list. The Network Registrar servers reference the trap recipients through aliases to allow multiple recipients at the same address, but at different ports. The attributes are as follows:
• recipient—Required unique (cluster-wide) identifier for the recipient
• host—Required string representation of the hostname or IP address of the recipient platform
• community—Optional community string that you can specify as part of the trap PDU for authentication purposes (the default community string is public)
• port—Optional port to which Network Registrar directs the trap (default is 162)
trap removeRecipient recipient
Removes a trap recipient from the cluster’s trap recipient list. You can delete a trap recipient from the list, but you cannot modify the recipients.
trap listRecipients
Lists all the trap recipients in the cluster’s trap recipient list and their attributes.
Traps Table 2-28 describes the traps and their corresponding SNMP notification names. All the traps are initially enabled by default. See also the “Free Address Traps” section on page 2-129.
Table 2-28 trap Command Traps
Trap SNMP Notification Detects or Determines
address-conflict ciscoNetRegAddressConflict Address conflict with another server
dhcp-failover-config- mismatch
ciscoNetRegFailover ConfigurationMismatch
Configuration mismatch with a DHCP failover peer
dns-queue-too-big ciscoNetRegDNSQueueToo Big
DHCP server’s queue of DNS messages is too large
duplicate-address ciscoNetRegDuplicateAddress Duplicate IP address
free-address-high ciscoNetRegFreeAddressHigh Free IP address count is no longer too low (default 20%)
free-address-low ciscoNetRegFreeAddressLow Free IP address count is too low (default 20%)
other-server-not- responding
ciscoNetRegOtherServerNot Responding
Another server is not responding
other-server- responding
ciscoNetRegOtherServer Responding
Another server is responding
server-start ciscoNetRegServerStart Server is started
server-stop ciscoNetRegServerStop Server is stopped
2-128Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandstrap
Usage Guidelines Free Address Traps
The free-address traps catch when the number of free IP addresses on a server falls below a certain threshold, and when to notify that they again move out of this area. You arm the traps using the trap enable free-address-low and trap enable free-address-high commands. You set the thresholds for each using the trap set free-address-low-threshold and trap set free-address-high-threshold commands, respectively. You set the low and high threshold values either by an absolute number, or by a percentage (followed by the percent sign). You must use the same unit of measure for both thresholds; for example, if the low threshold value is a percentage, the high threshold value must be as well. The free-address-low trap catches when the free addresses fall below the low threshold. The free-address-high trap catches when they are no longer too low. The high value must be equal to or greater than the low one. Both values default to 20 percent. These traps, like all others, apply on a server and not a scope by scope basis.
You generally set the low and high thresholds at a certain offset. For example, you can set the low value to 20%, in which case the DHCP server catches when the number of free addresses fall below 20%. You can then set the high threshold to 25% so that you get a notification at a slightly higher point that the addresses have again become free. As soon as the DHCP server issues a trap for one threshold condition, it arms the trap for the opposite condition. Because of this, creating a safety zone between the two thresholds eliminates issuing traps each time the free addresses hover close to and keep crossing the low threshold point.
Even if you disable one trap through the trap disable command, Network Registrar still sends its opposite as needed.
2-129Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsvendor-option
vendor-optionThe vendor-option command defines the option data format for vendor-specific options (DHCP option 43) as required to accommodate devices from a variety of vendors. You can:
• Create a vendor-specific option by name and associate it with a class-identifier string (option 60).
• Specify suboptions 1 through 255 in each vendor-specific option.
vendor-option name create vendor-class-id
vendor-option name delete
vendor-option name enable read-only
vendor-option name disable read-only
vendor-option name defineSuboption suboption number datatype [flags]
vendor-option name undefineSuboption suboption
vendor-option name listSuboptions
vendor-option name [show]
vendor-option list
vendor-option listnames
Syntax Description vendor-option name create vendor-class-id
Creates a vendor option and assigns the class-identifier string (DHCP Option 60) for the supported device. The option name is case-insensitive. Do not use a hyphen (-) as part of the name. The vendor-class-id should be unique to each vendor option name.
vendor-option name delete
Deletes a vendor option.
vendor-option name enable read-only
Prevents further changes to a vendor option. Enable the read-only attribute of the vendor-specific DHCP option before you use the option in a policy name setVendoroption command to set the data for the option.
vendor-option name disable read-only
Allows changes to a vendor option (the default).
vendor-option name defineSuboption suboption number datatype [flags]
Defines a suboption for a vendor option. The attributes are as follows:
• suboption—Name of the suboption to define or undefine for the vendor option
• number—Number of the suboption to add to the vendor option (from 1 through 255, with a default value of 43)
• option-datatype—Name of the option datatype or standard DHCP option
• flags—Comma-separated string of flags specifying formatting of the vendor option
2-130Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsvendor-option
The supported flags are as follows:
• array—Allows data for multiple suboptions when using the policy command to set vendor options. See the “Defining Vendor-Specific DHCP Options” section on page 2-131.
• no-suboption-opcode—Specifies that the DHCP server skips the byte that contains the suboption number.
• no-suboption-len—Specifies that the DHCP server skips the byte that contains the length of the suboption data. Devices that use an empty suboption to indicate the end of vendor-specific DHCP option data may require this.
• no-suboption-data—Specifies that the DHCP server skips the suboption data bytes. Devices that use an empty suboption to indicate the end of vendor-specific DHCP option data may require this.
vendor-option name undefineSuboption suboption
Makes a suboption-name undefined for a vendor option.
vendor-option name listSuboptions
Lists any suboptions defined for a vendor option.
vendor-option name [show]
Lists the attributes for a vendor option.
vendor-option list
Lists all vendor options and any attributes assigned to them.
vendor-option listnames
Lists just the names of the vendor options.
Usage Guidelines Defining Vendor-Specific DHCP Options
There are four main steps to configure Network Registrar to support a device that expects to receive vendor-specific DHCP options from the DHCP server:
Step 1 Define any necessary vendor-specific data types. Refer to the vendor’s manual for the device and use the option-datatype command to create any new data types required for vendor-specific suboptions.
Step 2 Create a vendor option. Locate the device’s class-identifier string (sent in Option 60 by the DHCP client device) in the vendor’s manual. Then, use the vendor-option command to create a vendor-specific DHCP option for the device.
Step 3 Define all required suboptions. Assign suboptions either vendor-specific option data types (created as Step 1) or standard DHCP data types. Use the vendor-option command to map suboptions formats to their appropriate data types.
Step 4 Set the values of the vendor option using the policy setVendorOption command.
2-131Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandsvendor-option
The following example is based on the Intel Preboot Execution Environment (PXE) Specification, Version 2.0. For continuity and completeness, the example includes all three commands required to accomplish its task. See the “vendor-option” section on page 2-130 and the “policy” section on page 2-90.
1. Define vendor-specific option data types. The IntelPxE device expects the DHCP server to return several vendor-specific suboptions. One such suboption is Suboption 8, which holds a set of IP addresses for boot servers available to the device. Suboption 8 has a distinct format that you can map into Network Registrar using the option-datatype command to create a option data type called IntelPXE_odt_suboption_8 for an IntelPXE-compatible network device. This device requires several suboptions with different formats. Map each suboption into Network Registrar using a separate set of option-datatype commands.
nrcmd> option-datatype IntelPXE_odt_suboption_8 create nrcmd> option-datatype IntelPXE_odt_suboption_8 defineField boot_server_type 1 WORD nrcmd> option-datatype IntelPXE_odt_suboption_8 defineField boot_server_IP_list 2 IPADDR_ARRAY nrcmd> option-datatype IntelPXE_odt_suboption_8 enable read-only
2. Create a vendor option for the device. PXEclient:Arch:xxxxxx:UNDI:yyyzzz exactly matches the string provided by the vendor as the class-identifier (Option 60) for the device, and creates the vendor option IntelPXE_vso.
nrcmd> vendor-option IntelPXE_vso create "PXEclient:Arch:xxxxxx:UNDI:yyyzzz"
3. Define all the required suboptions. Assign Suboption 8 to the option data type IntelPXE_odt_suboption_8 and define any other suboption that the device requires.
nrcmd> vendor-option IntelPXE_vso defineSuboption suboption_8 8 IntelPXE_odt_suboption_8 array
4. Set the data of the vendor option by setting the values of each suboption:
a. In the first array element of Suboption 8, set the boot server type field to type 2 (Microsoft Windows boot servers), and the boot server address list field to addresses 192.168.25.4 and 192.168.25.5. Include the braces and square brackets as part of the syntax of the suboption and its index.
nrcmd> policy network-1.2.3 setVendorOption IntelPXE_vso {suboption_8[0]} boot_server_type 2 nrcmd> policy network-1.2.3 setVendorOption IntelPXE_vso {suboption_8[0]} boot_server_IP_list 192.168.25.4,192.168.25.5
b. In the second array element, set the boot server type field to type 8 (HP OpenView boot server), and the boot server address list field to address 192.168.25.6.
nrcmd> policy network-1.2.3 setVendorOption IntelPXE_vso {suboption_8[1]} boot_server_type 8 nrcmd> policy network-1.2.3 setVendorOption IntelPXE_vso {suboption_8[1]} boot_server_IP_list 192.168.25.6
Related Commands option-datatype
2-132Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandszone
zoneThe zone command creates and edits DNS zones, as well as forces zone transfers. For additional information on zone scavenging, see the Network Registrar User’s Guide.
zone name create primary file=BINDfile
zone name create primary nameserver person [attribute=value…]
zone name create secondary address [attribute=value…]
zone name delete
zone name enable attribute
zone name disable attribute
zone name set attribute=value [attribute=value...]
zone name unset attribute
zone name get attribute
zone name [show]
zone list
zone listnames
zone name forceXfer secondary
zone name addHost hostname IPaddress [alias…]
zone name removeHost hostname
zone name listHosts
zone name addRR owner [ttl] [class] type data
zone name removeRR owner [type [data]]
zone name removeDynRR owner [type]
zone name cleanRR
zone name listRR {all | static | dynamic}
zone name getScavengeStartTime
zone name scavenge
zone name chkpt
zone name dumpchkpt
2-133Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandszone
Syntax Description See Table 2-29 on page 2-136 for the zone command attributes and their descriptions.
The name is the fully qualified domain name (FQDN), including the trailing dot.
zone name create primary file=BINDfile
Creates a primary zone by importing data from the BIND (zone) format file.
nrcmd> zone example.com. create primary file=host.local
zone name create primary nameserver person [attribute=value...]
Creates a primary zone, along with the DNS name server and the person in charge (and optionally any additional attributes). Note that re-creating an existing zone overwrites the old one.
The zone command automatically creates the SOA and NS resource records for you. Use the zone name addRR command to create an A record for the name server that you specified in the nameserver value. The following example creates an SOA record ns.test.org. andy.test.org. and an NS record ns.test.org.
nrcmd> zone test.org. create primary ns andy
Both of these records have the name of the zone (“test.org.” or “@”). Because name server ns.test.org. is in the test.org. zone, you must also provide an A record for it.
nrcmd> zone test.org. addRR ns A 192.168.2.2 nrcmd> server dns reload
zone name create secondary address [attribute=value…]
Creates a secondary zone, along with the IP address of the primary name server for zone transfers (and optionally any additional attributes).
zone name delete
Deletes a zone.
zone name enable attribute
Enables an attribute of a zone.
zone name disable attribute
Disables an attribute of a zone.
zone name set attribute=value [attribute=value...]
Sets one or more attributes for a zone.
zone name unset attribute
Unsets the value of an attribute of the zone.
zone name get attribute
Gets the value of an attribute of the zone.
zone name [show]
Shows the values of all attributes for a zone.
zone list
Lists all zones and their attributes.
zone listnames
Lists just the zone names.
2-134Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandszone
zone name forceXfer secondary
Forces the secondary server to initiate a zone transfer to a zone.
nrcmd> zone test.org. forceXfer secondary
Note The primary argument is currently not implemented.
zone name addHost hostname IPaddress [alias…]
Adds the hostname to a zone, along with its IP address and optional aliases.
nrcmd> zone example.com. addHost bethpc 192.168.1.10
zone name removeHost hostname
Removes a host from a zone.
zone name listHosts
Lists the hosts for a zone.
zone name addRR owner [ttl] [class] type data
Adds a resource record of a certain type for a zone. The attributes of this command are as follows:
• class—Class of resource record, always IN (for Internet) in DNS.
• owner—Owner of the resource record. See the “Owner Names” section on page 2-138.
• ttl—Resource record time to live (in seconds). See the “Default TTL Responses” section on page 2-138.
• type—Type of resource record, such as PTR or A. For full descriptions, see the Network Registrar User’s Guide.
• data—Data that depends on the resource record type.
For the resource record addition to take effect, you must reload the server. The following example adds a Name Server (NS) resource record.
nrcmd> zone example.com addRR @ NS ns.green.example.com. nrcmd> server dns reload
zone name removeRR owner [type [data]]
Removes all specified static resource records from a zone. Specify resource records by owner; owner and type; or owner, type, and data (in BIND-style format). Note that for the removal to take effect, you need to reload the server. See the attributes in the addRR syntax description. See the “Removing Resource Records” section on page 2-139.
zone name removeDynRR owner [type]
Removes all specified dynamic resource records. from a zone. Specify resource records by owner, or owner and type. The DNS server must be running. Changes take effect immediately; you do not need to reload the server. See the attributes in the addRR syntax description. See the “Removing Resource Records” section on page 2-139.
zone name cleanRR
Cleans out zone records that remain after you remove a zone. See the “Cleaning Resource Records” section on page 2-139. The following example deletes a zone’s unused or obsolete resource records.
nrcmd> zone example.coms cleanRR
2-135Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandszone
zone name listRR {all | static | dynamic}
Displays the resource records for a zone. You can display all the resource records, or just the static or dynamic resource records.
zone name getScavengeStartTime
Gets the time for the next scheduled zone scavenging.
zone name scavenge
Causes scavenging on all zones that have enabled the scvg-enabled attribute.
zone name chkpt
Forces an update to the zone checkpoint database for the specified zone. Set the checkpoint interval using the zone name set checkpoint-interval command.
zone name dumpchkpt
Forces an update to the zone checkpoint database and creates a humanly readable file of the zone or checkpoint.
Attributes Table 2-29 describes the zone command attributes.
Table 2-29 zone Command Attributes
Attribute Usage Description
auth-servers set= get
For a secondary zone only, the list of servers from which to transfer data. Required for a secondary zone, no default.
checkpoint- interval
set= get unset
Interval (in seconds) at which to checkpoint the zone (take the latest snapshot in the zone checkpoint database). See the “Logging Checkpoint Files and Scavenging” section on page 2-140. Optional, default 3 hours, range 1-168 (7 days).
defttl set= get unset
For a primary zone only, default TTL for this zone. Network Registrar responds to authoritative queries with an explicit TTL value, if one exists. If none exists, it responds with the default TTL value. See the “Default TTL Responses” section on page 2-138. Required for a primary zone, default 86400 seconds (one day), range 0-2147483647 seconds.
dynamic enable disable
For a primary zone only, enables or disables RFC 2136 dynamic updates to the zone. The most typical source of these updates is a DHCP server. Required, default enable.
dynupdate-set set= get
For a primary zone only, with zone name enable dynamic, the set of IP addresses from which to accept dynamic updates. Network Registrar considers addresses with zeroes in the least significant octets as network numbers with implicit masks in octet multiples. Required, default no addresses.
expire set= get
For a primary zone only, expiration interval, in seconds, of the zone. The time a secondary can continue to serve zone data without confirming that it is still current. Optional, default 604800 seconds (seven days), range 0-2147483647 seconds.
ixfr enable disable unset
For a secondary zone only, enables or disables requesting incremental transfers. Overrides the ixfr-enable setting for the server. See the “Enabling Incremental Zone Transfers by Server or Zone” section on page 2-139. Optional, no default.
2-136Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandszone
minttl set= get
For a primary zone only, minimum TTL for resource records for the zone. This is generally not used except under special configuration circumstances. See the “Default TTL Responses” section on page 2-138. Optional, range 0-2147483647, default, 86400.
notify enable disable unset
Enables notifying other authoritative servers when this zone changes. The setting overrides the global notify value for this zone. Optional, no default.
notify-set set= get
List of additional servers to notify when the zone changes. All servers listed in NS records for the zone, except the server described by the ns zone attribute (mname field of the SOA record), receive notifications. Network Registrar also notifies servers listed in the notify-set value. Optional, defaults to empty.
ns set= get
For a primary zone only, fully-qualified domain name of the primary for this zone. This host is the original or primary source of data for this zone. Required, no default.
origin get Fully qualified name of the zone’s root. Read-only.
person set= get
For a primary zone only, domain name that 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 [email protected] would become hostmaster.test.com. Required, no default.
refresh set= get
For a primary zone only, the refresh interval, in seconds, of the zone. Secondary servers use this as the period of polling for zone changes. Optional, default 10800 seconds (three hours), range 0-2147483647 seconds.
restricted-set set= get
With zone name enable restrict-xfer, the set of IP addresses that can request zone transfers. Network Registrar treats addresses with zeros in the least significant octets as network numbers, with implicit masks in octet multiples. Required, default zero entries, no value.
restrict-xfer enable disable
If enabled, restricts zone transfers to a specific set of hosts. If you restrict zone transfers, you need to use the restricted-set attribute to list the servers allowed to perform zone transfers. Required, default disable.
retry set= get
For a primary zone only, 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. Optional, default 3600 seconds (one hour), range 0-2147483647 seconds.
scvg-enabled enable disable
For a primary zone only, enables or disables dynamic resource record scavenging (stale record cleanup) of the zone. Use this for Microsoft clients, with other scavenging attribute settings. See the Network Registrar User’s Guide. This setting overrides that on the server level. Required, default disable.
scvg-ignore restarts- interval
set= get unset
For a primary zone only, the interval, in seconds, for which a server restart does not recalculate a start scavenging time. This setting overrides that on the server level. Optional, no default.
Table 2-29 zone Command Attributes (continued)
Attribute Usage Description
2-137Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandszone
Usage Guidelines Owner Names
You can specify the resource record’s owner name as one of the following:
• If the same name as the zone name—Enter the (@) symbol
• If the server is in the same domain—Relative name
• Fully qualified domain name (FQDN)
Default TTL Responses
Network Register responds to authoritative queries with an explicit TTL value. If there is no explicit TTL value, it uses the default TTL for the zone, as set by the value of the defttl zone attribute. Databases originating from versions of Network Registrar earlier than 3.5 do not have the defttl zone attribute, and use the minimum TTL in the zone’s SOA record for the default TTL.
If you have an earlier version of Network Registrar and want to enforce the minimum SOA record TTL, contact the Cisco TAC. Enforcing the minimum SOA TTL causes Network Registrar not only to use the minttl zone attribute value as the default TTL, but also as a floor value—resource records with explicit TTL values smaller than minttl assume the minttl value.
Normally, Network Registrar assumes the default TTL when responding with a zone transfer with resource records that do not have explicit TTL values. If the default TTL value for the zone is administratively altered, Network Registrar automatically forces a full zone transfer to any secondary DNS server requesting a zone transfer.
scvg-interval set= get unset
For a primary zone only, with zone name enable scvg-enabled, the interval, in seconds, at which the zone is scheduled for scavenging. This setting overrides that on the server level. See the “Logging Checkpoint Files and Scavenging” section on page 2-140. Optional, range 3600 (one hour) through 31536000 seconds. If no values are set, Network Registrar uses the server default values.
scvg-no- refresh- interval
set= get unset
For a primary zone only, with zone name enable scvg-enabled, the interval, in seconds, during which actions such as dynamic or prerequisite-only updates do not advance the timestamp for scavenging. This setting overrides that on the server level. Optional, range 3600 (one hour) through 31536000 seconds. If no values are set, Network Registrar uses the server default values.
scvg-refresh- interval
set= get unset
For a primary zone only, with zone name enable scvg-enabled, the interval, in seconds, during which the zone can have a timestamp updated to prepare for scavenging. This setting overrides that on the server level. Optional, range 3600 (one hour) through31536000 seconds. If no values are set, Network Registrar uses the server default values.
serial set= get
For a primary zone only, the current serial number of the zone, as found in its SOA record and maintained automatically by the DNS server. Required, no default, range 0-4294967295 seconds.
type get Type of role that the server should take for the zone, primary or secondary. Usually you only configure one server as primary for a zone, and configure several secondary servers to retrieve zone data through zone transfers. Read-only.
Table 2-29 zone Command Attributes (continued)
Attribute Usage Description
2-138Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandszone
Server Records
Windows 2000 domain controllers use the server (SRV) resource record to advertise services to the network. This resource record is defined in the RFC 2782, “A DNS RR for specifying the location of services (DNS SRV).” The RFC defines the format of the SRV record (DNS type code 33) as:
_service._protocol.name ttl class SRV priority weight port target
There should always be an A record associated with the SRV record’s target so that the client can resolve the service back to a host. In the Microsoft Windows 2000 implementation of SRV records, the records might look like this:
myserver.example.com A 10.100.200.11_ldap._tcp.example.com SRV 0 0 389 myserver.example.com_kdc._tcp.example.com SRV 0 0 88 myserver.example.com_ldap._tcp.dc._msdcs.example.com SRV 0 0 88 myserver.example.com
An underscore always precedes the service and protocol names. In the example, _kdc is the Kerberos Data Center. The priority and weight help you choose between target servers providing the same service (the weight differentiating those with equal priorities). If the priority and weight are all set to zero, the DNS server orders the clients randomly.
For more information on SRV records, see the Resource Records appendix of the Network Registrar User’s Guide.
Enabling Incremental Zone Transfers by Server or Zone
Using the server incremental zone transfer setting (dns enable ixfr-enable) gives you an easy way of globally turning incremental zone transfer (IXFR) on or off, or setting a general policy for your zones and specific exceptions to the server global value. With the zone ixfr setting (zone name enable|disable ixfr), if you:
• Enable IXFR for the zone, the zone acts differently than those that inherit the server global value.
• Disable IXFR for the zone, the zone acts differently than those that inherit the server global value.
Removing Resource Records
When there are multiple SRV records of the same owner, the zone name removeRR command removes all resource records having that owner. To remove only the resource records of a specific type, or to remove only a specific one, include the type, or type and data options. The following example removes all static resource records for the zone that have owner name green.
nrcmd> zone example.com. removeRR green
The following example removes only Address resource records that have owner name green.
nrcmd> zone example.com. removeRR green A
The following example removes only a specific static resource record with owner name green.
nrcmd> zone example.com. removeRR green A 192.168.1.52
Cleaning Resource Records
The zone name cleanRR command cleans the leftover zone records after you delete a zone. It uses the DNS server’s historical zone data to determine what part of this data to remove. Use the cleanRR keyword if you periodically delete and re-import zones, which can cause your database to grow.
2-139Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandszone
The behavior of the cleanRR keyword depends on the presence or absence of a new zone:
• Deleting and then re-creating the zone—Purges the entire old copy of the zone.
• Deleting and not re-creating the zone—Although the zone no longer exists, its resource records remain (but are marked “deleted”). In this case, using the cleanRR keyword does not affect the deleted zone and does not delete the records.
The cleanRR keyword does not print out a list of records to delete or prompt you for confirmation. You can safely run it at any time.
Logging Checkpoint Files and Scavenging
Use the dns set log-settings=chkpt command to log when checkpointing occurs for the DNS server for dynamic resource records. Use the dns set log-settings=scavenge command to log the resource records purged by scavenging. See Table 2-9 on page 2-48.
TTL in Zone File Exports and Imports
When Network Registrar receives a export zone CLI command, it records the default TTL for the zone in a BIND directive ($TTL). The value of the directive is determined by the rules that the “Default TTL Responses” section on page 2-138 describes.
Network Registrar also recognizes $TTL directives for zone file imports. The first $TTL directive it encounters serves as the default TTL for the zone. This value is assigned to defttl for future use. Subsequent $TTL directives do not override the first directive; that is, they do not change the default TTL for the zone. Instead, they provide the TTL for subsequent resource records that have no explicit TTL values. Consider the following BIND zone file:
$ORIGIN c.@ IN SOA ns joe 10 10800 3600 604800 7200 $TTL 3600 z IN A 1.2.3.4 $TTL 7200 y IN A 1.2.3.5 x 1800 IN A 1.2.3.6 $TTL 9800 w IN A 1.2.3.7 t 13400 IN A 1.2.3.8
This file is imported as:
default TTL: 3600c. IN SOA ns joe 10 10800 3600 604800 7200 z IN A 1.2.3.4 y 7200 IN 1.2.3.5 x 1800 IN A 1.2.3.6 w 9800 IN 1.2.3.7 t 13400 IN A 1.2.3.8
Notice that z does not have an explicit TTL value. Instead, it assumes the default TTL (3600). Also, notice that Network Registrar assigns both y and w explicit TTL values based on the last encountered $TTL directives.
2-140Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandszone
If the BIND zone file contains no $TTL directives, Network Registrar assumes the SOA minimum TTL value (the last value in the SOA record data) as the default TTL. For example, the zone file that follows is missing a $TTL directive:
$ORIGIN c. @ IN SOA ns joe 10 10800 3600 604800 7200 z IN A 1.2.3.4 y IN A 1.2.3.5 x 1800 IN A 1.2.3.6 w IN A 1.2.3.7 t 13400 IN A 1.2.3.8
Network Registrar imports this file as:
default TTL: 7200c. IN SOA ns joe 10 10800 3600 604800 7200 z IN A 1.2.3.4 y IN 1.2.3.5 x 1800 IN A 1.2.3.6 w IN 1.2.3.7 t 13400 IN A 1.2.3.8
Related Commands dns, server
2-141Network Registrar CLI Reference Guide
78-12875-01
Chapter 2 Using the nrcmd Commandszone
2-142Network Registrar CLI Reference Guide
78-12875-01
Ne78-12875-01
C H A P T E R 3
Using the nrcmd Program As an APIYou can use the nrcmd command to interactively configure and control a Network Registrar cluster, or you can use it as a programming interface for another program or script. This chapter describes how to use the nrcmd command as an application programming interface (API).
Connecting to Network RegistrarWhen you use the nrcmd command, you connect to a Network Registrar cluster to read and write configuration data, read state data, and perform control operations.
A Network Registrar cluster consists of the following:
• The persistent store, MCD, which contains configuration and state information for the DNS, DHCP, and TFTP servers.
• The server agent, AIC Server Agent, which starts and stops the protocol servers, and provides a standard control interface to them.
• The DNS and DHCP protocol servers.
Performing AuthenticationWhen you log into a cluster you are authenticated with a name and a password. The authentication protocol uses one-way hashes so that a password does not travel across the wire. In interactive mode, the nrcmd command prompts you for a valid user name and password. You can also provide the user name and/or password on the command line, in the environment, or in the Windows Registry. (On Solaris, the Windows Registry is emulated by files in the product configuration directories.)
Because you may not want to embed the administrator password in a command script, the environment variables and registry entries provide alternate locations with different visibility levels. The environment variables AIC_CLUSTER, AIC_NAME, and AIC_PASSWORD specify the cluster, administrator name and administrator password values. These are similar to the same registry keys in the directory HKEY_CURRENT_USER\Software\American Internet\Network Registrar\2.0.
For more information about creating administrator names and passwords, see the “admin” section on page 2-6.
3-1twork Registrar CLI Reference Guide
Chapter 3 Using the nrcmd Program As an APIChoosing Scripting Techniques
Choosing Scripting TechniquesBecause nrcmd does a significant amount of processing at connect time, it is more efficient to perform multiple commands in a single session rather than to initiate a distinct connection and login for each command. The simplest way to have a single nrcmd session perform multiple commands is to create a nrcmd batch file with one command per line and to redirect standard input from that file. A more complicated approach, but one that provides more control over the command sequence, is to run nrcmd from a controlling program and have that program send commands and read their status and output.
Using Nrcmd Batch FilesThe simplest way to automatically perform multiple configuration commands is to create a batch file of nrcmd commands and have nrcmd execute them sequentially.
For example, to create a scope and add some reservations to it, you can enter the following commands and store them in the file scope.txt:
scope demo1 create 24.10.2.0 255.255.255.0 scope demo1 addReservation 24.10.2.1 1,6,0a:23:45:67:89:01 scope demo1 addReservation 24.10.2.2 1,6,0c:23:45:67:89:02 scope demo1 addReservation 24.10.2.3 1,6,0c:23:45:67:89:03 scope demo1 addReservation 24.10.2.4 1,6,0a:23:45:67:89:04
You can then run a single nrcmd session to execute all of these commands:
% nrcmd –b < scope.txt
For more information about the scope command, see the “scope” section on page 2-103 in this guide.
The advantage to using batch files is that they allow you to execute multiple configuration commands while only incurring the connection cost once. The disadvantage to using batch files is that you cannot add program logic between nrcmd commands. If a command fails (such as the initial scope creation in the previous example), the batch file continues even though the subsequent commands are now useless.
Command SyntaxWhen you execute nrcmd commands that contain equal-signs, you must put them within quotation marks. For example, to use a single command to create a client-class name, enter:
nrcmd -C cluster -N name -P password "client MAC create client-class-name=name"
Adding Program ControlA more sophisticated method for automatically configuring and controlling Network Registrar is to have a program or script start a nrcmd session and communicate with the session through standard input and output.
To control nrcmd from another program, you need to start nrcmd from the controlling program and redirect standard input and output from nrcmd to file handles in the controlling program. The controlling program can then write commands to the input file handle and read results from the output file handle.
3-2Network Registrar CLI Reference Guide
78-12875-01
Chapter 3 Using the nrcmd Program As an APIChoosing Scripting Techniques
When running in batch mode, nrcmd reads a line of input at a time and prints a new line after the prompt. This provides an easily parsed sequence of lines in response to any command where:
• <status line> <result lines> <prompt line>
• The status line has the format [0-9]{3} .*.
• There may be zero or more resultant lines of any format.
• The prompt line is nrcmd>.
The exact details of starting up nrcmd as a child process, and writing to and reading from its standard input and output, are specific to the programming language you use to implement the controlling program.
3-3Network Registrar CLI Reference Guide
78-12875-01
Chapter 3 Using the nrcmd Program As an APIChoosing Scripting Techniques
3-4Network Registrar CLI Reference Guide
78-12875-01
Ne78-12875-01
C H A P T E R 4
Using Extension PointsYou can write extensions to affect how Network Registrar handles and responds to DHCP requests, and to change the behavior of a DHCP server that you cannot normally do using the user interfaces.
This chapter describes the extension points to which you can attach extensions. See also Appendix C, “DHCP Extension Dictionary Entries.”
Creating ExtensionsYou can alter and customize the operation of the Network Registrar DHCP server by using extensions, programs that you can write in TCL or C/C++.
You must complete the following procedures to create an extension for use in the DHCP server:
• Determine the task you want to perform.
• Determine the approach to use.
• Determine the extension point to which to attach the extension.
• Choose the language, TCL or C/C++.
• Write (and possibly compile and link) the extension.
• Add the extension to the DHCP server’s configuration.
• Attach the extension to the extension point.
• Reload the DHCP server so that it recognizes the extension.
• Test and debug the results.
Determining the TaskThe task to which to apply an extension is usually some modification of the DHCP server’s processing so that it better meets the needs of your environment.
For example, you might have an unusual routing hub that uses BOOTP configuration. This device issues a BOOTP request with an Ethernet hardware type (1) and MAC address in the chaddr field. It then sends out another BOOTP request with the same MAC address, but with a hardware type of Token Ring (6). Specifying two different hardware types causes the DHCP server to allocate two IP addresses to the device. The DHCP server normally distinguishes between a MAC address with hardware type 1 and one with type 6, and considers them to be different devices. In this case, you might want to write an extension that prevents the DHCP server from handing out two different addresses to the same device.
4-1twork Registrar CLI Reference Guide
Chapter 4 Using Extension PointsLanguage-Independent API
Deciding on the ApproachThere are often many solutions to a single problem. When choosing the type of extension to write, you should first consider rewriting the input DHCP packet. This is a good approach, because it avoids having to know the internal processing of the DHCP server.
You can solve the problem of the two IP addresses by writing either of the following extensions:
• One that causes the DHCP server to drop the Token Ring (6) hardware type packet.
• One that changes the Token Ring packet to an Internet packet and then switches it back again on exit. Although this extension would be more complex, the DHCP client could thereby use either return from the DHCP server.
This example illustrates a second useful approach to modifying the DHCP server’s behavior—rewriting the DHCP response packet just before returning it to the client. One reason to use extensions is to transmit information available only in the DHCP server to the external environment. The extension point that you can use for this purpose is post-send-packet. Call the post-send-packet extension point when transmitting any DHCP response packet to a DHCP client. See the “Using the post-send-packet Extension to Send the Packet” section on page 4-14.
Choosing the Extension PointTo decide on the appropriate extension point to perform the task, you should understand how the DHCP server processes client requests and generates DHCP responses. See the “DHCP Request Processing Using Extensions” section on page 4-9.
The example task uses the first extension point after the DHCP server receives the request packet (post-packet-decode), and the last extension point before the DHCP server transmits the response packet to the DHCP client (pre-packet-encode). See the “Using post-packet-decode When Decoding the Packet” section on page 4-10 and the “Using the pre-packet-encode Extension to Gather Response Packet Information” section on page 4-13.
Choosing the Extension LanguageYou can write extensions in TCL or C/C++. The capabilities of each language, so far as the DHCP server is concerned, are similar, although the application programming interface (API) is slightly different to support the two very different approaches to language design.
• TCL—Makes it a bit easier and quicker to write an extension. If the extension is short, the interpreted nature of TCL does not have a serious effect on performance. When you write an extension in TCL, you are less likely to introduce a bug that can crash the server.
• C/C++—Provides the maximum possible performance and flexibility, including communicating with external processes. The complexity of the C/C++ API is greater and the possibility of a bug in the extension crashing the server is more likely than with TCL because the extension operates in the same code space as the DHCP server itself.
Language-Independent APIBe aware of the following items independent of whether you write your extensions in TCL or C/C++.
4-2Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsLanguage-Independent API
Routine SignatureYou need to define the extension to the DHCP server as a file and a routine in that file. You then attach the extension to one or more of the DHCP server extension points. When the DHCP server reaches that extension point, it calls the routine that the extension defines. The routine returns with a success or failure. You can configure the DHCP server to drop a packet on an extension failure.
You can configure one file—TCL source file or C/C++ .dll or .so file—as multiple extensions to the DHCP server by specifying a different entry point for each configured extension.
The DHCP server calls every routine entry point with at least three arguments, the three dictionaries—request, response, and environment. Each dictionary is a representation of a key-value pair.
• The extension can retrieve data items from the DHCP server by performing a get method on a dictionary for a particular data item.
• The extension can alter data items by performing a put operation on the same named data item.
Although you cannot use all dictionaries at every extension point, the calling sequence for all routines is the same for every extension point. The extension encounters an error if it attempts to reference a dictionary that is not present at a particular extension point. See the “Environment Dictionary” section on page 4-15 and the “Request and Response Dictionaries” section on page 4-16.
DictionariesExtension points include three types of dictionaries—request, response, and environment:
• Request dictionary—Information associated with the DHCP request, along with all the information that came in the request itself. Data is string-, integer-, IP address-, and blob-valued (a sequence of bytes, not zero terminated).
• Response dictionary—Information associated with the generation of a DHCP response packet to return to the DHCP client. Data is string-, integer-, IP address-, and blob-valued (a sequence of bytes, not zero terminated)
• Environment dictionary—Information passed between the DHCP server and extension. Data is string-valued only.
You can also use the environment dictionary to communicate between two extensions running at different extension points. When encountering the first extension point at which some extension is configured, the DHCP server creates an environment dictionary. The environment dictionary is the only one in which the names of the allowable data items are not fixed by the DHCP server. You can use it to to insert any string-valued data item.
Every extension point in the flow of control between the request and response for the DHCP client (all extension points except pre-dns-add-forward), share the same environment dictionary. Thus, an extension may determine that some condition exists and place a sentinel in the environment dictionary so that a subsequent extension can avoid determining the same condition.
In the previous example, the extension at the post-packet-decode extension point determines that the packet was the interesting one—from a particular manufacturer’s device, BOOTP, and Token Ring—and then rewrites the hardware type from Token Ring to Ethernet. It also places a sentinel in the environment dictionary and then, at a very simple extension at the pre-packet-encode extension point, rewrites the hardware type back to Token Ring.
4-3Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsLanguage-Independent API
Utility MethodsEach dictionary has associated utility methods with which you can reset the trace level for an extension and log values to an output file.
Init-Entry Extension PointInit-entry is an additional extension point that the DHCP server calls when it configures or unconfigures the extension. This occurs when the starting, stopping, or reloading the server. This entry point has the same signature as the others for the extension, but you can only use the environment dictionary. You do not configure the init-entry extension with the nrcmd dhcp attachExtension command, but you configure it implicitly by defining an init-entry on an already configured extension.
In addition to configuring an init-entry with the name of the entry point, you can also configure a string of arguments that the DHCP server loads in the environment dictionary under the string arguments before calling the init-entry point. Using arguments, you can create a customized extension by giving it different init arguments and thus not requiring a change to the code to elicit different behavior.
You configure arguments by setting init-args on an existing extension point. These arguments are present for both the configure and unconfigure calls of the init-entry entry point. The extension-point name for the configure call is initialize and for the unconfigure call is uninitialize.
Note The order in which extensions are called at their init-entry point is not assured. It may not be the same from reload to reload or release to release.
Configuration ErrorsThere are many reasons why an extension can fail:
• The file may not be found.
• The entry point or init-entry point may not appear in the file.
• The extension itself can return failure from an init-entry call.
By itself, an extension failure is not fatal and does not prevent the DHCP server from starting. However, the configuration for that extension point will fail. If the DHCP server fails to configure any extension points, then the server will not start. Therefore, to debug the configuration process, you can configure your extension and the init-entry point without attaching it to an extension point. When you complete that process, you can attach your extension to an extension point.
Recognizing ExtensionsThe DHCP server only recognizes extensions when it initially configures itself at start or reload time. You can change an extension or the configuration for extensions in general. However, until you reload or restart the server, the changes have no effect. Forgetting to reload the DHCP server can be a frequent source of errors while debugging extensions.
The reason Network Registrar requires a reload is to ensure minimum processing impact by preloading extensions and getting them ready at server configuration time. While this approach is useful in production mode, it might cause some frustration when you are debugging extensions.
4-4Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsTCL Extensions
TCL ExtensionsIf you choose to write your extensions in TCL, you should understand the TCL API, how to handle errors and boolean variables, and how to initialize TCL extensions.
TCL APIEvery TCL extension has the same routine signature, as follows:
proc yourentry { request response environ } { # your-code }
To operate on the data items in any dictionary, you must treat these arguments as commands. Thus, to get the giaddr of the input packet, you would write:
set my_giaddr [ $request get giaddr ]
This sets the TCL variable my_giaddr to the string value of the giaddr in the packet; for example, 10.10.1.5 or 0.0.0.0.
You could rewrite the giaddr in the input packet by using the following TCL statement:
$request put giaddr "1.2.3.4"
To configure one routine entry for multiple extension points and to alter its behavior depending on the extension point from which it is called, the ASCII name of the extension point is passed in the environment dictionary under the key extension-point.
For some sample TCL extensions, see the Network Registrar directory:
• Solaris and Linux—/opt/nwreg2/examples/dhcp/tcl
• Windows—\Program Files\Network Registrar\examples\dhcp\tcl.
Dealing with TCL errorsYou generate a TCL error if you do one of the following:
• Reference a dictionary that is not available
• Reference a dictionary data item that is not available
• Request a put operation on an invalid data item, for example, an invalid IP address
In these cases, the extension immediately fails unless you surround the statement with a catch { } error statement:
catch { $request put giaddr "1.2.3.a" } error
Handling Boolean VariablesIn the environment dictionary, the boolean variables are string-valued and have a value of true or false. The DHCP server expects an extension to set the value to true or false. However, in the request or response dictionaries, boolean values are single-byte numeric format, and true is 1 and false is 0. While more efficient for the C/C++ extensions, this approach does make the TCL API a bit more complex.
4-5Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsC/C++ Extensions
Configuring TCL ExtensionsTo configure an extension, write it and place it in the extensions directory. For UNIX and Linux, this is the /opt/nwreg2/extensions/dhcp/tcl directory. For Windows, this is the \Program Files\Network Registrar\extensions\dhcp\tcl directory.
When the DHCP server configures an extension during startup, it reads the TCL source file into an interpreter. Any syntax errors in the source file that would render TCL interpreter unable to load the file would also fail the extension. Typically, the DHCP server generates an error traceback in the log file from TCL to help you to find the error.
Init-Entry Extension Point in TCLTCL extensions support the init-entry extension point, and the arguments supplied in the init-args parameter to the command line appear in the environment dictionary associated with the key arguments.
Multiple TCL interpreters may be running in the DHCP server, for performance purposes, each in its own TCL context. The server calls the TCL extension once at the init-entry point for every TCL context (interpreter) it runs. Ensure that your TCL extension’s init-entry is robust, given multiple calls.
Information cannot flow between the TCL contexts, but the init-entry can initialize global TCL variables in each TCL interpreter that any TCL extension can access, regardless of the interpreter.
Note that the TCL interpreters are shared among all of the TCL extensions. If your TCL extension initializes global variables or defines procedures, ensure that these do not conflict with some other TCL extensions’ global variables or procedure names.
C/C++ ExtensionsAll DHCP C/C++ extensions are called “dex” extensions, which is short for DHCP Extension.
C/C++ APIThe routine signature for both the entry and init-entry routines for the C/C++ API is as follows:
typedef int (DEXAPI * DexEntryPointFunction)( int iExtensionPoint, dex_AttributeDictionary_t* pRequest, dex_AttributeDictionary_t* pResponse, dex_EnvironmentDictionary_t* pEnviron );
Along with pointers to three structures, the integer value of the extension point is one of the parameters of each routine.
The C/C++ API was specifically constructed so that you do not have to link your shared library with any Network Registrar DHCP server files. You configure the entry to your routine when you configure the extension. The necessary call-back information for the operations to be performed on the request, response, and environment dictionaries is in the structures that comprise the three dictionary parameters passed to your extension routine.
The DHCP server returns all binary information in network order, which is not necessarily properly aligned for the executing architecture.
4-6Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsC/C++ Extensions
Using TypesMany C/C++ routines are available that use types, for example, getByType(). These routines are designed for use in performance-sensitive environments. The reasoning behind these routines is that the extension can acquire pointers to types once, for example, in the init-entry point, and thereafter use the pointers instead of string-valued names when calling the routines of the C/C++ API. Using types in this manner removes one hash-table lookup from the extension processing flow of execution, which should improve (at least fractionally) the performance of any extension.
Building C/C++ ExtensionsThe directories /opt/nwreg2/examples/dhcp/dex (UNIX) and \Program Files\Network Registrar\examples\dhcp\dex (Windows) contains example C/C++ extension code, as well as a short makefile designed to build the example extensions. To build your own extensions, you need to modify this file. It has sections for Microsoft Visual C++ V5.0, GNU C++, and SunPro C++. Simply move the comment lines to configure the file for your environment.
Your extension needs to reference the include file dex.h. This file contains the information your program needs to use the C/C++ API. When building C/C++ extensions on Windows, remember to add your entry points to the .def file.
After you build the .dll (Windows) or .so (UNIX) file (all dex extensions are shared libraries), you need to move them into the /opt/nwreg2/extensions/dhcp/dex directory (UNIX), or the \Program Files\Network Registrar\extensions\dhcp\dex directory (Windows). You can then configure them.
Using Thread-Safe ExtensionsThe DHCP server is multithreaded, so any C/C++ extensions written for it must be thread-safe. They must be capable of being called simultaneously by multiple threads, and possibly multiple processors, at the same entry point. You should have considerable experience writing code for a multithreaded environment before designing C/C++ extensions for Network Registrar.
Caution All C/C++ extensions must be thread-safe, or the DHCP server will not operate correctly, and will crash in ways that are extremely difficult to diagnose. All libraries and library routines that these extensions use must also be thread-safe.
On several operating systems, you must ensure that the runtime functions used are really thread-safe. Check the documentation for each function. Special thread-safe versions are provided (often functionname_r) on several operating systems. Because Windows provides different versions of libraries for multithreaded applications that are threadsafe, this problem usually does not apply.
Be aware that if any thread makes a nonthread-safe call, it affects any of the threads that make the safe or locked version of the call. This can cause memory corruptions, crashes, and so on.
Diagnosing these problems is extremely difficult, because the cause of these failures are rarely apparent. To cause a crash, you need very high server loads or multiprocessor machines with many processes. You might need running times of several days. Often, problems in extension implementation may not appear until after sustained periods of heavy load.
Because some runtime or third-party libraries might be making nonthread-safe calls that you cannot detect, check your executables to see what externals are being linked (nm on UNIX).
4-7Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsC/C++ Extensions
If the single threaded version of any of the functions in the following list are called by the thread (versions without the _r suffix by any thread on Solaris), do not use them. The interfaces to the thread-safe versions of these library routines may be different on different operating systems.
Thread-safe versions are as follows:
Configuring C/C++ ExtensionsBecause the .dll and .so files are active when the server is running, it is not a good idea to overwrite them. After the server is stopped, the .dll and .so files are not in use and you can overwrite them with newer versions.
Debugging C/C++ ExtensionsBecause your C/C++ shared library runs in the same address space as the DHCP server, and receives pointers to information in the DHCP server, any bugs in your C/C++ extension can very easily corrupt the DHCP server's memory, leading to a server crash. For this reason, use extreme care when writing and testing a C/C++ extension. Frequently, you should try the approach to an extension with a TCL extension and then code the extension in C/C++ for increased performance.
Pointers into DHCP Server Memory
The C/C++ extension interface routines return pointers into DHCP server memory in two formats:
• char* pointer to a series of bytes
• Pointer to a structure called an abytes_t, which provides a pointer to a series of bytes with an associated length (defined in dex.h).
asctime_r gethostbyname_r getservbyport_r
ctermid_r gethostent_r getservent_r
ctime_r getnetbyaddr_r getspent_r
fgetgrent_r getnetbyname_r getspnam_r
fgetpwent_r getnetent_r gmtime_r
fgetspent_r getprotobyname_r lgamma_r
gamma_r getprotobynumber_r localtime_r
getgrid_r getprotoent_r nis_sperror_r
getgrnam_r getpwent_r rand_r
getlogin_r getrpcbyname_r readdir_r
getpwnam_r getrpcbynumber_r strtok_r
getpwuid_r getrpcent_r tmpnam_r
getgrent_r getservbyname_r ttyname_r
gethostbyaddr_r
4-8Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsDHCP Request Processing Using Extensions
In both of these cases, the pointers into DHCP server memory are valid while the extension runs at that extension point. They are also valid for the rest of the extension points in the series processing this request. Thus, an abytes_t pointer returned in the post-packet-decode extension point is still valid in the post-send-packet extension point. It is not, however, valid in the pre-dns-add-forward extension point, because this extension point is not part of the cycle of request-response processing, but is handled by a different subsystem.
The pointers are valid for as long as the information placed in the environment dictionary is valid. However, there is one exception. One C/C++ routine, getType, returns a pointer to an abytes_t that references a type. These pointers are valid through the entire life of the extension. Typically, you would call this routine in the init-entry extension point and save the pointers to the abytes_t structures that define the types in the static data of the shared library. Pointers to abytes_t structures returned by getType are valid from the init-entry call for initialization until the call for uninitialization.
Init-Entry Entry Point in C/C++
The DHCP server calls the init-entry extension point once when configuring each extension and once when unconfiguring it. The dex.h file defines two extension point values that are passed as the extension points for the configure and unconfigure calls: DEX_INITIALIZE for configure and DEX_UNINITIALIZE for unconfigure. The environment dictionary value of the extension-point data item is initialize or uninitialize in each call.
When calling the init-entry extension point for initialize, if the environment dictionary data item persistent contains the value true, you can save and use the environment dictionary pointer any time before the return from the uninitialize call. In this way, background threads can use the environment dictionary pointer to log messages in the server’s log file. Note that you must interlock all access to the dictionary to ensure that at most one thread processes a call to the dictionary at any one time. You can use the saved dictionary pointer up to the time the extension returns from the uninitialize call. This way, the background threads can log messages during termination.
DHCP Request Processing Using ExtensionsThe Network Registrar DHCP server has extension points to which you can attach your own extensions. They have descriptive names that indicate where in the processing flow of control to use them.
Because the extension points are tied to the processing of input requests from DHCP clients, it is helpful to understand how the DHCP server handles requests. The stages in processing a request in the DHCP server are as follows:
1. Receive a packet from a DHCP client.
2. Decode the packet.
3. Perform client-class processing, if any.
4. Build a response template from the request.
5. Determine the network from which the request arrived.
6. Find a lease already associated with this client, if any, or locate a new lease for the client.
7. Serialize all requests associated with this lease.
8. When this request reaches the head of the serialization queue, determine if this lease is (still) acceptable for this client.
9. Gather all the data to include in the response packet.
4-9Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsDHCP Request Processing Using Extensions
10. Encode the response packet for transmission to the DHCP client.
11. Update stable storage, if necessary.
12. Send the packet to the DHCP client.
These stages are explained in the following sections. The extension points are indicated in bold.
Receiving a PacketThe DHCP server receives packets on port 67 (the DHCP input port) and queues them for processing. It attempts to empty the UDP input queue as quickly as possible and keeps all of the requests that it receives on an internal list for processing as soon as a free thread is available to process them. You can configure the length of this queue, and it will not grow beyond its maximum configured length.
Using post-packet-decode When Decoding the PacketWhen a free thread is available, the DHCP server allocates to it the task of processing an input request. The first action it takes is to decode the input packet to determine if it is a valid DHCP client packet. As part of this decoding process, the DHCP server checks all of the options to see if they are valid—if the lengths of the options make sense in the overall context of the request packet. It also checks all data in the DHCP request packet, but takes no action on any of the information in the packet at this stage.
Use the post-packet-decode extension point to rewrite the input packet.
After the DHCP server passes this extension point, it stores all information from the packet in several internal data structures to make subsequent processing more efficient.
Using pre-client-lookup and post-client-lookup for Client-Class ProcessingIf you enabled client-class processing, the DHCP server performs it at this stage.
Use the pre-client-lookup extension point to affect the client that is looked up, possibly by preventing the lookup or supplying data that overrides the existing data.
After the DHCP server passes the pre-client-lookup extension point, it looks up the client (unless the extension specifically prevents it) in the local database or in an LDAP database, if one was configured.
After the DHCP server looks up the client, it uses the data in the client entry to fill in additional internal data structures. The DHCP server uses data in the specified client-class entry to complete any information not specified by the client entry.
When the DHCP server retrieves all the data and stored it in the various places in the server’s internal data structures for additional processing, it runs the next extension point.
Use the post-client-lookup extension point to review the operation of the client-class lookup process, such as examining the internal server data structures filled in from the client-class processing. You can also use it to change any data before the DHCP server does additional processing.
4-10Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsDHCP Request Processing Using Extensions
Building a Response TemplateAt this stage, the DHCP server determines the type of the request and builds an appropriate response template based on the type of input request. For example, if the input request is a DHCPOFFER, the server creates a DHCPDISCOVER response to perform the processing. If the input request is a BOOTP request, the server creates a BOOTP response to perform the response processing.
Determining the NetworkThe DHCP server must determine the subnet from which every request originated and map that into a set of address pools or scopes that contain IP addresses.
Internal to the DHCP server is the concept of a network, which, in this context, refers to a LAN segment or physical network. In the DHCP server, every scope belongs to a single network. Some scopes are grouped together on the same network because their network numbers and subnet masks are identical. Others are grouped because they are related through the primary-scope pointer.
The Network Registrar DHCP server does the following to determine the network to use to process a DHCP client request:
• Determines the source address—Either the giaddror, if the giaddr is zero, the address of the interface on which the request arrived.
• Uses this address to search the scopes for any scope that was configured in the server that is on the same subnet as this address—If the server does not find a scope, it drops the request.
• After finding the scope, uses its network in subsequent processing.
Finding a Lease for the ClientNow that the DHCP server established the network, it searches the hash table held at the network level to see if this client’s client-id is already known to this network. Already known, in this context, means that this client previously received an offer or a lease on this network, and the lease was not offered to or leased by a different client since that time. Thus, a current lease or an available expired lease will appear in the network level hash table. If the DHCP server finds a lease, it proceeds to the next step, which is to serialize all requests for the same IP address.
If the DHCP server does not find a lease, and if this is a BOOTP or DHCPDISCOVER request, the server looks for a reserved lease from a scope in the network. If it finds a reserved lease, the server checks whether the scope and lease are both acceptable. The following must be true of the reserved lease and the scope that contains it:
• The lease must be available (not leased to another DHCP client).
• The scope must support the request type (BOOTP or DHCP).
• The scope must not be de-activated.
• The lease must not be de-activated.
• The scope selection tags must contain all of the client’s selection-criteria and one of the client’s selection-criteria-excluded.
• The scope must not be renew-only.
If the reserved lease is acceptable, the server proceeds to the next step, which is to serialize all requests for the IP address. Having failed to find an existing or reserved lease for this client, the server now attempts to find any available IP addresses for this client.
4-11Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsDHCP Request Processing Using Extensions
The general process the DHCP server uses is to scan all of the scopes associated with this network in round-robin order, looking for one that is acceptable for this client and also has available addresses. An acceptable scope has the following characteristics:
• If the client has selection-criteria associated with it, the scope’s selection tags must contain all of the client’s inclusion criteria.
• If the client has selection-criteria-excluded associated with it, the scope’s selection tags must contain none of the client’s exclusion criteria.
• The scope must support the client’s request type—If the client’s request is a DHCPREQUEST, the scope must be enabled for DHCP. Likewise, if the request is a BOOTP request, the scope must be enabled for BOOTP and dynamic BOOTP.
• It must not be renew-only.
• It must not be de-activated.
• It must have an available address.
If the DHCP server does not find an acceptable scope, it logs a message and drops the packet.
Serializing Requests for the Same IP AddressBecause multiple DHCP requests can be in process simultaneously for one client and one lease, they must be serialized at the level of the lease. They are queued on the lease and processed in order of queueing.
Determining If the Lease Is AcceptableThe DHCP server now determines if the lease is (still) acceptable for the client. In the case where this is a newly acquired lease for a first-time client, it will be acceptable. However, in the case where the server processes a renewal for an existing lease, the acceptability criteria may have changed since the lease was granted and needs to be checked again.
If the client has a reservation that is different from the current lease, the server first determines if the reserved lease is acceptable. The criteria for release acceptability are:
• The reserved lease must be available.
• The reserved lease must not be de-activated.
• The scope must not be de-activated.
• If the request is BOOTP, the scope must support BOOTP. If the request is DHCP, the scope must support DHCP.
• If the client has any selection-criteria, the scope’s selection tags must contain all of the client’s inclusion criteria.
• If the client has any selection-criteria-excluded, the scope’s selection tags must contain none of the client’s exclusion criteria.
• If the client previously associated with this lease is not the current client, the scope must not be renew-only.
4-12Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsDHCP Request Processing Using Extensions
If the reserved lease meets all of this criteria, the DHCP server considers the current lease unacceptable. If there is no reserved lease for this client, or the reserved lease did not meet the criteria for acceptability, the DHCP server examines the current lease for acceptability. The criteria for acceptability are:
• The lease must not be de-activated.
• The scope must not be de-activated.
• If the request is BOOTP, the scope must support BOOTP. If the request is DHCP, the scope must support DHCP.
• If the client does not have a reservation for this lease, and the request is BOOTP, the scope must support dynamic BOOTP.
• If the client does not have a reservation for this lease, no other client must have a reservation for this lease either.
• If the client has any selection-criteria, the scope’s selection tags must contain all of the client’s inclusion criteria.
• If the client has any selection-criteria-excluded, the scope’s selection tags must contain none of the client’s exclusion criteria.
• If the client previously associated with this lease is not the current client, the scope must not be renew-only.
At this point in the DHCP server processing, you can use the check-lease-acceptable extension point. You can use this to change the results of the acceptability test. Do this only with extreme care.
Upon determining that a lease is unacceptable, the DHCP server takes different actions, depending on the particular DHCP request currently being processed.
• DHCPDISCOVER—The DHCP server releases the current lease and attempts to acquire a different, acceptable lease for this client.
• DHCPREQUEST SELECTING—The DHCP server sends a NACK to the DHCP client because the lease is invalid. The client should then immediately issue a DISCOVER request to acquire a new DHCPOFFER.
• DHCPRENEW, DHCPREBIND—The DHCP server sends a NACK to the DHCP client to attempt to force the DHCP client into the INIT phase (attempt to force the DHCP client into issuing a DHCPDISCOVER request). The lease is still valid until the client actually issues the request.
• BOOTP—The DHCP server releases the current lease and attempts to acquire a different, acceptable lease for this client.
One reason for taking extreme care with the check-lease-acceptable extension point is that, if the answer returned by the extension point does not match the acceptability checks in the search for an available lease performed in a DHCPDISCOVER or dynamic BOOTP request, an infinite server loop can result (either immediately, on the next DHCPDISCOVER or BOOTP request). In this case, the server would acquire a newly available lease, determine that it was not acceptable, try to acquire a newly available lease, and determine that it was not acceptable, in a continuous loop.
Using the pre-packet-encode Extension to Gather Response Packet Information
In this stage of processing, the DHCP server collects all the data to send back in the DHCP response and determines the address and port to which to send the response. You can use the pre-packet-encode extension point to change the data sent back to the DHCP client in the response or to change the address to which the DHCP response should be sent.
4-13Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsDHCP Request Processing Using Extensions
Caution Any packets that you drop at the pre-packet-encode extension point, whether they be DHCP or BOOTP packets, still show the address to be leased in the Network Registrar lease state database, for as long as the remaining lease time. Because of this, it is advisable to drop packets at an earlier point.
Encoding the Response PacketIn this stage, the DHCP encodes the information in the response data structure into a network packet. If this DHCP client requires DNS activity, the DHCP server queues a DNS work request to the DNS processing subsystem in the DHCP server. That request runs whenever it can, but generally not before sending the packet to the client. See the “Using the pre-dns-add-forward Extension to Process DNS Requests” section on page 4-14.
Updating Stable StorageAt this stage, the DHCP server ensures that the on-disk copy of the information is up to date with respect to the IP address before proceeding.
Using the post-send-packet Extension to Send the PacketUse the post-send-packet extension point for any processing that you want to perform outside of the serious time constraints of the DHCP request-response cycle. By using the post-send-packet extension point, after the DHCP server sends the packet to the DHCP client, it calls this extension point.
If it takes a long time to connect to the external environment, the extension should use a separate thread for improved performance. The DHCP server has only a limited number of threads for request processing, and if some or (worse) all of them are stalled in an extension waiting on some external condition, the DHCP server’s performance suffers. There are no hard guidelines for how long is too long, but in general, if the extension completes within two or three seconds it should not impact the performance of the DHCP server. More than three seconds would definitely be too long. Thus, you should structure the extension to add a request to an internal queue in the extension code and immediately return. Use a separate thread owned by the extension to process this queue.
You can create a separate thread in the initialization call to the C/C++ extension’s init-entry routine. Remember to destroy the thread on the corresponding init-entry uninitialization call.
When adding a request to an internal queue for processing later, copy the data returned by dictionary get requests, because any pointers returned in C/C++ are typically invalid by the time the thread processing the queue runs.
Using the pre-dns-add-forward Extension to Process DNS RequestsThe DHCP server does the following to processes DNS work item requests:
1. Builds up a name to use for the A record—The DHCP server creates the name that it will use in the forward (A record) DNS request.
2. At this point, use the pre-dns-add-forward extension point. You can use this extension point to alter the name used for the DNS forward (A record) request.
4-14Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsExtension Dictionaries
3. Attempts to add the name, asserting that none exists yet—At this stage, the prerequisites for the DNS name update request indicate that the name should not exist. If it succeeds, the DHCP server proceeds to the next task, which is to update the reverse record.
4. Attempts to add the name, asserting that the DHCP server should supply it—The DHCP server attempts to add the host name, asserting that it exists and that is has the same TXT record as the one that was sent. If this succeeds, the server proceeds to the next task, which is to update the reverse record. If it fails, the server checks if it exhausted its naming retries. If it did, it exits and logs an error. If not, it returns to the first step, which is to build up a name for the A record.
5. Updates the reverse record—Now that the DHCP server knows which name to associate with the reverse (PTR) record, it can update the reverse record with no prerequisites, because it can assume it is the owner of the record. If the update fails, the DHCP server logs an error.
Extension DictionariesEvery extension is defined as a routine with three arguments. These arguments represent the request dictionary, response dictionary, and environment dictionary. Not every dictionary is available to every extension. Table 4-1 shows the extensions points and the dictionaries that are available to them.
Each of the three dictionaries consists of name-value pairs. The environment dictionary, which is available to every extension point, is the simplest dictionary. It consists of a set of name-value pairs in which the name and the value are both strings. The request and response dictionaries are more complex and their data is typed. Thus, when you set a value in one of these dictionaries, you need to match the data type to the value. You can use the dictionaries for getting, putting, and removing values.
Environment DictionaryThe environment dictionary is available at all extension points. It is strictly a set of name-value pairs in which both the name and the value are strings.
The DHCP server uses the environment dictionary to communicate with extensions in different ways at different extension points. At some extension points, the server places information in the environment dictionary for the extension to modify. In others, the extension may place values in the environment dictionary to control the flow or data after the extension completed its processing.
Table 4-1 Extensions Points and Dictionaries
Extension Point Dictionary
check-lease-acceptable Request, Response, Environment
init-entry: initialize Environment
init-entry: uninitialize Environment
post-client-lookup Request, Environment
post-packet-decode Request, Environment
post-send-packet Request, Response, Environment
pre-client-lookup Request, Environment
pre-packet-encode Request, Response, Environment
pre-dns-add-forward Environment
4-15Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsExtension Dictionaries
The environment dictionary is unique in that an extension may put any name-value pair it wishes in it. Although you will not get an error for using undocumented name-values, the server does not recognize them.
The DHCP server creates the environment dictionary when a DHCP request arrives and the dictionary remains with that request through the processing. Thus, an extension that runs at the post-packet-decode extension point may put data into the environment dictionary, and then an extension run at the pre-packet-encode extension point might read that information from the dictionary.
Note The extension point pre-dns-add-forward has an environment dictionary that is not the same as other extension points use. The extension point init-entry also has a unique environment dictionary only.
The following data items are always valid in the environment dictionary:
• extension-point (read-only)—Name of the extension point. It is made available to an extension so that one extension may run at several extension points and determine from which point it is called.
• extension-name-sequence (read-only)—Maps to a comma-separated string representing the configuration for this extension point. It allows an extension to determine the environment in which it is running. All the extensions that you configure for this extension point must be listed in sequential order and separated by commas. Any position in the sequence without an extension configured must be represented by adjacent commas. For example, to configure tclfirst as the first position in the sequence and dexscript as the fifth position in the sequence, you would use tclfirst,,,,dexscript.
• extension-name (read-only)—Name with which the extension was configured. The same piece of code can be configured as several different extensions and at several different extension points. This allows one piece of code to do different things, depending on how it is configured. The code can also use this string to find itself in the extension-name-sequence string, for which it needs to know its own name.
• extension-sequence (read-only)—String that is the sequence number of this extension at this extension point.
• trace-level (write-only)—Setting this to a number makes that number the current setting of extension-trace-level for all extensions processing this request.
Request and Response DictionariesThese dictionaries have a fixed set of accessible names. However, not all the names are accessible from every extension point. These dictionaries make internal server data structures available to the extension for read-write or in some cases, read-only access. Each data item has a particular data type. If you omit the correct data type (for C/C++ extensions) on a put operation, or if the DHCP server cannot convert it to the correct data type (for TCL extensions), the extension encounters an error.
The request dictionary is available at the beginning of the processing of a request. After the DHCP server creates a response, both the request and response dictionaries are available. It is an error to access a response dictionary before it is available.
In general, you cannot use an extension to change information that is configurable in the server. In some cases, however, you can use an extension to change configured information, but only for the duration of the processing for just that single request.
4-16Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsExtension Dictionaries
Decoded DHCP Packet Data Items
The DHCP protocol is a request-response UDP-based protocol and, thus, the stimulation for a DHCP server operation is usually a DHCP request from a client. The result is usually a DHCP response to be sent back to that client.
The DHCP extension facility makes the information input in the DHCP request available to extensions at most of the extension points, and the information to be sent as a response to a DHCP request available at the pre-packet-encode extension point.
In addition to this DHCP packet-based information, there is additional information that the DHCP server uses when processing DHCP requests. This information is associated with either the DHCP request or the DHCP response as part of the architecture of the DHCP server. Much of this information is also made available to extensions, and much of it can be both read and written—in many cases altering the processing algorithms of the DHCP server.
The request and response dictionaries, therefore, contain two classes of information in each dictionary. They contain decoded packet data items as well as other request or response associated data items. The decoded packet data items are those data items that are directly contained in or derived from the DHCP request or DHCP response. Access to the decoded packet data items allows you to read and, in some cases, rewrite the DHCP request and DHCP response packet. Figure 4-1 on page 4-17 shows the relationship between the request and the response dictionaries.
You can access information from the DHCP request packet, such as the giaddr, ciaddr, and all the incoming DHCP options by using the decoded packet data items in the request dictionary. Similarly, you can set the ciaddr and giaddr, and add and remove DHCP options in the outgoing DHCP response by accessing the decoded packet data items in the response dictionary.
Figure 4-1 Extensions Request and Response Dictionaries
It is important to realize that access to the packet information provided by the decoded packet data items is not all available to you. In the description of each extension point, the specific data items available to that extension point are listed. Because the decoded packet data items are always accessible as a group, they are listed as a group, which is the decoded packet data items. See the “Decoded DHCP Packet Data Items” section on page C-1 in this guide.
You access DHCP options by name. If the option is not present, no data is returned for that option. If you place an option into the decoded request or decoded response, it replaces any option with the same name already in the decoded request or decoded response, unless in the put operation the data is specifically supposed to be appended to existing data.
Request directory Response directory
Request packetDecodedpacket
data items
Additionalrequest-associatedinformation
Response packet
Additionalresponse-associatedinformation
1242
9
4-17Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsExtension Point Descriptions
Some DHCP options may have multiple values; for example, the routers option may have one or more IP addresses associated with it. These multiple values are accessed using indexed operations on the option name.
Note A clear operation on the request or response dictionary removes all the options in the decoded packet.
Using the dhcp-parameter-request-list Option
There is one option, dhcp-parameter-request-list, that is handled specially in two ways:
• It is available as a multiple-valued option of bytes under the name dhcp-parameter-request-list.
• It is also available as a blob-valued (a sequence of bytes) option under the name dhcp-parameter-request-list-blob.
You can get or put it using either name. The DHCP server handles the dhcp-parameter-request-list (and its blob variant as well) differently in the response dictionary than in the request dictionary. When it is accessed in the request dictionary, this option is just another DHCP option in the request dictionary. In the response dictionary, however, special processing takes place.
You can use the dhcp-parameter-request-list option in the response dictionary to control the order of the options returned to the DHCP or BOOTP client. When you put the option in the response dictionary, the DHCP server reorders the existing options so that the ones listed in the option are first and in the order that they appear in the list. Then, the remaining options appear in their current order after the last ones that were in the list. The DHCP server retains the list, and uses it to order any future options that are put into the response, until it is replaced by a new list.
When an extension does a get operation for the dhcp-parameter-request-list in the response dictionary, it does not look in the decoded response packet to find an option. Instead, the DHCP server synthesizes one that contains the list of all options currently in the decoded response packet.
Extension Point DescriptionsThe following sections describe each extension point, the actions, and the data items that are appropriate for each one. For all the extension points, you can read the extension-point and set trace-level in the environment dictionary. For most extension points, you can also tell the server to drop the packet.
Environment DictionaryThe following data items are available to all extension points:
• drop (read/write)—If the drop value is equal to the string true when the extension exits, the DHCP server drops the input packet and logs a message in the log file.
• extension-point (read-only)—Name of the extension point. For example, post-packet-decode.
• log-drop-message (read/write)—If the drop value is equal to the string true and the log-drop-message value is equal to the string false when the extension exits, the DHCP server drops the input packet, but does not log a message in the log file.
• trace-level (write-only)—Extension-trace-level for all extensions processing this request. Note that level 3 provides detailed information.
4-18Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsExtension Point Descriptions
For all extension points that have a request dictionary, the data items that begin with log and verbose-logging can be set at any time. The DHCP server reads them as needed.
post-packet-decodeThe dictionaries available are Request and Environment.
The post-packet-decode is the first extension point the DHCP server encounters when a request arrives. This extension point immediately follows the decoding of the input packet and precedes any processing on the data in the packet. The primary activity for an extension at this point is to read information from an input packet and do something with it. For example, you might use this extension point to rewrite the input packet.
This is one of the easiest extension points to use. If you can express the change in server behavior as a rewrite of the input DHCP or BOOTP packet, you should use this extension point. Because the packet was decoded, but not processed in any way, the number of side effects that you have to be aware of are very limited.
This is the only extension point at which you can make modifications to the decoded input packet and ensure that all the modifications are recognized.
If the extension decides that the packet should be dropped, and further processing terminated, it may do so by using the drop data item in the environment dictionary.
All of the decoded packet data items are specified in Appendix C, “DHCP Extension Dictionary Entries.” Table 4-2 lists items that are available in the post-packet-decode request dictionary.
pre-client-lookupThe dictionaries available are Request and Environment.
You can only use the pre-client-lookup extension point if you enabled client-class processing for your DHCP server. This extension point allows an extension to perform any or all of the following actions:
• Modify the client that is looked up during client-class processing.
• Specify individual data items to override any data items found from the client entry or the client-class it specifies.
• Instruct the server to skip the client lookup altogether. In this case, the only client data used is one that was supplied by the extension in the environment dictionary.
Although the request dictionary is available to make decisions about the operation of an extension running at this extension point, all the operations are controlled through the environment dictionary.
Table 4-2 post-packet-decode Data Items
Item Value Operation
client-port int read/write
client-ipaddress IP address read/write
os-type string read/write
release-by-ip int read/write
transaction-time int read-only
4-19Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsExtension Point Descriptions
Environment Dictionary
The following items are available at pre-client-lookup for client-class control:
• client-specifier (read/write)—Name of the client the client-class processing code looks up, either in MCD or LDAP. If you change it at this extension point, then the DHCP server will look up whatever client is specified.
• default-client-class-name (read/write)—Instructs the server to use the value associated with the default-client-class-name option as the class-name if:
– The client-specifier was not specified in the pre-client-lookup script.
– The specific client entry could not be located.
The default-client-class-name then assumes precedence over the class-name associated with the default client.
• release-by-ip (read/write)—Instructs the server to release the lease by the IP address if the lease cannot be retrieved by the client-id (derived from the DHCPRELEASE request).
• skip-client-lookup (read/write)—If you set this item to true, the DHCP server skips the normal client lookup that it would have performed immediately upon exit from this extension. In this case, the only data items used to describe this client are those placed in the environment dictionary.
Client-Class Data Input
If you set the following data items, their values override those determined from the client lookup (either in the internal database or from LDAP). If you do not add anything to the dictionary, then the server uses what is in the client value, or key.
• host-name (read/write)—Use this for the client in preference to the host-name options specified in the input packet, or any data from the client-entry or the client-class entry. If you set this to none, the DHCP server does not use any information from the client-entry or the client-class entry, but uses the name from the client’s request.
• domain-name (read/write)—Use this domain name for the client’s DNS operations in preference to the one specified in the scope. Note that the DNS server shown as the primary server for the domain in the scope must also be the primary server for the domain you specified. If there is no override for the domain name in the client entry or the client-class entry, the DHCP server uses the domain name from the scope. If the client entry or the extension contains the word none, the DHCP server uses the domain name from the scope.
• policy-name (read/write)—Use this policy as the policy specified for the client entry, overriding any policy specified by that client entry.
• action (read/write)—Convert this string to a number and use the result as the action. The numbers you can use are 0x1 (for exclude) and 0x2 (for one-shot).
• selection-criteria (read/write)—List of comma-separated strings, each specifying (for this input packet) a scope selection criteria for this client. Any scope this client uses must have all of these selection tags.
Use this to override any criteria specified in the client or client-class entry. If you do, the DHCP server does not use the client-entry’s selection criteria, independent of whether they were stored in the local database or in an LDAP database. If you set this to none, the DHCP server does not use selection tags for this packet. If you set this to a null string, the DHCP server treats it as if it were not set and uses the selection criteria from the client or the client-class entry.
4-20Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsExtension Point Descriptions
• selection-criteria-excluded (read/write)—List of comma-separated strings, each specifying (for this input) an exclusion criteria for this client. Any scope this client uses must not have any of these selection tags.
Use this to override any specified client or client-class entries. If you do, the DHCP server does not use the client entry’s exclusion criteria, independent of whether they were stored in the local database or in an LDAP database. If you set this to none, the DHCP server does not use any exclusion tags for this packet. If you set this to a null string, the DHCP server treats is as if it were not set and uses the exclusion criteria from the client or client-class entry.
• client-class-name (read/write)—Use the client-class specified by this data item to fill in the missing information in the client-entry. If there is no client-class corresponding to the name specified, the DHCP server logs a warning and continues processing. If you specify none, the DHCP server acts as if there is no client-class name specified in this client-entry.
• authenticate-until (read/write)—Absolute time, measured in seconds, from January 1, 1970. Use to indicate the time at which the client’s authentication expires. When the client’s authentication expires, the DHCP server uses the values in the client’s unauthenticated-client-class option instead of its client-class to fill in missing data items in the client-entry.
• unauthenticated-client-class-name (read/write)—Name of the client-class to use if the client is not authenticated. If you want to indicate that no unauthenticated-client-class-name is specified, then use an illegal client-class name as the value of this data item. The value none is fine, but any name that is not a client-class name will do. The DHCP server logs an error that the client-class is not present.
Request Dictionary
You can use all of the decoded packet data items specified in Appendix C, “DHCP Extension Dictionary Entries.” Table 4-3 describes request information items that are available in the pre-client-lookup request dictionary.
Table 4-4 describes client information items that are available in the pre-client lookup request dictionary.
Table 4-3 pre-client-lookup Request Information Data Items
Data Items Value Operation
client-ipaddress IP address read/write
client-port int read/write
transaction-time int read-only
Table 4-4 Pre-client-lookup Client Information Data Items
Data Items Value Operation
client-id blob read/write
client-id-created-from-mac-address int read-only
client-os-type string read/write
mac-address blob read/write
client-mac-address blob read/write
4-21Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsExtension Point Descriptions
Table 4-5 describes client understanding items that are available in the pre-client-lookup request dictionary.
post-client-lookupThe dictionaries available are Environment and Request.
You can use the post-client-lookup extension point to examine the results of the entire client-class processing operation, and take an action based on those results. You might want to use it to rewrite some of the results, or to drop the packet. If you want to override the host name in the packet returned from the client class processing from a script running at the post-client-lookup script point, set the host name to the client-requested-host-name in the request dictionary. This causes Network Registrar to look to the server as though the packet came in with whatever string you specified in that data item.
You also can use this extension point to place some data items in the environment dictionary to affect the processing of some extension running at the pre-packet-encode extension point, where it might load different options into the response packet or take other actions.
Environment Dictionary
The following data items are available at post-client-lookup:
• client-specifier (read-only)—Name of the client that the client-class processing looked up.
• cnr-ldap-query-failed (read-only)—The DHCP server sets this attribute to ease recovery from LDAP server failures. In this manner, a post-client-lookup script can respond to LDAP server failure. The DHCP server, after a client lookup, sets this flag to true if the LDAP query failed because of an LDAP server error. If the server received a response from the LDAP server, one of two conditions occurs:
– The flag is set to false.
– The cnr-ldap-query-failed attribute does not appear in the environment dictionary.
Request Dictionary
You can use all the decoded packet data items described in Appendix C, “DHCP Extension Dictionary Entries.” Table 4-6 describes request information items that are available in the post-client-lookup request dictionary.
Table 4-5 pre-client-lookup Client Understanding Data Items
Data Items Value Operation
client-wants-nulls-in-string int read/write
import-packet int read/write
reply-to-client-address int read/write
4-22Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsExtension Point Descriptions
Table 4-7 describes client information items that are available in the post-client-lookup request dictionary.
Table 4-8 describes client understanding information items that are available in the post-client-lookup request dictionary.
Table 4-6 post-client-lookup Request Information Data Items
Data Items Value Operation
client-ipaddress IP address read/write
client-port int read/write
transaction-time int read-only
Table 4-7 post-client-lookup Client Information Data Items
Data Items Value Operation
client-id blob read/write
client-id-created-from-mac-address int read-only
client-mac-address blob read/write
client-os-type string read/write
mac-address blob read/write
Table 4-8 Post-Client-Lookup Client Understanding Data Items
Data Items Value Operation
client-class-name string read-only
client-class-policy string read/write
client-domain-name string read/write
client-host-name string read/write
client-policy string read/write
client-requested-host-name string read/write
client-wants-nulls-in-string int read/write
import-packet int read/write
reply-to-client-address int read/write
selection-criteria string read/write
selection-criteria-excluded string read/write
4-23Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsExtension Point Descriptions
check-lease-acceptableThe dictionaries available are Request, Response, and Environment.
This check-lease-acceptable extension point comes immediately after the server determined whether the current lease is acceptable for this client. You can use this extension to examine the results of that operation, and to cause the routine to return different results. See the “Determining If the Lease Is Acceptable” section on page 4-12.
Environment Dictionary
The following data item is available in the environment dictionary at the check-lease-acceptable extension point:
• acceptable (read/write)—The DHCP server initializes this depending on whether this lease is acceptable for this client. You can read and change this result in an extension. Setting it to the string true indicates that it is acceptable; setting it to the string false indicates that it is unacceptable.
Request Dictionary
All the data items available for pre-packet-encode are available for check-lease-acceptable request.
Response Dictionary
All the data items available for pre-packet-encode are available for check-lease-acceptable response. In addition, this item is available:
• client-os-type (read/write)—You can read and change this data item in a extension. However, you can set it only by changing os-type in the post-packet-decode request dictionary.
pre-packet-encodeThe dictionaries available are Request, Response, and Environment.
Request Dictionary
You can use all the decoded packet data items described in Appendix C, “DHCP Extension Dictionary Entries.” Table 4-9 describes request information items that are available in the pre-packet-encode request dictionary.
Table 4-9 pre-packet-encode Request Information Data Items
Data Items Value Operation
client-ipaddress ip address read/write
client-port int read/write
transaction-time int read-only
4-24Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsExtension Point Descriptions
Table 4-10 describes client information items that are available in the pre-packet-encode request dictionary.
Table 4-11 describes client understanding information items that are available in the pre-packet-encode request dictionary.
Response Dictionary
You can use all the decoded packet data item described in Appendix C, “DHCP Extension Dictionary Entries.” Table 4-12 describes data items that are available in the pre-packet-encode response dictionary.
Table 4-10 pre-packet-encode Client Information Data Items
Data Items Value Operation
client-id blob read/write
client-id-created-from-mac-address int read-only
client-macaddress blob read/write
mac-address blob read/write
Table 4-11 pre-packet-encode Client Understanding Data Items
Data Items Value Operation
client-class-name string read-only
client-class-policy string read/write
client-domain-name string read/write
client-host-name string read/write
client-policy string read/write
client-requested-host-name string read/write
client-wants-nulls-in-string int read/write
import-packet int read/write
reply-to-client-address int read/write
selection-criteria string read/write
selection-criteria-excluded string read/write
Table 4-12 pre-packet-encode Response Dictionary Data Items
Data Items Value Operation
auto-configure int read/write
reply-ipaddress IP address read/write
reply-port int read/write
scope-ping-clients int read-only
scope-renew-only int read-only
scope-renew-only-expire-time int read-only
4-25Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsExtension Point Descriptions
Table 4-13 describes client information items that are available in the pre-packet-encode response dictionary.
Table 4-14 describes lease information items that are available in the pre-packet-encode response dictionary.
scope-selection-criteria string read-only
scope-send-ack-first int read-only
transaction-time int read-only
Table 4-12 pre-packet-encode Response Dictionary Data Items (continued)
Data Items Value Operation
Table 4-13 pre-packet-encode Client Information Data Items
Data Items Value Operation
client-domain-name string read/write
client-host-name string read/write
client-id blob read/write
client-id-created-from-mac-address int read-only
client-mac-address blob read/write
client-requested-host-name string read/write
domain-name-changed int read/write
host-name-changed int read/write
host-name-in-dns int read/write
last-transaction-time int read-only
mac-address blob read/write
reverse-name-in-dns int read/write
Table 4-14 pre-packet-encode Lease Information Data Items
Data Items Value Operation
lease-deactivated int read-only
lease-ipaddress IP address read-only
lease-reserved int read-only
lease-state string read-only
start-time-of-state int read-only
4-26Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsExtension Point Descriptions
Table 4-15 describes scope address information items that are available in the pre-packet-encode response dictionary.
Table 4-16 describes scope acceptability information items that are available in the pre-packet-encode response dictionary.
Table 4-17 describes scope DNS information items that are available in the pre-packet-encode response dictionary.
pre-dns-add-forwardThe dictionary available is Environment.
You can use the pre-dns-add-forward extension point to choose the name and affect the DNS retries during update operations.
Table 4-15 pre-packet-encode Scope Address Information Data Items
Data Items Value Operation
scope-network-number IP address read-only
scope-primary-network-number IP address read-only
scope-primary-subnet-mask IP address read-only
scope-subnet-mask IP address read-only
Table 4-16 pre-packet-encode Scope Acceptability Information Data Items
Data Items Value Operation
scope-allow-bootp int read-only
scope-allow-dhcp int read-only
scope-allow-dynamic-bootp int read-only
scope-available-leases int read-only
scope-deactivated int read-only
Table 4-17 pre-packet-encode Scope DNS Information Data Items
Data Items Value Operation
scope-dns-forward-server-address IP address read-only
scope-dns-forward-zone-name string read-only
scope-dns-number-of-host-bytes int read-only
scope-dns-reverse-server-address IP address read-only
scope-dns-reverse-zone-name string read-only
scope-update-dns-enabled int read-only
scope-update-dns-for-bootp int read-only
4-27Network Registrar CLI Reference Guide
78-12875-01
Chapter 4 Using Extension PointsExtension Point Descriptions
Environment Dictionary
The following data items are available in the environment dictionary at the pre-dns-add-forward extension point:
• host-name (read/write)—Host name that the DHCP server tries next when updating the DNS server. You can use an extension to read and change the name.
• txt-string (read/write)—TXT record string the DHCP server writes to DNS. By default this is the client-id rendered as a blob, but it can be anything. It identifies this client as the owner of this name, so correct operation relies on a one-to-one mapping between the text string and the client.
• domain-name (read-only)—Domain name the DHCP server uses for DNS updates.
• renaming-retries (read-only)—Current renaming retry count.
• maximum-renaming-retries (read/write)—Maximum number of renaming retries.
• last-name-number (read/write)—Last number that was used to disambiguate a DNS name.
• last-name-number-length (read/write)—Length of that number, that is, the number of characters it used in the name when rendered as a decimal number.
• ignore-prerequisites (read/write)—If you set it to true, the DHCP server ignores the setting of the prerequisites on the DNS A record update, which will cause the last client to attempt to get a name to succeed. The default behavior of the DHCP server is for the first client to use a name to get the name and for later clients to get a disambiguated name.
• continue (read/write)—The DHCP server will continue to update DNS if any renaming retries are left. If you set this to false, the DHCP server stops attempting to update DNS, even if renaming retries remain.
4-28Network Registrar CLI Reference Guide
78-12875-01
Ne78-12875-01
A P P E N D I X A
Codes and FormatsThis appendix provides information about the status codes, and the import and export formats.
Status ReturnsNrcmd returns status information on the first line of information written to the standard output stream. If there is more data, Nrcmd displays this information on additional lines.
The first line consists of a numeric status that is followed by a human-readable error status.
The status codes are all three-digit integer decimal numbers. The range 100-599, are grouped as follows in Table A-1:
For anything other than an error, Network Registrar assumes that the requested operation was completed; however, some warning messages signal a condition that must be corrected. Unless a fatal error occurs, the command line interface will keep running in interactive mode. Fatal errors imply that something serious happened and that you must restart the Network Registrar command line processor.
Network Registrar Error CodesTable A-2 lists and describes the Network Registrar error codes.
Table A-1 Status Information
Value Description
100-199 Normal return
200-299 Informational (warning)
300-499 Error
500-599 Fatal Error
Table A-2 Error Codes
Number Description
100 OK
101 OK, with warnings
A-1twork Registrar CLI Reference Guide
Appendix A Codes and FormatsNetwork Registrar Error Codes
102 Lease already reserved to this client
103 Lease not reserved
104 Lease deleted along with reservation
105 Lease created along with reservation
106 Assertion failed
107 NamespaceID currently in use by at least one scope
204 Assigned host is not contained in pool zone
301 No Server Found
302 Not Found
303 Read only property
304 No Policy Found
305 Too many
306 Unknown command
307 Unknown keyword
308 Unknown parameter
309 Too many arguments
310 Too few arguments
311 No response to lease request
312 Unexpected response from server
313 No match
314 Duplicate object
315 Import Failure
316 Invalid
317 Open failed
318 No MAC Address Found
319 No Lease Found
320 Generic error
321 Invalid name
322 Feature not supported
323 Read error
324 Invalid IP address list
325 Invalid type
326 ODBC Database access error
327 IP address not contained within pool subnet
328 Identical MX resource record already exists
329 Identical TXT resource record already exists
Table A-2 Error Codes (continued)
Number Description
A-2Network Registrar CLI Reference Guide
78-12875-01
Appendix A Codes and FormatsNetwork Registrar Error Codes
330 Address is not contained in pool
331 Host is already assigned to an address
332 Address is already assigned to a host
333 No unassigned IP address found in pool
334 Address has not been assigned to a host
335 Static address pools are not enabled, create a pool to enable
336 Range overlaps another pool
337 Host has multiple IP address assignments
338 Address has multiple host assignments, must supply <name> argument
339 Expected unsigned 16-bit preference value
340 ODBC 3.x or higher required;
350 Generic DHCP error
351 Cannot resolve partner name to an IP address
352 No failover object for specified partner
353 Still communicating with partner
354 Server is already in partner-down state
355 Cannot set partner-down while in recover
356 Not allowed in read-only mode
357 Not a secondary
358 Not a primary
359 No zone matched
360 Force xfer for this zone is already scheduled
361 Lease is not reserved
362 Scope unknown in server
363 Invalid IP address in server
364 Invalid MAC address in server
365 Failure creating MAC address in server
366 Unknown object in server
367 Command not supported by server
368 Bad length in server
369 Inconsistent scope in server
370 updateSMS not configured in server
371 Server out of memory
372 SMS interface .dll did not load correctly
373 updateSMS already processing in server
374 Invalid word array
Table A-2 Error Codes (continued)
Number Description
A-3Network Registrar CLI Reference Guide
78-12875-01
Appendix A Codes and FormatsNetwork Registrar Error Codes
375 updateSMS Invalid argument
376 Lease is reserved to a different client
377 Client already reserved a different lease
378 Field name or number not found
379 Suboption name or number already exists
380 Suboption name or number not found
381 Invalid character '-' in vendor-option name
382 Data not found for vendor-option
383 Field name or number already exists
384 counted-array can only be used with array types
385 Read-only attribute cannot be modified
386 Required attribute cannot be unset
387 Invalid namespace ID
388 Invalid IP Address syntax
389 Invalid namespace name
390 Invalid IP Address value
391 Invalid namespace specification
392 Cannot remove sessions current namespace
393 Duplicate property
394 Invalid namespace id specification
395 Lease has no scope pointer -- internal error
401 Login Failure
402 Permission denied
403 Couldn't lock database
404 Login Required
405 Invalid license key
406 A lock is required for this operation
407 Unable to release lock
408 Unable to obtain lock
409 Couldn't lock static address pool
501 Connection Failure
502 Server Failure
503 Cluster Version Failure
Table A-2 Error Codes (continued)
Number Description
A-4Network Registrar CLI Reference Guide
78-12875-01
Appendix A Codes and FormatsImport and Export File Formats
Import and Export File FormatsThis section describes the import leases and export leases file format.
The syntax is:
field1|field2|field3|…
The fields are listed next. If, in the import file, you chose not to supply the information for an optional field, you need to use delimiters ( | ) so that the number of fields is still 12. For example, type xyz|abc||123.
• MAC address in xx:xx:xx:…:xx format (required)
• MAC address type (required)
• MAC address length (required)
• IP address in dotted decimal format, a.b.c.d (required)
• Start of lease time (GMT) (optional)
• Lease expiration time (GMT) (optional)
• Allowable extension time (GMT)(optional)
• Last transaction time (GMT) (optional)
• IP address of the DHCP server (optional)
• Host name (without domain) (optional)
• Domain name (optional)
• Client ID (optional)
• Namespace (optional; if omitted, it is the global namespace)
Note For all the time fields, you can use either the number of seconds since 1970, or day, month, date, time, year format (Mon Apr 13 16:35:48 1998).
A-5Network Registrar CLI Reference Guide
78-12875-01
Appendix A Codes and FormatsImport and Export File Formats
A-6Network Registrar CLI Reference Guide
78-12875-01
Ne78-12875-01
A P P E N D I X B
DHCP Extension Dictionary APIA dictionary is a data structure that contains key-value pairs. There are two types of dictionaries: the attribute dictionaries that are used by the request and response dictionaries, and the environment dictionary.
This appendix contains the dictionary method calls you can use when accessing dictionaries from Tcl extensions and from shared libraries.
Tcl Attribute Dictionary APIAn attribute dictionary is a dictionary in which the keys are constrained to be the names of attributes as defined in the Access Registrar server configuration, and the values are the string representation of the legal values for that particular attribute. For example, IP addresses are specified by the dotted-decimal string representation of the address, and enumerated values are specified by the name of the enumeration. This means that numbers are specified by the string representation of the number.
Attribute dictionaries have the unusual feature that there can be more than one instance of a particular key in the dictionary. These instances are ordered, with the first instance at index zero. Some of the methods of an attribute dictionary allow an index to be specified to indicate a particular instance or position in the list of instances to be referenced.
Attribute Dictionary MethodsAttribute dictionaries use commands that allow you to change and access the values in the dictionaries. Table B-1 lists the commands that you can use with the request and response dictionaries.
Table B-1 Tcl Attribute Dictionary Methods
Name Syntax
get $dict get attribute [index [bMore] ]
Returns the value of the attribute from the dictionary, represented as a string. If the dictionary does not contain the attribute, the empty string is returned instead.
If you include the index value, this returns the indexth instance of the attribute. Some attributes can appear more than once in the request or response packet. The index selects which instance to return.
If you include the bMore, the get method sets bMore to TRUE if there are more attributes after the one returned, and to FALSE otherwise. You can use this to determine whether to make another call to get to retrieve other instances of the attribute.
B-1twork Registrar CLI Reference Guide
Appendix B DHCP Extension Dictionary APITcl Attribute Dictionary API
Tcl Environment Dictionary MethodsA dictionary is a data structure that contains key/value pairs. An environment dictionary is a dictionary in which the keys and values are constrained to be strings. The environment dictionary is used to communicate information from the extension to the server and from extension to extension within the processing of a particular request. Note that there can be only one instance of a key in the environment dictionary.
Table B-2 describes the commands that you can use with the environment dictionary.
log $dict log level message …
Outputs a message into the DHCP server’s logging system. The level should be LOG_ERROR, LOG_WARNING, or LOG_INFO. The remaining arguments are concatenated together and sent to the logging system at the specified level.
remove $dict remove attribute [index]
Removes the attribute from the dictionary. If you omit the index or set it to the special value REMOVE_ALL, this removes any existing instances of the attribute. If you include the index as a number, this removes the instance of the attribute at the position indicated. This method always returns 1, even if the dictionary does not contain that attribute at that index.
put $dict put attribute value [index]
Associates a value with the attribute in the dictionary. If you omit the index or set it to the special value REPLACE, this replaces any existing instances of the attribute with the single value. If you include the index value and as the special value APPEND, this appends a new instance of the attribute to the end of the list of instances of the attribute. If you include the index value as a number, this inserts a new instance of the attribute at the position indicated. If you set the index value to the special value AUGMENT, this only puts the attribute if there is not one already.
trace $dict trace level message …
Outputs a message into the packet tracing system used by the DHCP server. At level 0, no tracing occurs. At level 1, only an indication that the server received the packet and sent a reply is output. As the number gets higher, the amount of data output increases, until at level 4 everything is traced as output. The remaining arguments are concatenated and sent to the tracing system at the specified level.
Table B-1 Tcl Attribute Dictionary Methods (continued)
Name Syntax
Table B-2 Tcl Environment Dictionary Methods
Name Syntax
clear $dict clear
Removes all entries from the dictionary.
containsKey $dict containsKey key
Returns 1 if the dictionary contains the key, otherwise returns 0.
firstKey $dict firstKey
Returns the name of the first key in the dictionary. Note that the keys are not stored sorted by name.
B-2Network Registrar CLI Reference Guide
78-12875-01
Appendix B DHCP Extension Dictionary APIDEX Attribute Dictionary API
DEX Attribute Dictionary APIA dictionary is a data structure that contains key-value pairs. An attribute dictionary is a dictionary in which the keys are constrained to be the attributes as defined in the DHCP server configuration, and the values are constrained to be legal values for that particular attribute. Attribute dictionaries have the unusual feature that there can be more than one instance of a particular key in the dictionary. These instances are ordered, with the first instance at index 0. Some of the methods of an attribute dictionary allow an index to be specified to indicate a particular instance or position in the list of instances to be referenced.
When writing DEX extensions (DHCP Extensions), you can specify keys as the string representation of the name of the attribute or by type, which is a byte sequence defining the attribute. The values can also be specified as the string representation of the value or as the byte sequence, which is the attribute. These options mean that some of these access methods have four different variations that are the combinations of string or type for the key, and string or bytes for the value.
get $dict get key
Returns the value of the key from the dictionary. If the dictionary does not contain the key, the empty string is returned instead.
isEmpty $dict isEmpty
Returns 1 if the dictionary has no entries, otherwise returns 0.
log $dict log level message …
Outputs a message into the logging system used by the DHCP server, level should be one of the LOG_ERROR, LOG_WARNING or LOG_INFO. The remaining arguments are concatenated together and sent to the logging system at the specified level.
nextKey $dict nextKey
Returns the name of the next key in the dictionary that follows the key returned in the last call to firstKey or nextKey.
put $dict put key value
Associates value with the key in the dictionary, replacing an existing instance of key with the new value.
remove $dict remove key
Removes the key from the dictionary. Always returns 1, even if the dictionary did not contain the key.
size $dict size
Returns the number of entries in the dictionary.
trace $dict trace level message …
Outputs a message into the packet tracing system used by the DHCP server. At level 0, no tracing occurs. At level 1, only an indication that the server received the packet and sent a reply is output. As the number gets higher, the amount of information output is greater, until at level 4 everything the server traces is output. The remaining arguments are concatenated together and sent to the tracing system at the specified level.
Table B-2 Tcl Environment Dictionary Methods (continued)
Name Syntax
B-3Network Registrar CLI Reference Guide
78-12875-01
Appendix B DHCP Extension Dictionary APIDEX Attribute Dictionary API
Attribute Dictionary MethodsAttribute dictionaries use active commands, called methods, that allow you to change and access the values in the dictionaries. Table B-3 lists the methods that you can use with the request and response dictionaries.
Table B-3 DEX Attribute Dictionary Methods
Name Syntax
allocateMemory void* pDict->allocateMemory ( dex_AttributeDictionary_t* pDict, unsigned int iSize )
Allocates memory for use in scripts that persists only for the lifetime of this request. This memory is released when processing for this request is complete.
get const char* pDict->get ( dex_AttributeDictionary_t* pDict, const char* pszAttribute, int iIndex,abool_t* pbMore )
Returns the value of the iIndex’d instance of the attribute from the dictionary, represented as a string. If the dictionary does not contain the attribute (or that many instances of the attribute), the empty string is returned instead.
If pbMore is non-zero, the get method will set pbMore to TRUE if there are more instances of the attribute after the one returned and to FALSE otherwise. This can be used to determine whether another call to 'get' should be made to retrieve other instances of the attribute.
getBytes const abytes_t* pDict->getBytes ( dex_AttributeDictionary_t* pDict, const char* pszAttribute, int iIndex, abool_t* pbMore )
Returns the value of the iIndex’d instance of the attribute from the dictionary, as a sequence of bytes. If the dictionary does not contain the attribute (or that many instances of the attribute), returns 0 instead. If pbMore is non-zero, the getBytes method sets pbMore to TRUE if there are more instances of the attribute after the one returned, and to FALSE otherwise. This can be used to determine whether another call to getBytes should be made to retrieve other instances of the attribute.
getByType constabytes_t* pDict->getByType ( dex_AttributeDictionary_t* pDict, const char* pszKey)
Returns the value of the iIndex’d instance of the attribute from the dictionary, as represented as a string. If the dictionary does not contain the attribute (or that many instances of the attribute), returns the empty string instead. If pbMore is non-zero, the getByType method sets pbMore to TRUE if there are more instances of the attribute after the one returned and to FALSE otherwise. This can be used to determine whether another call to getByType should be made to retrieve other instances of the attribute.
getBytesByType const abytes_t* pDict-> getBytesByType ( dex_AttributeDictionary_t* pDict,const abytes_t* pAttribute, int iIndex,abool_t* pbMore )
Returns the value of the iIndex'd instance of the attribute from the dictionary, as a sequence of bytes. If the dictionary does not contain the attribute (or that many instances of the attribute), 0 is returned instead.
If pbMore is non-zero, sets the variable pointed to TRUE if there are more instances of the attribute after the one returned and to FALSE otherwise. This can be used to determine whether another call to 'get' should be made to retrieve other instances of the attribute.
B-4Network Registrar CLI Reference Guide
78-12875-01
Appendix B DHCP Extension Dictionary APIDEX Attribute Dictionary API
getType const char* pDict->getByType ( dex_AttributeDictionary_t* pDict, const abytes_t* pAttribute )
Returns a pointer to the byte sequence defining the attribute, if the attribute name matches a configured attribute, 0 otherwise.
log abool_t pDict->log ( dex_AttributeDictionary_t* pDict, int iLevel, const char* pszFormat, ... )
Outputs a message into the logging system used by the DHCP server. iLevel should be one of DEX_LOG_ERROR, DEX_LOG_WARNING or DEX_LOG_INFO. The pszFormat argument is treated as a printf-style format string, and it, along with the remaining arguments, are formatted and sent to the logging system at the specified level.
put abool_t pDict->put ( dex_AttributeDictionary_t* pDict, const char* pszAttribute, const char* pszValue, int iIndex )
Converts pszValue to a sequence of bytes, according to the definition of pszAttribute in the server configuration. Associates that sequence of bytes with the attribute in the dictionary. If iIndex equals the special value DEX_REPLACE, replaces any existing instances of the attribute with a single value. If iIndex equals the special value DEX_APPEND, it appends a new instance of the attribute to the end of the list of existing instances of the attribute. Otherwise, a new instance of the attribute is inserted at the position indicated. This method returns TRUE unless the attribute name does not match any configured attributes or the value could not be converted to a legal value. If iIndex equals the special value DEX_AUGMENT, only puts the attribute if there is not one already.
putByType abool_t pDict->putByType ( dex_AttributeDictionary_t* pDict, const abytes_t* pAttribute, const char* pszValue, int iIndex )
Converts pszValue to a sequence of bytes, according to the definition of pszAttribute in the server configuration. Associates that sequence of bytes with the attribute in the dictionary. If iIndex equals the special value DEX_REPLACE, replaces any existing instances of the attribute with a single new value. If iIndex equals the special value DEX_APPEND, appends a new instance of attribute to the end of the list of existing instances of the attribute. Otherwise, inserts a new instance of the attribute at the position indicated. This method returns TRUE unless the attribute name does not match any configured attributes or the value could not be converted to a legal value.
putBytes abool_t pDict->putBytes ( dex_AttributeDictionary_t* pDict, const char* pszAttribute, const abytes_t* pValue, int iIndex )
Associates pValue with the attribute pszAttribute in the dictionary. If iIndex equals the special value DEX_REPLACE, replaces any existing instances of the attribute with a single new value. If iIndex equals the special value DEX_APPEND, appends a new instance of attribute to the end of the list of existing instances of the attribute. If iIndex equals the special value DEX_AUGMENT, only puts the attribute if there is not one already. Otherwise, a new instance of the attribute is inserted at the position indicated. This method returns TRUE unless the attribute name does not match any configured attributes.
Table B-3 DEX Attribute Dictionary Methods (continued)
Name Syntax
B-5Network Registrar CLI Reference Guide
78-12875-01
Appendix B DHCP Extension Dictionary APIDEX Attribute Dictionary API
DEX Environment Dictionary APIA dictionary is a data structure that contains key/value pairs. An environment dictionary is a dictionary in which the keys and values are constrained to be strings. The environment dictionary is used to communicate information from the script to the server and from script to script within the processing of a particular request. Note that there can be only one instance of a key in the environment dictionary.
DEX Environment Dictionary MethodsThe environment dictionary uses active commands, called methods, that allow you to change and access the values in the dictionary. Table B-4 lists the methods that you can use with the environment dictionary.
putBytesByType abool_t pDict->putBytesByType ( dex_AttributeDictionary_t* pDict,const abytes_t* pAttribute,const abytes_t* pValue, int iIndex )
Associates pValue with the attribute pszAttribute in the dictionary. If iIndex equals the special value DEX_REPLACE, replaces any existing instances of the attribute with the new value. If iIndex equals the special value DEX_APPEND, appends a new instance of attribute to the end of the list of existing instances of the attribute. If iIndex equals the special value DEX_AUGMENT, only puts the attribute if there is not one already. Otherwise, inserts a new instance of the attribute at the position indicated. This method returns TRUE unless the attribute name does not match any configured attributes.
remove abool_t pDict->remove ( dex_AttributeDictionary_t* pDict, const char* pszAttribute, int iIndex )
Removes the attribute from the dictionary. If iIndex equals the special value DEX_REMOVE_ALL, remove any existing instances of the attribute. Otherwise, removes the instance of the attribute at the position indicated. Returns TRUE, even if the dictionary did not contain that attribute at that index, unless the attribute name does not match any configured attribute.
removeByType abool_t pDict->removeByType ( dex_AttributeDictionary_t* pDict, const abytes_t* pAttribute, int iIndex )
Removes the attribute from the dictionary. If iIndex equals the special value DEX_REMOVE_ALL, removes any existing instances of the attribute. Otherwise, the instance of the attribute at the position indicated is removed. Always returns TRUE, even if the dictionary does not contain that attribute at that index.
trace abool_t pDict->trace ( dex_AttributeDictionary_t* pDict, int iLevel, const char* pszFormat, ... )
Outputs a message into the packet tracing system used by the DHCP server. At level 0 no tracing occurs. At level 1 only an indication that the packet was received and a reply was sent is output. As the number gets higher, the amount of information output is greater, until at level 4 everything traceable is output. The remaining arguments are formatted and sent to the tracing system at the specified level.
Table B-3 DEX Attribute Dictionary Methods (continued)
Name Syntax
B-6Network Registrar CLI Reference Guide
78-12875-01
Appendix B DHCP Extension Dictionary APIDEX Attribute Dictionary API
Table B-4 DEX Environment Dictionary Methods
Name Syntax
allocateMemory void* pDict->allocateMemory ( dex_EnvironmentDictionary_t* pDict, unsigned int iSize )
Allocates memory for use in scripts that persist only for the lifetime of this request. This memory is released when processing for this request is complete.
clear void pDict->clear ( dex_EnvironmentDictionary_t* pDict )
Removes all entries from the dictionary.
containsKey abool_t pDict->containsKey ( dex_EnvironmentDictionary_t* pDict,const char* pszKey )
Returns TRUE if the dictionary contains the key, otherwise returns FALSE.
firstKey const char* pDict->firstKey ( dex_EnvironmentDictionary_t* pDict )
Returns the name of the first key in the dictionary. Note that the keys are not stored sorted by name.
get const char* pDict->get ( dex_EnvironmentDictionary_t* pDict, const char* pszKey )
Returns the value associated with the key from the dictionary. If the dictionary does not contain the key, the empty string is returned.
isEmpty abool_t pDict->isEmpty ( dex_EnvironmentDictionary_t* pDict )
Returns TRUE if the dictionary has 0 entries, FALSE otherwise.
log abool_t pDict->log ( dex_EnvironmentDictionary_t* pDict, int iLevel, const char* pszFormat, ... )
Outputs a message into the logging system used by the DHCP server. iLevel should be one of DEX_LOG_ERROR, DEX_LOG_WARNING or DEX_LOG_INFO. The pszFormat argument is treated as a printf-style format string, and it, along with the remaining arguments, are formatted and sent to the logging system at the specified level.
nextKey const char* pDict->nextKey ( dex_EnvironmentDictionary_t* pDict )
Returns the name of the next key in the dictionary that follows the key returned in the last call to firstKey or nextKey.
put abool_t pDict->put ( dex_EnvironmentDictionary_t* pDict, const char* pszKey, const char* pszValue )
Associates the value with the key in the dictionary, replacing any existing instance of the key with the new value.
remove abool_t pDict->remove ( dex_EnvironmentDictionary_t* pDict, const char* pszKey )
Removes the key and the associated value from the dictionary. Always returns TRUE, even if the dictionary did not contain the key.
B-7Network Registrar CLI Reference Guide
78-12875-01
Appendix B DHCP Extension Dictionary APIDEX Attribute Dictionary API
size int pDict->size ( dex_EnvironmentDictionary_t* pDict )
Returns the number of entries in the dictionary.
trace abool_t pDict->trace ( dex_EnvironmentDictionary_t* pDict, int iLevel, const char* pszFormat, ... )
Outputs a message into the packet tracing system used by the DHCP server. At level 0 no tracing occurs. At level 1 only an indication that the packet was received and a reply was sent is output. As the number gets higher, the amount of information output is greater, until at level 4 everything traceable is output. The remaining arguments are formatted and sent to the tracing system at the specified level.
Table B-4 DEX Environment Dictionary Methods (continued)
Name Syntax
B-8Network Registrar CLI Reference Guide
78-12875-01
Ne78-12875-01
A P P E N D I X C
DHCP Extension Dictionary EntriesThis appendix describes the data items available in the request and response dictionaries. The environment dictionary entries are described in the “Environment Dictionary” section on page 4-15. For more information about extension dictionaries see the “Extension Dictionaries” section on page 4-15.
• The request dictionary consists of decoded packet data items, and the request dictionary specific data items.
• The response dictionary consists of the decoded packet data items, and the response dictionary specific data items.
Decoded DHCP Packet Data ItemsThe decoded DHCP packet data items represent the information in the DHCP packet, and are available in both the request and response dictionaries.
Both the request and response dictionaries provide access to considerably more internal server data structures than just the decoded request and decoded response.
The DHCP and BOOTP fields are available in both the request and response dictionaries.
All of the options followed by an asterisk (*) are multiple, which means that there may be more than one value associated with each option. In the DHCP/BOOTP packet, all of these data items appear in the same option. However, in the extension interface, these multiple data items are accessible through indexing. For more information about indexing in the Tcl and C/C++ APIs, see Appendix C, “DHCP Extension Dictionary Entries” and “Using the dhcp-parameter-request-list Option” section on page 4-18.
You can access options up to type 100 that do not have names in Table C-1 as option -n, in which n is the option number. All fields are read/write.
Table C-1 DHCP and BOOTP Fields
Name Value
chaddr blob (sequence of bytes)
ciaddr IP address
file string
flags 16-bit unsigned integer
giaddr IP address
hlen 8-bit unsigned integer
C-1twork Registrar CLI Reference Guide
Appendix C DHCP Extension Dictionary EntriesDecoded DHCP Packet Data Items
Table C-2 lists the DHCP and BOOTP options.
hops 8-bit unsigned integer
htype 8-bit unsigned integer
op 8-bit unsigned integer
secs 16-bit unsigned integer
siaddr IP address
sname string
xid 32-bit unsigned integer
yiaddr IP address
Table C-1 DHCP and BOOTP Fields (continued)
Name Value
Table C-2 DHCP and BOOTP Options
Name (*=multivalue) Number Value
all-subnets-local 27 byte-valued boolean
arp-cache-timeout 35 int
boot-file 61 string
boot-size 13 16-bit unsigned integer
broadcast-address 28 IP address
cisco-vpn-id 168 blob (sequence of bytes)
cookie-servers* 8 IP address
default-ip-ttl 23 8-bit unsigned int
default-tcp-ttl 37 8-bit unsigned int
dhcp-class-identifier 60 string
dhcp-client-identifier 61 blob (sequence of bytes)
dhcp-lease-time 51 int
dhcp-max-message-size 57 16-bit unsigned integer
dhcp-message 56 string
dhcp-message-type 53 blob (sequence of bytes)
dhcp-option-overload 52 blob (sequence of bytes)
dhcp-parameter-request-list* 55 8-bit unsigned integer
dhcp-parameter -request-list-blob
55 blob (sequence of bytes)
dhcp-rebinding-time 59 int
dhcp-renewal-time 58 int
dhcp-requested-address 50 IP address
dhcp-server-identifier 54 IP address
dhcp-user-class-id 77 string
C-2Network Registrar CLI Reference Guide
78-12875-01
Appendix C DHCP Extension Dictionary EntriesDecoded DHCP Packet Data Items
domain-name 15 string
domain-name-servers* 6 IP address
extensions-path 18 string
finger-servers* 73 IP address
font-servers* 48 IP address
host-name 12 string
ieee802.3-encapsulation 36 8-bit unsigned integer
impress-servers* 10 IP address
interface-mtu 26 16-bit unsigned integer
ip-forwarding 19 byte-valued boolean
irc-servers* 74 IP address
log-servers* 7 IP address
lpr-servers* 9 IP address
mask-supplier 30 byte-valued boolean
max-dgram-reassembly 22 16-bit unsigned integer
merit-dump 14 string
mobile-ip-home-agents* 68 IP address
name-servers* 5 IP address
netbios-dd-servers* 45 IP address
netbios-name-servers* 44 IP address
netbios-node-type 46 blob (sequence of bytes)
netbios-scope 47 string
nis+-servers* 65 IP address
nis+domain 64 string
nis-domain 40 string
nis-servers* 41 IP address
nntp-servers* 71 IP address
non-local-source-routing 20 byte-valued boolean
ntp-servers* 42 IP address
path-mtu-aging-timeout 24 int
path-mtu-patheau-tables* 25 16-bit unsigned integer
perform-mask-discovery 29 byte-valued boolean
policy-filters* 21 IP address (there can be two policy filters, each one having its own IP address)
pop3-servers* 70 IP address
Table C-2 DHCP and BOOTP Options (continued)
Name (*=multivalue) Number Value
C-3Network Registrar CLI Reference Guide
78-12875-01
Appendix C DHCP Extension Dictionary EntriesDecoded DHCP Packet Data Items
relay-agent-information
suboptions:
82 blob (sequence of bytes)
cisco-server-id-override suboption 152 IP address
cisco-subnet-selection suboption 150 IP address
cisco-vpn-id suboption 151 string. The first byte defines the type of the option, where 0 means the rest of the option contains a VRF name as a string. If the first byte is 1, the rest of the option contains an RFC 2685-style VPN ID. This is typically seven additional bytes.
cisco-vpn-id-data suboption 151 blob (does not require suboption number as first byte)
relay-agent-circuit-id suboption 1 blob (requires suboption number as first byte; deprecated in favor of relay-agent-circuit-id-data)
relay-agent-circuit-id- data
suboption 1 blob (does not require suboption number as first byte)
relay-agent-remote-id suboption 2 blob (requires suboption number as first byte; deprecated in favor of relay-agent-remote-id-data)
relay-agent-remote-id- data
suboption 2 blob (does not require suboption number as first byte)
relay-agent-server-id- override-data
suboption 182 IP address
relay-agent-vpn-id-data suboption 181 string
relay-agent-subnet- selection-data
suboption 180 IP address
resource-location-servers* 11 IP address
root-path 17 string
router-discovery 31 byte-valued boolean
router-solicitation-address 32 IP address
routers* 3 IP address
smtp-servers* 69 IP address
static-routes* 33 IP address
streettalk-directory- assistance-servers*
76 IP address
streettalk-servers* 75 IP address
subnet-mask 1 IP address
subnet-selection 118 IP address
swap-server 16 IP address
tcp-keepalive-internal 38 int
tcp-keepalive-garbage 39 byte-valued boolean
tftp-server 66 string
Table C-2 DHCP and BOOTP Options (continued)
Name (*=multivalue) Number Value
C-4Network Registrar CLI Reference Guide
78-12875-01
Appendix C DHCP Extension Dictionary EntriesRequest Dictionary
Table C-3 lists the decoded packet fields.
Request DictionaryTable C-4 lists the data items that you can set in the request dictionary. The data items can be set at any time. The DHCP server reads them at various times. Unless indicated otherwise, all operations are read/write.
time-offset 2 int
time-servers* 4 IP address
trailer-encapsulation 34 byte-valued boolean
vendor-encapsulated-options 43 blob (sequence of bytes)
vpn-id 167 blob (sequence of bytes)
www-servers* 72 IP address
x-display-managers* 49 IP address
Table C-2 DHCP and BOOTP Options (continued)
Name (*=multivalue) Number Value
Table C-3 Decoded Packet Field
Data Item Value Description
dump-packet int When the value of dump-packet is set to 1, Network Registrar dumps the current decoded DHCP/BOOTP packet to the log file. An extension can put the value 1 into the dump-packet data item at multiple points in its execution. This may be useful when debugging extensions.
mac-address blob MAC address that came in the client packet. The first byte is the hardware type, the second is the hardware length, and the remaining (up to 16) is the information from the chaddr read just after post-packet-decode. This is a useful aggregation of the htype, hlen, and chaddr fields of the DHCP packet. When read it is constructed from these fields; when written it is placed into these fields.
relay-agent-circuit-id blob Accesses and manipulates the relay-agent circuit id data from either a DHCP request or response. Requires the suboption number (1) as the first byte. Deprecated in favor of the relay-agent-circuit-id-data data item.
relay-agent-circuit- id-data
blob Accesses and manipulates the relay-agent circuit id data from either a DHCP request or response.
relay-agent-remote-id blob Accesses and manipulates the relay-agent remote id data from either a DHCP request or response. Requires the sub-option number (2) as the first byte. Deprecated in favor of the relay-agent-remote-id-data data item.
relay-agent-remote- id-data
blob Accesses and manipulates the relay-agent remote id data from either a DHCP request or response.
C-5Network Registrar CLI Reference Guide
78-12875-01
Appendix C DHCP Extension Dictionary EntriesRequest Dictionary
Table C-4 Request Dictionary Specific Data Items
Data Item Value
allow-bootp int
If set to 1, for this request BOOTP is allowed for any scope. Read during scope selection and while checking for lease acceptability.
allow-dhcp int
If set to a 1, for this request DHCP is allowed for any scope. Read during scope selection and while checking for lease acceptability.
allow-dynamic-bootp int
If set to a 1, for this request dynamic BOOTP is allowed for any scope. Read during scope selection and while checking for lease acceptability.
boot-reply-options blob
Overrides any bootp-reply-options specified in any policy. Read when gathering data for the output packet.
client-class-name string
Name of the client-class used to complete the client information (if any).
client-class-policy string
Name of the policy that is associated with the client-class. If set, it must be with the name of a policy that was already configured in the server.
client-domain-name string
Domain name that the client wants to use. It may not exist, in which case the DHCP server uses the domain name specified in the scope. It is read when queuing the request for DNS update just prior to the update of stable storage.
client-host-name string
Hostname used for the client in DNS. It is read when queuing in the request for a DNS update just prior to the update of stable storage. It is updated with the actual name placed into DNS when that operation completes.
client-id blob
Client identification that the server uses to keep track of the client. This may be the client-id that was sent with a request or internally generated from the MAC address. See client-id-created-from-mac-address.
client-id-created-from-mac- address
int
If this is 1, the client-id was created from the MAC address and the client-id should not be used in reporting, nor should it ever be equal to a client-id that was not created from a MAC address.
client-ipaddress IP address
IP address from which the client sent its packet. Note that it could be zero if the client does not yet have an IP address.
client-mac-address blob
This is the MAC address that is stored in the client object associated with the request dictionary. It has the same format (and was created from) the mac-address described in the “Decoded DHCP Packet Data Items” section on page C-1.
C-6Network Registrar CLI Reference Guide
78-12875-01
Appendix C DHCP Extension Dictionary EntriesRequest Dictionary
client-os-type int
You can change the value in the client entry of the request packet by setting the value in the request dictionary at the pre-client-lookup or post-client-lookup extension points. This value can also be read at the check-lease-acceptable extension point, but cannot be set there. To set the value, you must first set the os-type in the post-packet-decode request dictionary.
client-policy string
Name of the policy that is associated with the client entry. If you set this, it must be with the name of a policy that is already configured in the DHCP server.
client-port int
Port from which the client sent its request.
client-requested-host-name string
Hostname that the client requested be used for the DNS update. The DHCP server saves this information so that a change can be detected.
client-wants-nulls-in-string int
Determines whether the DHCP server returns strings to the client terminated with a null. If set to 1, the server terminates strings with a null. If set to 0, the server does not terminate strings with a null.This is set before post-packet-decode and read when encoding the response packet after pre-packet-encode.
dhcp-reply-options blob
If specified, overrides any dhcp-reply-options specified in any policy. Read when gathering data for the output packet.
import-packet int
Determines whether the server treats the packet as if came from an import client. If set to 1, the server treats it like an import client and performs all DNS operations on it prior to sending an ACK. Read when checking whether the server is in import mode (right after post-packet-decode), getting ready for DNS processing, and when setting the reply address.
log-client-criteria-processing int
If set to a 1, for this request the criteria processing for the client is logged. Read when attempting to acquire a new lease for a client that does not have one, and when checking a lease for acceptability.
log-client-detail int
If set to a 1, for this request the results of the client-class processing are logged. Read at the end of client-class processing, after the post-client-lookup extension point is run.
log-dns-update-detail int
If set to a 1, for this request DNS update details are logged. (Not implemented in this release.)
log-failover-detail int
If set to a 1, a more detailed level of logging of failover activity is enabled. For example, all failover state changes are logged.
log-incoming-packet-detail int
If set to a 1, for this request incoming packets should be dumped in detail into the log. Read prior to packet decoding and therefore prior to the first extension point.
Table C-4 Request Dictionary Specific Data Items (continued)
Data Item Value
C-7Network Registrar CLI Reference Guide
78-12875-01
Appendix C DHCP Extension Dictionary EntriesRequest Dictionary
log-incoming-packets int
If set to a 1, for this request incoming packets should be logged. Read after decoding the packet and after the post-decode-packet extension point.
log-ldap-create-detail int
If set to a 1, messages are logged whenever the DHCP server initiates a lease state entry create to an LDAP server, receives a response from an LDAP server, or retrieves a result or error message from an LDAP server.
log-ldap-query-detail int
If set to a 1, messages are logged whenever the DHCP server initiates a query to an LDAP server, receives a response from an LDAP server, or retrieves a query result or an error message from an LDAP server.
log-ldap-update-detail int
If set to a 1, messages are logged whenever the DHCP server initiates an update lease state to an LDAP server, receives a response from an LDAP server, or a retrieves a result or error message from an LDAP server.
log-leasequery int
If set to a 1, messages are logged when leasequery packets are processed without internal errors and result in an ACK or a NAK.
log-incoming-packets int
If set to a 1, for this request incoming packets should be logged. Read after decoding the packet and after the post-decode-packet extension point.
log-missing-options int
If set to a 1, for this request missing options, that is, options that are requested by a client but that the DHCP server cannot return, are logged. Read during gathering of data for the response.
log-outgoing-packet-detail int
If set to a 1, for this request the outgoing packet should be dumped in detail into the log. Read just prior to sending the packet to the DHCP client and after pre-packet-encode.
log-unknown-criteria int
If set to a 1, for this request any unknown criteria specified in the client’s inclusion or exclusion criteria are logged. Read either when acquiring a lease for a new client or when checking the acceptability of a lease for an existing client.
namespace-description string (read-only)
Description for the namespace. See the namespace-name data items for details.
namespace-id int (read-only)
Namespace identifier. See the namespace-name data items for details.
namespace-name string (read-only)
Name of the namespace. The request dictionary does not have valid values for these items at the post-packet-decode script point, but does at all others, because the namespace has not yet been determined. This is so that a script can change the vpn-id option or sub-option at the post-packet-decode script point and thus affect the namespace that is used for a lease.
Table C-4 Request Dictionary Specific Data Items (continued)
Data Item Value
C-8Network Registrar CLI Reference Guide
78-12875-01
Appendix C DHCP Extension Dictionary EntriesRequest Dictionary
namespace-vrf-name string (read-only)
Virtual routing and forwarding table identifier for the namespace. See the namespace-name data items for details.
namespace-vpn-id blob, typically 7 bytes (read-only)
Virtual private network identifier for the namespace. See the namespace-name data items for details.
ping-clients int
If set to a 1, for this request a ping should be performed prior to offering a lease. Read just prior to determining if a lease is acceptable for a client.
reply-to-client-address int
If set to 1, the server sends the response packet to the client-ip-address and the client-port instead of using the RFC-mandated algorithm.
selection-criteria string
Comma-separated string that contains the scope’s selection criteria.
selection-criteria-excluded string
Comma-separated string that contains the scope’s exclusion criteria.
send-ack-first int
If set to a 1, for this request DNS should be updated after the ACK for DHCP requests. Read just prior to initiating the DNS operation.
transaction-time int
Time, in seconds, since 1970 that the input packet was decoded.
update-dns-for-bootp int
If set to a 1, for this request DNS should be updated for BOOTP requests. Read just prior to initialing the DNS operation for BOOTP.
verbose-logging int
If set to a 1, for this request verbose logging is enabled. Read at various times during processing.
Table C-4 Request Dictionary Specific Data Items (continued)
Data Item Value
C-9Network Registrar CLI Reference Guide
78-12875-01
Appendix C DHCP Extension Dictionary EntriesResponse Dictionary
Response DictionaryTable C-5 lists the data items you can set in the response dictionary at any time. The DHCP server reads them at various times. Unless indicated otherwise, the operation is read/write.
Table C-5 Response Dictionary Specific Data Items
Data item Value
auto-configure int
Network Registrar can ask and be notified if auto-configuration should be disabled on the local subnet. Writing an extension script to return yiaddr=0.0.0.0 and set this option (0xFB) to 0 prevents a Windows 2000 RC3 DHCP client from auto-configuring, allowing clients to choose a link-local IP address so that they can communicate with other hosts on the same link.
client-domain-name string (read-only)
From the client information in the lease, the domain name that the client wants to use. It might not exist, in which case the DHCP server uses the domain name specified in the scope. It is read when queuing the request for DNS update just prior to the update of stable storage.
client-host-name string
From the client information in the lease, the hostname that the DHCP server puts into DNS. Read when queueing the request for a DNS update just prior to the update of stable storage.
client-id blob
From the client information in the lease, the client identification that the server used to keep track of the client. This might be the client-id that was sent with a request or a client-id that was internally generated from the MAC address.
client-id-created-from- mac-address
int (read-only)
From the client information in the lease. If 1, the client-id was created from the MAC address and the client-id should not be used in reporting, nor should it ever be equal to a client-id that was not created from a MAC address.
client-mac-address blob
From the client information in the lease, the MAC address that is stored in the client object associated with the request dictionary. It has the same format (and was created from) the mac-address described above.
client-os-type int
You can change the value in the client entry of the request packet by setting the value in the request dictionary at the pre-client-lookup or post-client-lookup extension points. This value can also be read at the check-lease-acceptable extension point, but cannot be set there. To set the value, you must first set the os-type in the post-packet-decode request dictionary.
client-requested-host-name string
From the client information in the lease, the hostname that the client requested to be used for the DNS update.
domain-name-changed int
If set to 1, the domain name in the current packet differs from the domain name used in the DNS update. Read after check-lease-acceptable and before pre-packet-encode.
C-10Network Registrar CLI Reference Guide
78-12875-01
Appendix C DHCP Extension Dictionary EntriesResponse Dictionary
host-name-changed int
If set to 1, the hostname in the current packet differs from the hostname used in the DNS update. Read after check-lease-acceptable and before pre-packet-encode.
host-name-in-dns int
If set to 1, the hostname is in DNS. Read after check-lease-acceptable and before pre-packet-encode. Written after the hostname is placed into DNS.
last-transaction-time int (read-only)
Time, in seconds, since 1970, that the DHCP server last heard from this client.
lease-deactivated int (read-only)
If set to 1, the lease is deactivated.
lease-ipaddress IP address (read-only)
IP address of the lease that the DHCP server uses in processing.
lease-namespace-description string (read-only)
Description for the namespace stored with a response’s lease.
lease-namespace-id int (read-only)
Identifier for the namespace stored with a response’s lease.
lease-namespace-name string (read-only)
Name of the namespace stored with a response’s lease.
lease-namespace-vrf-name string (read-only)
Virtual routing and forwarding table identifier for the namespace stored with a response’s lease.
lease-namespace-vpn-id blob, typically 7 bytes (read-only)
Virtual private network identifier for the namespace stored with a response’s lease.
lease-relay-agent-circuit-id blob
Accesses and manipulates the relay-agent circuit id data as stored with a response’s lease. Requires the suboption number 1 as the first byte. Deprecated in favor of the lease-relay-agent-circuit-id-data data item.
lease-relay-agent-circuit-id-data
blob (use instead of the deprecated lease-relay-agent-circuit-id item)
Accesses and manipulates the relay-agent-circuit-id-data data as stored with a response’s lease. Relevant only if the dhcp command’s save-relay-agent-data attribute is enabled.
lease-relay-agent-remote-id blob
Accesses and manipulates the relay-agent-remote-id data as stored with a response’s lease. Requires the suboption number 2 as the first byte. Deprecated in favor of the lease-relay-agent-remote-id-data data item.
lease-relay-agent-remote-id-data
blob (use instead of the deprecated lease-relay-agent-remote-id item)
Accesses and manipulates the relay-agent-remote-id-data data as stored with a response’s lease. Relevant only if the dhcp command’s save-relay-agent-data attribute is enabled.
Table C-5 Response Dictionary Specific Data Items (continued)
Data item Value
C-11Network Registrar CLI Reference Guide
78-12875-01
Appendix C DHCP Extension Dictionary EntriesResponse Dictionary
lease-relay-agent-server-id- override-data
IP address
Accesses and manipulates the relay-agent-server-id-override-data data as stored with a response’s lease. Relevant only if the dhcp command’s save-relay-agent-data attribute is enabled.
lease-relay-agent-subnet- selection-data
IP address
Accesses and manipulates the relay-agent-subnet-selection-data data as stored with a response’s lease. Relevant only if the dhcp command’s save-relay-agent-data attribute is enabled.
lease-relay-agent-vpn-id-data blob
Accesses and manipulates the relay-agent-vpn-id data as stored with a response’s lease. Relevant only if the dhcp command’s save-relay-agent-data attribute is enabled.
lease-reserved int (read-only)
If set to 1, the lease is reserved.
lease-state string (read-only)
State of the lease, which can be available, offered, expired, leased, or unavailable.
mac-address blob
If set to 1, the scope allows BOOTP. Written after a DNS operation completes.
namespace-description string (read-only)
Description for the namespace.
namespace-id int (read-only)
Namespace identifier.
namespace-name string (read-only)
Name of the namespace.
namespace-vrf-name string (read-only)
Virtual routing and forwarding table identifier for the namespace.
namespace-vpn-id blob, typically 7 bytes (read-only)
Virtual private network identifier for the namespace.
ping-clients int
If equal to a 1, specifies that for this request a ping should be performed prior to offering a lease. Read just prior to determining if a lease is acceptable for a client.
reply-ipaddress IP address
The IP address to use when replying to the DHCP client. Read just after pre-packet-encode. If you change the value of this data item in the pre-packet-encode extension point, the IP address you place in this data item should be for a system that is able to respond to ARP queries for that IP address (unless the IP address is for a broadcast IP address). Even if unicast is enabled and the broadcast flag is not set in the DHCP request, the local ARP cache is not set with a mapping from a new reply-ipaddress in the pre-packet-encode extension point to the MAC address in the DHCP request.
reply-port int
The port to use when replying to the DHCP client. Read just after pre-packet encode.
Table C-5 Response Dictionary Specific Data Items (continued)
Data item Value
C-12Network Registrar CLI Reference Guide
78-12875-01
Appendix C DHCP Extension Dictionary EntriesResponse Dictionary
reverse-name-in-dns int
If equal to 1, then the reverse name is in DNS. Read prior to initializing a DNS operation.
scope-allow-bootp int
If equal to 1, then the scope allows BOOTP. Written after a DNS operation completes.
scope-allow-dhcp int (read-only)
If set to 1, the scope allows DHCP.
scope-allow-dynamic-bootp int (read-only)
If set to 1, the scope allows dynamic BOOTP.
scope-available-leases int (read-only)
Number of available leases on the current scope.
scope-deactivated int (read-only)
If set to 1, the scope is de-activated.
scope-dns-forward-server- address
IP address (read-only)
DNS server to use for the DNS forward address.
scope-dns-forward-zone- name
string (read-only)
Forward zone name configured in the scope.
scope-dns-number-of-host- bytes
int (read-only)
Number of host bytes used by the DHCP server code that handles DNS updates.
scope-dns-reverse-server- address
IP address (read-only)
DNS server to use for the DNS reverse address.
scope-dns-reverse-zone- name
string (read-only)
Reverse zone name configured in the scope.
scope-name string (read-only)
The name of the scope that contains the lease that the DHCP server is processing.
scope-network-number IP address (read-only)
Network number of the scope that contains the lease the DHCP server is processing.
scope-ping-clients boolean (read-only)
If set to 1, the scope associated with the current lease was configured to support a ping operation prior to offering a lease.
scope-primary-network- number
IP address (read-only)
Network number of this scope’s primary scope.
Table C-5 Response Dictionary Specific Data Items (continued)
Data item Value
C-13Network Registrar CLI Reference Guide
78-12875-01
Appendix C DHCP Extension Dictionary EntriesResponse Dictionary
scope-primary-subnet-mask IP address (read-only)
Subnet mask of this scope’s primary scope.
scope-renew-only int (read-only)
If set to 1, the scope is renew-only.
scope-renew-only-expire- time
int (read-only)
Absolute time, in seconds since January 1, 1970, at which a renew-only scope should cease to be renew-only
scope-selection-tags string (read-only)
Comma-separated string that contains the scope’s selection criteria.
scope-send-ack-first int (read-only)
If set to 1, the scope sends an ACK before performing the rest of the processing.
scope-subnet-mask IP address (read-only)
Subnet mask of the scope that contains the lease the DHCP server is processing.
scope-update-dns-enabled int (read-only)
If set to 1, the scope has update-DNS-enabled.
scope-update-dns-for-bootp int (read-only)
If set to 1, the scope has update-DNS-enabled for BOOTP.
start-time-of-state int (read-only)
Time, in seconds, since 1970, this lease was first placed into its current state.
transaction-time int (read-only)
Time, in seconds, since 1970 that the request was decoded.
Table C-5 Response Dictionary Specific Data Items (continued)
Data item Value
C-14Network Registrar CLI Reference Guide
78-12875-01
Netw78-12875-01
I N D E X
A
action (client command) 9
activate keyword (subnet command) 119
activating
leases 71
SNMP traps 127
subnet 119
active-directory-domain attribute (tftp command) 122
activity-summary log flag (dhcp command) 33
activity summary log messages (dhcp command) 22
addException (dns command) 49
addHost method (zone command) 135
adding
exception DNS servers 44
forwarder DNS servers 44
reservations to scopes 105
root hint DNS servers 44
scope ranges 104
SNMP trap recipients 128
addRange method (scope command) 104
addr attribute (scope command) 105
addr-blocks-default-selection-tags (dhcp command) 22
addr-blocks-default-selection-tags (namespace command) 85
addr-blocks-use-client-affinity (dhcp command) 22
addr-blocks-use-client-affinity (namespace command) 85
addr-blocks-use-lan-segments
dhcp command 22
namespace command 85
addr-blocks-use-lan-segments (namespace command) 85
addr-blocks-use-selection-tags (dhcp command) 22
addr-blocks-use-selection-tags (namespace command) 85
addRecipient method (trap command) 128
addReservation method (scope command) 105
address (address-block command) 3
address attribute (lease command) 72
address-block-policy
commands 5
address-block-policy command 5
address blocks
address 3
creating 2
default selection tags (dhcp) 22
default selection tags (namespace command) 85
deleting 2
embedded policies 3
getting attribute values 3
grouping IP subnets 4
initial subnet size 3
listing 3
listing names only 3
managing 2
namespace ID 3
namespaces 3
policy names 3
segment names
segment-name (address block command) 4
selection tags 4, 85
setting attributes 2
showing attribute values 3
subnet allocation requests 22
subnets of 3
unsetting attributes 3
address-conflict attribute (trap command) 128
addresses
IN-1ork Registrar CLI Reference Guide
Index
exporting 52
address range
removing 104
addRR method (zone command) 135
admin command 6
administrators
changing passwords 6
creating 6
deleting 6
getting password 6
listing 6
managing 6
passwords 7
setting passwords 6
showing attributes 6
unsetting passwords 6
AIC_CLUSTER environment variable 2, 1
AIC_NAME environment variable 2, 1
AIC_PASSWORD environment variable 2, 1
AIC Server Agent 1
allocating
buffers (DHCP) 29
subnets by address blocks 22, 85
subnets by lan-segment attribute 22, 85
allow-client-a-record-update attribute (policy command) 92
allow-dual-zone-dns-update attribute (policy command) 93
allow-lease-time-override attribute (policy command) 93
API (using nrcmd as) 1
APPEND attribute index special value 2, 5, 6
append-user-class-id-to-selection-tag attribute (dhcp command) 23
A record 14
arguments
specifying a series of 3
array flag in defineSuboption keyword flags attribute (vendor-option command) 131
arrays
vendor options 5
IN-2Network Registrar CLI Reference Guide
asserting
sessions 117
attaching
extension points 21
attribute dictionary 1
methods 1
attribute flags 4
attributes
of objects 3
optional 4
read-only 4
required 4
AUGMENT attribute index special value 2, 5, 6
authenticate-until (client command) 9
authenticate-until attribute (client command) 11
authenticate-until data item 21
authentication 1
auth-servers attribute (zone command) 136
auto-configure data item 25
available addresses keyword (lease-notification) 80
available state (lease command) 75
B
batch file
nrcmd 2
BIND
interoperability 53, 62
mapping boot file directives to nrcmd 64
named.boot file 63
nrcmd command mappings 64
boolean option data type 18
boolean variables 5
BOOTP 1, 3, 12, 13, 19
request 11
bootp attribute (scope command) 105
bootp-reply-options attribute (policy command) 93
byte option data type 18
78-12875-01
Index
C
C/C++
extensions 1, 2, 6
cache file, DNS 45
flushing 49
caching (TFTP server)
enabling 121
can-create attribute (ldap command) 67
can-query attribute (ldap command) 67
can-update attribute (ldap command) 67
catch error statement 5
changemask keyword (scope command) 104
changing
administrator passwords 6
scope netmask 104
check-lease-acceptable extension point (dhcp command) 35, 13, 15
environment dictionary 24
request dictionary 24
response dictionary 24
checkpoint-interval attribute (zone command) 136
chkpt method (zone command) 133, 136
ciscoNetRegAddressConflict SNMP notification 128
ciscoNetRegDNSQueueTooBig SNMP notification 128
ciscoNetRegDuplicateAddress SNMP notification 128
ciscoNetRegFailoverConfigurationMismatch SNMP notification 128
ciscoNetRegFreeAddressHigh SNMP notification 128
ciscoNetRegFreeAddressLow SNMP notification 128
ciscoNetRegOtherServerNot Responding SNMP notification 128
ciscoNetRegOtherServer Responding SNMP notification 128
ciscoNetRegServerStart SNMP notification 128
ciscoNetRegServerStop SNMP notification 128
class attribute (zone command resource record method) 135
classes of objects (configuring) 2
cleanRR method (zone command) 135
78-12875-01
clearing
unavailable leases in scopes 104
clearUnavailable method (scope command) 104
client
client class 9
listing client identifiers 9
client-binary-client-id attribute (lease command) 72
client-cache-count attribute (dhcp command) 23
client-cache-ttl attribute (dhcp command) 23
client caching 12
client-class attribute (dhcp command) 23
client-class command 13
client-classes
creating 13
delete 13
getting attribute values 13
listing 14
listing attributes 14
listing names 14
managing 13, 15
setting attributes 13
showing attribute values 13
unsetting attributes 13
client-class-name (client command) 9
client-class-name data item 21, 23, 25
client-class-policy command 15
client-class-policy data item 23, 25
client command 8
domain-name attribute 9
client-criteria-processing log flag (dhcp command) 33
client-detail log flag (dhcp command) 33
client-dns-name attribute (lease command) 73
client-dns-name-up-to-date flag (lease command) 73
client-domain-name attribute (lease command) 73
client-domain-name attribute (subnet command) 120
client-domain-name data item 23, 25, 26
client-flags attribute (lease command) 73
client-flags attribute (subnet command) 120
client-host-name
IN-3Network Registrar CLI Reference Guide
Index
data item 23, 25
lease command 73
subnet command 120
client-host-name data item 26
client-id
data item 21, 23, 25, 26
lease command attribute 73
subnet command attribute 120
client-id-created-from-mac-address data item 21, 23, 25, 26
client-id-created-from-mac-address flag (lease command) 73
client-ipaddress data item 19, 21, 23, 24
client-last-transaction-time (subnet command) 120
client-last-transaction-time attribute (lease command) 73
client-mac-addr attribute (lease command) 73
client-mac-address (subnet command) 120
client-mac-address data item 21, 23, 25, 26
client-os-type attribute (lease command) 73
client-os-type data item 21, 23
client-policy command 16
client-policy data item 23, 25
client-port data item 19, 21, 23, 24
client-requested-host-name data item 23, 25, 26
clients
actions 9
authentication time 9
configuring embedded policies 16
creating 8, 57
deleting 8
domain name 120
embedded-policies 9
excluding 9
getting attribute values 8
host-name 120
host-name attribute 9
hostnames 12
limiting authentication 11
listing 9
managing 8
IN-4Network Registrar CLI Reference Guide
one-shot leases 9, 10
policy-names 9
selection-criteria 10
selection-criteria-excluded 10
setting attributes 8
showing attributes 8
unathenticated-client-class-name 10
unsetting attribute values 8
user-defined 10
use-release-grace-period 9
client-specifier data item 20, 22
client-wants-nulls-in-string data item 22, 23, 25
clusters 1
connection 1
license 83
specifying (export addresses command) 53
specifying (lease-notification command) 81, 82
specifying (report command) 99
clusters, components of
AIC Server Agent 1
MCD persistent store 1
clusters attribute (export addresses command) 53
clusters attribute in configuration file (lease-notification command) 82
cnr-5-0-upgraded attribute (dhcp command) 23
cnr-ldap-query-failed data item 22
collect-performance-statistics attribute (dhcp command) 23
column-separator keyword (report command) 98
commands
address-block 2
address-block-policy 5
admin 6
client 8
client-class 13
client-class-policy 15
client-policy 16
custom-option 17
dhcp 20
78-12875-01
Index
dhcp-interface 41
dns 43
exit 51
export 52
extension 57
force-lock 60
help 61
import 62
ldap 65
lease 71
lease-notification 79
license 83
namespace 84
option-datatype 87
policy 90
remote-dns 96
report 98
save 102
scope 103
scope-policy 110
scope-selection-tag 111
server 112
session 116
subnet 119
tftp 121
trap 127
vendor-option 130
zone 133
community attribute (trap addRecipient command) 128
config keyword (lease-notification command) 80
config keyword (report command) 98
configuration file
lease-notification 81
specifying
export addresses command 54
configuring
attributes of objects 3
classes of objects 2
connections attribute (ldap command) 67
78-12875-01
continue data item 28
controlling
nrcmd from another program 2
counted-array option data type flag 88
create-dictionary attribute (ldap setEntry command) 66
create keyword 3
create-object-classes attribute (ldap command) 67
create-string-dictionary attribute (ldap setEntry command) 66
creating 130
address blocks 2
administrator 6
client-classes 13
clients 8, 57
custom options (desc attribute) 17
custom options (number attribute) 17
custom options (type attribute) 17
DHCP custom options 17
DHCP extensions 57
DHCP interfaces 41
LDAP server 65
namespaces 84
option data types 87
policies 91
remote DNS servers 96
scopes 103
scope-selection tags 111
csrc-configuration-file attribute (tftp command) 122, 125
custom-option command
delete 18
number attribute 18
type attribute 18
custom options
creating (desc attribute) 17
creating (DHCP) 17
creating (number attribute) 17
creating (type attribute) 17
DHCP 17
getting attribute values 18
IN-5Network Registrar CLI Reference Guide
Index
listing (DHCP) 18
setting custom DHCP options 18
showing DHCP attributes 18
unsetting attribute values 18
D
database changes
saving 102
datatype attribute (option-datatype command) 87
dbsn attribute (dhcp command) 23
deactivated attribute (scope command) 105
deactivate keyword (subnet command) 119
de-activating
leases 71
SNMP traps 127
subnets 119
decoded DHCP packet data items 17
default-attribute-value attribute (ldap command) 67
default-client-class-name data item 20
default delection tags, dhcp 22
default-device attribute (tftp command) 122
default interface 41
default log flag (dhcp command) 33
default selection tags, namespace 85
defer-lease-extensions attribute (dhcp command) 23
deferring 36
defineField method (option-datatype command) 87
defineSuboption method (vendor-option command) 130
defining
namespace (scope command) 3, 107
option data type fields 87
defttl attribute (zone command) 136
delete-leases-in-state-with-no-configured-namespace attribute (dhcp command) 24
delete-orphaned-leases attribute (dhcp command) 24
deleting
address blocks 2
administrators 6
IN-6Network Registrar CLI Reference Guide
client-classes 13
clients 8
DHCP custom options 18
DHCP extensions 57
DHCP interfaces 41
LDAP server 65
namespaces 84
option data types 87
policies 91
remote DNS servers 96
reservations (lease) 72
reservations (lease command) 76
scopes 103
scope-selection tags 111
vendor options 130
desc 18
desc attribute (custom option command) 17
description (namespace command) 85
detaching
extension points 21
DEX
C/C++ extensions 6
shared library 6
dex.h file 7
DEX_INITIALIZE extension point value 9
DEX_UNINITIALIZE extension point value 9
DEX attribute dictionary
allocMemory method 4
getBytesByType method 4
log method 5
putBytesByType method 6
remove method 6
trace method 6
DEX environment dictionary 6
allocateMemory 7
clear 7
containsKey 7
firstKey 7
get 7
78-12875-01
Index
isEmpty 7
log 7
nextKey 7
put 7
remove 7
size 8
trace 8
dexextension.c file (dhcp command) 40
dextrace example extension (dhcp command)
DHCP
extension points
dextrace 40DHCP
allocating buffers 29
attaching extension points 21
buffer size 29
client
cache 23
time to live 23
client-class 23
client criteria processing 33
client details 33
client identifier (MAC address) 28
collecting performance statistics 23
configuration messages (reducing) 34
congestion (packet processing) 24
custom options 17
deleting leases without a namespace-id 24
detaching extension points 21
details on incoming packets 33
details on outgoing packets 34
dexextension.c file 40
disabling attributes 20
DISCOVER 13
discover-interfaces attribute 24
displaying log messages for DNS operations 33
dns-timeout attribute 24
docsis-version-id-missing attribute 24
dropping packets 33
78-12875-01
dropping packets (extension failures) 24
ECHO 27
enabling attributes 20
extension points 35
acting on input packet information 35
DNS retries 36
examining the results of operations 35
post-client-lookup 35
post-send-packet 35
pre-client-lookup 35
rewriting info in the response packet 35
extensions 21
extension trace level values 25
failover 37
available leases 25
backup server 25
bynamic BOOTP 25
configuring 25
lease period 25
main server 25
maximum client lead time 26
multiple lease state updates 25
partner down mode 22
polling interval 26
recover state 26
related servers 22
safe period 26
timeout interval 26
use-safe-period 26
failover detail 33
failover lease period factor 38
getting attribute values 21
ignore-requests-for-other-servers attribute 78
import mode 27
incoming packet information 33
inhibit optimization 27
input port 10
interfaces 41
listing 42
IN-7Network Registrar CLI Reference Guide
Index
Internet Control Message Protocol (ICMP) 27
ip-history 27
IP lease history 28
last transaction time accuracy 28
LDAP
creating a lease state entry 33
details on communications 33
leasequery processing 34
queries 33
library path 37
listing extensions 21
logging default 33
log settings 28
managing 20
mapping the user class ID 29
maximum
DHCP requests 29
DHCP responses 29
DNS packets 29
DNS time to live 29
ping packets 29
remaining retries 29
waiting packets 30
mcd
blob objects per bulk read 30
missing options 34
monitoring performance 23
multiple LDAP servers 28
OFFER request 11
one-lease-per-client 30
performance monitoring 23
pointers into server memory 8
preventing
messages
invalid packets 34warnings 34
preventing messages
BOOTP 34
dropped packets 34
IN-8Network Registrar CLI Reference Guide
failover 34
successful outgoing response packets 34
timeout of leases or offers 34
REBIND request 13
reducing logging when busy 34
relationship to existing tags 23
relay agent option 2
reloading 4
renewing client leases (lease extensions) 23
RENEW request 13
REQUEST SELECTING request 13
requests for other servers 27
retries 29
return-client-fqdn-if-asked 30
saving lease renewal time 30
saving the vendor-class-identifier 30
scope-selection tag list 31
sentinel in environment dictionary 3
serial numbers 23
server activity summary 33
setting attributes 20
showing upgrades 23
skip-client-lookup 31
SMS
generating network discovery records 31
network discovery records 40
overriding the internal default value 31
setting the lease interval 31
specifying the site code 31
subnet masks 26
troubleshooting MAC Addresses 40
unicast 26
unknown selection criteria 35
unsetting attributes 20
update-dns-for-bootp 31
use
client-fqdn-first 32
client-fqdn-option 31
host-name 32
78-12875-01
Index
ldap-client-data 32
vpn communication 32
dhcp
activity summary log messages 22
lease state database 30
save-relay-agent-data attribute 30
scope command attribute 105
set log-settings=failover-detail 114
dhcp command 20
dhcp-failover-config-mismatch attribute (trap command) 128
dhcp-interface command 41
create 41
delete 41
get 41
list 42
listnames 42
set 41
show 41
dhcp-only keyword (report command) 98
dhcp-parameter-request-list option 18
dhcp-reply-options attribute (policy command) 93
DHCP server
client-last-transaction-time 120
getRelatedServers 22
import mode 37
setPartnerDown 22
update SMS 22
disable keyword 4
disabling
DHCP server attributes 20
DNS server attributes 44
incremental transfers or multiple records on remote DNS servers 97
LDAP attributes 65
policy attributes 91
read-only attribute (vendor-option command) 130
read-only option data types 88
scope attributes 104
78-12875-01
servers 112
subnet allocation by address block 22, 85
TFTP server 121
discover-interfaces attribute (dhcp command) 24
DISCOVER request 13
dn-attribute attribute (ldap command) 67
dn-create-format attribute (ldap command) 67
dn-format attribute (ldap command) 67
DNS
addException 49
cache
maximum TTL 46
size 46
fake-ip-name-response 45
fetching glue records 46
hiding subzone hierarchy 45
incremental transfer behavior 45
incremental zone transfers
to maintain secondary zones 45
lame delegation (notify) 45
local ports 45
log flags
NOTIFY 48
maximum
changes 46
minimum
interval before notification 46
negative responses
fake-ip-name-response 50
notify-rcv-interval 46
NOTIFY request 46, 48
notify-send-stagger 46
notify-wait 46
recursive queries 46
relaxing RFC restrictions 47
remote ports 47
removeException 49
resource records (rebuilding indexes) 50
round robin (equivelent records) 47
IN-9Network Registrar CLI Reference Guide
Index
scvg-interval attribute 47
scvg-no-refresh-interval 47
setting log messages 46
slave mode 47
storing negative query results 47, 50
subnet-sorting 47
update-relax-zone-name 47
dns command 43
addException 44
addForwarder 44
addRootHint 44
disable 44
enable 43
flushCache 45
forceXfer 45
get 44
listExceptions 44
listForwarder 45
listRootHints 44
rebuildRR-Indexes 45
recording start scavenging time 47
removeException 44
removeForwarder 44
removeRootHint 44
set 44
show 44
unset 44
dns-queue-too-big attribute (trap command) 128
dns-reverse-zone-name attribute (scope command) 105
dns-rev-server-addr attribute (scope command) 105
dns-server-addr attribute (scope command) 105
DNS servers
managing 43
remote 96
dns-timeout attribute (dhcp command) 24
dns-update-detail log flag (dhcp command) 33
dns-update-pending flag (lease command) 73
dns-zone-name attribute (scope command) 105
docsis-access attribute (tftp command) 123
IN-10Network Registrar CLI Reference Guide
docsis-file-logging attribute (tftp command) 123
docsis-log-file-count attribute (tftp command) 123
docsis-pathname-prefix attribute (tftp command) 123
docsis-version-id-missing attribute (dhcp command) 24
domain name (client) 120
domain-name (client command) 9
domain-name-changed data item 26
domain-name data item 20, 28
double-quotes 2
drop data item 18
drop-old-packets attribute (dhcp command) 24
drop-packet-on-extension-failure attribute (dhcp command) 24
dropped-waiting-packets log flag (dhcp command) 33
duplicate-address attribute (trap command) 128
dynamic attribute (zone command) 136
dynamic BOOTP 37
dynamic-bootp attribute (scope command) 106
dynamic-dns attribute (scope command) 106
dynupdate-set attribute (zone command) 136
E
embedded policies
configuring 16
managing 15
embedded-policy
address-block command attribute 3
client command attribute 9
scope command attribute 106
embedded policy commands
address-block-policy 5
scope-policy 110
enable keyword 4
enabling
DHCP server attributes 20
DNS server attributes 43
incremental transfers or multiple records on remote DNS servers 96
78-12875-01
Index
LDAP attributes 65
policy attributes 91
read-only attribute (vendor-option command) 130
read-only option data types 88
scope attributes 104
servers 112
TFTP server 121
TFTP server caching 121
entering
administrator passwords 7
password 6
entry attribute (extension command) 57, 58
entry points
extensions 57
env-dictionary attribute (ldap setEntry command) 66
environment dictionary 3, 15
definition 3
drop data item 18
extension-point data item 18
log-drop-message data item 18
trace-level data item 18
errors-to keyword (lease-notification) 80
exception DNS servers 44
exceptions (dns command)
DNS
exceptions 49
exclude action (client command) 9
exclude-from-dhcp-packet option data type flag 88
exit command 51
exiting the CLI 51
expiration attribute (lease command) 73
expiration attribute (subnet command) 120
expire attribute (zone command) 136
expired state (lease command) 75
export addresses
clusters 53
configuration files
54
export command 52
78-12875-01
addresses 52
hostfile 52
leases 52
zone 53
zonenames 53
exporting server data 52
extension 58
arguments 58
entry points 58
extension command 57
create 57
delete 57
get 58
list 58
listnames 58
set 57
show 58
unset values 57
extension dictionaries 3, 15
extensioninit-entry points 58
extension-name environment dictionary string 16
extension-name-sequence environment dictionary string 16
extension-point environment dictionary string 16
extension points
attaching 21
check-lease-acceptable 13
debugging 4
decoded data items 17
detaching 21
DHCP 35
environment dictionary 15
flow control 9
handling configuration errors 4
initialize 4
languages 58
post-client-lookup 22
post-packet-decode 19
pre-client-lookup 19
IN-11Network Registrar CLI Reference Guide
Index
pre-dns-add-forward 14, 27
pre-packet-encode 13
recognizing extensions 4
uninitialize 4
using types 7
extensions
allocating threads 14
arguments 4
boolean variables 5
building C/C++ extensions 7
catch error statement 5
configuration errors 4
configuring C/C++ 8
debugging C/C++ 8
deciding the approach 2
definition 1
determining the task 1
DHCP 57
entry points 57
filenames 57
global variables 6
hash-table lookup 7
language 57
recognizing 4
routine signature 3
shared library 8
specifying true and false 5
extension-sequence environment dictionary string 16
extension-trace-level attribute (dhcp command) 25
F
failover
attribute states 109
backup percentage 37
configuration mismatch (trap command) 128
dhcp command attribute 25
lazy update 38
lease period factor 38
IN-12Network Registrar CLI Reference Guide
maximum client lead time (dhcp command) 38
notifying a DHCP server 22
partner down mode 22
related servers 22
scope command attribute 106
setting backup percentage 37
failover-backup-percentage attribute (dhcp command) 25, 37
failover-backup-server attribute
dhcp command 25
scope command 106
failover-bulking attribute (dhcp command) 25
failover-detail log flag (dhcp command) 33
failover-dynamic-bootp-backup-percentage attribute 25
failover-lease-period-factor attribute (dhcp command) 25, 38
failover-main-server attribute (dhcp command) 25
failover-main-server-name attribute (scope command) 106
failover-maximum-client-lead-time attribute (dhcp command) 26
failover-new-backup-percentage attribute (scope command) 106
failover-poll-interval attribute (dhcp command) 26
failover-poll-timeout attribute (dhcp command) 26
failover-recover attribute (dhcp command) 26
failover-safe-period attribute (dhcp command) 26
failover-use-safe-period attribute (dhcp command) 26
fake-ip-name-response (dns command) 45, 50
fetching
glue records (DNS) 46
field attribute (option-datatype command) 87
field data types (export command) 56
file attribute (extension command) 57, 58
file-caching attribute (tftp command) 123
file keyword (report command) 98
filenames 58
extensions 57
flags
lease command 73
78-12875-01
Index
lease command attribute 73, 74
option-datatype command attribute 88
vendor-option command attribute 130
flushing
DNS cache 45
DNS cache file 49
force-available keyword (subnet command) 119
force-lock 60
forceXfer method (zone command) 135
forcing
lease availability 72
subnet availability 119
forwarder DNS servers 44
forwarding
recursive queries 44
FQDN
client-fqdn option (dhcp command) 31
dhcp command 30
in host files 52
policy command 92
zone command 134
FQDN (export command) 52
free-address attribute (trap command) 128
free-address-high attribute (trap command) 128
free-address-high-threshold attribute (trap command) 127
free-address-low-threshold attribute (trap command) 127
G
generating
reports 98
getHealth method (server command) 113
get method 3
getOption method (policy command) 91
getRelatedServers method (server command) 113
getRelatedServers report (server command) 114
getStats method (server command) 113
get-subnet-mask-from-policy attribute (dhcp command) 26
78-12875-01
getting
address block attribute values 3
administrator password 6
client attribute values 8
client-class attribute values 13
DHCP custom option attribute values 18
DHCP extension attribute values 58
DHCP interface attribute values 41
DHCP server attribute values 21
DNS server attribute values 44
health of server 113
help 61
LDAP attributes 66
LDAP entries 66
lease attributes 72
license key values 83
policy attributes 91
policy options 91
policy vendor options 92
related DHCP failover servers 113, 114
related DHCP servers 22
scope attributes 104
scopes for leases 72
server statistics 113
server versions 113
session attributes 117
session serial numbers 117
SNMP trap threshold attributes 127
subnet attributes 119
TFTP server attributes 122
getType routine 9
getVendorOption method (policy command) 92
grace-period attribute (policy command) 93
H
hardware-unicast attribute (dhcp command) 26
hash-table lookup 7
help command 61
IN-13Network Registrar CLI Reference Guide
Index
hide-subzones attribute (dns command) 45
hiding
subzone hierarchy (DNS) 45
high-water attribute (subnet command) 120
HKEY_CURRENT_USER environment variable 2
home-directory attribute (tftp command) 123
host attribute (trap addRecipient command) 128
host files
exporting 52
hostname attribute (ldap command) 68
host-name-changed data item 26
host-name data item 20, 28
host-name-in-dns data item 26
hostnames (client command) 9, 12, 120
I
id (namespace command) 85
ignore-icmp-errors attribute (dhcp command) 27
ignore-prerequisites data item 28
ignore-requests-for-other-servers attribute (dhcp command) 27, 78
immutable (read-only) attributes 4
import commands 62
import leases 62
import named.boot 62
importing server data 62
import leases command 62
import-mode attribute (dhcp command) 27
import named.boot command 62
import-packet data item 22, 23, 25
incoming-packet-detail log flag (dhcp command) 33
incoming-packets log flag (dhcp command) 33
incremental zone transfers
behavior 45
ixfr-enable attribute 45
maintaining secondary zones 45
inhibit-busy-optimization attribute (dhcp command) 27
init-args attribute (extension command) 58
IN-14Network Registrar CLI Reference Guide
init-entry attribute (extension command) 58
init-entry call 4
init-entry extension 4
init-entry extension point 6, 7, 9, 15
persistent data item 9
initial-packet-timeout attribute (tftp command) 123
initial-subnet (address-block command) 3
interface
default 41
interoperable with BIND 53, 62, 63
in-use-addresses attribute (subnet command) 120
IP address array option data type 18
IP address option data type 18
IP history
database directory 28
ip-history attribute (dhcp command) 27
ip-history-dir attribute (dhcp command) 28
ixfr attribute (zone command) 136
ixfr-enable attribute (dns command) 45
ixfr-expire-interval attribute (dns command) 45
ixfr keyword (remote-dns command) 96
K
keywords
create 3
disable 4
enable 4
set 3
L
lame-deleg-notify attribute (dns command) 45
lang attribute (extension command) 58
language attribute (extension command) 57
languages
extensions 57
last-name-number data item 28
78-12875-01
Index
last-name-number-length data item 28
last-transaction-time attribute (subnet command) 120
last-transaction-time data item 26
last-transaction-time-granularity attribute (dhcp command) 28
lazy update, failover 38
LDAP
can-create 67
can-query 67
can-update 67
connections 67
create-dictionary 66
create-object-classes 67
create-string-dictionary 66
default-attribute-value 67
dn 67
dn-create-format 67
dn-format 67
env-dictionary 66
hostname 68
limit-requests 68
max-referrals 68
max-requests 68
password 68
port 68
preference 68
query-dictionary 66
referral-atttr 68
referral-filter 68
search-filter 68
search-path 69
search-scope 69
threadwaitiime 69
timeout 69
update-dictionary 66
update-search 69
update-search-path 69
update-search-scope 69
username 69
78-12875-01
ldap command 65
create 65
delete 65
disable 65
enable 65
get 66
getEntry 66
list 66
listnames 66
set 65
setEntry 66
show 66
unset 66
unsetEntry 66
ldap-create-detail log flag (dhcp command) 33
ldap-host-name attribute (tftp command) 124
ldap-initial-timeout attribute (tftp command) 124
ldap-maximum-timeout attribute (tftp command) 124
ldap-mode attribute (dhcp command) 28
ldap-password attribute (tftp command) 124
ldap-port-number attribute (tftp command) 124
ldap-query-detail log flag (dhcp command) 33
ldap-root-dn attribute (tftp command) 124
LDAP server
managing 65
ldap-update-detail log flag (dhcp command) 33
ldap-user-name attribute (tftp command) 124
ldap-use-ssl attribute (tftp command) 124
lease command 71
activate 71
address attribute 72
available state 75
client-binary-client-id 72
client-dns-name attribute 73
client-dns-name-p-to-date flag 73
client-domain-name 73
client-flags attribute 73
client-host-name attribute 73
client-id attribute 73
IN-15Network Registrar CLI Reference Guide
Index
client-id-created-from-mac-address flag 73
client-last-transaction-time attribute 73
client-os-type attribute 73
deactivate 71
delete-reservation 72
dns-update-pending flag 73
expiration attribute 73
expired state 75
flags attribute 74
force-available 72
get 72
get-scope-name 72
leased state 75
lease-renewal-time attribute 74
list 72
-lansegment 72
-macaddr 72
-subnet 72
macaddr 72
namespace-id attribute 74
offered state 75
other-available state 75
pending-available state 75
relay-agent-circuit-id attribute 74
relay-agent-option attribute 74
relay-agent-remote-id attribute 74
relay-agent-vpn-id attribute 74
released state 75
reverse-dns-up-to-date flag 73
send-reservation 71
show 72
start-time-of-state attribute 74
state attribute 75
unavailable state 75
vendor-class-id attribute 75
lease-deactivated data item 26
leased state (lease command) 75
lease extensions 36
deferring 36
IN-16Network Registrar CLI Reference Guide
lease-ipaddress data item 26
lease-notification command 79
available addresses keyword 80
config keyword 80
errors-to keyword 80
leasing-only keyword 80
mail-host keyword 80
namespace keyword 80
recipients keyword 80
scopes keyword 80
sendmail program 80
specifying config file 81
leasequery log flag (dhcp command) 34
lease-renewal-time attribute (lease command) 74
lease-reserved data item 26
leases
clearing unavailable 104
exporting 52
forcing availability 72
getting scopes 72
managing 71
notifications 79
scope 104
setting namespace 71
showing MAC addresses 72
lease-state data item 26
lease times
policies 95
scope policies 5, 110
leasing-only keyword (lease-notification) 80
leasing-only keyword (report command) 98
license command 83
get 83
set key 83
show 83
unset key 83
license key (license command) 83
licenses
managing 83
78-12875-01
Index
Lightweight Directory Access Protocol
See LDAP
limiting authentication
clients 11
limit-requests attribute (ldap command) 68
listFields method (option-datatype command) 88
listHosts method (zone command) 135
listing
address block names only 3
address blocks 3
administrators 6
client class attributes 14
client-classes 14
client-class names 14
clients identifiers 9
DHCP custom options 18
DHCP extensions 58
DHCP interface names 42
DHCP interfaces 42
exception DNS servers 44
extensions 21
forwarder DNS servers 45
LDAP servers 66
leases 72
leases in LAN segments 72
leases in subnet 72
leases with MAC address 72
namespace names 85
namespaces 85
option data type fields 88
option data type names 88
option data types 88
policies 91
policy names 91
policy options 92
policy vendor options 92
remote DNS server names 97
remote DNS servers 97
reservations 105
78-12875-01
root hint DNS servers 44
scope leases 104
scope names 104
scope ranges 105
scopes 104
scope-selection tags 111
SNMP trap recipients 128
subnets 119
subnets of address blocks 3
suboptions (vendor-option command) 131
vendor-option command attributes 131
listing client attributes 9
listLeases method (scope command) 104
listOptions method (policy command) 92
listRanges method (scope command) 105
listRecipients method (trap command) 128
listReservations method (scope command) 105
listRR method (zone command) 136
listSuboptions method (vendor-option command) 131
listVendorOptions method (policy command) 92
little-endian option data type flag 88
localhost 2
local-port-num attribute (dns command) 45
locking
sessions 117
log-drop-message data item 18
log-file-count attribute (tftp command) 124
log files, size and number of 113
log-file-size attribute (tftp command) 124
logging
servers 113
log-level attribute (tftp command) 124
log-settings attribute (dhcp command) 28
log-settings attribute (dns command) 46
logsize attribute (server command) 113
M
mac-address data item 21, 23, 25, 26
IN-17Network Registrar CLI Reference Guide
Index
MAC addresses
client 120
extension example 1
specifying 10
troubleshooting (dhcp command) 40
mac-address-only attribute (dhcp command) 28
mail-host keyword (lease-notification) 80
managing
address-blocks 2
administrators 6
client-classes 13, 15
clients 8
DHCP servers 20
embedded policies for client-classes commands
client-class-policy 15
licenses 83
namespaces 84
option data types 87
policies 90
remote DNS servers 96
scopes 103
scope-selection tags 111
servers 112
session 116
subnets 119
TFTP server 121
map-user-class-id attribute (dhcp command) 29
mask attribute (scope command) 107
mask-bits keyword (report command) 98
max-cache-ttl attribute (dns command) 46
max-dhcp-requests attribute (dhcp command) 29
max-dhcp-responses attribute (dhcp command) 29
max-dns-packets attribute (dhcp command) 29
max-dns-renaming-retries attribute (dhcp command) 29
max-dns-retries attribute (dhcp command) 29
max-dns-ttl attribute (dhcp command) 29
maximum client lead time (MCLT) 38, 114
maximum-renaming-retries data item 28
max-inbound-file-size attribute (tftp command) 125
IN-18Network Registrar CLI Reference Guide
max-ping-packets attribute (dhcp command) 29
max-referrals attribute (ldap command) 68
max-requests attribute (ldap command) 68
max-waiting-packets attribute (dhcp command) 30
mcd-blobs-per-bulk-read attribute (dhcp command) 30
MCD persistent store
clusters 1
mem-cache-size attribute (dns command) 46
methods 3
Microsoft Visual C++ 7
minimal-config-info log flag (dhcp command) 34
min-socket-buffer-size attribute (tftp command) 125
minttl attribute (zone command) 137
missing-options log flag (dhcp command) 34
multirec keyword (remote-dns command) 96
N
NACK 13
name
namespace command 85
named.boot keyword (import command) 62
namespace 85
description 85
import command 63
lease command 71
lease-notification command 79
name attribute 85
report command 98
setting for lease 71
setting for session 116
setting to default for session 116
VPN identifier 86
namespace (address-block command) 3
namespace (scope command) 107
defining 3, 107
namespace command 84, 86
create 84
delete 84
78-12875-01
Index
list 85
listnames 85
set 84
show 85
unset 85
namespace defaults (scope command)
setting 3, 107
namespace-id
address-block command attribute 3
lease command attribute 74
scope command attribute 107
subnet command attribute 120
namespace keyword (lease-notification) 80
namespace keyword (report command) 99
namespaces
managing 84
name string (id attribute) 85
neg-cache-ttl attribute (dns command) 46
netmask
changing scope 104
nlogs attribute (server command) 113
no-dropped-bootp-packets log flag (dhcp command) 34
no-dropped-dhcp-packets log flag (dhcp command) 34
no-failover-activity log flag (dhcp command) 34
no-failover-conflict log flag (dhcp command) 34
no-fetch-glue attribute (dns command) 46
no-invalid-packets log flag (dhcp command) 34
no-recurse attribute (dns command) 46
no-reduce-logging-when-busy log flag (dhcp command) 34
no-suboption-data flag in defineSuboption keyword flags attribute (vendor-option command) 131
no-suboption-len flag in defineSuboption keyword flags attribute (vendor-option command) 131
no-suboption-opcode flag in defineSuboption keyword flags attribute (vendor-option command) 131
no-success-messages log flag (dhcp command) 34
NOTIFY, DNS 48
log flags 48
notify attribute (dns command) 46
78-12875-01
notify attribute (zone command) 137
notify-defer-cnt attribute (dns command) 46
notifying
down failover server 114
of failover (DHCP server) 22
notify-min-interval attribute (dns command) 46
notify-rcv-interval attribute (dns command) 46
notify-send-stagger attribute (dns command) 46
notify-set attribute (zone command) 137
notify-wait attribute (dns command) 46
no-timeouts log flag (dhcp command) 34
nrcmd
adding program control 2
batch file 2
general syntax 1
list of commands 5
methods 3
program location 1
specifying a series of arguments 3
using double-quotes 2
nrcmd session
managing 116
ns attribute (zone command) 137
NT registry 2
providing username and/or password 1
number
custom-option command attribute 18
custom options command attribute 17
vendor-option command attribute 130
O
offered state (lease command) 75
offer-timeout attribute (policy command) 93
one-lease-per-client attribute (dhcp command) 30
one-shot action (client command) 9, 10
optional attributes 4
option-datatype command 87
create 87
IN-19Network Registrar CLI Reference Guide
Index
defineField 87
delete 87
disable read-only 88
enable read-only 88
list 88
listFields 88
listnames 88
show 88
undefineField 88
option-datatype-name attribute (vendor-option command) 130
option data types 19
boolean 18
byte 18
byte array 18, 13
IP address 18
IP address array 18
managing 87
signed array 18
signed integer 18
string option 18
unsigned array 19
unsigned integer 19
word 19
options
system registry 2
origin attribute (zone command) 137
os-type data item 19
other-available state (lease command) 75
other-server-not-responding attribute (trap command) 128
other-server-responding attribute (trap command) 128
other-server-stop attribute (trap command) 128
outgoing-packet-detail log flag (dhcp command) 34
ownername attribute (zone command resource record method) 135
IN-20Network Registrar CLI Reference Guide
P
packet-file-name attribute (policy command) 93
packet-server-name attribute (policy command) 93
packet-siaddr attribute (policy command) 93
PARTNER-DOWN STATE 37
password attribute (ldap command) 68
passwords
administrator 7
entering (administrator) 6, 7
pending-available state (lease command) 75
performance monitoring
DHCP server 23
permanent-leases attribute (policy command) 94
person attribute (zone command) 137
ping-clients attribute (scope command) 107
ping-timeout attribute (scope command) 107
policies
lease times 95
managing 90
reply options 94
policy (address-block command) 3
policy attribute (scope command) 107
policy command 90
create 91
delete 91
disable 91
enable 91
get 91
getOptions 91
getVendorOptions 92
list 91
listnames 91
listOptions 92
listVendorOptions 92
set 91
setLeaseTime 92
setOption 91
setVendorOptions 92
78-12875-01
Index
show 91
unset 91
unsetOptions 91
unsetVendorOptions 92
policy-name (client command) 9
policy-name data item 20
port 67 10
port-number attribute (tftp command) 125
ports
ldap command attribute 68
remote (DNS) 47
trap addRecipient command attribute 128
position attribute (option-datatype command) 87
post-client-lookup
environment dictionary 22
request dictionary 22
post-client-lookup extension point 15, 22
post-client-lookup extension point (dhcp command) 35
post-packet-decode
deciding the approach 2
post-packet-decode extension point 15, 16, 19
post-packet-decode extension point (dhcp command) 35
post-send-packet extension point 35, 2, 9, 15
pre-client-lookup
environment dictionary 20
request dictionary 21
pre-client-lookup extension point 15, 19
pre-client-lookup extension point (dhcp command) 35
pre-dns-add-forward
environment dictionary 28
pre-dns-add-forward extension point 36, 3, 9, 14, 15, 27
preference attribute (ldap command) 68
pre-packet-encode
deciding the approach 2
request dictionary 24, 25
pre-packet-encode extension point 35, 2, 3, 13, 15, 16
primary-addr attribute (scope command) 107
primary-mask attribute (scope command) 107
primary-scope attribute (scope command) 107
78-12875-01
protocols
authentication 1
providing
username and/or password (NT registry) 1
put method 3, 5
Q
query-dictionary attribute (ldap setEntry command) 66
quotes
nrcmd 2
R
read-access attribute (tftp command) 125
read-only (immutable) attributes 4
read-only keyword (option-datatype command) 88
read-only keyword (vendor-option command) 130
REBIND request 13
rebuilding
resource record indexes 45, 50
recipient attribute (trap addRecipient command) 128
recipients keyword (lease-notification) 80
recording
start scavenging time (dns command) 47
recursive queries
DNS 46
referral-attr attribute (ldap command) 68
referral-filter attribute (ldap command) 68
refresh attribute (zone command) 137
registry
NT 2
Registry or environment variables 2
related failover servers 22
relay-agent-circuit-id attribute (lease command) 74
relay agent data
saving 30
relay-agent-option (subnet command) 120
IN-21Network Registrar CLI Reference Guide
Index
relay-agent-option attribute (lease command) 74
relay-agent-remote-id attribute (lease command) 74
relay-agent-vpn-id attribute (lease command) 74
release-by-ip data item 19, 20
released state (lease command) 75
reloading 4
server 10
servers 113
the server (after client configuration) 10
reload method (server command) 113
remote-dns command 96
create 96
delete 96
disabling 97
enabling 96
list 97
listnames 97
unset 97
remote DNS servers
managing 96
remote-port-num attribute (dns command) 47
REMOVE_ALL index special value 2, 6
removeDynRR method (zone command) 135
removeException method (dns command) 49
removeHost method (zone command) 135
removeRange method (scope command) 104
removeRecipient method (trap command) 128
removeReservation method (scope command) 105
removeRR method (zone command) 135
removing
exception DNS servers 44
forwarder DNS servers 44
reservations from scopes 105
root hint DNS servers 44
scope ranges 104
SNMP trap recipients 128
renaming-retries data item 28
renew-only attribute (scope command) 107
RENEW request 13
IN-22Network Registrar CLI Reference Guide
REPLACE attribute index special value 2, 5, 6
reply-ipaddress data item 25
reply options
scope policies 5, 110
reply-port data item 25
reply-to-client-address data item 22, 23, 25
report command 98
reporting
TFTP server trace levels 122
reports
generating 98
request dictionary 3, 15
REQUEST SELECTING request 13
required attributes 4
reservations (lease command)
deleting 72, 76
sending 71, 75
reservations (scope command)
adding 105
listing 105
removing 105
resource records
automatic creation (zone command) 134
rebuilding indexes 45, 50
response dictionary 3, 15
restricted-set attribute (zone command) 137
restrict-xfer attribute (zone command) 137
retry attribute (zone command) 137
return-client-fqdn-if-asked attribute (dhcp command) 30
reverse-dns-up-to-date flag (lease command) 73
reverse-name-in-dns data item 26
RFC 2782 139
root hint DNS servers
adding 44
round-robin attribute (dns command) 47
routine signature 3, 5, 6
78-12875-01
Index
S
save command 102
save-lease-renew-time attribute (dhcp command) 30
save-negative-cache-entries attribute (dns command) 47, 50
save-vendor-class-id attribute (dhcp command) 30
saving
database changes 102
relay agent data 30
scope-allow-bootp data item 27
scope-allow-dhcp data item 27
scope-allow-dynamic-bootp data item 27
scope-available-leases data item 27
scope command 103, 2
addRange 104
addReservations 105
changeMask 104
clearUnavailable 104
create 103
delete 103
disable 104
enable 104
get 104
list 104
listLease 104
listnames 104
listRanges 105
listReservations 105
removeRange 104
removeReservations 105
set 104
setting namespace defaults 107
setting namespace defaults (scope command) 3
show 104
unset 104
scope-deactivated data item 27
scope-disabled failover attribute state (scope command) 109
78-12875-01
scope-dns-forward-server-address data item 27
scope-dns-forward-zone-name data item 27
scope-dns-number-of-host-bytes data item 27
scope-dns-reverse-server-address data item 27
scope-dns-reverse-zone-name data item 27
scope-enabled failover attribute state (scope command) 109
scope-network-number data item 27
scope-ping-clients data item 25
scope policies
lease times 5, 110
reply options 5, 110
scope-policy command 110
unsetVendorOptions 5
scope-primary-network-number data item 27
scope-primary-subnet-mask data item 27
scope-renew-only data item 25
scope-renew-only-expire-time data item 25
scopes
adding ranges 104
managing 103
namespace 107
removing ranges 104
reservations 105
scope-selection-criteria data item 26
scope-selection-tag command 111
create 111
delete 111
list 111
scope-selection tags, DHCP
inclusion and exclusion criteria 111
managing 111
scope-selection-tags attribute (dhcp command) 31
scope-send-ack-first data item 26
scopes keyword (lease-notification) 80
scope-subnet-mask data item 27
scope-update-dns-enabled data item 27
scope-update-dns-for-bootp data item 27
Scripts
IN-23Network Registrar CLI Reference Guide
Index
See extension points
scvg-enabled attribute (zone command) 137
scvg-ignore-restart-interval (dns command) 47
scvg-interval attribute (dns command) 47
scvg-interval attribute (zone command) 138
scvg-no-refresh-interval attribute (dns command) 47
scvg-no-refresh-interval attribute (zone command) 138
search-filter attribute (ldap command) 68
search-list attribute (tftp command) 125
search-path attribute (ldap command) 69
search-scope attribute (ldap command) 69
selection-criteria (client command) 10
selection-criteria data item 12, 20, 23, 25
selection-criteria-excluded (client command) 10
selection-criteria-excluded data item 12, 21, 23, 25
selection tags
namespace command 85
selection-tags (address-block command) 4
selection-tags (subnet command) 120
selection-tags attribute (scope command) 107
sending
reservations (lease) 71
reservations (lease command) 75
sendmail program (lease-notification) 80
Sentinels in environment dictionaries 3
serial attribute (zone command) 138
series of arguments
specifying in nrcmd 3
server command 112
disable 112
enable 112
getHealth 113
getRelatedServers 113, 114
getStats 113
get version 113
reload argument 4
reloading 113
serverLogs 113
setPartnerDown 113, 114
IN-24Network Registrar CLI Reference Guide
start 113
stop 113
updateSms 113, 115
server-lease-time attribute (policy command) 94
serverLogs method (server command) 113
servers
managing 112
server-start attribute (trap command) 128
server statistics
getting 113
session
asserts 117
locking 117
serial numbers 117
session command 116
assert 117
locked 117
get 117
set
default-format 116
namespace 116
visibility 117
show 117
unset
namespace 116
session-timeout attribute (tftp command) 125
set keyword 3
setLeaseTime method (policy command) 92
setOption method (policy command) 91
setPartnerDown method (server command) 113
setting
address block attributes 2
administrator passwords 6
client attributes 8
client-class attributes 13
custom DHCP option attributes 18
DHCP extension attributes 57
DHCP failover-bakckup-percentage 37
DHCP interface attributes 41
78-12875-01
Index
DHCP server attributes 20
DNS log messages 46
DNS server attributes 44
failover backup percentage 37
LDAP attributes 65
LDAP entries 66
license key 83
namespace 116
namespace attributes 84
namespace defaults (scope command) 3, 107
namespace for lease 71
partner down for DHCP failover servers 113, 114
partner down mode for DHCP server 22
policy attribute values 91
policy DHCP option values 91
policy lease times 92
policy vendor options 92
scope attributes 104
session default format 116
session visibility 117
SNMP trap threshold attributes 127
TFTP server attributes 121
setVendorOption method (policy command) 92
shared library 6, 8
showing
address block attribute values 3
administrator attributes 6
client attributes 8
client-class attribute values 13
DHCP custom option attributes 18
DHCP extension attribute values 58
DHCP interface attribute values 41
DNS server attributes 44
LDAP attributes 66
lease attributes 72
license values 83
MAC addresses for leases 72
namespace attributes 85
option data type attributes 88
78-12875-01
policy attributes 91
scope attributes 104
session attributes 117
SNMP trap threshold attributes 128
subnet attributes 119
TFTP server attributes 122
signed array option data type 18
signed integer option data type 18
Simple Network Management Protocol
See SNMP
skip-client-lookup attribute (dhcp command) 31
skip-client-lookup data item 20
slave-mode attribute (dns command) 47
SMS
network discovery (dhcp command) 40
updating 22
updating servers 113, 115
sms-lease-interval attribute (dhcp command) 31
sms-library-path attribute (dhcp command) 31, 37
sms-network-discovery attribute (dhcp command) 31
sms-site-code attribute (dhcp command) 31
SNMP notifications (associated with trap command) 128
SNMP traps
activating 127
de-activating 127
managing 127
Solaris
environment variables 2
specifying
clusters (for export addresses) 53
clusters (report command) 99
MAC addresses 10
namespace (report command) 99
series of arguments (nrcmd) 3
specifying (lease- notification)
mail-host 80
specifying (lease-notification)
clusters 81, 82
configuration file 81
IN-25Network Registrar CLI Reference Guide
Index
configuration files 80
e-mail recipients 80
e-mail sender 80
leasing only 80
namespace 80
number of available addresses 80
scopes 80
split-lease-times attribute (policy command) 94
starting
servers 113
start keyword (server command) 113
start-on-reboot attribute (server command) 112
start-time-of-state attribute (lease command) 74
start-time-of-state data item 26
state attribute (lease command) 75
status codes 102
stop keyword (server command) 113
stopping
servers 113
storing
negative query results (DNS) 47, 50
string option data type 18
subnet allocation
by address block selection tags 22
using lan-segment attribute 22, 85
subnet allocation (by address block)
disabling 22, 85
subnet command 119
activate 119
deactivate 119
force-available 119
get 119
list 119
show 119
subnets
forcing availability 119
managing 119
selection tag strings from clients 120
subnet-sorting attribute (dns command) 47
IN-26Network Registrar CLI Reference Guide
suboption-name (vendor-option command)
undefine 131
suboption-name attribute (vendor-option command) 130
suboptions (vendor-option command)
list 131
SunPro C++ 7
surpressing warning messages 32
syntax, general
nrcmd 1
synthesize-name attribute (scope command) 108
synthetic-name-stem attribute (scope command) 108
System Management Server
See SMS
system registry
Network Registrar options 2
T
Tcl API 5
Tcl attribute dictionary 1
get method 1
log method 2
put method 2
remove method 2
trace method 2
Tcl extensions 1, 2
example location 5
extensions directory 6
tftp command 121
disable 121
enable 121
get 122
set 121
show 122
unset 121
TFTP server
managing 121
threadwaittime attribute (ldap command) 69
timeout attribute (ldap command) 69
78-12875-01
Index
token ring 3
trace-level data item 18
trace-level environment dictionary string 16
trace levels (TFTP server)
reporting 122
transaction-time data item 19, 21, 23, 24, 26
trap command 127
addRecipient 128
disable 127
enable 127
get 127
listRecipient 128
removeRecipient 128
set 127
show 128
unset 127
trap-free-address-high attribute (scope command) 108
trap-free-address-high-threshold attribute (scope command) 108
trap-free-address-low attribute (scope command) 108
trap-free-address-low-threshold attribute (scope command) 108
trap-free-address-reset attribute (scope command) 108
troubleshooting
MAC Addresses (dhcp) 40
TTL, default responses 138
ttl attribute (zone command resource record method) 135
txt-string data item 28
type attribute (custom-option command) 18
typeattribute (custom options) 17
type attribute (zone command) 138
type attribute (zone command resource record method) 135
types
using 7
U
unauthenticated-client-class-name (client command) 10
78-12875-01
unauthenticated-client-class-name data item 21
unavailable state (lease command) 75
undefineField method (option-datatype command) 88
undefineSuboption method (vendor-option command) 131
undefining
option data type fields 88
suboption-name (vendor-option command) 131
unknown-criteria log flag (dhcp command) 35
unsetOption method (policy command) 91
unsetting
address block attributes 3
administrator password 6
client attribute values 8
client-class attributes 13
DHCP custom option attribute values 18
DHCP extension attribute values 57
DHCP server attributes 20
DNS server attribute values 44
incremental transfers or multiple records on remote DNS servers 97
LDAP attributes 66
LDAP entries 66
license key 83
namespace 116
namespace attribute values 85
policy attributes 91
policy options 91
policy vendor options 92
scope attributes 104
scope policy vendor options 5
SNMP trap threshold attributes 127
TFTP server attributes 121
unsetVendorOption method (policy command) 92
unsigned array option data type 19
unsigned integer option data type 19
update-dictionary attribute (ldap setEntry command) 66
update-dns-first attribute (scope command) 108
update-dns-for-bootp attribute (dhcp command) 31
IN-27Network Registrar CLI Reference Guide
Index
update-dns-for-bootp attribute (scope command) 108
update-relax-zone-name attribute (dns command) 47
update-search-attribute attribute (ldap command) 69
update-search-path attribute (ldap command) 69
update-search-scope attribute (ldap command) 69
updateSms method (server command) 113
updating
SMS servers 113, 115
use-client-fqdn attribute (dhcp command) 31
use-client-fqdn-first attribute (dhcp command) 32
use-dns-update-prereqs attribute (scope command) 32, 108
use-home-directory-as-root attribute (tftp command) 125
use-host-name attribute (dhcp command) 32
use-ldap-client-data attribute (dhcp command) 32
user-defined (client command) 10
use-release-grace-period action (client command) 9
username attribute (ldap command) 69
use-server-settings failover attribute state (scope command) 109
V
validating database objects 102
variables, environment
AIC_CLUSTER 2, 1
AIC_NAME 2, 1
AIC_PASSWORD 2, 1
HKEY_CURRENT_USER 2
variables, registry or environment
Network Registrar 2
vendor-class-id attribute (lease command) 75
vendor-option
delete 130
disable read-only attribute 130
enabling the read-only attribute 130
vendor-option attributes
listing 131
vendor-option command 130
IN-28Network Registrar CLI Reference Guide
vendor options 130
arrays in 5, 95, 110
create 130
listing names
listing
vendor option names 131version keyword (server command) 113
virtual private network (VPN) 4
virtual routing forwarding 86
VPN
See virtual private network
vpn-communication attribute (dhcp command) 32
vpn-id (namespace command) 86
vrf-name (namespace command) 86
W
warning messages
suppressing with dhcp command 32
word array option data type 19
word option data type 19
write-access attribute (tftp command) 126
Z
zone command 133
attributes, table of 136
zone names
exporting 53
zones
exporting 53
78-12875-01