13.3 Managing the DNS Server Configuration | DNS on Windows Server 2003

The DNS server is one of the few Microsoft services that you can configure completely from a command line. The dnscmd utility has been around since Windows NT. Microsoft has added new options with every major operating system release. With it, you can modify server settings and create, query, and manipulate zones and resource records. In the Windows Server 2003 version, there are even dnscmd commands for managing Active Directory application partitions.

Using dnscmd is straightforward. Here is the generic syntax:

dnscmd ServerName Command AdditionalOptions

The ServerName parameter is used to target a remote name server. It is optional and, if not included, runs the command against the local server (which must be a name server). You can also use a single dot (.) to target the local server.

The Command parameter is required and corresponds to an action you can perform against the server. The Windows Server 2003 version of dnscmd supports 37 different commands. Running dnscmd from a command line without passing any parameters displays the complete list of supported commands.

The AdditionalOptions parameter is optional for some commands, required for some, and not used for others. To see what additional parameters are needed for a command, run dnscmd Command /? from the command line.

The final point worth mentioning about dnscmd is that it does not communicate with a name server via dynamic updates, zone transfers, or any other standard DNS communication protocol. Instead, it uses RPC to talk directly to the DNS Server service on the target name server. This is why, if the DNS Server service is not running on a name server, you can't run dnscmd against it; start it with sc first.

We will now take a tour through the dnscmd command options (all 37 of them). Normally, we wouldn't go into so much detail about a utility's options but, unfortunately, much of the Microsoft documentation on dnscmd is inconsistent. We've tested each command and attempted to provide definitive information about its usage and syntax. A positive side effect of reading through each command is that you will become well-versed in the capabilities and limitations of the Microsoft DNS Server.

13.3.1 dnscmd Server Commands

You can view the settings for a name server by using the /Info command. Likewise, you can use the /Config command to change any of these settings. (Table 14-1 provides a complete list of supported settings.) Commands are also available to configure the addresses the server listens on (/ResetListenAddresses), configure forwarding (/ResetForwarders), initiate scavenging (/StartScavenging), clear the server cache (/ClearCache), and view DNS utilization statistics (/Statistics).

/Info [<PropertyName>]

This command displays the DNS server settings. These settings are stored under the following registry key:

HKLM\SYSTEM\CurrentControlSet\Services\DNS\Parameters

If you run this command without other options, all settings and their values are displayed. Alternatively, you can display a single setting by specifying the name of the setting after the command.

This example displays the ForwardingTimeout setting on matrix:

C:\> dnscmd matrix /info ForwardingTimeout

/Config /<PropertyName> <PropertyValue>

This command sets a server setting. The first parameter should be the name of the property you want to set, followed by the value.

This example shows how to change the /ForwardingTimeout setting to 3 (seconds) on matrix:

C:\> dnscmd matrix /config /ForwardingTimeout 3

/ResetListenAddresses [<ServerIPAddresses>]

By default, the Microsoft name server listens for client requests on all networks to which it is directly connected. With this command, you can limit the networks that the server listens on by specifying a whitespace-separated list of one or more IP addresses. These IP addresses must be valid addresses configured on network adapters on the server or the command fails. To reset to the default, run this command without any IP addresses.

This example sets the listen addresses on matrix to 10.13.19.84 and 10.7.19.76:

C:\> dnscmd matrix /resetlistenaddresses 10.13.19.84 10.7.19.76

/ResetForwarders [<ForwarderIPAddresses>]

Use this command to enable forwarding on a name server. Specify a whitespace-separated list of the IP addresses of the name servers to which it should forward requests. If you run this command without any IP addresses, it disables forwarding.

This example enables forwarding on matrix and forwards unresolved queries to 10.13.19.84 and 10.7.19.76:

C:\> dnscmd matrix /resetforwarders 10.13.19.84 10.7.19.76

/StartScavenging

This command starts the scavenging process on all zones configured for scavenging on the name server. Even though it may return a success message, successful scavenging depends on the following:

Scavenging must have previously been enabled on the server. This command enables scavenging and sets it to run every 168 hours (7 days):
```
C:\> dnscmd matrix /config /scavenginginterval 168
```
Scavenging must have previously been enabled on one or more zones. This command enables scavenging on the fx.movie.edu zone:
```
C:\> dnscmd matrix /config fx.movie.edu /aging
```
Resource records must have previously had aging enabled. By default, resource records that are added via dynamic update have aging enabled. You can also configure a record to be aged when you create it using the /aging option with the /recordadd command. To enable aging on all resource records in a zone, see the /ageallrecords command.
This example initiates scavenging on matrix:
```
C:\> dnscmd matrix /startscavenging
```

This command causes scavenging to start, but it does not wait for scavenging to complete so it will pretty much always return success. To see the results of the scavenging, you'll want to view the DNS event log once scavenging has had enough time to run.

/ClearCache

The Microsoft DNS Server keeps a cache in memory of records that it has resolved locally or through recursive queries. These records are cached for the duration of the time to live (TTL) setting on each record. If a record was recently changed and you want to update the cache so the server returns the latest version, you can flush the cache using this command.

This example clears the server cache on matrix:

C:\> dnscmd matrix /clearcache

/Statistics [<StatNumber>]

The Microsoft DNS Server keeps track of performance statistics related to the number of requests, queries, updates, zone transfers, packets, and Active Directory reads and writes it processes. This is useful information for monitoring the utilization of your name server. Running this command without any parameters prints all statistics.

You can also view a subset of statistics. Several statistics categories group similar metrics together, such as query-related metrics. You can view a subset of metrics by summing the hexadecimal numbers associated with the categories you want to see. Here is a list of each category and its number.

Start number	Category
000001	Time
000002	Query
000004	Query2
000008	Recurse
000010	Master
000020	Secondary
000040	Wins
000100	Wire Update
000200	Security
000400	Ds
000800	Internal Update
010000	Memory
040000	Dbase
080000	Records
100000	PacketMem

This example displays the query-related statistics (2 + 4) for matrix:

C:\> dnscmd matrix /statistics 6

Keep in mind that these are numbers are in hex, so 4 + 8 would equal C, not 12.

13.3.2 dnscmd Zone Commands

Over half of the dnscmd command options relate to configuring or querying zones.

/AgeAllRecords <ZoneName> [<NodeName>] [/Tree] [/f]

In order for resource records to be scavenged after a period of time, a timestamp must be associated with the record. The /AgeAllRecords command allows you to set the current time as the timestamp for all records in a zone, or for a specific node in a zone. The node name can be any node in the zone, @ to represent all records, or the name of a subdomain. If you specify a subdomain for the node, use the /tree option to set a timestamp on all records in the subdomain.

By default, you are prompted for confirmation before records are aged. To disable this prompt, use the /f option.

This example shows how to age all resource records in the cgi subdomain of the fx.movie.edu zone:

C:\> dnscmd /ageallrecords fx.movie.edu cgi /tree

/Config <ZoneName> /<PropertyName> [<PropertyValue>]

This command configures settings for both name servers and zones. To configure zone settings, specify the zone name followed by the property name and value (if necessary).

This example turns on aging for the fx.movie.edu zone:

C:\> dnscmd /config fx.movie.edu /aging

/EnumZones [<Filters>]

This command lists the zones stored on a server. Several filter options are available if you want to view a subset of zones. These include: /Primary, /Secondary, /Forwarder, /Stub, /Cache, /Auto-Created, /Forward, /Reverse, /Ds, /File, /DomainDirectoryPartition, /ForestDirectoryPartition, /CustomDirectoryPartition, /LegacyDirectoryPartition, and /DirectoryPartition.

This example enumerates all AD-integrated zones stored on the local server:

C:\> dnscmd /enumzones /ds

/WriteBackFiles [<ZoneName>]

This command allows you to write to persistent storage any updates to the zone that are stored only in memory. If you do not specify a zone name, changes to any zone stored on the server are written to persistent storage.

This example writes to disk any changes to the fx.movie.edu zone that are stored in memory:

C:\> dnscmd /writebackfiles fx.movie.edu

/ZoneAdd <ZoneName> <ZoneType> [<ZoneOptions>]

This command adds a zone to a server. The first parameter is the name of the zone, and the second is the zone type. Based on the zone type, there may be additional zone options that you can also specify. Here is the list of zone types and associated zone options:

/DsPrimary [/dp <AppPartitionName> | /domain | /forest | /legacy]
/Primary /file <FileName>
/Secondary <MasterIPAddresses> [/file <FileName>]
/Stub <MasterIPAddresses> [/file <FileName>]
/DsStub <MasterIPAddresses> [/dp <AppPartitionName> | /domain | /forest | /legacy]
/Forwarder <MasterIPAddresses> [/Timeout <Time>] [/Slave]
/DsForwarder <MasterIPAddresses> [/Timeout <Time>] [/Slave] [/dp <AppPartitionName> | /domain | /forest | /legacy]

This example creates an AD-integrated zone named fx.movie.edu and stores it in the forest DNS application partition:

C:\> dnscmd /zoneadd fx.movie.edu /dsprimary /forest

/ZoneDelete <ZoneName> [/DsDel] [/f]

This command deletes a zone from a server. When deleting an AD-integrated zone, you must specify the /DsDel option or an error will be returned.

Before deleting the zone, you are prompted to confirm the deletion. The /f option skips the confirmation step.

This example deletes the AD-integrated fx.movie.edu zone from the local server and from Active Directory:

C:\> dnscmd /zonedelete fx.movie.edu /DsDel

/ZoneExport <ZoneName> <ZoneFileName>

This command exports the contents of a zone into a standard zone file. This is useful when troubleshooting AD-integrated zones, which do not generate zone files.

The first parameter is the zone name, followed by the filename to which to export the zone. This file is created in %systemroot%\System32\dns on the target server.

This example shows how to export the contents of the fx.movie.edu zone to a file named fx-export.dns:

C:\> dnscmd /zoneexport fx.movie.edu fx-export.dns

/ZoneInfo <ZoneName> [<PropertyName>]

This command displays the settings for a zone. These settings are stored under the following registry key:

HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\DNS Server\Zones\ZoneName

By default, all settings for a zone are displayed, but you can optionally specify a property name to display the value for only that setting.

This example displays all settings for the fx.movie.edu zone:

C:\> dnscmd /zoneinfo fx.movie.edu

/ZonePause <ZoneName>

With this command, you can stop the name server from responding to queries for a zone and from processing updates. Use the /ZoneResume command to restart the zone.

This example shows how to pause the fx.movie.edu zone:

C:\> dnscmd /zonepause fx.movie.edu

/ZonePrint <ZoneName>

This command prints the resource records for the specified zone. This is similar to the /ZoneExport command, except that the contents of the zone are printed to the screen instead of to a file. You can obviously redirect the contents to a file if desired.

This example prints the resource records in the fx.movie.edu zone:

C:\> dnscmd /zoneprint fx.movie.edu

/ZoneRefresh <ZoneName>

This command is run against a secondary name server to force a zone transfer of a particular zone. The zone transfer occurs only if the serial number in the zone's SOA record on the master server is higher than the serial number on the secondary server the command is run against.

This example causes the local server to perform a zone transfer of the fx.movie.edu zone if the master server has a higher SOA serial number:

C:\> dnscmd /zonerefresh fx.movie.edu

/ZoneReload <ZoneName>

This command causes the specified zone to be reloaded from its zone file or from Active Directory for AD-integrated zones.

This example shows how to reload the fx.movie.edu zone:

C:\> dnscmd /zonereload fx.movie.edu

/ZoneResetMasters <ZoneName> [/local] [<MasterIPAddresses>]

This command sets the list of master IP addresses that the server uses to perform zone transfers for the specified zone. To remove the current master IP addresses, run this command without any parameters.

If you specify /local against an AD-integrated stub zone, the new master list is "local" to the target server only. All other servers will use the master list stored in AD.

This example configures 10.7.52.25 as the master server for the fx.movie.edu zone:

C:\> dnscmd /zoneresetmasters fx.movie.edu 10.7.52.25

/ZoneResetScavengeServers <ZoneName> [<ServerIPAddresses>]

For AD-integrated zones that have scavenging enabled, you can limit the servers that perform scavenging with this command. By default, all servers that have scavenging enabled remove out-of-date records in zones that also have scavenging enabled. If you omit the list of servers, it reverts to the default, which is all servers performing a periodic scavenge.

This example shows how to restrict scavenging of the fx.movie.edu zone to the name servers 10.7.19.76 and 10.7.25.63:

C:\> dnscmd /zoneresetscavengeservers fx.movie.edu 10.7.19.76 10.7.25.63

/ZoneResetSecondaries <ZoneName> [<ZoneTransferOptions>] [<NotifyOptions>]

This command configures which secondary servers can perform zone transfers and receive NOTIFY messages for the specified zone. ZoneTransferOptions is optional and, if included, can be one of the following:

/NoXfr

Zone transfers are not allowed to any server.

/NonSecure

Zone transfers are allowed to any server.

/SecureNs

Only servers listed in the NS records for the zone can perform zone transfers.

/SecureList <IPAddresses>

Only servers specified by IPAddresses can perform zone transfers.

NotifyOptions is also optional and can be one of the following:

/NoNotify

Change notifications are not sent to any servers.

/Notify

Change notifications are sent to all servers listed in the NS records for the zone.

/NotifyList <IPAddresses>

Change notifications are only sent to the servers specified by IPAddresses.

This example enables NOTIFY and allows only servers that have NS records in the zone to perform zone transfers for the fx.movie.edu zone:

C:\> dnscmd /zoneresetsecondaries fx.movie.edu /securens /notify

/ZoneResetType <ZoneName> <ZoneType> [<ZoneOptions>] [/OverWrite_Mem | /OverWrite_Ds]

This command changes the type of a zone. For example, you can change a secondary zone to become a primary zone. See the ZoneType options for the /ZoneAdd command because they are nearly identical for this command. The only difference is that for AD-integrated zones, you need to use /DirectoryPartition instead of /dp to specify the application partition to store the zone in.

The /OverWrite_Mem and /OverWrite_Ds options can be used when converting non-AD-integrated zones to AD-integrated zones. /OverWrite_Mem causes the contents of the zone in AD to overwrite what is stored locally. /OverWrite_Ds causes the contents of the locally stored zone to overwrite what is in AD.

This example shows how to change the primary zone fx.movie.edu to be AD-integrated, and store it in the forest DNS application partition:

C:\> dnscmd /zoneresettype fx.movie.edu /dsprimary forestdnszones.movie.edu

/ZoneResume <ZoneName>

This command can be used to start a zone that has been stopped with the /ZonePause command. When a zone is paused or stopped, the name server does not answer queries or process updates for the zone.

This example resumes the fx.movie.edu zone:

C:\> dnscmd /zoneresume fx.movie.edu

/ZoneUpdateFromDs <ZoneName>

Name servers that support AD-integrated zones periodically poll Active Directory for changes to those zones. By default, this happens every five minutes. You can use the /ZoneUpdateFromDs command to force the name server to check Active Directory for changes. You can also change the polling frequency by running this command where <Minutes> is how often to poll Active Directory:

C:\> dnscmd /config /dspollinginterval Minutes

This example shows you how to force the local name server to check Active Directory for changes to the fx.movie.edu zone:

C:\> dnscmd /zoneupdatefromds fx.movie.edu

/ZoneWriteBack <ZoneName>

When a Microsoft DNS Server receives updates for a file-based zone, it does not immediately commit those changes to disk. Instead, it stores them in memory and periodically writes the changes to its permanent storage. The /ZoneWriteBack command allows you to manually initiate the write-back action for a zone.

For AD-integrated zones, all changes are written immediately to Active Directory as they are processed.

This example shows how to write to disk any changes stored in memory for the fx.movie.edu zone:

C:\> dnscmd /zonewriteback fx.movie.edu

13.3.3 dnscmd Application Partition Commands

In Windows Server 2003, AD-integrated zones can be stored in application partitions, which we described in Chapter 8. Not only can you use dnscmd to store a particular zone in an application partition, but you can query, create, delete, and control which domain controllers replicate an application partition. In short, dnscmd is not only your primary command-line interface for managing DNS, but for managing DNS application partitions as well.

/CreateBuiltinDirectoryPartitions /domain | /forest | /alldomains

If you install a new Windows Server 2003 Active Directory forest, the default DNS application partitions are installed automatically. If you delete these application partitions and need to recreate them, you can use this command. The type of built-in application partition to create is a required parameter. /domain creates a domainwide application partition (e.g., domaindnszones.movie.edu) for the domain of the server this command is run against. /forest creates a forestwide DNS application partition (e.g., forestdnszones.movie.edu). /alldomains creates a domainwide application partition for all domains in the forest. (This does not include the forestwide application partition.)

This example shows how to create the built-in domainwide DNS application partitions in the forest that the target server is in:

C:\> dnscmd  /CreateBuiltinDirectoryPartitions /alldomains

/CreateDirectoryPartition <AppPartitionName>

This command creates an application partition, which can be used either for replicating AD-integrated zone data or for other application data.

This example shows how to create an application partition named apps.fx.movie.edu:

C:\> dnscmd /CreateDirectoryPartition apps.fx.movie.edu

/DeleteDirectoryPartition <AppPartitionName>

This command deletes an application partition. Deleting an application partition deletes all objects that are stored in it.

This example shows how to delete an application partition named apps.fx.movie.edu:

C:\> dnscmd /DeleteDirectoryPartition apps.fx.movie.edu

/DirectoryPartitionInfo <AppPartitionName> [/detail]

Use this command to display information about an application partition. The information includes the distinguished name in Active Directory, the corresponding crossRef object in the Partitions container, a list of replica servers, and the number of zones stored (if AD-integrated zones are stored in it). By default, very long domain names are truncated in the output. You can use the optional /detail switch to make sure long names are not truncated.

This example displays the properties of the forestdnszones.movie.edu application partition:

C:\> dnscmd /DirectoryPartitionInfo forestdnszones.movie.edu

/EnlistDirectoryPartition <AppPartitionName>

With this command, you make the target name server a replica server for the specified application partition. This causes the server to replicate the contents of the application partition. Note that you cannot use this command to "enlist" servers that are not running the DNS Server service.

This example causes matrix to become a replica server for the apps.movie.edu application partition:

C:\> dnscmd matrix /EnlistDirectoryPartition apps.movie.edu

/EnumDirectoryPartitions [/custom]

This command prints a list of the application partitions in the forest that the target server is a member of. The output includes whether the server is enlisted with each application partition or not. /custom is optional and can be used to display only the non-default application partitions. (These are the ones created by /CreateBuiltinDirectoryPartitions.)

This example displays all of the custom application partitions in a forest:

C:\> dnscmd /EnumDirectoryPartitions /custom

/UnenlistDirectoryPartition <AppPartitionName>

Whereas the /EnlistDirectoryPartition adds a server to an application partition, this command removes (or "unenlists") a server from an application partition.

This example removes matrix from the apps.fx.movie.edu application partition:

C:\> dnscmd matrix /UnenlistDirectoryPartition apps.fx.movie.edu

/ZoneChangeDirectoryPartition <ZoneName> [<AppPartitionName> | /domain | /forest | /legacy]

Use this command to move an AD-integrated zone between application partitions and the System container. The first two parameters must be the name of the zone to move followed by the application partition to move it to. This can take the form of a FQDN of an application partition, /domain to move it to the default domain application partition for name servers, /forest for the default forest application partition for name servers, or /legacy to move it to the System container of a domain.

This example moves the fx.movie.edu zone to the default domain application partition for name servers:

C:\> dnscmd /ZoneChangeDirectoryPartition fx.movie.edu /domain

13.3.4 dnscmd Resource Record Commands

The dnscmd utility can query, create, and delete resource records using the /EnumRecords, /RecordAdd, /RecordDelete, and /NodeDelete commands. Each of these commands requires the same two parameters following the command option. The first is the name of the zone (ZoneName) you want to perform the task against. The second is the name of the node (NodeName) that corresponds to the owner of the target resource record (or records).

/EnumRecords <ZoneName> <NodeName> [/Type <RRType> <RRData>] [/Authority] [/Glue] [/Additional] [/Node | /Child | /StartChild <Child>] [/Continue | /Detail]

This command has several options that provide flexibility with enumerating resource records in a zone.^[1] The only required parameters are ZoneName and NodeName. If you want to match all resource records, you can replace NodeName with @ instead of a specific node name. Here are the other optional parameters used to control the types of records enumerated and the information that is displayed for each.

^[1] Besides providing different options for querying records, /EnumRecords is different from the nslookup command because it uses RPC to communicate with the Microsoft DNS Server instead of the standard DNS protocol. This also means that the /EnumRecords command does not work with non-Microsoft DNS Servers.

/Type <RRType>: Restrict the records that are returned to a specific resource record type (RRType).
/Authority: Display only authoritative data.
/Glue: Display any glue information for each record.
/Additional: Display any additional information for each record.
/Node: Display only the records for the specified node.
/Child: Display only the child records of the specified node.
/StartChild <ChildNodeName>: Display only the records starting at a particular child node (i.e., subdomain)
/Continue: Display all matching records regardless of the number. By default, after the buffer has been filled, it stops displaying records.
/Detail: Display detailed debugging information for each record.

This example displays all records associated with the node matrix in the fx.movie.edu zone:

C:\> dnscmd /enumrecords fx.movie.edu matrix

This example displays all A records in the fx.movie.edu zone:

C:\> dnscmd /enumrecords fx.movie.edu @ /Type A

/NodeDelete <ZoneName> <NodeName> [/tree] [/f]

This command deletes all resource records associated with a node. You can delete a subdomain of records by specifying the name of the subdomain for <NodeName> along with the /tree option.

By default, you are prompted to confirm the deletion. To disable the confirmation request, use the /f switch.

This example deletes the cgi.fx.movie.edu subdomain and all the resource records contained within it:

C:\> dnscmd /nodedelete cgi.fx.movie.edu /tree

/RecordAdd <ZoneName> <NodeName> [/Aging] [/OpenAcl] [<TTL>] <RRType> <RRData>

This command allows you to create any of the resource records supported by the Microsoft DNS Server. The first two required parameters are the zone name and node name. You can then specify any of these optional parameters:

/Aging

Enables aging for the record. If scavenging has been turned on for the server and zone, the record is deleted after the refresh and no-refresh intervals unless the record is updated.

/OpenAcl

For AD-integrated zones, the ACL on this record is configured so that anyone can modify it initially. After a client updates the record, only that client (by default) has permission to modify the record. An administrator who is pre-populating records for clients might use this option. The first time each client touches the record the record becomes locked down to only that client for future updates.

<TTL>

Time-to-live value for the record.

The next two parameters are required. They are the record type (RRType) and record data (RRData) fields.

This example adds an A record for matrix in the fx.movie.edu zone:

C:\> dnscmd /recordadd fx.movie.edu matrix A 10.7.19.76

/RecordDelete <ZoneName> <NodeName> <RRType> <RRData> [/f]

While /NodeDelete allows you to delete all of the resource records associated with a specific node, you can delete individual records with /RecordDelete. After the ZoneName and NodeName parameters, you must specify the RRType and RRData.

This command prompts for confirmation before proceeding with the deletion. You can disable the confirmation prompt using the /f option.

This example deletes the A record for matrix in the fx.movie.edu zone:

C:\> dnscmd /recorddelete fx.movie.edu matrix A 10.7.19.76