TCP/IP Information

DNS Administration

DNS Administration

Table of Contents

About This Information

  • Who Should Use This Information
  • What This Information Describes
  • What's New in This Information
  • Conventions Used in This Information
  • Where to Find More Information
  • Dynamic IP and DDNS Information
  • DDNS RFCs
  • Request for Comments (RFC) Documents
  • Introducing DDNS

    Learning about DDNS

  • Domain Name System (DNS) Overview
  • Domain Name Servers
  • Master Servers
  • Caching-Only Servers
  • Dynamic Updates
  • DDNS Servers and Clients
  • Authentication of Dynamic Updates
  • RSA Digital Signatures
  • SIG and KEY Resource Records
  • Planning for DDNS

  • System Requirements and DDNS Programs
  • Migrating Existing BIND Configurations
  • Migrating from UNIX-Style BIND Files
  • Migrating from Earlier Versions of OS/2 TCP/IP
  • Planning Domains
  • Adding Dynamic Domains to Existing Configurations
  • Updating Domain Data in Secondary Name Servers
  • Planning Domain Name Servers
  • Planning for Security
  • Dynamic Secured Mode
  • Dynamic Presecured Mode
  • Establishing and Using DDNS

  • Starting the DDNS Server Administrator Program
  • Setting Up Domains
  • Step 1. Establish the Basic Domain Name Server
  • Step 2. Establish Primary Domains
  • Step 3. Establish Secondary Domains
  • Step 4. Create Zone Keys for Dynamic Domains
  • Step 5. Start the Name Server
  • Step 6. Check Your Configuration
  • Step 7. Verify That Your Name Server Can Resolve Names
  • Step 8. Register New Primary and Secondary Name Servers
  • Using Advanced DDNS Functions
  • Notifying Secondary Name Servers of Domain Data Changes
  • Downloading Changed Domain Data from a Primary Name Server
  • Defining Identification Information Required from Dynamic IP End Users
  • Synchronizing Data Expiration Times between Clients and Servers
  • Separating Static and Dynamic Domain Data in a Dynamic Domain
  • Deleting SIG Resource Records
  • Backing Up a Dynamic Domain Data File
  • Reducing Cache Time for Dynamic Data
  • Maintaining DDNS

  • Modifying a Configuration
  • Modifying the Configuration for Static Domains
  • Modifying the Configuration for Dynamic Domains
  • Verifying a Configuration
  • Viewing the SYSLOG File
  • Verifying That the Name Server Can Resolve Names
  • Viewing the NSUPDATE Log
  • Diagnosing Configuration Problems
  • Viewing Signature Data for Dynamic Data Entries
  • Starting Debug Tracing
  • Viewing the Name Server Database
  • Viewing the Name Server Status
  • DDNS Files

  • Key File (DDNS.DAT)
  • Extended-Configuration File (DNSEXT.CFG)
  • Configuration Files
  • Boot File
  • Cache (Root Server) File
  • Domain Data Files
  • Cache and Domain Data File Contents
  • Special Characters Used in Configuration Files
  • Sample Files
  • Sample Extended-Configuration File (DNSEXT.CFG)
  • Sample Boot File (NAMED.BT)
  • Sample Cache (Root Server) File (NAMED.CA)
  • Sample Reverse Domain Data File for a Static Domain (NAMED.REV)
  • Sample Separated Forward Domain Data Files for a Dynamic Domain
  • Sample Forward Domain Data File for a Dynamic Domain (NAMED.DM2)
  • Sample SYSLOG Configuration File (SYSLOG.CNF)
  • Sample NSUPDATE Log Configuration File (NSUPDATE.CNF)
  • DDNS Commands

  • Syntax Diagrams
  • DDNSCFG Command
  • DDNSZONE Command
  • HOST Command
  • NAMED Command
  • NSSIG Command
  • NSUPDATE Command
  • NSUPDATE Subcommands
  • NSUPDATE Example (Adding a Host to a Presecured Dynamic Domain)
  • NSUPDATE Error Codes
  • Notices

  • Copyright Notices
  • Disclaimers
  • Acknowledgments
  • Trademarks

  • About This Information

    This document contains information about DNS administration using the Dynamic Domain Name System (DDNS), one of the components of IBM's Dynamic IP. With Dynamic IP, you can define network host configuration parameters at a central location and automate configuration of IP hosts. Dynamic IP is the integration of the Dynamic Host Configuration Protocol (DHCP), which provides configuration information to IP hosts, and DDNS, which provides dynamic host name-to-IP address (and IP address-to-host name) mapping for the Dynamic IP clients.

    This section describes:


    Who Should Use This Information

    This information is for system administrators who configure and maintain DNS using IBM's DDNS or who want to learn about DDNS.


    What This Information Describes

    This document includes these topics:

    It also includes information about:


    What's New in This Information

    This document includes updated information from these documents that were provided in earlier releases of OS/2 and TCP/IP for OS/2:

    It also includes information about the DDNS Server Administrator program, which enables you to quickly and easily configure both static and dynamic DNS domains.


    Conventions Used in This Information

    Command and file statement syntax is shown as follows:


    Where to Find More Information

    This section lists:

    It also describes how to obtain RFCs.

    Dynamic IP and DDNS Information

    For an overview of Dynamic IP and DDNS, see DHCP and Dynamic IP Introduction.

    For information about configuring a DHCP server to work with DDNS, see DHCP Server Administration.

    For background information about the Domain Name System, see DNS and BIND in a Nutshell by Paul Albitz and Cricket Liu (O'Reilly & Associates, Inc., 1997).

    DDNS RFCs

    DDNS protocols are described in these Request for Comment (RFC) documents:

    1034
    Domain Names--Concepts and Facilities, P.V. Mockapetris

    1035
    Domain Names--Implementation and Specification, P.V. Mockapetris

    1123
    Requirements for Internet Hosts--Application and Support, R. Braden

    1995
    Incremental Zone Transfer in DNS, M. Ohta

    1996
    A Mechanism for Prompt Notification of Zone Changes (DNS NOTIFY), P.Vixie

    Request for Comments (RFC) Documents

    The Internet is governed by protocols, which are defined in Internet Engineering Task Force (IETF) Request For Comments (RFC) documents. RFCs outline existing protocols, suggest new protocols, and establish standards for the Internet protocol suite. Internet drafts are proposals, techniques, and mechanisms that document IETF work in progress. Online copies of RFCs and Internet drafts are available from the InterNIC.

    To access RFCs or Internet drafts, point your Web browser at this URL, which goes to the Internet Documentation and IETF Information home page.

    http://ds1.internic.net/ds/dspg0intdoc.html
    

    You can transfer RFCs and Internet drafts by pointing your browser at this URL:

    ftp://ftp.ds.internic.net
    

    Alternatively, you can use FTP to connect to ds.internic.net. Then, you can transfer the files from the RFC directory using this format:

        RFCnnnn.TXT
        RFCnnnn.PS
    
    where:
    nnnn
    Is the RFC number
    TXT
    Indicates text format
    PS
    Indicates PostScript format

    In the RFC directory, the format for the RFC index is:

        RFC-INDEX.TXT
    

    Note:

    Many RFCs are available only in text format. Before requesting a PostScript file, first check the RFC Index to make sure the RFC is available in that format.

    You can also request online copies of RFCs through electronic mail, from the automated InterNIC mail server, by sending a message to mailserv@ds.internic.net. You must include one of these commands in the body of your note:

        SEND RFCnnnn.TXT
        SEND RFCnnnn.PS
    
    where:
    nnnn
    Is the RFC number
    TXT
    Indicates text format
    PS
    Indicates PostScript format

    For example, to request the text format of RFC 812, you would specify this command in the body of your note:

        SEND RFC812.TXT
    

    To request an online copy of the RFC index, include this command in the body of your note:

        SEND RFC-INDEX.TXT
    

    Introducing DDNS

    IBM's Dynamic Domain Name System (DDNS) is based on, and is a superset of, the Internet Software Consortium's publicly-available implementation of the Berkeley Internet Name Domain (BIND), level 4.9.3. DDNS supports both static and dynamic Domain Name System (DNS) domains. In static domains (traditional DNS domains), a system administrator creates and maintains all the data in the DNS database. In dynamic domains, authorized clients can update their own data. The client updates are authenticated using fail-safe RSA public-key digital signature technology.

    The administrator can use IBM's Dynamic IP, which includes DDNS and IBM's Dynamic Host Configuration Protocol (DHCP), to define network host configuration parameters at a central location and automate the configuration of IP hosts. DDNS provides dynamic host name-to-IP address (and IP address-to-host name) mapping for Dynamic IP clients. DHCP provides configuration information to IP hosts.

    Using DDNS with dynamic domains reduces DNS server administration, which is especially important in rapidly growing or changing TCP/IP networks and in networks where hosts change locations frequently. For example, when a host moves from subnet X to subnet Z, its IP address changes. The A resource record, which contains a mapping of a host's DNS name to its IP address, must also change so other hosts in the network can locate the client through DNS queries at its new IP address. In traditional Domain Name Systems, the user must prearrange this subnet move with an administrator. The administrator must manually change the DNS configuration files before reloading the DNS server database.

    Using DDNS, the host automatically updates its A record with its new address, which is obtained from DHCP on subnet Z without administrator intervention. In addition, IBM DHCP servers can be configured to automatically update PTR records for addresses that they serve to network hosts. The PTR record contains the reverse mapping (from a host's IP address to its host name).

    These new DDNS functions are available with TCP/IP for OS/2 Version 4.1:


    Learning about DDNS

    This section describes DDNS concepts. It includes these topics:


    Domain Name System (DNS) Overview

    While TCP/IP applications refer to hosts (computers) by their IP addresses, users find it easier to use host names. To enable the use of host names in a network, the Domain Name System (DNS) translates host names to IP addresses. DNS provides the host name to IP address mapping through network nodes called domain name servers. DNS also can provide other information about nodes and networks such as the TCP/IP services available at a node, the location of domain name servers in a network, or information about mail exchangers.

    DNS organizes the nodes (hosts) in a network into a hierarchy. A domain is a subset of a network consisting of a host and all of the hosts below it in the hierarchy. The domain at the top of a network hierarchy is known as the root domain. The root domain contains a list of all the root name servers (root servers), which store information about nodes in the root domain and about its subdomains. The root servers store the names of the name servers for the subdomains (the top-level domains in the network), which in turn store the names of name servers for their respective subdomains. For the Internet, the root servers store the names of the name servers for the delegated domains such as "com" (commercial), "edu" (education), and "mil" (military). To limit access to the Internet, for example, if a firewall is being used, root servers can be defined for the root domain of an enterprise's network.

    The complete name of a host, also known as the fully qualified domain name (FQDN), is a series of labels separated by dots or periods. Each label represents an increasingly higher domain level within a network. The complete name of a host connected to one of the larger networks generally has more than one subdomain, as in these examples:

    hostabc.subdomain2a.subdomain2
     
    user4720.eng.mit.edu
    

    Domain names reflect the hierarchy level of the domains themselves. For example, the domain eng.mit.edu is the lowest level domain and is a subdomain of mit.edu. The subdomain mit.edu is a subdomain of edu.

    Note:

    Local network administrators have the authority to name the local domains in a network.

    You can refer to a host in your domain by its host name only. However, a domain name server requires the complete name. The resolver, which is a local client that sends queries to and processes responses from a name server, combines the host name with the domain name before sending the address resolution request to the domain name server.

    DNS also provides IP address to host name mapping using a special domain called in-addr.arpa. The format of an in-addr.arpa name is the reverse octet order of an IP address concatenated with "in-addr.arpa"; for example, 143.30.67.9.in-addr.arpa is the in-addr.arpa form of the address 9.67.30.143.

    InterNIC is responsible for network and user registration, including network number, top-level domain name assignment, and "in-addr.arpa" domain assignment. For more information about registration, point your Web browser at this URL:

    ds.internic.net
    

    For a complete description of the basic concepts of the Domain Name System, see RFC 1034 and RFC 1035.


    Domain Name Servers

    A domain name server is a network node that maintains a database of information about all nodes in a zone, which is the set of subdomains for which the domain name server can resolve names and IP addresses. The domain name server is considered to be authoritative for its zone (known as its zone of authority). Using a name server for host name resolution rather than using the host table (the HOSTS file in the directory specified by the ETC environment variable) eliminates the need for a single, centralized clearinghouse for all names. A complete database is not kept by any one domain name server in a network.

    The purpose of a domain name server is to provide information about hosts in a network. TCP/IP applications query domain name servers to translate host names into IP addresses or to obtain information about a host or domain. A client who needs to communicate with another host either uses the IP address of the remote host or sends a query to a domain name server for host name resolution.

    If the domain name server that receives a query has the information (either because the name is in its zone of authority or because it has the information stored in its cache), it performs the resolution. If the query has a complete host name (fully qualified domain name), the domain name server returns the IP address for the host. If the query has an IP address, the domain name server returns the complete host name.

    When a domain name server cannot resolve a host name, it searches the domain hierarchy until it finds a name server that can resolve the name. The search typically begins with the defined root servers and then progresses down through the hierarchy until the requested information is found. The information for the query, along with the name server information found during the search, is cached for a period of time to use in subsequent name resolution requests.

    An alternate way of resolving names when a domain name server cannot resolve a name, a method which enterprises often use, is for the name server to forward the query to other name servers designated as forwarders. If the forwarders cannot resolve the name, the original name server can be configured to subsequently try the typical search (beginning with the root servers). Over time, the forwarders build up a large cache of information, which reduces the number of requests that have to be routed to the defined root servers.

    You can establish two types of name servers:

    Master Servers

    A master server is an authority for its domain. It can be a primary or a secondary (backup) server. A master server can function as a primary name server for one domain and a secondary name server for another domain. Each domain must have a primary name server and should have at least one secondary name server.

    Note:

    Master servers cache (store) data for the domains for which they are not an authority.

    A primary name server maintains all the data corresponding to its domain. Upon request, it can send its information to other name servers in its domain, known as secondary name servers.

    A secondary name server acts as a backup to a primary server if the primary name server becomes unavailable or overloaded. When a secondary name server starts, it requests all data for the specified domain from the primary name server. A secondary name server requests updated data from the primary server either because it receives notification from the primary name server (if the notify function is being used) or because it queries the primary name server and determines that the data has changed. Unless the primary server determines that downloading the entire domain is more efficient because of the large number of changes, only the changed data is downloaded, that is, an incremental zone transfer is performed.

    Note:

    An incremental zone transfer requires support in both primary and secondary servers.

    Caching-Only Servers

    A caching-only server is not an authority for any domain. When a caching-only server receives a query, it checks its cached (stored) data for the requested information. If it does not have the information, it requests the information from the appropriate master server. The caching-only server stores this data for a period of time determined by the time-to-live (TTL) field that is included in the received data and can use the data to resolve subsequent queries.


    Dynamic Updates

    In Dynamic IP, both the address (A) record, which maps a host's name to its IP address, and the pointer (PTR) record, which maps a host's IP address to its name, can be updated dynamically. The DDNS client program, NSUPDATE, is used to update information in a DDNS server.

    Dynamic updates are performed by any of the following:

    1. Network client: A host, such as a DHCP client, that typically updates its A record with current IP address information and can also update its text (TXT) record.

    2. DHCP server: A host that updates PTR records with current host name information for the addresses it allocates and that, under certain circumstances, updates A records for clients that either cannot or do not update the A records themselves.

    3. DDNS system administrator: A user who can update information in a dynamic domain (including A, PTR, and other records) either by using the DDNS Server Administrator program or by using the NSUPDATE command from a command prompt.

    The NSUPDATE agent, an extension to the NSUPDATE program used by a DHCP client or server, enhances the DDNS update process as follows:

    If a DDNS server is down when dynamic updates are requested by a DHCP client or server, the updates are saved by NSUPDATE and retried later.

    For information on how to set up a Dynamic IP client to use DDNS, refer to DHCP and Dynamic IP Introduction. For more information about configuring the DHCP server, see DHCP Server Administration.


    DDNS Servers and Clients

    DDNS servers are a superset of static DNS servers, and, therefore, they are fully compatible with existing DNS servers and can define traditional static primary or secondary domains as well as dynamic domains.

    DDNS clients can dynamically register their name and address mappings in the DNS tables directly. A DDNS client contains two major components: the resolver and the NSUPDATE agent. The resolver uses the TCP/IP RESOLV2 file in the directory specified by the ETC environment variable to determine how and where to send DNS name query requests. The NSUPDATE agent uses the client's key file (DDNS.DAT in the directory specified by the ETC environment variable) to determine how and where to send DDNS update requests.

    Note:

    The RESOLV2 file specifies the name servers to which to send name query requests and the domains to be searched. The DDNS.DAT file contains the name of the primary DDNS server to which update requests are to be sent.

    The DDNS.DAT file does not replace the RESOLV2 file and, in fact, both files are needed for correct operation of the DDNS client. Because the files are independent, they can contain values for the DNS domain and the name server(s) for performing DNS name queries that are different from those for performing DDNS updates. This independence enables a host to retain its unique network identity and resolve host names quickly, even when it moves to other locations in the network.

    For example, suppose you are based at a company's location in Raleigh, North Carolina and your laptop computer is configured as a DHCP client with DDNS and is registered with the local DDNS server as the host name myhost.raleigh.company.com. Now suppose that you take your laptop computer to your company's office in Austin, Texas, which is internetworked with the Raleigh office but has its own DNS server that serves a domain called austin.company.com.

    Assuming both office networks support DHCP, then when you are in Austin, your RESOLV2 file will contain austin.company.com as your domain and the address of the local Austin DNS server while your DDNS.DAT file remains unchanged and continues to update the Raleigh DDNS server with your DHCP-served address in Austin. Even though your locally-served domain has changed, your identity in the network remains constant as myhost.raleigh.company.com.

    Because your serving domain has changed, the default domain, which is used to resolve any host names, has also changed. For example, if you enter "ping myhost" when in Raleigh, you are pinging your own host, myhost.raleigh.company.com. However, when in Austin, you are pinging the host myhost.austin.company.com.


    Authentication of Dynamic Updates

    Without DDNS client authentication, an unauthorized (and perhaps malicious) host might impersonate an unsuspecting host by remapping the address entry for the unsuspecting host to that of its own. After the remapping, the unauthorized host could intercept data intended for the unsuspecting host (for example, login passwords).

    For the DDNS protocol, RSA digital signatures are used to authenticate the owner of DNS resource records. Two DNS resource records (SIG and KEY) carry the RSA security data necessary to authenticate the clients that are requesting updates of the DNS database.

    RSA Digital Signatures

    RSA digital signature technology is based on the use of RSA private-public key pairs. These key pairs are generated to have a mathematically-unique relationship such that:

    If a DDNS client is going to register its own name, it generates an RSA key pair and the public key is registered with the DDNS name server as a KEY resource record for that particular host name.

    The DDNS client retains the RSA key pair (with the private key encrypted) in the client key file (DDNS.DAT in the directory specified by the ETC environment variable). When the DDNS client sends update requests to the DDNS name server, the private key is used to compute the digital signature that is sent with the update.

    When the DDNS name server receives the update request, it uses the DDNS client's public key (in the KEY resource record) to:

    In this way, only the owners of the information (those that have the private key necessary to generate the correct digital signature) can update resource records that are secured by an existing KEY resource record.

    In addition, a DDNS administrator can create and use a zone key for each dynamic domain. The zone key is the administrator's RSA key pair for a particular domain and enables the administrator to create, modify, or delete any host's record in the domain. The private key is used for signing update requests for the administrator. The server examines the signature to identify update requests from the administrator. The public key is stored in the domain data file as a KEY resource record for the domain. The private and public keys are stored in the administrator's key file (DDNS.DAT).

    SIG and KEY Resource Records

    The SIG and KEY resource records are used by DDNS for authenticating clients that request updates to the DNS database. The DDNS server uses the SIG resource record in an update request from a client, along with that client's existing KEY resource record in the server, to verify that the originator of an update message is in fact the owner of a resource targeted by the update request.

    A KEY resource record holds the RSA public key of the creator of the record. There is one KEY resource record for each host plus one zone KEY resource record for the administrator of the domain.

    A SIG resource record holds an RSA digital signature, which is generated at the client and included in a dynamic update to the DDNS server. There is one SIG record for each type of resource record.


    Planning for DDNS

    To assist you in planning for DNS or introducing dynamic updates into your current IP network, this section contains these topics:


    System Requirements and DDNS Programs

    To use DDNS, you must have these programs installed:

    To configure DDNS using the DDNS Server Administrator program, you also need:

    DDNS includes the server and client programs, the DDNS Server Administrator program, sample files, and online information. The DDNS sample files can be found in the SAMPLES\ETC\NAMEDB\ subdirectory for TCP/IP.

    The programs and utilities for DDNS are:

    named.exe
    The DDNS server program

    nsupdate.exe
    The DDNS client program

    ddnsaps.cmd
    The DDNS Server Administrator program server

    ddnsapc.cmd
    The DDNS Server Administrator program client

    ddnscfg.exe
    The DDNS client configuration program for a DHCP client

    ddnszone.cmd
    A utility that assists in creating security information for the administrator of dynamic domains

    host.exe
    A program that contacts a name server to translate a host name to its IP address or an IP address to its host name

    nssig.exe
    A program that sends signals to the domain name server

    nslookup.exe
    A program that queries domain name servers

    You can use the DDNS Server Administrator program to quickly and easily configure either a name server that has the DDNS Server Administrator program installed or a remote name server that has the TCP/IP login file (TCPLOGIN.HTM) installed.

    Notes:

    1. The remote name server must also be a Web server.

    2. The TCP/IP login file must be in a directory that is exported by the Web server. For information on setting up the TCP/IP login file, see the README for TCP/IP for OS/2.

    Migrating Existing BIND Configurations

    This section provides useful information if you are replacing an existing BIND DNS server with a Dynamic DNS server. Your existing BIND server is likely either on a UNIX-style operating platform such as IBM's AIX or on an earlier version of TCP/IP for OS/2.

    Migrating from UNIX-Style BIND Files

    If your existing BIND DNS server is on a UNIX-style platform, the easiest way to migrate your files to DDNS is to install files on a HPFS file system drive. In this case, DDNS requires no modification to the files.

    If you prefer or are limited to a FAT file system drive:

    Migrating from Earlier Versions of OS/2 TCP/IP

    If you are upgrading your OS/2 DNS V2 kit to the Dynamic DNS server, and you don't want to specify any dynamic domains, then you don't need to modify any of your configuration files.

    If you are migrating from OS/2 Warp TCP/IP Version 3.1 and do not want to use any of the new function, you do not have to modify your configuration files.


    Planning Domains

    In planning domains, you need to consider:

    Adding Dynamic Domains to Existing Configurations

    Dynamic domains must be primary domains. You can either convert an existing static primary domain to allow dynamic updates or create a new primary domain to contain dynamic updates.

    If you convert an existing static primary domain, you can maintain a single domain for all your existing statically-defined hosts as well as for your new DDNS clients. Your existing static host entries are protected against updates even though they are not explicitly protected by KEY resource records in the database.

    To enable a static host to become dynamic, you must delete the static information for that host from the domain data files.

    You can physically separate the static and dynamic data for a dynamic domain by putting the data into separate files. Separating the data provides the following advantages:

    Updating Domain Data in Secondary Name Servers

    Secondary name servers for a dynamic domain might require more frequent updates than those for a static domain. To keep the secondary databases current, you should plan how and when the secondary name servers are to be refreshed. You can use the notify function, which is the default, or you can rely on the traditional refresh intervals.


    Planning Domain Name Servers

    Each domain must have a primary name server and should have at least one secondary name server. A name server can function as a primary name server for one domain and a secondary name server for another.

    Note:

    A DDNS name server must have a static IP address and, therefore, cannot be a DHCP client.

    Before you can establish domain name servers in your network, you need to determine the following:

    You also need to determine which authoritative (primary or secondary) name servers to register. A name server can be registered with the name servers for the parent domain of the domain for which the name server is authoritative. Registering a name server enables it to communicate with and receive queries from name servers outside of the domain for which it is authoritative. To use DNS throughout your network, you need to register at least one name server from each domain.

    A DDNS client must know the fully qualified domain name or IP address of the primary DDNS server to which to send an update request. A Dynamic IP client using the DDNS client configuration program for a DHCP client (DDNSCFG) defaults the name of the primary DDNS server to ns-updates.domainname, where domainname is the the same as the host's domain name. For example, if the name of a host is user4321.rtp.ibm.com, the primary DDNS server for that host defaults to ns-updates.rtp.ibm.com. An end user at a Dynamic IP client can override the "ns-updates" default at any time by simply changing the primary DDNS name server using the DDNS client configuration program for a DHCP client.

    If you want to have clients use "ns-updates" for the primary DDNS server, you will need to configure the primary DDNS name server to have that name, either directly, with an address (A) resource record, or indirectly, with an alias (CNAME) resource record in the dynamic domain. The network clients will then work without end users needing to know or specify the name of the primary DDNS name server.

    To use a name other than the default, plan to do one of the following:


    Planning for Security

    IBM DDNS servers use RSA digital signatures to authenticate DDNS update requests. The RSA public key and digital signature are contained in the KEY and SIG resource records, respectively.

    DDNS supports two modes of securing updates for a dynamic domain:

    Both modes protect a name in the database from unauthorized updates. The difference between these modes is whether the DDNS server allows the creation of a KEY resource record, or whether it must already have a KEY resource record defined for a resource in the domain. For presecured mode, the KEY resource record must be already defined in the domain before an update is accepted; specifically, the administrator must enter the KEY resource record data in the domain data file for each client that will be making updates.

    Note:

    In either mode, the administrator has the authority to create, update, or delete any resource records in a dynamic domain, regardless of who created the records, by using the zone key.

    Dynamic Secured Mode

    For secured dynamic domains, clients can generate their own RSA key pair and dynamically register a KEY resource record containing the public key with a DDNS server. This means, essentially, that any host can register with a DDNS server for a dynamic domain but cannot make updates to any host entries other than one(s) it registered.

    In secured mode (the default), any host that complies with the DDNS protocol can create resource records in a dynamic domain. Once created, these records can be updated only by the host that created them or by the administrator.

    DDNS client key generation and subsequent key registration happen automatically and without any user action. Once a host's public KEY resource record and accompanying resource records (for example, an A record) are committed to the DDNS database, only the client that registered those resource records can update them because only that client possesses the unique private key corresponding to the public KEY resource record.

    This mode of dynamic domain operation practically eliminates DNS database administration for hosts within the domain.

    Dynamic Presecured Mode

    For presecured dynamic domains, hosts must be pre-authorized by a DDNS administrator before they can update their DDNS entry. Essentially, the DDNS administrator must pre-configure RSA key information in the DDNS server for every host that is authorized to create or update resource records in a dynamic domain. Further, the administrator must also distribute the correct, corresponding key information to each host.

    In presecured mode, only hosts that have been pre-authorized by a DDNS administrator can create resource records in a dynamic domain. Once created, these records can be updated only by the host that created them or by the administrator.

    Presecured operation provides complete control over which hosts can register and update resource records but requires the additional administration of creating and distributing security information for each of the authorized hosts.


    Establishing and Using DDNS

    This section describes how to:


    Starting the DDNS Server Administrator Program

    The DDNS Server Administrator program enables you to quickly and easily configure both static and dynamic DNS domains. If you are using the DDNS Server Administrator program to configure the name server, start it in one of the following ways:

    Note:

    When you start this program, you will be prompted for a password. If you have forgotten the password or want to change it, use the TCP/IP Administrator Password program.

    Note:

    For information about using the DDNS Server Administrator program, use the help provided with the program.

    Setting Up Domains

    Note:

    To learn how to set up a simple Dynamic IP network consisting of one workstation as a Dynamic IP client and a second workstation as both the DHCP server and the DDNS server, refer to the quick start information in DHCP and Dynamic IP Introduction.

    This section describes the basic steps for setting up domains using IBM's DDNS, either manually or using the DDNS Server Administrator program. The steps are:

    1. Establish the basic domain name server.
    2. If desired, configure the name server as primary for one or more domains:
    3. If desired, configure the name server as secondary for one or more domains.
    4. For each dynamic domain, create a zone key.
    5. Start the name server.
    6. Check your configuration.
    7. Verify that the name server can resolve names.
    8. If desired, register the name server.

    Note:

    For the details of DNS, see DNS and BIND in a Nutshell.

    Step 1. Establish the Basic Domain Name Server

    If you are using the DDNS Server Administrator program to configure the name server, do the following:

    1. Open the Domain Name Server Notebook.

    2. On the Server tab, verify the name and IP address of the name server, and, if applicable, enter the names and IP addresses of other interfaces.

    3. If desired, on the Files tab, specify a different cache file name, or, to import a cache file, click Import.

    4. On the Roots and Forwarders tab, specify the names and IP addresses of the root servers.

    5. Close the Domain Server Notebook.

    6. If you want the name server to be a caching-only name server, the configuration is complete, and you can skip to the step for starting the name server. Otherwise, continue with the next step.

    If you are manually configuring the name server,

    1. Prepare the configuration files as follows:

    2. If you want the name server to be a caching-only name server, the configuration is complete, and you can skip to the step for starting the name server. Otherwise, continue with the next step.

    Step 2. Establish Primary Domains

    Note:

    This step is needed only if you want to have any primary domains.

    You can configure the name server as primary for the following:

    Establish Static Primary Domains

    Note:

    This step is needed only if you want to have any static primary domains.

    If you are using the DDNS Server Administrator program to configure the name server as primary for a static domain, do the following:

    1. Open the Primary Domain Notebook.

    2. On the Domain Configuration tab, specify the domain for which the name server is primary and change the domain type to static. (The default is dynamic for new domains.)

    3. If you do not want to create reverse mappings (the default), go to the Domain Options tab and uncheck the Automatically Create Reverse Mappings for Statically Defined Hosts in This Domain check box.

    4. If desired, on the Files tab, change the path and file name of the domain data file.

    5. Close the Primary Domain Notebook.

    6. Add hosts using the Add Hosts Window and the Host Notebook.

    If you are manually configuring the name server as primary for a forward or reverse static primary domain, do the following:

    1. Modify the boot file to specify the domain for which the name server is primary, and the path and file name of the domain data file.

    2. Create the necessary domain data files to define the hosts in the domain for which this name server is primary.

    Establish Secured Dynamic Primary Domains

    Note:

    This step is needed only if you want to have any secured dynamic primary domains.

    If you are using the DDNS Server Administrator program to configure the name server as a primary for a secured dynamic domain, do the following:

    1. Open the Primary Domain Notebook.

    2. On the Domain Configuration tab, specify the domain for which the name server is primary.

      Note:

      The domain type is set to dynamic, which is the default, and secured mode is the default for a dynamic domain.

    3. If you do not want to create reverse mappings (the default), go to the Domain Options tab and uncheck the Automatically Create Reverse Mappings for Statically Defined Hosts in This Domain check box.

    4. If desired, on the Files tab, change the path and file name of the domain data file.

    5. Close the Primary Domain Notebook.

      Note:

      When you close the Primary Domain Notebook, a zone key is automatically created.

    6. If you want to add any static hosts to the domain for which the name server is primary, use the Add Hosts Window and the Host Notebook to add them.

    7. If you do not want to use the alias "ns-updates" for the name server (which is created automatically), delete the alias or use the Alias Notebook to add a different alias.

    If you are manually configuring the name server as primary for a secured dynamic domain, do the following:

    1. Modify the boot file to specify the domain for which the name server is primary, and the path and file name of the domain data file. Be sure to specify the dynamic keyword.

    2. If you want to add any static hosts to the domain for which this name server is primary, create or modify the domain data files to define the hosts.

    3. If you want to use the default name of "ns-updates" for the name server, add an alias for it in the domain data file.

    Establish Presecured Dynamic Primary Domains

    Note:

    This step is needed only if you want to have any presecured dynamic primary domains.

    If you are using the DDNS Server Administrator program to configure the name server as primary for a presecured dynamic domain, do the following:

    1. Open the Primary Domain Notebook.

    2. On the Domain Configuration tab, if desired, specify the domain for which the name server is primary. Also, note that the domain type is set to dynamic (the default).

    3. To set the mode to presecured, on the Domain Configuration tab, click Dynamic Options to go to the Dynamic Options Notebook, and then check the Only System Administrator Can Create Client's Host Name check box.

    4. To generate host keys, in the Dynamic Options Notebook, click Generate Keys for Hosts to go to the Generate Keys Window. There, type in host names, clicking Add after each one, and then click OK to return to the Dynamic Options Notebook.

    5. Close the Dynamic Options Notebook.

    6. If you do not want to create reverse mappings, (the default), go to the Domain Options tab and uncheck the Automatically Create Reverse Mappings for Statically Defined Hosts in This Domain check box.

    7. If desired, on the Files tab, change the path and file name of the domain data file.

    8. Close the Primary Domain Notebook.

      Note:

      When you close the Primary Domain Notebook, a zone key is automatically created and any host keys that you requested are created.

    9. If you want to add any static hosts to the domain for which the name server is primary, use the Add Hosts Window and the Host Notebook to add them.

    10. If you do not want to use the alias "ns-updates" for the name server (which is created automatically), delete the alias or use the Alias Notebook to add a different alias.

    If you are manually configuring the name server as primary for a presecured dynamic domain, do the following:

    1. Modify the boot file to specify the domain for which the name server is primary, and the path and file name of the domain data file. Be sure to specify the dynamic presecured keywords.

    2. If you want to add any static hosts to the domain for which this name server is primary, create or modify the domain data files to define the hosts.

    3. If you want to use the default name of "ns-updates" for the name server, add an alias for it in the domain data file.

    4. Add each host to the domain as follows:

      1. Use NSUPDATE with the -g parameter to generate a key for the host and save it in the key file (DDNS.DAT).

      2. Use NSUPDATE with the -a parameter to dynamically register and save the host's KEY resource record in the domain data file.

      3. Manually extract the key entry from the key file (DDNS.DAT) for the host into a separate file and distribute it to the end user for installation in the DDNS.DAT file in the directory specified by the ETC environment variable.

      Note:

      An example shows using NSUPDATE to add a host to a presecured dynamic domain.

    Step 3. Establish Secondary Domains

    Note:

    This step is needed only if you want to have any secondary domains.

    If you are using the DDNS Server Administrator program to configure the name server as secondary for a domain, do the following:

    1. Open the Secondary Domain Notebook.

    2. On the Domain Configuration tab, specify the domain for which the name server is secondary and specify one or more master servers.

    3. If desired, on the Files tab, change the path and file names of the files in which the domain data from the primary domain is to be stored.

    4. Close the Secondary Domain Notebook.

    If you are manually configuring the name server as secondary for a domain, modify the boot file to specify the domain for which the name server is secondary, one or more master servers, and the path and file names of the files in which the domain data from the primary domain is to be stored.

    Step 4. Create Zone Keys for Dynamic Domains

    Note:

    This step is required for dynamic primary domains and is done for you automatically if you are using the DDNS Server Administrator program to configure the name server as primary for a dynamic domain.

    If you are manually configuring the name server as primary for a dynamic domain, use the DDNSZONE command to create the zone key for the domain. After the zone key is generated and the DDNS server is started, you can take the key file (DDNS.DAT) with you and, if you need to add or modify dynamic entries in the DNS database remotely, you can use NSUPDATE with the -a option.

    To modify a zone key, use the DDNSZONE command.

    Step 5. Start the Name Server

    If you are using the DDNS Server Administrator program, do the following:

    1. Use the File pull-down menu to save the configuration.

    2. Use the Server pull-down menu to start the name server.

    If you are manually configuring the name server, do one of the following:

    Step 6. Check Your Configuration

    After you start the name server, check the SYSLOG file to make sure the domains are configured the way you intended, that all the domains came up, and that no errors occurred.

    Step 7. Verify That Your Name Server Can Resolve Names

    To verify that the domain name server is working and can resolve names, use the HOST command.

    Note:

    Make sure that the RESOLV2 file on the client points to the name server you are testing.

    For example, if the name server is working and you enter this command:

    host aix-ps2.test.raleigh.ibm.com
    
    you would see a message similar to this:
    aix-ps2.test.raleigh.ibm.com is 9.67.30.13
    

    Step 8. Register New Primary and Secondary Name Servers

    If you configure the name server as a new authoritative (primary or secondary) name server for a domain, you might need to register the name server with the name servers for the parent domain. Registering the name server enables it to communicate with and receive queries from name servers outside of the domain for which it is authoritative.

    Note:

    If you do not register a name server, the only way it can receive queries is if it is listed in a host's RESOLV2 file.

    To register the name server, provide the following information to the administrator of the parent domain:


    Using Advanced DDNS Functions

    This section describes how to use the advanced functions of DDNS, which enable you to tune your configuration. It includes these topics:

    Notifying Secondary Name Servers of Domain Data Changes

    The notify function enables DDNS servers to inform a specified set of secondary servers that the domain data has changed. This option, which facilitates the updating of the secondary name servers and enables them to remain more current, is particularly important in domains that allow dynamic updates.

    Alternatively, secondary servers can determine whether to refresh their domain data by querying the master server to see if the serial number has changed. The intervals for querying the master server and retrying failed refreshes are defined in the SOA resource record.

    The default setting for the notify function is on.

    To turn off or control the notify function using the DDNS Server Administrator program, use the Primary or Secondary Domain Notebook as follows:

    To turn off or control the notify function manually, use the DNSEXT.CFG file (in the NAMEDB subdirectory in the directory specified by the ETC environment variable) as follows:

    For more information about the notify function, refer to RFC 1996.

    Downloading Changed Domain Data from a Primary Name Server

    The incremental zone transfer function increases the data transfer efficiency in a large domain or a dynamic domain with frequent updates. It enables a secondary name server to download only the changed data for a domain, rather than the data for the entire domain, from the primary name server. (The traditional method is to download the entire domain.)

    Note:

    An incremental zone transfer requires support in both primary and secondary servers.

    Occasionally, the number of changes is so high that it is more efficient to transfer a full zone rather than just the changed data. When the master server detects that situation, it transfers the whole zone.

    If the name server is stopped, or an nssig -HUP command is used to reload the configuration files, the information about past incremental changes might not be retained. In that case, or if problems occur during an incremental transfer, a full zone transfer is attempted.

    Note:

    IBM's DDNS always performs an incremental zone transfer, if possible.

    For more information about incremental zone transfer, refer to RFC 1995.

    Defining Identification Information Required from Dynamic IP End Users

    To enable the system administrator to quickly correlate an end user with a particular DDNS host name, the DHCP administrator can define up to 4 fields of identification information to be required from a Dynamic IP client end user, such as the end user's name and phone number. These required fields are defined in option 192 in the DHCP server. If a Dynamic IP client is served option 192, the DDNS client configuration program for a DHCP client (DDNSCFG) prompts the user for the corresponding information. The information is stored as a TXT record in the DDNS server.

    For more information on configuring the DHCP server, see DHCP Server Administration.

    Synchronizing Data Expiration Times between Clients and Servers

    The client/server time synchronization option specifies that the DDNS server is to remove data from the database after an interval of time specified by a client rather than at an absolute time specified by the client. This option is important when the client and server clocks are not identical, either because of time zone differences or incorrect clock settings.

    The DDNS server uses the interval of time specified by the client to calculate an adjusted data-expiration time, which can also be forwarded to secondary name servers.

    The default setting for both the client/server time synchronization and the forwarding of the adjusted time to secondary name servers is on.

    To control or turn off the client/server time synchronization using the DDNS Server Administrator program, use the Dynamic Options Notebook as follows:

    To control or turn off the client/server time synchronization manually, use the DNSEXT.CFG file (in the NAMEDB subdirectory in the directory specified by the ETC environment variable) as follows:

    Separating Static and Dynamic Domain Data in a Dynamic Domain

    To enable more efficient processing when dynamic data is updated, you can physically separate the static and dynamic data for a dynamic domain into separate files. The separation of data also allows updating of static data while the name server is running as well as maintaining any user comments in the static data.

    The default, if you are using the DDNS Server Administrator program, is to separate the data for new dynamic domains or, if the data is not separated for an existing dynamic domain, to prompt you whether to separate the data. The default, if you are configuring manually, is not to separate the data.

    To turn off the separation of data using the DDNS Server Administrator program, use the Primary Domain Notebook. Go to the Files tab, and uncheck the For Dynamic Domains, Keep Dynamic and Static Data for This Domain in Separate Files check box.

    To manually separate the data, do the following:

    1. Move the static data from the domain data file into a separate file.

    2. Add an $INCLUDE control-entry statement in the domain data file to include the separate static data file.

    3. In the DNSEXT.CFG file (in the NAMEDB subdirectory in the directory specified by the ETC environment variable), set sepDynStatic=yes for the domain.

    Deleting SIG Resource Records

    A SIG record exists for each record type that is entered or updated dynamically for a host and continues to exist even after the corresponding record has expired. The SIG record contains information about who entered or updated the corresponding record and when, and also when the record expired or is to expire.

    In normal operation, SIG records are not deleted. However, if the option to delete SIG records is enabled, the server automatically removes the SIG records for a host when the host name expires. For presecured dynamic domains, all SIG records corresponding to a host's resource records, except for the SIG KEY resource record, are deleted. For secured dynamic domains, all SIG records corresponding to a host's resource records, including the SIG KEY resource record, are deleted.

    If SIG records are being deleted, they are deleted when a query is received for the expired host name or at a specific time each day, whichever comes first.

    The default setting for the SIG-record deletion is off. If SIG-record deletion is set to on, the default time for deletion is 2 am.

    To turn on SIG-record deletion using the DDNS Server Administrator program, use the Dynamic Options Notebook as follows:

    To turn on SIG-record deletion manually, use the DNSEXT.CFG file (in the NAMEDB subdirectory in the directory specified by the ETC environment variable) as follows:

    Backing Up a Dynamic Domain Data File

    The DDNS server can save a copy of the file containing the dynamic domain data each time a dynamic update is made. This provides a backup of the dynamic data if an error occurs in writing the updates to the file.

    The backed-up data is stored in a subdirectory named BAK in the directory where the domain data is stored. The name of the file remains the same. For example, if the dynamic data is stored in the \NAMEDB\DOMAIN1.DOM file in the directory specified by the ETC environment variable, then the backup copy would be stored in the \NAMEDB\BAK\DOMAIN1.DOM file in the directory specified by the ETC environment variable.

    The default setting for the dynamic data backup is on.

    To turn off dynamic data backup using the DDNS Server Administrator program, go to the Dynamic Options Notebook and uncheck the Save Copy of Data before Each Update check box.

    To turn off dynamic data backup manually, set safeWrite=no for the domain in the DNSEXT.CFG file in the NAMEDB subdirectory in the directory specified by the ETC environment variable.

    Reducing Cache Time for Dynamic Data

    By default, dynamic data is created with a time-to-live (TTL) value of about 1 hour and 15 minutes. The TTL value is the amount of time a server caching the data will continue distributing the data before checking again with a master server. Thus, if a host IP address changes, it is possible for a server to still give out the old address (in error) for the TTL period of time. If the default TTL value is too long for a particular configuration, this option enables the administrator to specify a smaller, override TTL value to be given out by master servers for dynamically entered data.

    The default is not to use an override TTL value.

    To turn on the override TTL using the DDNS Server Administrator program, go to the Dynamic Options Notebook, check the Set a Maximum Time to Cache Dynamic Data for This Domain check box and specify the override TTL value in the Maximum Time field.

    To turn on the override TTL manually, set ttlSet=yes for the domain in the DNSEXT.CFG file (in the NAMEDB subdirectory in the directory specified by the ETC environment variable) and specify the override TTL value on the ttlSet.value option.


    Maintaining DDNS

    This section describes how to:


    Modifying a Configuration

    This section describes how to modify the configuration for static domains and dynamic domains.

    Modifying the Configuration for Static Domains

    If you need to modify the configuration for a static domain (for example, to add new host information), you can change the configuration in one of these ways:

    Modifying the Configuration for Dynamic Domains

    The DDNS server performs dynamic updates in the appropriate domain file as the updates occur. You can change the configuration for a dynamic domain in one of these ways:

    Note:

    The serial number will be updated automatically.

    Verifying a Configuration

    To verify a configuration, you can:

    Viewing the SYSLOG File

    The name server logs all significant events to the SYSLOG file, which is in the NAMEDB subdirectory in the directory specified by the ETC environment variable. You can check the messages in this file to determine if there were problems in loading your configuration.

    Two levels of logging are available: without debug-level messages (the default) and with debug-level messages. Usually the default is sufficient for normal usage. To change the logging level to include the debug-level messages, do one of the following:

    This is an example of a SYSLOG file for a configuration that had no errors. You can check the INFO statements to see if the domains were loaded correctly, as in the statements that show the loading of the raleigh.ibm.com and 34.37.9.in-addr.arpa domains. If there are no INFO statements indicating that the domains were loaded, you can check the other statements to look for any problems that might have occurred.

    05/08 13:23:45 NOTICE: : starting. named 4.9.3-BETA26, Mar 24 1997, 18:03:05.
    05/08 13:23:46 INFO:   : SECURED primary zone "raleigh.ibm.com" loaded (serial 1000167)
    05/08 13:23:46 INFO:   : Static primary zone "34.37.9.in-addr.arpa" loaded (serial 1000090)
    05/08 13:23:47 INFO:   : Static secondary zone "tcp.raleigh.ibm.com" loaded (serial 93070808)
    05/08 13:23:47 INFO:   : Static cache zone "" loaded (serial 0)
    05/08 13:23:47 NOTICE: : Created SIGHUP thread.
    05/08 13:23:47 NOTICE: : Created SIGINT thread
    05/08 13:23:47 NOTICE: : Created SIGIOT thread
    05/08 13:23:47 NOTICE: : Created MAINT ALARM thread
    05/08 13:23:47 NOTICE: : Created SIGUSR1 thread
    05/08 13:23:47 NOTICE: : Created SIGUSR2 thread
    05/08 13:23:47 NOTICE: : Ready to answer queries.
    

    Verifying That the Name Server Can Resolve Names

    To verify that the domain name server is working and can resolve names, use the HOST command.

    Viewing the NSUPDATE Log

    The NSUPDATE agent, when used for a DHCP client or server, logs all significant events to the NSUPDATE.LOG file, which is in the directory specified by the ETC environment variable.

    Two levels of logging are available: without debug-level messages (the default) and with debug-level messages. Usually the default is sufficient for normal usage. To change the logging level to include the debug-level messages, remove the comment from the LOG_DEBUG entry in the NSUPDATE.CNF file in the directory specified by the ETC environment variable.

    This is an example of an NSUPDATE log file that had no errors and in which the debug-level messages were included. You can check the EVENT statements to see if the NSUPDATE actions were successful, as in the statements that show host myhost101.raleigh.ibm.com being added and the update steps succeeding. If there are problems, the EVENT statements will contain an error code that indicates the problem.

    05/12 09:09:25 INFO:   : Starting nsupdate agent.
    05/12 09:09:25 INFO:   : No previous crash recover file exists
    05/12 09:09:25 INFO:   : Update A record update template = nsupdate -h%s -s"d;a;*;a;a;%s;s;%s;311040;q"
    05/12 09:09:26 INFO:   : Delete A record mapping template = nsupdate -h%s -s"d;a;%s;d;txt;%s;s;%s;0;q""
    05/12 09:09:26 INFO:   : Update hostname mapping for myhost101.raleigh.ibm.com
    05/12 09:09:26 EVENT:  : Added to mainQ -hmyhost101.raleigh.ibm.com -sd;a;*;a;a;8.67.112.50;s;18000;311040;q with transid 32177
    05/12 09:09:26 DEBUG:  : Number of elements in main queue = 1
    05/12 09:09:26 EVENT:  : Deleted from mainq -sd;a;*;a;a;8.67.112.50;s;18000;311040;q
    05/12 09:09:26 EVENT:  : DDNSInitUpdate...succeeded
    05/12 09:09:26 EVENT:  : DDNSUpdate_A...succeeded
    05/12 09:09:26 EVENT:  : DDNSUpdate_A...succeeded
    05/12 09:09:27 EVENT:  : DDNSSignUpdate...succeeded
    05/12 09:09:27 EVENT:  : DDNSSendUpdate...succeeded
    05/12 09:09:27 INFO:   : Proxy item with transid 32177 not found
    

    Diagnosing Configuration Problems

    Several utilities are available for diagnosing name server configuration problems. You can:

    Viewing Signature Data for Dynamic Data Entries

    SIG records for dynamic data entries contain data that can help you understand the absence or presence of dynamic data. From the SIG records, you can determine information such as:

    To view the SIG records with formatted fields, use the NSLOOKUP command as follows:

    Note:

    The use of NSLOOKUP requires that your name server address, which is specified in the RESOLV2 file (in the directory specified by the ETC environment variable), have a reverse mapping in your network.

    1. Start the NSLOOKUP command shell:
      nslookup
      

    2. Set the query type to SIG records:
      set qtype=sig
      

    3. Enter the name of a host whose SIG records you want to look at, for example, one of the following:
      myhost.
      myhost.raleigh.ibm.com.
      

      Note:

      Repeat this step for each host for which you want to view SIG records.

    4. Exit the command shell by typing exit or by pressing Ctrl+C.

    Note:

    For more information about NSLOOKUP, see the TCP/IP Command Reference.

    This example shows the NSLOOKUP responses when viewing the SIG records for host cooldude.test3.raleigh.ibm.com:

    Default Server:  elmer.test3.tcp.raleigh.ibm.com
    Address:  9.37.34.7
    > set qtype=sig
    > cooldude.test3.tcp.raleigh.ibm.com
            Signature Record covering A RR's
            Authentication Algorithm = 1 (MD5/RSA)  Labels = 4
            Original TTL          = 4660 (1 hour 17 mins 40 secs)
            Client SIG expiration = 850399944, Thu Dec 12 09:12:24 1996
            Time signed           = 850396344, Thu Dec 12 08:12:24 1996
            Server SIG expiration = not available.
            Key footprint = 0x3957
            Signer's name = cooldude.test3.tcp.raleigh.ibm.com
            Signature = dK+5juRCCPVQNidwhQ8C7WjqLcnMTr9jrMa2BjEsvoTU9LgOKA/V/TdvxkFy
    EsV0kMrmAjEmNvYzHZAGthPctQ==
    cooldude.test3.tcp.raleigh.ibm.com
            Signature Record covering KEY RR's
            Authentication Algorithm = 1 (MD5/RSA)  Labels = 4
            Original TTL          = 4660 (1 hour 17 mins 40 secs)
            Client SIG expiration = 853510361, Fri Jan 17 09:12:41 1997
            Time signed           = 850396362, Thu Dec 12 08:12:42 1996
            Server SIG expiration = not available.
            Key footprint = 0x3957
            Signer's name = cooldude.test3.tcp.raleigh.ibm.com
            Signature = XhGPsjhBpf1ok8J9mESO9STFtmtv+v7qnHrIPf7MXpLIBQTk4kO+rWw0XNa+
    9/d0WD+O0
    test3.tcp.raleigh.ibm.com       nameserver = elmer.test3.tcp.raleigh.ibm.com
    test3.tcp.raleigh.ibm.com       nameserver = buzz1.test3.tcp.raleigh.ibm.com
    elmer.test3.tcp.raleigh.ibm.com internet address = 9.37.34.7
    buzz1.test3.tcp.raleigh.ibm.com internet address = 9.37.34.149
    >
    

    Starting Debug Tracing

    If you have problems with the domain name server and need to collect information for service, you can start debug tracing for the domain name server. The debugging information is saved in a trace file (NAMED.RUN file in the NAMEDB subdirectory in the directory specified by the ETC environment variable).

    When you start debug tracing, you can set the level of debug messages from 1 (fewest messages written) to 11 (all debug messages written). If you do not specify the level of debug messages, the level defaults to 1. Level 5 is adequate for most purposes.

    To start debug tracing when you start the domain name server, use the -d option of the NAMED command. For example, to start the debug tracing with debug message level 5, enter:

    named -d 5
    

    To start debug tracing without restarting the name server or to increase the level of debug messages by one level, use the -USR1 option of the NSSIG command, as follows:

    nssig -USR1
    

    Note:

    If you use the -USR1 option after setting or increasing the level of debug messages to 11, the level remains at 11.

    To stop debug tracing while the name server is running, use the -USR2 option of NSSIG, as follows:

    nssig -USR2
    

    Viewing the Name Server Database

    To view the contents of the name server database and cache entries, use the -INT option of the NSSIG command. The nssig -INT command causes the domain name server database and cache file to be written to the NAMED.DMP file in the NAMEDB subdirectory in the directory specified by the ETC environment variable.

    The NAMED.DMP file enables you to see what data is in the name server cache database, which includes authoritative data as well as cached data. You can use this data to check whether the name server has the data you expect. You can also see the current time-to-live (TTL) values for cached data decreasing over time. For more information about the specifics of this file, see DNS and BIND in a Nutshell.

    This is an example NAMED.DMP file:

    ; Dumped at Thu May  8 13:27:00 1997
    ;; ++zone table++
    ; raleigh.ibm.com (type 1, class 1, source c:\mptn\etc\namedb\named.dom)
    ;	time=863114941, lastupdate=863110032, serial=1000167,
    ;	refresh=3000, retry=3000, expire=86400, minimum=3000
    ;	ftime=0, xaddr=[0.0.0.0], state=0cc1, pid=0
    ; 34.37.9.in-addr.arpa (type 1, class 1, source c:\mptn\etc\namedb\named.rev)
    ;	time=863113956, lastupdate=863093174, serial=1000090,
    ;	refresh=3000, retry=3000, expire=3000, minimum=3000
    ;	ftime=863093174, xaddr=[0.0.0.0], state=0041, pid=0
    ; 35.37.9.in-addr.arpa (type 2, class 1, source c:\mptn\etc\namedb\d35.sec)
    ;	time=863112767, lastupdate=0, serial=0,
    ;	refresh=600, retry=600, expire=0, minimum=0
    ;	ftime=0, xaddr=[0.0.0.0], state=0060, pid=0
    ;	z_addr[1]: [9.37.34.149]
    ; tcp.raleigh.ibm.com (type 2, class 1, source c:\mptn\etc\namedb\tcp.sec)
    ;	time=863112490, lastupdate=863112411, serial=93070808,
    ;	refresh=90, retry=30, expire=360, minimum=3600
    ;	ftime=863112410, xaddr=[0.0.0.0], state=0041, pid=0
    ;	z_addr[1]: [9.37.32.94]
    ;; --zone table--
    ; Note: Cr=(auth,answer,addtnl,cache) tag only shown for non-auth RR's
    ; Note: NT=milliseconds for any A RR which we've used as a nameserver
    ; --- Cache & Data ---
    $ORIGIN 
    .	86391	IN	NS	castor.cdf.ibm.com.	;Cr=auth [9.14.1.2]
    	86391	IN	NS	pollux.cbe.ibm.com.	;Cr=auth [9.14.1.2]
    	86391	IN	NS	leda2.cwp.ibm.com.	;Cr=auth [9.14.1.2]
    $ORIGIN 37.9.in-addr.arpa.
    34		IN	SOA	buzz1.raleigh.ibm.com. bug.raleigh.ibm.com. (
    		1000090 3000 3000 3000 3000 )	;Cl=5
    		IN	NS	buzz1.raleigh.ibm.com.	;Cl=5
    		IN	NS	elmer.raleigh.ibm.com.	;Cl=5
    $ORIGIN 34.37.9.in-addr.arpa.
    115		IN	PTR	bug.raleigh.ibm.com.	;Cl=5
    149		IN	PTR	buzz1.raleigh.ibm.com.	;Cl=5
    7		IN	PTR	elmer.raleigh.ibm.com.	;Cl=5
    $ORIGIN ibm.com.
    raleigh		IN	KEY	0x0080   0   1 AQO1TxJDbnsviCW66NOwALsBJ1pvtHmjgM91V1w+d2GMpEX73IX0+EY/egXDkrboWWDhW5zRzsNJkIDphKNsP0w5	;Cl=3
    		IN	SOA	bug.test3.tcp.raleigh.ibm.com. cpalmer.swamp.watson.ibm.com. (
    		1000167 3000 3000 86400 3000 )	;Cl=3
    		IN	NS	elmer.raleigh.ibm.com.	;Cl=3
    		IN	NS	buzz1.raleigh.ibm.com.	;Cl=3
    $ORIGIN cwp.ibm.com.
    leda2	86391	IN	A	9.14.1.3	;Cr=answer [9.14.1.2]
    $ORIGIN cdf.ibm.com.
    castor	604791	IN	A	9.78.1.2	;Cr=answer [9.14.1.2]
    $ORIGIN raleigh.ibm.com.
    tcp		IN	SOA	buzz.tcp.raleigh.ibm.com. dmbarton.ralvmm.raleigh.ibm.com. (
    		93070808 90 30 360 3600 )	;Cl=4
    		IN	NS	buzz.tcp.raleigh.ibm.com.	;Cl=4
    cat	4660	IN	A	7.37.34.114	;Cl=3
    elmer	4660	IN	A	9.37.34.7	;Cl=3
    bug	4660	IN	A	9.37.34.115	;Cl=3
    dog	4660	IN	A	8.37.34.113	;Cl=3
    buzz1	4660	IN	A	9.37.34.149	;Cl=3
    $ORIGIN tcp.raleigh.ibm.com.
    mikev	86400	IN	CNAME	mikev.raleigh.ibm.com.	;Cl=4
    other-end-of-stimpy	IN	A	9.67.116.113	;Cl=4
    software	86400	IN	CNAME	software.raleigh.ibm.com.	;Cl=4
    		IN	CNAME	goofy.tcp.raleigh.ibm.com.	;Cl=4
    upton2	86400	IN	CNAME	upton2.raleigh.ibm.com.	;Cl=4
    reindeer	86400	IN	CNAME	reindeer.raleigh.ibm.com.	;Cl=4
    brittone	86400	IN	CNAME	brittone.raleigh.ibm.com.	;Cl=4
    cousinit	IN	A	9.67.113.105	;Cl=4
    		IN	HINFO	"IBM-PS/2" "OS/2"	;Cl=4
    .
    .
    .
     
    

    Viewing the Name Server Status

    To view the name server status, use the -IOT option of the NSSIG command. The nssig -IOT command causes the name server to store the status of the domain name server in the NAMED.STA file in the NAMEDB subdirectory in the directory specified by the ETC environment variable.

    The NAMED.STA file enables you to see how busy the name server is, including how many of each different type of query the name server has handled as well as the number of interactions on a per-host basis. For more information about the specifics of this file, see DNS and BIND in a Nutshell.

    This is an example NAMED.STA File:

    +++ Statistics Dump +++ (860496535) Tue Apr  8 06:48:55 1997
    16	time since boot (secs)
    16	time since reset (secs)
    0	Unknown query types
    ++ Name Server Statistics ++
    (Legend)
    	RQ	RR	RIQ	RNXD	RFwdQ
    	RFwdR	RDupQ	RDupR	RFail	RFErr
    	RErr	RTCP	RAXFR	RLame	ROpts
    	SSysQ	SAns	SFwdQ	SFwdR	SDupQ
    	SFail	SFErr	SErr
    (Global)
    	0 0 0 0 0  0 0 0 0 0  0 0 0 0 0  0 0 0 0 0  0 0 0
    -- Name Server Statistics --
    --- Statistics Dump --- (860496535) Tue Apr  8 06:48:55 1997
    +++ Statistics Dump +++ (863112424) Thu May  8 13:27:04 1997
    13	time since boot (secs)
    13	time since reset (secs)
    0	Unknown query types
    ++ Name Server Statistics ++
    (Legend)
    	RQ	RR	RIQ	RNXD	RFwdQ
    	RFwdR	RDupQ	RDupR	RFail	RFErr
    	RErr	RTCP	RAXFR	RLame	ROpts
    	SSysQ	SAns	SFwdQ	SFwdR	SDupQ
    	SFail	SFErr	SErr
    (Global)
    	0 2 0 0 0  0 0 0 0 0  0 0 0 0 0  3 0 0 0 2  0 0 0
    [9.14.1.2]
    	0 1 0 0 0  0 0 0 0 0  0 0 0 0 0  1 0 0 0 0  0 0 0
    [9.37.32.94]
    	0 1 0 0 0  0 0 0 0 0  0 0 0 0 0  1 0 0 0 0  0 0 0
    [9.37.34.149]
    	0 0 0 0 0  0 0 0 0 0  0 0 0 0 0  1 0 0 0 2  0 0 0
    -- Name Server Statistics --
    --- Statistics Dump --- (863112424) Thu May  8 13:27:04 1997
    

    DDNS Files

    This section describes the files used by the DDNS domain name server:


    Key File (DDNS.DAT)

    The information created and used by NSUPDATE is stored in the key file (DDNS.DAT in the directory specified by the ETC environment variable). The DDNS.DAT file and entries are created by NSUPDATE from parameters supplied to it by other programs, end users, or network administrators. NSUPDATE automatically generates the RSA key pair for a new entry and, when appropriate, automatically registers the public KEY resource record with the DDNS server for the entry.

    The format of entries in the DDNS.DAT file is:

    host ddnsserver keypair

    host

    Specifies the fully qualified domain name or IP address of this host.

    ddnsserver

    Specifies the fully qualified domain name or IP address of the primary DDNS server for the host's domain.

    keypair

    Specifies the RSA private key, encrypted, followed by the public key.

    The following is an example of a DDNS.DAT entry:

    host4321.rtp.ibm.com ns-updates.rtp.ibm.com GMsAd... Dxst4...
    

    Attention: RSA keys are stored as very long strings and must be contained on a single line in a file. Some text editors do not handle these long file record lengths and can corrupt a DDNS.DAT file either by truncating entries or by splitting the text across several records. Be sure to use an editor that supports long file record lengths if you need to edit a DDNS.DAT file.


    Extended-Configuration File (DNSEXT.CFG)

    The extended-configuration file (DNSEXT.CFG), which is optional, provides additional configuration options for the domain name server beyond those provided by the traditional BIND DNS configuration files. If you want to use values other than the defaults for any of the options configured by this file, then this file is required.

    A sample extended-configuration file shows the defaults and the syntax rules for this file. To use this file, create the file (or modify the sample) and place it in the NAMEDB subdirectory in the directory specified by the ETC environment variable.

    Notes:

    1. If you are using the DDNS Server Administrator program, the extended-configuration file is created and updated for you.

    2. The reverseMapping keyword is set and used only by the DDNS Server Administrator program.

    Note:

    The format of each entry in the DNSEXT.CFG file is as follows:

    domainname (
    option
    option
    ...
    )
    

    domainname

    Specifies the name of the domain for which the options are being defined.

    option

    Specifies an extended-configuration option for the specified domain, as follows:

    Note:

    Each option must appear on its own line in the file.

    notify= yes| no

    Specifies whether secondary names servers are to be notified when the domain data is updated. The default set of servers to notify is the list of secondary name servers specified with NS records in the domain data file. You can change this list by using notify.add or notify.remove to add or remove servers, respectively. If notify=yes, you can also specify the following options:

    notify.add=IPaddress

    Specifies the IP address, in dotted-decimal notation, of a name server to include in the notify set. This option can be repeated. This option is ignored if notify=no. This option has no default.

    Note:

    Delete the notify.add option for a server when you no longer want to include that server in the notify set.

    notify.remove=IPaddress

    Specifies the IP address, in dotted-decimal notation, of a name server that is not to be included in the notify set. This option can be repeated. This option is ignored if notify=no. This option has no default.

    Note:

    Delete the notify.remove option for a server when you no longer want to remove that server from the notify set.

    notify.delayTime=n

    Specifies the interval, in seconds, between the first attempt to notify a server in the notify set and the first attempt to notify the next server in the notify set. This option is ignored if notify=no. The default for this option is 30 seconds.

    notify.retryTime=n

    Specifies the interval, in seconds, between successive attempts to notify a particular name server, if the attempts fail. This option is ignored if notify=no. The default for this option is 60 seconds.

    notify.retryNumber=n

    Specifies the maximum number of attempts to be made to notify a particular name server if the server fails to respond. This option is ignored if notify=no. The default for this option is 3.

    timeSync= yes| no

    Specifies whether client/server time synchronization is in effect. For client/server time synchronization, the name server calculates an adjusted data expiration time based on the length of time requested by a client rather than the absolute time specified by the client. Client/server time synchronization helps ensure the accuracy of the client-specified data expiration time when client and server clock settings are not identical or when clients and servers reside in different time zones. If timeSync=yes, you can also specify the following option:

    timeSync.toSecondaries= yes| no

    Specifies whether the adjusted data expiration time calculated by the name server is to be forwarded to the secondary name servers or to programs that request it. This option is ignored if timeSync=no.

    safeWrite= yes| no

    Indicates whether the DDNS server is to create a backup copy of its dynamic domain data file before each update. All changes except those associated with the most recent update are backed up. If you have chosen to separate the static and dynamic data, only the dynamic data is backed up.

    sigDel= no| yes

    Specifies whether a host's SIG records are to be removed when its name (KEY resource record) expires. For secured domains, all SIG records for the host will be deleted. For presecured domains, all SIG records corresponding to a host's resource records, except for the SIG KEY resource record, will be deleted. When set to no, SIG records remain indefinitely. When sigDel=yes, you can also specify the following option:

    sigDel.time=hour

    Specifies the hour, in 24-hour time, when the SIG records are to be removed from the database. This option is ignored if sigDel=no. The default for this option is 2 am.

    ttlSet= no| yes

    Specifies whether a maximum time for caching dynamic data on caching servers is to be handed out on queries. If so, the time specified is used instead of all longer cache times specified elsewhere, such as in a client record. This option enables the administrator to reduce the cache times for dynamically entered records. If ttlSet=yes, you must also specify the following option:

    ttlSet.value=n

    Specifies the maximum amount of time, in seconds, that the dynamic data for this domain is to be cached on caching servers. This option is ignored if ttlSet=no. If ttlSet=yes, you must specify this option. This option has no default.

    deferUpdCnt=n

    Specifies for dynamic domains the maximum number of updates that are to be made before the serial number is incremented. The default for this option is 100.

    incrTime=n

    Specifies for dynamic domains the maximum number of seconds to wait after an update before the serial number is incremented. The default for this option is 300 seconds (5 minutes).

    keyToSec= yes| no

    Specifies whether KEY and SIG records, which are used only in dynamic domains, are to be transferred to secondary name servers for the domain. Specify keyToSec=no when you are using a static DNS server as a secondary to a dynamic domain, and the static DNS server fails during a zone transfer because it fails to recognize the KEY and SIG resource records used in dynamic domains.

    sepDynStatic= no| yes

    Specifies whether the static and dynamic data for this dynamic domain are to be stored in separate files.

    Configuration Files

    This section describes the configuration files used by the domain name server:

    Note:

    If you are using the DDNS Server Administrator program, these files are created and updated for you.

    Boot File

    The boot file is the main configuration file for the domain name server. The default name of the boot file is either NAMED.BT or NAMED.BOOT. When the domain name server starts, it reads information from the boot file, such as the domain names for which this name server is authoritative and the location of the domain data.

    A boot file contains these types of entries:

    The entries can contain special characters.

    For each domain name server defined, you would have a set of entries similar to those shown in the sample boot file.

    Primary Entry

    A primary entry in the boot file identifies a domain for which this server is to be a primary name server, and the file from which to get its domain data.

    Note:

    A domain name server can be primary for one or more domains. If so, the boot file will contain a primary entry for each domain and each entry will point to its own file.

    The format of the primary entry is:

    primary domainname filepath [ dynamic secured| presecured]

    primary

    Specifies that this is a primary entry.

    domainname

    Specifies the name of the domain for which this domain name server will be a primary server.

    filepath

    Specifies the path and name of the domain data file for this domain name server.

    Note:

    If the path includes backslashes, you must type two backslash characters for each one you want to use.

    dynamic

    Specifies that the domain can be dynamically updated by DDNS client hosts.

    secured

    Specifies that the domain is running in secured mode. This is the default for dynamic domains.

    presecured

    Specifies that the domain is running in presecured mode.

    These example statements show primary entries. The statements identify the name server as a primary domain name server for the static domain test.raleigh.ibm.com and for the dynamic domain test2.raleigh.ibm.com. The server will get the domain information for test.raleigh.ibm.com from the C:\MPTN\ETC\NAMEDB\NAMED.DOM file and the domain information for test2.raleigh.ibm.com from the C:\MPTN\ETC\NAMEDB\NAMED2.DOM file.

    primary test.raleigh.ibm.com c:\\mptn\\etc\\namedb\\named.dom
    primary test2.raleigh.ibm.com c:\\mptn\\etc\\namedb\\named2.dom dynamic
    

    Secondary Entry

    A secondary entry in the boot file identifies a domain for which this server is to be a secondary name server and the master servers from which to get the domain data.

    Note:

    A domain name server can be secondary for one or more domains. If it is, the boot file will contain a secondary entry for each domain, and each entry will point to its own file.

    The format of the secondary entry is:

    secondary domainname IPaddress filepath

    secondary

    Specifies that this is a secondary entry.

    domainname

    Specifies the name of the domain for which this domain name server will be a secondary server.

    IPaddress

    Specifies the IP address of the domain name server from which this name server should get the domain data. This address is usually the address of the primary name server, but it can also be the address for another secondary name server. Multiple addresses can be specified, in which case the secondary name server tries each address, in the order listed, until it successfully transfers the domain.

    filepath

    Specifies the path and file name where the secondary domain server will store the domain data that it receives from the master server.

    Note:

    If the path includes backslashes, you must type two backslash characters for each one you want to use.

    These example statements show secondary entries. The first statement, which has one master server address, identifies the name server as secondary for the test.raleigh.ibm.com domain and specifies that it will get its domain data (for domain test.raleigh.ibm.com) from the master server with the IP address 9.67.30.143 and will store the data in the C:\MPTN\ETC\NAMEDB\NAMED1.SEC file. The second statement, which has two master server addresses, identifies the name server as secondary for the test2.raleigh.ibm.com domain and specifies that it will get its domain data (for domain test2.raleigh.ibm.com) from the master server with the IP address 9.67.30.144 (and, if that is unsuccessful, from the master server with the IP address 9.67.30.147) and will store the data in the C:\MPTN\ETC\NAMEDB\NAMED2.SEC file.

    secondary test.raleigh.ibm.com 9.67.30.143 c:\\mptn\\etc\\namedb\\named1.sec
    secondary test2.raleigh.ibm.com 9.67.30.144 9.67.30.147 c:\\mptn\\etc\\namedb\\named2.sec
    

    Cache Entry

    The cache entry in the boot file identifies the cache (root server) file. The cache file contains the names and addresses of the defined root servers. The domain name server contacts the root servers when attempting to resolve queries outside its zone of authority.

    The format of the cache entry is:

    cache . filepath

    cache

    Specifies that this is a cache entry.

    .

    Specifies that the cache file is for the root (parent) domain. A period (.) is a special character indicating the root domain.

    filepath

    Specifies the path and name of the cache file for this domain name server.

    Note:

    If the path includes backslashes, you must type two backslash characters for each one you want to use.

    This example statement shows a cache entry. The statement identifies the C:\MPTN\ETC\NAMEDB\NAMED.CA file as the file that contains the addresses of the root servers.

    cache  .   c:\\mptn\\etc\\namedb\\named.ca
    

    Directory Entry

    The directory entry in the boot file specifies the current working directory in which the domain data files are to be found.

    Note:

    If the DDNS Server Administrator program reads in a directory entry, it incorporates the directory information into the file path statements and then discards the entry when it writes the file.

    The format of the directory entry is:

    directory workdir

    directory

    Specifies that this is a directory entry.

    workdir

    Specifies the directory path that is to be used as the current working directory.

    Note:

    If the path includes backslashes, you must type two backslash characters for each one you want to use.

    This example statement shows a directory entry, along with a primary entry. The primary statement specifies a domain data file of NAMED2.DOM for the test2.raleigh.ibm.com domain. Because the directory statement specifies that the current working directory is C:\MPTN\ETC\NAMEDB, the domain data file for the test2.raleigh.ibm.com domain is actually C:\MPTN\ETC\NAMEDB\NAMED2.DOM.

    directory c:\\mptn\\etc\\namedb
    primary test2.raleigh.ibm.com named2.dom dynamic
    

    Forwarders Entry

    The forwarders entry in the boot file specifies one or more name servers to which to send unresolved queries.

    Note:

    If you specify the forwarders entry, you can also specify the slave entry.

    The format of the forwarders entry is:

    forwarders IPaddresses

    forwarders

    Specifies that this is a forwarders entry.

    IPaddresses

    Specifies the IP addresses of one or more name servers to which to forward unresolved queries.

    This example statement shows a forwarders entry. The statement identifies the servers with IP addresses 9.37.34.148 and 9.37.32.55 as forwarders.

    forwarders 9.37.34.148 9.37.32.55
    

    Slave Entry

    The slave entry in the boot file specifies that the name server can contact only forwarders for resolving queries.

    Note:

    The slave entry can be specified only if the forwarders entry is also specified.

    The format of the slave entry is:

    slave

    Note:

    The slave entry has no parameters.

    Cache (Root Server) File

    The cache (root server) file contains the names and IP addresses of the root authoritative domain name servers. The path and name of this file are specified in the cache entry in the boot file. The file name can be whatever you want.

    Note:

    Despite the name of this file, it does not contain cached domain data.

    When a name server does not have the data to resolve a query, it typically contacts the root servers to begin its search down through the domain name hierarchy. Because of that, the cache file is usually required if a name server is to interact with other name servers.

    The cache file contains control entries and resource records.

    For each domain name server defined, you would have a set of entries similar to those shown in the sample cache file.

    Domain Data Files

    The domain data files contain information about a domain, such as the IP addresses and names of the hosts in the domain. A domain data file contains the data for only one domain. The file name can be whatever you want.

    The forward domain data file contains entries that provide forward mapping; that is, the file maps names to IP addresses for hosts in the domain. The file also contains other data for the hosts, such as mail (MX) or text (TXT) resource records. For dynamic domains with separated static and dynamic data, the forward domain data file, which contains the dynamic data, must contain an $INCLUDE statement to include the file that contains the static data.

    The reverse domain data file contains entries that provide reverse mapping; that is, they map IP addresses to host names. This file contains pointer (PTR) resource records. The IP addresses are represented as special names called in-addr.arpa names.

    Domain data files contain control entries and resource records.

    For each primary domain, you would have a domain data file. The sample files include a static domain reverse-mapping file and a dynamic domain forward-mapping file with the static and dynamic data unseparated. They also include sample files for a dynamic domain with data separated into a dynamic domain data file and a static domain data file.

    Cache and Domain Data File Contents

    Cache (root server) and domain data files contain these types of entries:

    The entries can also contain special characters.

    Control Entries

    Control entries perform special functions within the cache (root server) and domain data files.

    Note:

    Control entries can contain special characters.

    These two control entries are defined:

    $ORIGIN domainname

    Specifies a domain name that is to be appended to each host name that does not end with a period (.), for example:
    $ORIGIN test.raleigh.ibm.com
    

    Note:

    The domain specified applies to the host names that follow the $ORIGIN entry, until a subsequent $ORIGIN entry sets the origin to another domain name. The origin for host names that precede an $ORIGIN statement is the domain specified on the primary statement in the boot file.

    $INCLUDE file [origin]

    Specifies a file that is to be included in the current file, for example:
    $INCLUDE c:\\mptn\\etc\\namedb\\named.inc
    

    To specify a domain name that sets a temporary origin domain for the entries in an included file, include the origin name, for example:

    $INCLUDE c:\\mptn\\etc\\namedb\\named.inc raleigh.ibm.com
    

    Note:

    If the domain data is separated for a dynamic domain, the static domain data must be included in the dynamic domain data file using this control entry.

    Resource Records

    Data associated with hosts is contained in resource records in the cache (root server) and domain data files. The start-of-authority (SOA) resource record is the only required resource record.

    Note:

    Resource records can contain special characters.

    The format of a resource record is:

    hostname [ttl] IN recordtype recorddata

    hostname

    Specifies the name of the host to which the resource record applies. If this field is blank, the resource record applies to the previously specified host. This is a complete name; if the name does not end with a period (.), the name of the origin domain is appended to form a complete name.

    ttl

    Specifies the time-to-live (TTL) value for this entry, in number of seconds, which is the amount of time that a record is valid in a cache. Because a default TTL value is specified in the default-TTL field in the SOA record, this TTL value is optional.

    IN

    Specifies the address class for this entry as internet.

    recordtype recorddata

    Indicates the type of record for this entry and any record-specific data that is required. The following record types and record data are valid:

    A IPaddress

    Indicates an address record, which contains the dotted-decimal IP address for the name identifying the record. This record provides forward mapping (host name to IP address). The A keyword is followed by the IP address.

    CNAME canonicalname

    Indicates a canonical name record, which provides alias or alternative name information for a host name. The name specified in the host name field of the record is an alternative to the name specified in the canonical (real) name field. The CNAME keyword is followed by the canonical name.

    HINFO processor operatingsystem

    Indicates a host information record, which specifies the processor type and operating system of a node. The HINFO keyword is followed by the processor and operating system; any text is valid for these parameters.

    KEY publickey

    Indicates a public key record, which contains the RSA public key of the creator of the record. This resource record is used only for dynamically defined entries. There is one zone key for the domain and one key for each dynamically defined host. The KEY keyword is followed by the public key.

    Note:

    This record is created and updated by NSUPDATE. Do not edit this record.

    MB mailhost

    Indicates a mailbox record, which contains the name of a host that is to receive mail for the user specified in the host name field. The MB keyword is followed by the name of the host that is to receive the mail.

    MG groupmember

    Indicates a mail group member record, which specifies the name of a mailbox belonging to the mail group specified in the host name field. The MG keyword is followed by the complete host name of the mailbox.

    MINFO responsiblehost errorhost

    Indicates a mailbox information record, which specifies the mail addresses of the clients responsible for the mail group specified in the host name field and the mailbox that is to receive error messages. The MINFO keyword is followed by the complete host names of the responsible and error mailboxes.

    MR newname

    Indicates a mail rename name record, which specifies a mailbox that is a rename of the mailbox specified in the host name field. The MR keyword is followed by the mail rename name.

    MX preference exchange

    Indicates a mail exchanger record, which identifies a host capable of acting as a mail exchange for the host or domain specified in the host name field. A mail exchange runs a mail agent that delivers or forwards mail for the specified host or domain. The preference is a number between 0 and 65535, where 0 indicates the most preferred mail exchanger. A preference number is significant only in relation to other specified mail exchangers. If the mail exchanger with the lowest preference number cannot be contacted, then the one with the next lowest number is tried. The MX keyword is followed by the mail preference and complete host name for this mail exchange.

    NS servername

    Indicates a name server record, which contains the name of an authoritative name server for the domain specified in the host name field. The NS keyword is followed by the complete name of the name server.

    PTR hostname

    Indicates a pointer record, which is used to store data for the in-addr.arpa domain and contains the host name referenced by an IP address. The PTR keyword is followed by the complete host name.

    SIG recordtype signaturedata

    Indicates a signature-data record, which contains information about the last dynamic update for each of the specified record types. There is one SIG record for each type of resource record. The SIG keyword is followed by the type of record to which it applies and by the signature information, such as when the client created (signed) an update, the client's identification, and when the client and server expect the data to expire.

    Note:

    This record is created by NSUPDATE. Do not edit this record. To view formatted SIG records, use NSLOOKUP.

    SOA sourcename mbox serial refresh retry expire defaultTTL

    Indicates the start-of-authority record, which specifies that this name server is authoritative for the domain specified in the host name field. This record, which is required, contains the administrative details of the domain. There is only one SOA record per domain. The SOA keyword is followed by:

    • sourcename, the domain name of the name server responsible for the domain.

    • mbox, the mail address of the user responsible for the domain. This is a fully qualified domain name (such as test.raleigh.ibm.com); the @ symbol is not allowed.

    • serial, the serial number of the domain database, which identifies the current revision of the data.

    • refresh, the refresh interval, which indicates the length of time (in seconds) a secondary server for this domain should allow between refreshes from the master server.

      Note:

      If the notify option is being used, the notify parameters control the refreshing of the secondary name servers.

    • retry, the retry interval, which indicates the length of time (in seconds) a secondary server for this domain should allow before retrying a failed refresh.

    • expire, the expiration time, which indicates the length of time a secondary server should consider its data valid in the event it is not able to contact the master server. If there is no contact with the master server prior to the expiration time, the secondary server will consider its data stale, and it will no longer respond to queries for this domain.

    • defaultTTL, the default time-to-live (TTL) value for records that do not have a TTL value specified, which determines the length of time the data can be cached. This value is given in response to a query or a secondary transfer.

    Note:

    Two parameters previously coded on the SOA resource record, the deferred update count and the increment time, are now specified in the extended-configuration file (DNSEXT.CFG in the NAMEDB subdirectory in the directory specified by the ETC environment variable) with the deferUpdCnt and incrTime options, respectively, although they are still accepted on the SOA record. If they are specified in both the SOA record and the DNSEXT.CFG file, the values in the DNSEXT.CFG file are used.

    TXT textdata

    Indicates a text string record, which contains descriptive text. The TXT keyword is followed by any descriptive text.

    WKS IPaddress protocol servicelist

    Indicates a well-known-services record, which describes the services provided by a protocol on a particular interface. Each defined TCP/IP service has a unique protocol number. The WKS keyword is followed by the IP address, a protocol number, and a list of the services provided.

    Special Characters Used in Configuration Files

    The following characters have special meanings in configuration files:

    @
    Denotes the current domain (origin).

    .
    Represents the null domain name of the root.

    \
    When followed by any character other than a digit, indicates that the character, rather than the character's special meaning, is to be used. For example, in a mail box specification, you can use a backslash followed by a dot (\.) to place a dot in the local part of the name. The name server treats the dot as a normal character and not as the end of the name.

    ( )
    Specifies the grouping of data that spans lines. Line terminations are not recognized within parentheses. These are typically used in SOA records.

    ;
    Specifies a comment, which can appear anywhere on a line. The remainder of the line is ignored.

    Note:

    If you enter comments into a domain data file that contains dynamic data for a dynamic domain, the comments are deleted when the next update to the domain is made. Comments are not maintained in a domain data file that contains dynamic data because they can degrade the performance of the file update process. If the data for a dynamic domain is separated, the comments in the static domain data remain intact.

    Sample Files

    During installation, sample files for DDNS are installed in the SAMPLES\ETC\NAMEDB\ subdirectory. You can customize these files for your use. The following sample files are available:

    Sample Extended-Configuration File (DNSEXT.CFG)

    This is a sample extended-configuration file (DNSEXT.CFG). Comments in the file, which begin with a semicolon (;), describe the syntax rules for the file. Refer to information about the DNSEXT.CFG file for descriptions of the entries.

    ;
    ; dnsext.cfg:  IBM DNS configuration parameters (in %ETC\namedb)
    ;      The values shown are all default values (file is not required).
    ;
    ;      Formatting features:
    ;
    ;        1. Comments are denoted by ';', and may be anywhere on the line.
    ;           anything after the ';' on a line is considered part of the comment.
    ;        2. Configuration data begins with the domain name, followed by
    ;           optional blanks, followed by an open '(', all on one line.
    ;        3. After the domain name lines, there may be one or more lines
    ;           of the format "keyword=parameter".  Each of these keyword
    ;           specifications must be on a line by itself (with optional comments).
    ;        4. After all the desired keywords have been specified for the domain,
    ;           there must be a ')', on a line by itself.
    ;        5. There may be any number of these domain units specified, but
    ;           the only ones which will be used are those which correspond
    ;           to a domain specified in the boot file.  If a domain is listed
    ;           more than once, only the first instance will be used.
    ;        6. Blank lines are ignored.
    ;        7. Within a domain, parameters may be specified in any order.  If
    ;           there are duplicate entries, the last one will be used.
    ;
    raleigh.ibm.com (
    notify=yes
    ;notify.add = 9.37.34.149
    ;notify.remove=9.37.34.7
    ;notify.delayTime= 30
    ;notify.retryTime = 60
    ;notify.retryNumber = 3
    timeSync=yes
    timeSync.toSecondaries=yes
    safeWrite=yes
    sigDel=no
    ;sigDel.time=2
    ttlSet=no
    ;ttlSet.value=3600
    deferUpdCnt=100
    incrTime=300
    keyToSec=yes
    sepDynStatic=no
    )
    

    Sample Boot File (NAMED.BT)

    This is a sample boot file (NAMED.BT). The notes explain some highlights of the file, which are indicated by numbers in braces. Refer to information about the boot file for descriptions of the entries.

    ;
    ; NAMED.BT file for name server configuration.
    ;
    ; type       domain       [master]       source file or host
    ;
    ; The following dynamic zone uses separation of dynamic & static data
    primary    raleigh.ibm.com          c:\\mptn\\etc\\namedb\\named.dom dynamic    {1}
    ; This next example (commented out) shows same data with no separation
    ;primary    raleigh.ibm.com          c:\\mptn\\etc\\namedb\\named.dm2 dynamic   {1}
     
    ; The following zone is static
    primary    34.37.9.in-addr.arpa     c:\\mptn\\etc\\namedb\\named.rev            {2}
    ;
    secondary  35.37.9.in-addr.arpa 9.37.34.149 c:\\mptn\\etc\\namedb\\d35.sec      {3}
    secondary  tcp.raleigh.ibm.com  9.37.32.94  c:\\mptn\\etc\\namedb\\tcp.sec      {4}
    ;
    cache    .                          c:\\mptn\\etc\\namedb\\named.ca             {5}
    ;
    

    {1}
    This entry identifies this server as a primary server for the raleigh.ibm.com domain, which is a dynamic domain, and specifies that the domain data is in the C:\MPTN\ETC\NAMEDB\NAMED.DOM file. The commented-out entry specifies a different domain data file (NAMED.DM2) to be used when the data is not separated.

    {2}
    This entry identifies this server as a primary server for a static reverse domain 34.37.9.in-addr.arpa and specifies that the domain data is in the C:\MPTN\ETC\NAMEDB\NAMED.REV file.

    {3}
    This entry identifies this server as a secondary server for the reverse domain 35.37.9.in-addr.arpa and specifies that it will get its domain data from the name server at address 9.37.34.149 and will store the domain data in the C:\MPTN\ETC\NAMEDB\D35.SEC file.

    {4}
    This entry identifies this server as a secondary server for the tcp.raleigh.ibm.com domain and specifies that it will get its domain data from the name server at address 9.37.32.94 and will store the domain data in the C:\MPTN\ETC\NAMEDB\TCP.SEC file.

    {5}
    This entry identifies the cache file, which lists the root servers, as the C:\MPTN\ETC\NAMEDB\NAMED.CA file.

    Sample Cache (Root Server) File (NAMED.CA)

    This is a sample cache (root server) file (NAMED.CA). The notes explain some highlights of the file, which are indicated by numbers and letters in braces. Refer to information about the cache file for descriptions of the entries.

    ;***********************************************************************
    ;   Root domain data (cache file)
    ;   --------
    ;   Contains all addresses and records for the root zone              
    ;
    ;***********************************************************************
    ;  root nameserver(s) for ibm                                          
    ;  (if no firewall, these would be the true internet root nameservers) 
    ;
    .                            608000  IN  NS  leda.cwp.ibm.com.    {1}
    {a}                          {b}     {c} {d} {e}
    .                            608000  IN  NS  castor.cbe.ibm.com.
    .                            608000  IN  NS  pollux.cbe.ibm.com.
    ;
    ; address(es) of domain nameservers
    ;
    leda.cwp.ibm.com.           608000  IN  A   9.14.1.2              {2}
    castor.cbe.ibm.com.         608000  IN  A   9.78.1.2
    pollux.cbe.ibm.com.         608000  IN  A   9.46.1.2
    ;
    ;
    

    {1}
    This name server entry identifies leda.cwp.ibm.com as a domain name server for the root domain.

    {a}
    This field specifies the domain as . (the root domain).

    {b}
    This field specifies the number of seconds that this entry is to be retained on servers caching the data as 608000 seconds.

    {c}
    This field specifies the address class as internet (IN).

    {d}
    This field specifies the resource record type as name server (NS).

    {e}
    This field specifies the name of the domain name server to query for information about this domain as leda.cwp.ibm.com.

    {2}
    This address entry maps the name leda.cwp.ibm.com to the IP address 9.14.1.2.

    Sample Reverse Domain Data File for a Static Domain (NAMED.REV)

    This is a sample static reverse domain data file (NAMED.REV). The notes explain some highlights of the file, which are indicated by numbers in braces. Refer to information about the domain data files for descriptions of the entries.

    ;
    ; reverse domain:  9.37.34.x
    ;    This is a static zone (no updates will be made), and comments will stay
    ;
    $ORIGIN 37.9.in-addr.arpa.
    34              IN      SOA     buzz1.raleigh.ibm.com. bug.raleigh.ibm.com. (    {1}
                    1000090 3000 3000 3000 3000 )                                    {1}
                    IN      NS      buzz1.raleigh.ibm.com.    {2}
                    IN      NS      elmer.raleigh.ibm.com.
    $ORIGIN 34.37.9.in-addr.arpa.                             {3}
    7               IN      PTR     elmer.raleigh.ibm.com.    {4}
    149             IN      PTR     buzz1.raleigh.ibm.com.
    115             IN      PTR     bug.raleigh.ibm.com.
    

    {1}
    These lines are the start-of-authority (SOA) entry for the 34.37.9.in-addr.arpa domain. The SOA entry lists information about the domain. The left and right parentheses mark the beginning and end, respectively, of the SOA data.

    {2}
    This name server (NS) entry identifies the host name buzz1.raleigh.ibm.com as a name server for the 34.37.9.in-addr.arpa domain.

    {3}
    This control entry indicates that all subsequent entries for which the host name does not end with a period are to have the specified string (34.37.9.in-addr.arpa.) appended to their names.

    {4}
    This pointer (PTR) entry maps the IP address 9.37.34.7 to the elmer.raleigh.ibm.com host name.

    Sample Separated Forward Domain Data Files for a Dynamic Domain

    These sample domain data files contain the domain data for a dynamic domain that has separated data:

    Refer to information about the domain data files for descriptions of the entries.

    Sample Domain Data File for Dynamic Data (NAMED.DOM)

    This is a sample separated domain data file containing the dynamic data (NAMED.DOM). The notes following the sample explain some highlights of the file, which are indicated by numbers in braces. Refer to information about the domain data files for descriptions of the entries.

    Note:

    This is how the file appears before the zone key is created.
    ;
    ;  Forward domain, dynamic zone.  Dynamic data is separate from static data.
    ;
    $ORIGIN ibm.com.
    raleigh         IN      SOA     buzz1.raleigh.ibm.com. bug.raleigh.ibm.com. (   {1}
                    1000167 3000 3000 86400 3000 )                                  {1}
                    IN      NS      elmer.raleigh.ibm.com.   {2}
                    IN      NS      buzz1.raleigh.ibm.com.
    $ORIGIN raleigh.ibm.com.                                 {3}
    ;
    ;  Dynamic entries will be placed here.
    ;
    $INCLUDE c:\\mptn\\etc\\namedb\\raleigh.sta              {4}
    

    {1}
    These lines are the start-of-authority (SOA) entry for the raleigh.ibm.com domain. The SOA entry lists information about the domain. When the domain data is separated, the SOA resource record is in the file that contains the dynamic data. The left and right parentheses mark the beginning and end, respectively, of the SOA data.

    {2}
    This name server entry identifies elmer.raleigh.ibm.com as a name server for the raleigh.ibm.com domain.

    {3}
    This control entry indicates that all subsequent entries for which the host name does not end with a period are to have the specified string (raleigh.ibm.com.) appended to their names.

    {4}
    This control entry includes the static domain data file, the C:\MPTN\ETC\NAMEDB\RALEIGH.STA file.

    Sample Domain Data File for Static Data (RALEIGH.STA)

    This is a sample separated domain data file that containing the static data (RALEIGH.STA). It is included by the sample dynamic domain data file NAMED.DOM. The notes following the sample explain some highlights of the file, which are indicated by numbers in braces. Refer to information about the domain data files for descriptions of the entries.

    ; This is the static data for the domain raleigh.ibm.com   {1}
    dog     4660    IN      A       8.37.34.113                {2}
    buzz1   4660    IN      A       9.37.34.149
    cat     4660    IN      A       7.37.34.114
    bug     4660    IN      A       9.37.34.115
    elmer   4660    IN      A       9.37.34.7
    

    {1}
    This line is a comment. Because this file contains only static domain data and data is being separated as specified in the DNSEXT.CFG file, it will not be dynamically updated and the comments will be left intact.

    {2}
    This address (A) entry maps the host name dog.raleigh.ibm.com. to the IP address 8.37.34.113.

    Sample Forward Domain Data File for a Dynamic Domain (NAMED.DM2)

    This is a sample forward domain data file for a dynamic domain that does not have separated dynamic and static data (NAMED.DM2). The notes following the sample explain some highlights of the file, which are indicated by numbers in braces. Refer to information about the domain data files for descriptions of the entries.

    Note:

    This is how the file appears before the zone key is created.
    ;
    ; Forward domain file.  Dynamic zone.  These comments will be lost.
    ;   No separation of dynamic and static data.
    ;
    $ORIGIN ibm.com.
    raleigh         IN      SOA     buzz1.raleigh.ibm.com. bug.raleigh.ibm.com. (   {1}
                    1000167 3000 3000 86400 3000 )                                  {1}
                    IN      NS      elmer.raleigh.ibm.com.   {2}
                    IN      NS      buzz1.raleigh.ibm.com.
    $ORIGIN raleigh.ibm.com.                                 {3}
    dog     4660    IN      A       8.37.34.113              {4}
    buzz1   4660    IN      A       9.37.34.149
    cat     4660    IN      A       7.37.34.114
    bug     4660    IN      A       9.37.34.115
    elmer   4660    IN      A       9.37.34.7
    ; 
    ; Dynamic entries will be intermixed with static data in this file
    ;
    

    {1}
    These lines are the start-of-authority (SOA) entry for the raleigh.ibm.com domain. The SOA entry lists information about the domain. The left and right parentheses mark the beginning and end, respectively, of the SOA data.

    {2}
    This name server (NS) entry identifies the host name elmer.raleigh.ibm.com as a name server for the raleigh.ibm.com domain.

    {3}
    This control entry indicates that all subsequent entries for which the host name does not end with a period are to have the specified string (raleigh.ibm.com.) appended to their names.

    {4}
    This address (A) entry maps the host name dog.raleigh.ibm.com. to the IP address 8.37.34.113.

    Sample SYSLOG Configuration File (SYSLOG.CNF)

    The SYSLOG configuration file (SYSLOG.CNF) configures the logging for the name server. The logging information is stored in the SYSLOG file. This is the default SYSLOG.CNF file, which is installed in the NAMEDB subdirectory in the directory specified by the ETC environment variable if the file does not already exist there. Comments in the sample file, which begin with the number sign (#), explain the fields in the file.

    Note:

    The entry that specifies debug-level messages is commented out.
    #################################
    # system log configuration file #
    #################################
    #
    #   Here is a list of all the keywords whose value can be specified
    #   in this file:
    #
    #   Keyword          Effect
    #   -------------    ---------------------------------------------------
    #
    #   numLogFiles      The number of log files desired.
    #   logFileSize      The Size of log files in K bytes.
    #   logFileName      The name of the most recent log file.
    #   logItem          One item to be logged.
    #
    #
    #  Log files.  This set of parameters specifies the log files that will be
    #  maintained by this server.  Each parameter is identified by a keyword
    #  and followed by its value.
    #
    #  Keyword      Value           Definition
    #  --------     ------------    ------------------------------------------
    #  numLogFiles  0 to n          number of log files.  If 0 is specified,
    #                               no log file will be maintained and no log
    #                               message is display anywhere.  n is the
    #                               maximum number of log files maintained as
    #                               the size of the most recent log file
    #                               reaches its maximum size and a new log file
    #                               is created.
    #
    #  logFileSize  in K bytes      maximum size of a log file.  When the size
    #                               of the most recent log file reaches this
    #                               value, it is renamed and a new log file is
    #                               created.
    #
    #  logFileName  file path       name of the most recent log file.  Less
    #                               recent log files have the number 1 to
    #                               (n - 1) appended to their names; the larger
    #                               the number, the less recent the file.
    #
    #  logItem                      One item that will be logged.
    #               LOG_EMERG       system is unusable
    #               LOG_ALERT       action must be taken immediately
    #               LOG_CRIT        critical conditions
    #               LOG_ERR         error conditions
    #               LOG_WARNING     warning conditions
    #               LOG_NOTICE      normal but signification condition
    #               LOG_INFO        informational
    #               LOG_DEBUG       debug-level messages
    #
    #
    numLogFiles     4
    logFileSize     100
    logFileName     syslog.
    logItem         LOG_EMERG
    logItem         LOG_ALERT
    logItem         LOG_CRIT
    logItem         LOG_ERR
    logItem         LOG_WARNING
    logItem         LOG_NOTICE
    logItem         LOG_INFO
    #logItem         LOG_DEBUG
    

    Sample NSUPDATE Log Configuration File (NSUPDATE.CNF)

    The NSUPDATE log configuration file (NSUPDATE.CNF) configures the logging for NSUPDATE. The logging information is kept in the NSUPDATE.LOG file. This is the default NSUPDATE.CNF file, which is installed in the directory specified by the ETC environment variable if the file does not already exist there. Comments in the sample file, which begin with the number sign (#), explain the fields in the file.

    Note:

    The entry that specifies debug-level messages is commented out.
    ###############################
    # nsupdate configuration file #
    ###############################
    #
    #   Here is a list of all the keywords whose value can be specified
    #   in this file:
    #
    #   Keyword          Effect
    #   -------------    ---------------------------------------------------
    #
    #   numLogFiles      The number of log files desired.
    #   logFileSize      The Size of log files in K bytes.
    #   logFileName      The name of the most recent log file.
    #   logItem          One item to be logged.
    #
    #
    #  Log files.  This set of parameters specifies the log files that will be
    #  maintained by this server.  Each parameter is identified by a keyword
    #  and followed by its value.
    #
    #  Keyword      Value           Definition
    #  --------     ------------    ------------------------------------------
    #  numLogFiles  0 to n          number of log files.  If 0 is specified,
    #                               no log file will be maintained and no log
    #                               message is display anywhere.  n is the
    #                               maximum number of log files maintained as
    #                               the size of the most recent log file
    #                               reaches its maximum size and a new log file
    #                               is created.
    #
    #  logFileSize  in K bytes      maximum size of a log file.  When the size
    #                               of the most recent log file reaches this
    #                               value, it is renamed and a new log file is
    #                               created.
    #
    #  logFileName  file path       name of the most recent log file.  Less
    #                               recent log files have the number 1 to
    #                               (n - 1) appended to their names; the larger
    #                               the number, the less recent the file.
    #
    #  logItem                      One item that will be logged.
    #               LOG_EVENT       major event occurrences
    #               LOG_ERROR       error conditions
    #               LOG_WARNING     warning conditions
    #               LOG_INFO        informational
    #               LOG_DEBUG       debug-level messages
    #
    #
    numLogFiles     4
    logFileSize     100
    logFileName     nsupdate.log.
    logItem         LOG_EVENT
    logItem         LOG_ERROR
    logItem         LOG_WARNING
    logItem         LOG_INFO
    #logItem         LOG_DEBUG
    

    DDNS Commands

    The DDNS commands are:

    In this section, syntax diagrams show you how to correctly type a command or subcommand.


    Syntax Diagrams

    Syntax diagrams show you how to correctly type a command or subcommand. Read the syntax diagram from left to right and from top to bottom, following the horizontal line (the main path).

    Syntax diagrams use the following symbols:

    >>
    Marks the beginning of the syntax
    >
    Marks the continuation of the syntax
    |
    Marks the beginning and end of a fragment or part of the syntax
    ><
    Marks the end of the syntax

    Required parameters are displayed on the main path. Optional parameters are displayed below the main path. Default parameters are displayed above the main path.

    Parameters are either keywords or variables. You must type keywords as they are shown in the syntax diagram. Variables represent names or values you supply. Include all punctuation shown in the diagram, such as colons, semicolons, commas, quotation marks, and minus signs.

    Type Required Parameters: In this example, you must type both keyword and variable.

    >>-keyword--variable-------------------------------------------><
     
    

    Choose One Required Item from a List: In this example, you must choose either keyword2 or variable2.

    >>-keyword---+-keyword2--+-------------------------------------><
                 +-variable2-+
     
    

    Choose One Optional Item from a List: In this example, you can choose keywordx, keywordy, or keywordz.

    >>-keyword1---+----------+-------------------------------------><
                  +-keywordx-+
                  +-keywordy-+
                  +-keywordz-+
     
    

    Choose One Optional Item from a List with a Default: In this example, you can choose keyworda, keywordb, or keywordc. If you do not choose one, keyworda, which is the default, is used.

                  +-keyworda-+
    >>-keyword1---+----------+-------------------------------------><
                  +-keywordb-+
                  +-keywordc-+
     
    

    Include Several Items or Repeat Items from a List: In this example, you can repeat or choose several or all of keyword3, keyword4 var4, and keyword5; if you choose more than one item or repeat items, you must use a semicolon (;) between the items.

                 +-;------------------+
                 V                    |
    >>-keyword-----+-----------------++----------------------------><
                   +-keyword3--------+
                   +-keyword4--var4--+
                   +-keyword5--------+
     
    

    DDNSCFG Command

    Use the DDNSCFG command to start the DDNS client configuration program for a DHCP client. The syntax is:

                                             +---------------+
                                             V               |
    >>-ddnscfg--- -hhostname-- -pnameserver----+-----------+-+-----><
                                               +- -l#value-+
     
    

    -hhostname

    Specifies the host being configured.

    -pnameserver

    Specifies the name or IP address of the primary DDNS name server.

    -l#value

    Specifies the value of an identification information field required by the system administrator. Up to 4 fields can be required. # is a number (1 to 4) indicating which field the value is for.

    Note:

    The value cannot contain colons (:) or semicolons (;).

    DDNSZONE Command

    Use the DDNSZONE command to create or modify zone keys on the DDNS server for a dynamic domain. The public key is stored in the domain file as a KEY resource record for the zone. The private and public keys are stored in the key file. (The default key file is DDNS.DAT in the directory specified by the ETC environment variable).

    By default, the DDNSZONE command uses the boot file located in the NAMEDB subdirectory in the directory specified by the ETC environment variable to prompt the user through creating or modifying the keys for the dynamic domains defined therein. DDNSZONE updates the configuration files for a dynamic domain with the KEY resource record and places the corresponding key information in the key file (DDNS.DAT).

    The syntax is:

    >>-ddnszone----------------------------------------------------><
     
    

    HOST Command

    Use the HOST command to verify that the domain name server can resolve names. The HOST command contacts a DNS server to translate a specified host name to its IP address or translate a specified IP address to its host name.

    Note:

    To check a name server, it must either be registered or listed in the RESOLV2 file.

    The syntax is:

    >>-host---+-hostname--+----------------------------------------><
              +-IPaddress-+
     
    

    hostname

    Specifies the name of the host whose IP address is to be translated.

    IPaddress

    Specifies the IP address of the host whose name is to be translated.

    NAMED Command

    Use the NAMED command to start the domain name server. The syntax is:

    >>-named--+----------------------+--+---------------+--+-------------+->
              +- -d-+------------+---+  +- -pportnumber-+  +- -bbootfile-+
                    +-debuglevel-+
     
    >--------------------------------------------------------------><
     
    

    -d debuglevel

    Specifies debug tracing, in which debugging information is written to the NAMED.RUN file in the NAMEDB subdirectory in the directory specified by the ETC environment variable. The optional variable debug_level specifies the level of debug messages. Valid levels are 1 to 11, where 11 supplies the most debugging information and 1 is the default. Level 5 is adequate for most purposes.

    -pportnumber

    Reassigns the Internet socket at which the domain name server listens for domain requests. If this parameter is not specified, the domain name server listens at the socket defined in the SERVICES file in the directory specified by the ETC environment variable with an entry that begins with domain. This option is used primarily for testing.

    -bbootfile

    Specifies the name of the boot file. If this parameter is not specified, the domain name server looks for the NAMED.BT file in the NAMEDB subdirectory in the directory specified by the ETC environment variable. If the NAMED.BT file is not found, it looks for the NAMED.BOOT file in the same directory.

    NSSIG Command

    Use the NSSIG command to reload or dump the database, turn debugging trace on or off, or obtain statistics for the name server. The syntax is:

    >>-nssig---+--------+------------------------------------------><
               +- -HUP--+
               +- -INT--+
               +- -IOT--+
               +- -USR1-+
               +- -USR2-+
     
    

    -HUP

    Reads the boot file from the disk and reloads the domain name server's database.

    -INT

    Dumps the domain name server's database and cache file to the NAMED.DMP file in the NAMEDB subdirectory in the directory specified by the ETC environment variable.

    -IOT

    Stores statistics for the domain name server in the NAMED.STA file in the NAMEDB subdirectory in the directory specified by the ETC environment variable.

    -USR1

    Starts debug tracing for the domain name server and sets the level of debug messages to 1 or, if debug tracing is already started, increases by 1 the level of debug messages.

    Note:

    If you use the -USR1 option after setting or increasing the level of debug messages to 11, the level remains at 11.

    -USR2

    Stops debug tracing.

    NSUPDATE Command

    Use the NSUPDATE command to dynamically update information in a DDNS name server that is configured to accept updates. You can use the NSUPDATE command to start the NSUPDATE command shell, where you use the NSUPDATE subcommands interactively to perform the updates. Alternatively, you can use NSUPDATE in "batch" mode by specifying a subcommand sequence using the -s parameter.

    This section also describes an NSUPDATE example and the NSUPDATE error codes.

    The syntax is:

    >>-nsupdate----------------------------------------------------->
     
    >--+---------------------------------------------------------------------------------------+->
       +--+- -xkeyfile-- -kkeyfile-- -hhostname-- -ddomainname-- -pprimaryddns-- -rIPaddress-+-+
          +- -s "commandstring"--------------------------------------------------------------+
     
    >-+-----+--+-----+--+-----+--+-----+--+-----+------------------><
      +- -a-+  +- -f-+  +- -g-+  +- -q-+  +- -v-+
     
    

    Displaying NSUPDATE Help

    >>-nsupdate-- -?-----------------------------------------------><
     
    

    Note:

    To start the NSUPDATE command shell, use the NSUPDATE command without the -s parameter. After you enter the NSUPDATE command shell, you can use the NSUPDATE subcommands. To exit the command shell, use the quit subcommand.

    -xkeyfile

    Specifies an alternate key file to use for storing and retrieving the administrator key information. By default, NSUPDATE uses the DDNS.DAT file in the directory specified by the ETC environment variable, or if the -k parameter is used, the key file specified by the -k keyword.

    -kkeyfile

    Specifies an alternate key file to use for storing and retrieving client key information. By default, NSUPDATE uses the DDNS.DAT file in the directory specified by the ETC environment variable.

    -hhostname

    Specifies the name or alias of a remote host.

    -ddomainname

    Specifies the name of the dynamic domain for the host. This parameter is not needed if the -h parameter specifies a complete host name.

    -pprimaryddns

    Specifies the complete name or IP address of the DDNS server that is primary for the domain.

    Note:

    This parameter is required the first time an update is made for a particular host name, unless a wildcard entry that applies to the host name being entered has been specified previously in the key file.

    -rIPaddress

    Specifies the IP address used to update PTR records. (You cannot specify -r if you specify -h or -d.)

    -s "commandstring "

    Specifies a string of NSUPDATE subcommands with the associated required input. Subcommands are separated by semicolons (;).

    Note:

    This parameter is useful for programs that call NSUPDATE.

    This example shows how the -s parameter is used to add an A record for host name host4321.rtp.ibm.com with an IP address of 9.67.96.10, an expiration time of one hour (3600 seconds), and a dynamic data extension time of 36 days (3110400 seconds):

    nsupdate -h host4321.rtp.ibm.com -s "a;a;9.67.96.10;s;3600;3110400;q"
    

    Note that the -p parameter is not used in this example because the example assumes that the key file entry for this host already exists in the key file (DDNS.DAT in the directory specified by the ETC environment variable) and contains the complete name or IP address of the primary DDNS server.

    -a

    Specifies administrator mode. When this mode is on, records in the update are signed and authenticated using the zone key for the domain, as opposed to creating or using the private key of the specified host.

    -f

    Specifies that wildcard entries in the key file should be used. This parameter is typically used by the DHCP server.

    -g

    Specifies that a key file entry is to be generated in the key file (DDNS.DAT) for the host but the key is not to be registered with the DDNS server.

    -q

    Specifies quiet mode. When this mode is on, no prompting or informational messages are displayed.

    -v

    Specifies verbose mode, which is used for debugging purposes. When this mode is on, all the requests to and responses from the name server are displayed.

    -?

    Displays help for the NSUPDATE command.

    NSUPDATE Subcommands

    The following subcommands can be used in the NSUPDATE command shell.

    add Subcommand

    The add subcommand appends to an update request a name, along with its associated records, that is to be added to the domain, whether or not the name exists. If the name exists, then this operation functions the same as exists. If the name does not exist, then this operation functions the same as new.

    >>-add---------------------------------------------------------><
     
    

    delete Subcommand

    The delete subcommand appends to an update request the records that are to be deleted from the domain. This operation is successful only if the specified records exist.

    >>-delete------------------------------------------------------><
     
    

    exists Subcommand

    The exists subcommand appends to an update request the records associated with an existing name that are to be added to the domain. This operation is successful only if the name the records are associated with exists in the domain. This operation updates records that belong to an existing node in the name space.

    >>-exists------------------------------------------------------><
     
    

    new Subcommand

    The new subcommand appends to an update request a new name, along with its associated records, that is to be added to the domain. This operation is successful only if the name of the record does not already exist in the domain. This operation creates a new node in the name space and adds records to that node.

    >>-new---------------------------------------------------------><
     
    

    quit Subcommand

    The quit subcommand quits the program. (You can also press Ctrl+C to quit the program.)

    >>-quit--------------------------------------------------------><
     
    

    sign Subcommand

    The sign subcommand signs and sends the update request. You will be prompted for a dynamic data expiration time, which is the amount of time that the name server is to keep the dynamic data for the update, and the dynamic data extension time (also called the signature pad time), which is the amount of time that the name server is to keep the host or alias name after all other data for the name has expired.

    >>-sign--------------------------------------------------------><
     
    

    ttl Subcommand

    The ttl subcommand sets the default time-to-live (TTL) value to be used in records on the update request. The default value is 4660 seconds.

    >>-ttl---------------------------------------------------------><
     
    

    NSUPDATE Example (Adding a Host to a Presecured Dynamic Domain)

    This section shows an example console session using NSUPDATE in interactive mode (in the command shell). The example assumes that the administrator has already set up the zone key and that the private key for the zone is included in the local key file (DDNS.DAT in the directory specified by the ETC environment variable). The example shows the administrator's input (in bold) and the system responses when using NSUPDATE to add a host name to a presecured dynamic domain:

    [C:\]NSUPDATE -g -h kitty.raleigh.ibm.com -p darth1.raleigh.ibm.com
    --- NSUPDATE Utility ---
    ---
    Key Gen ...... succeeded ...
    [C:\]nsupdate -a -h kitty.raleigh.ibm.com -p darth1.raleigh.ibm.com
    --- NSUPDATE Utility ---
     
    Enter Action (Add,Delete,Exists,New,TTL,Send,Quit)
    > a
    ---
    InitDDNSUpdate ...... succeeded ...
    ..rrtype (A,PTR,CNAME,MX,KEY,HINFO,TXT): key
    DDNSUpdate_KEY (Add Flags 0000 Protocol 0 Algid 1
          Keylen 64 Key[0-15]: AQO1w0z8pLap13LN ...succeeded
     
    Enter Action (Add,Delete,Exists,New,TTL,Send,Quit)
    > s
    ..sig Expiration (secs from now, ENTER for 3600 (1 hour)):
    ..sig KEY pad (ENTER for default of 3110400 (36 days)):
    DDNSSignUpdate ...succeeded
    DDNSSendUpdate ...succeeded
     
    Enter Action (Add,Delete,Exists,New,TTL,Send,Quit)
    > q
     
    [C:\]
    

    NSUPDATE Error Codes

    This list describes the NSUPDATE error codes.

    0

    Explanation:

    Successful.

    -12

    Explanation:

    This error code indicates that no response was received from the specified DDNS server.

    -11

    Explanation:

    This error code indicates that the DDNS server rejected the DDNS client program's update request because the digital signature for the message failed authentication, that is, because the key in the DDNS.DAT file in the directory specified by the ETC environment variable is not valid.

    This happens when your private security key, used to generate the digital signature for the message, does not pair with the corresponding public key registered at the server for the specified host name. NSUPDATE obtains the security key information from DDNS.DAT. If the file is corrupted or deleted, your DDNS update requests will fail authentication.

    -10

    Explanation:

    This error code indicates that no key was found in the DDNS.DAT file in the directory specified by the ETC environment variable. If public security key information is already registered with the DDNS server for the specified host name or the -f parameter was specified on the NSUPDATE command, your DDNS.DAT file must contain the necessary key information. Either your DDNS.DAT file has been deleted or corrupted or the appropriate wildcard entry has not been correctly generated.

    -2

    Explanation:

    This error code indicates an error in the parameters specified. Make sure that the updatednsa or updatednstxt statement in the DHCPCD.CFG file has not been corrupted. If either has been corrupted, delete the entire statement from the client configuration file (DHCPCD.CFG) and re-run the DDNS client configuration program (DDNSCFG.EXE), which will automatically reinsert a valid updatednsa or updatednstxt statement.

    -1

    Explanation:

    This error code indicates an unexpected internal error.

    1

    Explanation:

    This error code indicates a format error. The DDNS name server was unable to interpret the request.

    2

    Explanation:

    This error code indicates a server error. The DDNS name server was unable to process this request because of a problem with the name server.

    3

    Explanation:

    This error code indicates a name error. The DDNS server did not recognize the fully-qualified host name specified in the request.

    4

    Explanation:

    This error code indicates that the DDNS server did not recognize the operation in the update request.

    5

    Explanation:

    This error code indicates that the DDNS server refused the requested operation for security or policy reasons, for example, when attempting to update a zone that is not dynamic.

    6

    Explanation:

    This error code indicates an alias error. The DDNS server refused the requested operation because the fully-qualified host name specified is an alias for another host name.

    7

    Explanation:

    This error code indicates a name error. The DDNS server refused the ADDNAMENEW request operation because the host name specified already exists.

    9

    Explanation:

    This error code indicates a zone error. The DDNS server refused the requested operation because the server is not authoritative for the domain name specified or because the records to be updated exist in more than one zone.

    10

    Explanation:

    This error code indicates a timestamp problem. The DDNS server refused the requested operation because the timestamp preceded that used in an earlier request.


    Notices

    First Edition (September 1997)

    The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions; therefore, this statement may not apply to you.

    This publication might include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.

    This publication was developed for products and services offered in the United States of America. IBM may not offer the products, services, or features discussed in this document in other countries, and the information is subject to change without notice. Consult your local IBM representative for information on the products, services, and features available in your area.

    Requests for technical information about IBM products should be made to your IBM reseller or IBM marketing representative.


    Copyright Notices

    © Copyright International Business Machines Corporation 1997. All rights reserved.

    Note to U.S. government Users -- Documentation related to restricted rights -- Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

    IBM is required to include the following statements in order to distribute portions of this document and the software described herein.

    __________________________________

    The TCP/IP client and server software included herein contains network security technology licensed from RSA Data Security, Inc. This technology is licensed solely for use with software using technology previously licensed from RSA Data Security, Inc.


    Disclaimers

    References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program or service is not intended to state or imply that only IBM's product, program, or service may be used. Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalent product, program, or service may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, programs, or services, except those expressly designated by IBM, are the user's responsibility.

    IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

       IBM Director of Licensing
       IBM Corporation
       500 Columbus Avenue
       Thornwood, NY 10594
       U.S.A.
    

    Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact IBM Corporation, Department LZKS, 11400 Burnet Road, Austin, TX 78758, U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.


    Acknowledgments

    TCP/IP for OS/2 incorporates compression code by the Info-ZIP group. There are no extra charges or costs due to the use of this code, and the original compression sources are freely available from Compuserve in the OS2USER forum and by anonymous ftp from the Internet site ftp.uu.net:/pub/archiving/zip.


    Trademarks

    The following terms are trademarks of the IBM Corporation in the United States or other countries or both:

    The following terms are trademarks of other companies:

    Java and HotJava are trademarks of Sun Microsystems, Incorporated.

    UNIX is a trademark of UNIX System Laboratories, Inc.

    Other company, product, and service names which may be denoted by a double asterisk (**), may be trademarks or service marks of others.