

The Microsoft DNS Server is currently beta software.


-----------------
1.0 Configuration
-----------------

You must have a set of configuration files in place in order for the
DNS service to start.  These files are:

  - A file named "boot" in the %SystemRoot%\system32\drivers\etc directory.

  - Database files specified by the boot file.

You can use files from a BIND installation at your site.  Or if you are
developing a new site, you can start from the included sample files,
which contain comments to help explain their format and how to edit them
for your site.

NOTE: the sample files MUST be edited for your site!


The included files are:
  boot
  cache
  arpa-127.rev
  arpa-192.rev
  place.dom

The purpose of these files is as follows:

boot    - This file controls the startup behavior of the DNS server.
          The syntax of Windows NT DNS boot files is compatible with
          BIND boot files.  Briefly, the syntax of this file is as
          follows:

          Commands must begin at the beginning of a line.  No spaces
          may precede commands.  Recognized commands are: "directory,
          cache, primary, and secondary."  The syntax of these commands
          is:

          "directory <pathname>"  - Causes the server to read database
          files from the directory given by <pathname> instead of from
          the %SystemRoot%\system32\drivers\etc directory.

          "cache     .    <filename>" - Specifies a file used to help
          the DNS service contact name servers for the root domain.
          This command and the file it refers to MUST be present.
          A cache file suitable for use on the Internet is provided.

          "primary    <domain> <filename>" - Specifies a domain for
          which this name server is authoritative and a database file
          which contains the name information for that domain.

          "seconday   <domain> <hostlist> [<filename>]" - Specifies
          a domain for which this name server is authoritative, and
          a list of host's IP addresses from which to attempt downloading
          the zone information, rather than reading it from a file.
          The optional filename instructs the DNS service to maintain
          a backup copy of the downloaded information, in the specified
          file.

cache   - This file contains host information that is needed to
          resolve names outside the authoritative domains.  It contains
          names and addresses of root name servers.
          For users on the Internet the provided file should suffice.
          For installations NOT connected to the internet the file
          should be edited to contains the name server authoritative
          for the root of your private network.

arpa-127.rev  - A database file for the 127.in-addr.arpa. domain.
                This domain is used for reverse-lookups of IP numbers
                in the 127 network, such as "localhost."  This file
                must be edited before use on production DNS servers.

arpa-192.rev  - A fictitious database file for reverse lookups in
                a fictitious "192" network.  This file must be edited
                and renamed before use on production DNS servers.

place.dom     - A fictitious database file for looking up host names
                in the "place.dom" domain.  This file must be edited
                and renamed before use on production DNS server.

To use these files, you must change the database information to match
your company's addressing and configuration.


1.1 Learning about DNS

I heartily recommend reading "DNS and BIND" by Paul Albitz and Cricket
Liu ( publisher: O'Reilly and Associates ).  This book is a great
introduction to the Domain Name System, and to configuring BIND database
files.


--------------------
2.0  WINS resolution
--------------------

The MS DNS server now contains fast, asynchronous resolution through WINS
lookup.

In some settings, particularly installations with DHCP enabled WindowsNT,
Windows95 or WFW3.11 clients, it will be advantageous to enable the DNS
service to lookup unresolved names through WINS.

First you must decide which DNS zones have WINS clients.  Then on the
DNS server for that zone, enable WINS resolution, pointing the DNS
server at the appropriate WINS server(s) that serves the hosts in that
zone.

For example, you might have DHCP configured WINS clients in the domain
"place.dom." Then with WINS lookup if a query for "testhost.place.dom."
that was NOT found in the place.dom database file, WINS servers would be
queried for "TESTHOST" resolving the host's address.

Using $WINS directive:

  For each domain in which you wish to attempt WINS resolution of
  hostnames, add the "$WINS" directive, specifying the address(es) of
  the WINS server(s) the DNS server should use to lookup unresolved names
  in that zone.

  Note that this directive must be on a line by itself, and start in column 1.  Note also,
  example:

  $WINS 10.2.3.2  10.2.4.2

WINS is not yet available for reverse lookup (in-addr.arpa) domains.


----------------
3.0 Installation
----------------

If you have previously installed the MS DNS service, and are simply
updating to a later release:

    1.  Stop the DNS service.  Type "net stop DNS" on the command line, or
        use the services manager in the control panel.

    2.  Go to your system32 directory.  Rename your dnssvc.dll to save as
        a backup.

    3.  Copy the new dnssvc.dll to your system32 directory.

    4.  "net start dns" will restart your DNS service.

    5.  "net stop dns" will stop the DNS service when it is necessary
         to make changes to the database files.


For a new installation of the Domain Name Server Service, follow these
instructions:

    1.  Read through this entire file.  Be sure that the boot file and
        the database files are in the proper directories.

    2.  You must install the TCP/IP protocol software on your machine.

    3.  Run the "install" batch file from the directory which contains
        the DNS service files.  This batch file will:

        - Copy the DNS service executable file to your system directory.

        - Configure the registry entries that control the DNS server.

    4.  Setup your database files from either a previous installation,
        or by editing the sample files contained in this distribution.
        (see above).

    5.  "net start dns" will restart your DNS service.

    6.  If the service fails to start check the event viewer for DNS
        errors.  Most configuration will cause an event that lists
        the specific cause of the problem.

    7.  If you wish to change the startup mode:
        - select "services" control panel applet
        - select "Domain Name Server Service"
        - choose "Manual" or "Automatic" startup.
        With automatic startup the DNS service will start after the
        machine boots.  With manual startup, you must start the service
        from this applet or type "net start dns".

    8.  Selecting "Stop" in the services applet or "net stop dns" will
        stop the DNS service when it is necessary to make changes to the
        database files.



-------------
4.0 Reminders
-------------

Doubled domain names is frequently caused by failing to place trailing
periods (".") at the end of fully qualified names.

If the error goes away when you ping the IP address (e.g., pinging
foobar's IP address gives the correct name), then the problem must
involve either a CNAME or A record (or both) for foobar with a
fully-qualified (totally spelled out) domain name on the right hand
side, that does not end in 'dot'.

Otherwise, the problem is two-fold:
        1) The reverse-lookup file for the in-addr.arpa domain has the wrong
domain name in the SOA record, in this case, "dc-tbc.microsoft.com."
instead of "xxx.in-addr.arpa."
        2) The PTR record for that IP number has an FQDN on the
right-hand-side (as it generally must) and does not end in 'dot'.

Generally, If you type the trailing dot on the command line and the
lookup fails, but it succeeds with a short name, your database files
have missing dots at the end of FQDNs.


-----------------
5.0 Release notes
-----------------

Warnings:

-- Recursive retry

  In this beta version, recursive requests are not retried correctly on
  timeout.  If the DNS server does not get a response from the desired
  name server closest to the client's question name, the query will simply
  timeout.  To insure correct operation of the DNS server, it is essential
  that name servers are correct and are reachable at the their given
  address.

  Carefully check:

  -- Cache file for correct NS and ONLY reachable addresses in A records.
  If NOT on the internet, have at least one DNS server be authoritative
  for the root domain and list it in the cache file.

  -- Zone file for correct NS sub-zone delegations.  Insure that ONLY
  reachable addresses are given in "glue" A records for the sub-zone
  name servers.

  -- Forwarders directive for a reachable address for the FIRST forwarder.
  ONLY the first forwarders server will be queried, so it MUST be up and
  running for the DNS to handle recursive queries.

  Recursion will be corrected to retry properly in the near future.


- Zone file write back

  After a zone transfer, the orginal zone database file will NOT be
  rewritten.  This does not cause response from the DNS while it is
  running, but it does mean that when the DNS service is shutdown and
  restarted, another zone transfer must take place.  This will be fixed
  very soon.


- TCP recursion

  Recursive lookups to other name servers are NOT yet supported for TCP
  queries.  This is coming later this fall.  If you are using nslookup
  to query the server, set the query mode to use UDP.


- Address sorting

  No attempt is made to sort addresses of multi-homed hosts (hosts with
  multiple addresses).  The DNS server round robins the address list of
  all multi-homed hosts.  This is the simplest solution for handling load
  balancing to a multi-homed server.  If this solution is insufficient for
  or causes problems at your site, please send a bug report explaining the
  issue.  Optionally providing alternatives to round robinning is under
  consideration.


- WINS reverse lookup

  WINS resolution is not available for reverse lookup domains
  (in-addr.arpa. domains).   This is coming soon.


- WINS name errors.

  To avoid giving bogus "name error" responses for names which have
  not yet replicated across WINS servers, WINS lookup does not pass
  back name does not exist errors, until all WINS servers have responded.
  This means, that if you specify MULTIPLE WINS servers, AND one of the
  WINS servers is down, then queries for non-existent names will not be
  answered.

  Note again, this applies ONLY to non-existent names, when a specified WINS
  server is down.  Post-beta, I will add some detection of non-responsive
  WINS servers, which will solve this problem.


- SNMP + Perfmon

  The DNS does not currently export its counters through SNMP or Perfmon.
  This support will be added after the beta.


Not supported:

- sortlist directive
- $INCLUDE directive

Supported resource records:

- A, PTR, NS, SOA, CNAME, MX, MB, MR, MG, HINFO, TXT, MINFO, RT, RP,
    X25, ISDN, WKS, AFSDB are fully supported.

- The MD and MF resource types are not supported in database files.
  These record types are obsolete, and references to them should be
  change to the MX type.  Occurences of these types in database files
  are logged to the EventLog.


Incompatibilities:

-   Some versions of nslookup require server support of the IQUERY
    opcode, which is a deprecated method of looking up an IP number.

    An example session with such an nslookup follows:

      machine# nslookup
      *** Can't find server name for address 1.2.3.4: Not implemented
      *** Can't find initialize address for server : Timed out
      Default Server:  localhost
      Bus error (core dumped)
      machine#

  * The solution to this problem is to upgrade to a newer version of
    nslookup, which is publicly available on the internet.

  * A work-around to this problem is to point nslookup to a BIND
    name server at startup and then issue the "lserver" command
    to change servers.  Most nslookup versions support the syntax:
    "nslookup - initial_server".  Be sure to specify the initial
    server as an IP number.

General Disclaimer:

- This DNS server has been developed on NT 3.5 and NT 3.51.  It has not
  been used or tested on NT 3.1.

- This DNS server is Beta software provided for testing purposes.


----------------------------
6.0 Contacts for Bug Reports
----------------------------

If you would like to report a bug or a suggestion, or if you have
a quesition, please email:

  dnsbug@microsoft.com.

When reporting bugs please:

1)  INCLUDE the VERSION NUMBER which appears in the first DNS event
    (event id 1).
2)  Include any other DNS events which may indicate the problem or
    clarify the circumstances when the problem occured.


To check on the status of the latest version and availability of updates,
please e-mail:

  dnsbeta@microsoft.com.

Thanks for participating in this Beta program!

