ANS 2.8.3 Manual 20081107 PDF

Nominum
ANS
Authoritative
Administrator’s
Name
Manual
Server
Product Version 2.8.3

Date November 7, 2008
Copyright ©2002-2008 Nominum, Inc. - All Rights Reserved
This software and documentation is subject to and made available pursuant to the terms of the Nominum
License Agreement, and may be used or copied only in accordance with the terms of that Agreement.
This manual, in whole or in part, may not be reproduced, translated or reduced to any machine-readable
form without prior written approval from Nominum, Incorporated.
Nominum, Incorporated
2000 Seaport Boulevard
Suite 400
Redwood City, CA, 94063
USA
http://www.nominum.com
Navitas and Vantio are trademarks of Nominum, Incorporated.
All other trademarks are the property of their respective companies.

Table of Contents
List of Tables ..............................................................................vii
List of Figures..............................................................................ix
1 Introduction to Nominum ANS..............................................1
Communicating with ANS ................................................................................1
About This Manual ..........................................................................................2
2 Getting Started With ANS.....................................................5

Starting the ANS Server ...................................................................................5
Loading a DNS Master File ..............................................................................6
Additional Technical Background....................................................................8
3 Zones and Templates ..........................................................13

Zones .............................................................................................................13
Templates.......................................................................................................19
4 Database Drivers ................................................................27

Database Drivers............................................................................................27
5 Server, View and Zone Options...........................................35

Option Formats ..............................................................................................35
Nominum ANS i
ii Table of Contents
Server Options ...............................................................................................36

View Options..................................................................................................40
Zone Options..................................................................................................46
6 Using the Command Channel with ANS..............................67

nom_tell.........................................................................................................68
.......................................................................................................................73
ANS-Specific Command Channel Commands ................................................73
add-view ........................................................................................................75
add-zone ........................................................................................................75
block-checkpoints..........................................................................................76
checkpoint .....................................................................................................76
delete-view.....................................................................................................76
delete-zone.....................................................................................................77
flush...............................................................................................................77
force-maintenance..........................................................................................78
force-notify.....................................................................................................78
force-transfer..................................................................................................78
list-events ......................................................................................................78
pid..................................................................................................................79
process-information........................................................................................79
purge-zone .....................................................................................................79
reopen-log-files ..............................................................................................80
restart.............................................................................................................80
request-events................................................................................................80
show-events....................................................................................................80
show-data.......................................................................................................81
show-maintenance..........................................................................................82
show-server ....................................................................................................84
Nominum ANS
Table of Contents iii
show-view ......................................................................................................85
show-zone ......................................................................................................87
list-drivers......................................................................................................89
statistics.........................................................................................................90
stop ................................................................................................................94
uuid................................................................................................................94
unblock-checkpoints......................................................................................94
update-data ....................................................................................................94
update-server .................................................................................................96
update-view....................................................................................................96
update-zone....................................................................................................99
version .........................................................................................................100
7 The ANS Utilities .............................................................101

A Note On Service Definitions in channel.conf............................................102
Syntax ..........................................................................................................102
Common Configuration Elements.................................................................104
ans_load.......................................................................................................104
ans_import ...................................................................................................110
ans_dump ....................................................................................................113
ans_listzones................................................................................................115
ans_listviews................................................................................................116
ans_delete....................................................................................................116
ans_loadzoneconf.........................................................................................117
ans_dumpzoneconf.......................................................................................118
ans_copy ......................................................................................................118
ans_diff ........................................................................................................120
ans_edit .......................................................................................................122
ans_versions ................................................................................................123
Nominum ANS
iv Table of Contents
Executing ans_* Commands From A Remote Machine................................124
8 Examples of Zone Operations ...........................................127

Adding Zones...............................................................................................127
Deleting a Zone............................................................................................129
Purging Zones ..............................................................................................130
Updating Zones............................................................................................130
Updating Zone Policies ................................................................................135
9 SNMP in ANS ...................................................................139

SNMP Concepts and Architecture................................................................139
General Notes on SNMP for Nominum Products ..........................................140
nom_snmpagent ...........................................................................................141
Configuration Files.......................................................................................142
Nominum-specific MIBs ..............................................................................143
Using SNMP with ANS.................................................................................144
The nom_snmpagent Configuration File.......................................................146
Using the Command Channel with nom_snmpagent.....................................150
Using Net-SNMP Command-line Tools with nom_snmpagent ......................152
10 Secret Key Transaction Authentication (TSIG) .................157

DNS TSIG ....................................................................................................157
GSS-TSIG ....................................................................................................161
11 Supporting Programs.........................................................165
ans_signer....................................................................................................165
nom_keytool.................................................................................................167
nom_maketsigsecret.....................................................................................168
nom_nanny ..................................................................................................168
Nominum ANS
Table of Contents v
A Statistics ...........................................................................175
B ANS Events ......................................................................179
C Logging Switches ..............................................................185
D Examples of Server and View Operations .........................189
Server Operations.........................................................................................189
Running Nominum ANS in a chroot() Jail ....................................................196
View Operations...........................................................................................200
E ANS Files .........................................................................205

Introduction .................................................................................................205
The ANS Working Directory.........................................................................205
ANS Files Quick Reference .........................................................................206
The Server Configuration File ......................................................................208
View Files ....................................................................................................208
VDB Database Files.....................................................................................210
ANS and the Nominum Command Channel .................................................211
Index.........................................................................................213
Nominum ANS
vi Table of Contents
Nominum ANS
List of Tables
Table 1-1 Typographical Conventions.......................................................................................3
Table 2-1 ans Command-line Options.......................................................................................9
Table 3-1 Derived Zone Elements...........................................................................................18
Table 4-1 VDB Driver Arguments...........................................................................................28
Table 4-2 cc Driver Arguments...............................................................................................29
Table 4-3 file Driver Arguments .............................................................................................30
Table 5-1 Option Formats .......................................................................................................35
Table 5-2 ANS Server Options................................................................................................36
Table 5-3 ANS View Options..................................................................................................41
Table 5-4 Zone options ...........................................................................................................47
Table 6-1 nom_tell command-line options ..............................................................................70
Table 6-2 ANS Command Channel messages..........................................................................73
Table 6-3 Zone Maintenance Status ........................................................................................82
Table 6-4 Zone Maintenance Tasks ........................................................................................83
Table 6-5 Zone Maintenance Tasks Reflected Via The Command Channel............................83
Table 7-1 Database revision flags .........................................................................................103
Table 7-2 Common Configuration Elements..........................................................................104
Table 7-3 ans_load Options ..................................................................................................105
Table 7-4 ans_import Options...............................................................................................111
Table 7-5 ans_dump Options ................................................................................................114
Table 7-6 ans_dump --revision Formats ...............................................................................115
Table 7-7 ans_listzones Options ...........................................................................................115
Table 7-8 ans_listviews Options ...........................................................................................116
Table 7-9 ans_delete Options ...............................................................................................117
Table 7-10 ans_loadzoneconf Options ....................................................................................117
Table 7-11 ans_dumpzoneconf Options ..................................................................................118
Table 7-12 ans_copy Options..................................................................................................119
Table 7-13 ans_diff Options....................................................................................................120
Table 7-14 ans_edit Options ...................................................................................................122
Table 7-15 ans_versions Options ............................................................................................123
Table 8-1 $DELETE Directives ............................................................................................134
Nominum ANS vii

viii List of Tables
Table 8-2 update-policy Zone Option Examples ...................................................................136

Table 9-1 nom_snmpagent options........................................................................................141
Table 11-1 ans_signer Options ...............................................................................................166
Table 11-2 nom_keytool Subcommands..................................................................................167
Table 11-3 nom_nanny Command-Line Options.....................................................................169
Table 11-4 nom_nanny Command Channel Commands ..........................................................170
Table 11-5 nom_nanny Configuration File Options ................................................................172
Table A-1 Statistics types ......................................................................................................175
Table B-1 ANS Events ..........................................................................................................181
Table B-2 Non-View-Specific Events ....................................................................................184
Table C-1 Logging switches...................................................................................................185
Table C-2 Global Logging Switches.......................................................................................188
Table D-1 Listen-on Configuration Statement Examples .......................................................193
Table E-1 ANS Files Quick Reference..................................................................................206
Table E-2 VDB Database Files .............................................................................................210
Nominum ANS
List of Figures
Figure 2-1 Example DNS Master file..........................................................................................7
Figure 6-1 Example channel.conf entries .................................................................................68
Figure 6-2 add-view Example ..................................................................................................75
Figure 6-3 Deleting a view from the server with nom_tell ........................................................77
Figure 6-4 Flushing the cache..................................................................................................77
Figure 6-6 show-maintenance Command with Status Tag.........................................................84
Figure 6-5 Displaying a Zone’s Maintenance State With show-maintenance............................84
Figure 6-7 Displaying the Server’s Global Configuration With show-server .............................85
Figure 6-8 Sample default.vc File ............................................................................................86
Figure 6-9 Output of nom_tell show-view Command for Default View .....................................87
Figure 6-10 show-zone Results for Default Zone ........................................................................88
Figure 6-11 show-zone Results for a Specific Zone ....................................................................89
Figure 6-12 Using nom_tell to Generate Statistics for a View ....................................................92
Figure 6-13 Enabling Per-Zone Statistics With update-zone......................................................93
Figure 6-14 Stop ANS With nom_tell.........................................................................................94
Figure 6-15 update-data with nom_tell interactive mode ...........................................................95
Figure 6-16 Update Server using nom_tell .................................................................................96
Figure 6-17 Adding a View Option with update-view.................................................................97
Figure 6-18 Using show-view to see the Results of an Update ...................................................98
Figure 6-19 Setting a Log Switch with update-view....................................................................99
Figure 6-20 version command output .......................................................................................100
Figure 8-1 Adding a Master Zone...........................................................................................127
Figure 8-2 Adding Data to a Master Zone Using update-data.................................................128
Figure 8-3 Add a Slave Zone..................................................................................................128
Figure 8-4 Verifying an Added Option with show-zone ..........................................................136
Figure 8-5 Adding a Host-based allow-update Option Using update-zone .............................136
Figure E-1 Sample Server Configuration File .........................................................................208
Figure E-2 Sample View Configuration File ...........................................................................209
Nominum ANS ix
x List of Figures
Nominum ANS
1
Introduction to Nominum
ANS
The Authoritative Name Server (ANS) is an authoritative Domain Name System (DNS) nameserver. ANS
includes a full implementation of DNS authoritative server standards, and several operational and data-
base stability advantages over other authoritative nameserver implementations, including:
• Flexible, fast reconfiguration.
• High performance, which both supports the ability to serve very large datasets and amounts of
traffic, and provides resilience against sharply increased loads that typically occur during DDOS
attacks and virus epidemics.
• Rapid start times, reducing downtime when ANS must be restarted.
• Enhances uptime by reducing situations in which a restart is required.
• Ability to use Nominum’s VDB to store DNS data.
Communicating with ANS

It is possible to communicate with ANS in several ways—this flexibility means that data may, in most
cases, be updated without having to restart the ANS server.
This manual, where practical, describes these methods, which include the following:
Nominum 1
2 Chapter 1: Introduction to Nominum ANS
• Using the ans.conf configuration file. This optional method is discussed in Chapter 2, ”Getting
Started With ANS”.
• Using the Nominum Command Channel (CC) protocol via the nom_tell program. This method
is discussed in Chapter 6, ”Using the Command Channel with ANS”.
• Using a utility program (which itself communicates via the Command Channel). These utilities
are discussed in Chapter 7, ”The ANS Utilities”.
About This Manual

The Nominum Authoritative Name Server Administrator’s Manual is intended for system administrators
who are configuring Nominum’s Authoritative Name Server (ANS). It is assumed that readers are familiar
with DNS concepts and terms.
Organization
Chapter 1, ”Introduction to Nominum ANS”, this chapter, describes ANS in general terms and provides a
view of the Manual’s organization.
Chapter 2, ”Getting Started With ANS”, provides the most basic information for starting the ANS server
and loading a master zone file.
Chapter 3, ”Zones and Templates”, provides information on zone types in ANS.
Chapter 4, ”Database Drivers”, describes each of the supported drivers.
Chapter 5, ”Server, View and Zone Options”, lists each option with a brief description.
Chapter 6, ”Using the Command Channel with ANS”, provides information regarding how to manipulate
the data being served by ANS via the nom_tell program, which is an implementation of the Nominum
Command Channel protocol. Several examples of modifying data are included.
Chapter 7, ”The ANS Utilities”, describes the programs used to manipulate DNS zones and data.
Chapter D, ”Examples of Server and View Operations”, gives examples of how to perform many common
DNS administration tasks at the server and view levels.
Chapter 8, ”Examples of Zone Operations”, gives examples of common operations at the zone level.
Chapter 9, ”SNMP in ANS”, describes the SNMP functionality included in ANS.
Chapter 10, ”Secret Key Transaction Authentication (TSIG)”, describes how to configure TSIG and
GSS-TSIG with ANS.
Nominum
About This Manual 3
Chapter 11, ”Supporting Programs”, describes programs that support the use of ANS, especially with
authentication.
Appendix A, Statistics, lists the statistics supported by this server.
Appendix B, ANS Events, describes the events that can be requested by Command Channel clients. These
events are useful for organizations wishing to integrate ANS with other programs, or with an existing Sim-
ple Network Protocol Management (SNMP) monitoring system.
Appendix C, Logging Switches, covers the logging switches for ANS.
Appendix E, ANS Files, discusses the locations and purpose of all files that ANS creates.
Typographical Conventions
The following typographical conventions are used throughout the Administrator’s Manual:
Convention Use Example

bold Unix commands, and system facilities cd
such as syslog. syslog
italic Filenames, program or utility names, channel.conf
domain names, UNIX pathnames and example.com
Uniform Resource Locators (URLs), http://www.nominum.com
zones and views.
constant width Object fields, option names, formats, name
and excerpts from code and configu- all-subnets-local
ration files. ListOf
# This is a comment
constant width bold User-provided input for interactive % cd /usr/local
sessions or scripts.
constant italic Variables for which a context-sensitive % cd /usr/directory
substitution should be made.
% The command-line prompt for inter- % cd /tmp
active sessions.
# The prompt for the root user. # mkdir /yourdirectory
Table 1-1 Typographical Conventions
Example Conventions
In command examples, the backslash character (\) denotes artificial linebreaks—for example:
Nominum
4 Chapter 1: Introduction to Nominum ANS
ans> update-zone zone=example.com \

also-notify=10.0.0.3
is rendered without carriage returns in actual use:
ans> update-zone zone=example.com also-notify=10.0.0.3
Nominum
2
Getting Started With ANS
This chapter explains the steps needed to get started with ANS.
For this section, we assume that the ANS software has already been installed according to the INSTALL
instructions included with the ANS package. We also assume that you already have some DNS zone data
that you are serving via some means other than ANS that you wish to load into ANS.
Once installed, there are only two things you need to do to start DNS service via ANS:
1. Start the server.
2. Load DNS data.
Starting the ANS Server

The nom_nanny utility program starts and monitors Nominum servers, using each server’s initialization
script. Processes started by nom_nanny are subsequently monitored by nom_nanny. If the server process
fails for any reason, nom_nanny attempts to restart the server process.
Start the Nominum ANS server as follows:
1. Start the nom_nanny program as root:
# /etc/init.d/nom_nanny start
2. Start the ANS server process:
Nominum 5
6 Chapter 2: Getting Started With ANS
# /etc/init.d/ans start
3. (optional) Start the snmpagent and/or SOAP API services, if appropriate.
NOTE When an engine’s initialization script is executed, it first checks to see if the nom_nanny
process is running. If nom_nanny is already running, the initialization script instructs
nom_nanny to start the engine process. If the nom_nanny process isn’t running, the
engine’s initialization process simply starts the engine process, which then runs unmoni-
tored.
Confirming That ANS is Running Using nom_tell
The nom_tell program uses the Nominum Command Channel to communicate with Nominum servers.
This program is described in detail in Chapter 6, "Using the Command Channel with ANS". You can use
nom_tell to determine whether ANS is running:
# ans version
{
type => 'version'
vendor => 'Nominum'
product => 'ANS'
platform => '<platform>'
version => '<version>'
}
Loading a DNS Master File

Now that the server is running, you just need to tell it what DNS data to serve. You probably already have
a DNS Master file, such as the one used as an example in this section.
ANS supports the RFC 1035 master file format (see ftp://ftp.rfc-editor.org/in-notes/rfc1035.txt), with
some enhancements.
(If you are not already running a DNS server, you may not have such a file and should use other ways of
loading data into ANS, which are discussed in subsequent chapters.)
The ans_load command is a utility that is provided especially to load existing zone data that is in the stan-
dard DNS Master File format. For details about this utility, see Chapter 7, "The ANS Utilities". Use the
ans_load command to read and load a DNS master file into a Nominum ANS database. This example
loads the zone example from the DNS master file example.master.
Nominum
Loading a DNS Master File 7
First, here are the contents of the example.master file:
$TTL 3600
$ORIGIN example.
@ SOA ns1 hostmaster 100 3600 1800 604800 3600
NS ns1
NS ns2
ns1 A 10.0.0.1
ns2 A 10.0.0.2
mail1 A 10.0.0.3
mail2 A 10.0.0.4
host1 A 10.1.0.1
host2 A 10.1.0.2
A 10.2.0.2
MX 0 mail1
MX 10 mail2
host3 A 10.1.0.3
host4 A 10.1.0.4
A 10.2.0.4
MX 0 mail1
MX 10 mail2
Figure 2-1 Example DNS Master file
You can load this data by issuing an ans_load command. For more detail on ans_load, see ”ans_load”
on page 104 of Chapter 7, ”The ANS Utilities”.
# ans_load example example.master
The server is now serving the zone. In the server’s logging output, you will see the following:
ANS: info: default/example (master): added

ANS: info: default/example (master): modified
The first line says that a new zone called example was created in the default view. Views are discussed in
Chapter 2, "Getting Started With ANS" and subsequent chapters.
Nominum
The second line means that this zone was modified (in this case, data was added to the empty zone that
was created).
A dig command (dig is a freely available DNS query tool) confirms that the data is now present in the
ANS server. Your ANS server is now running and serving data.
# dig @::1 example. soa
; <<>> DiG 8.3 <<>> @::1 example. soa

; (1 server found)
;; res options: init recurs defnam dnsrch
;; got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 32477
;; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 2, ADDITIONAL: 2
;; QUERY SECTION:
;; example, type = SOA, class = IN
;; ANSWER SECTION:
example. 1H IN SOA ns1.example. hostmaster.example. (
100 ; serial
1H ; refresh
30M ; retry
1W ; expiry
1H ) ; minimum
;; AUTHORITY SECTION:
example. 1H IN NS ns2.example.
example. 1H IN NS ns1.example.
;; ADDITIONAL SECTION:
ns2.example. 1H IN A 10.0.0.2
ns1.example. 1H IN A 10.0.0.1
;; Total query time: 26 msec

;; FROM: example.org to SERVER: ::1
;; WHEN: Wed Dec 17 02:18:10 2003
;; MSG SIZE sent: 25 rcvd: 140
Additional Technical Background

While starting the server and loading data is enough to get many people started with ANS, some sites
may need more details regarding the server command options and configuration file in order to meet
their specific operational requirements. This section provides more details on these topics.
Nominum
Additional Technical Background 9
The ans Command

The ans command takes the following arguments:
ans [-c|--configuration file] [-f |--foreground]

[-F |--foreground-with-syslog] [-h|--help] [--no-safe-mode]
[--safe-mode] [-r|--root directory] [-s|--syslog-facility facility]
[-u |--user username] [--usage] [-v|--version] [-V]
Command Line Option Description

-c file, --configuration Read configuration from the specified database instead of the
file default configuration database, /var/nom/ans/ans.conf.
-f|--foreground Run in the foreground. The server will not daemonize. Logging is
directed to stderr.
-F|--foreground-with-syslog Run in the foreground. The server will not daemonize. Logging is
directed to both stderr and syslog.
-h|--help Display a help message and exit.
--no-safe-mode If a fatal error occurs during server setup, exit with a non-zero sta-
tus instead of entering “safe mode”. See ”--safe-mode”.
--safe-mode Start the server in “safe mode”.
In safe mode, as much as possible of the configuration is loaded,

but no DNS listeners are activated. The Command Channel lis-
tener is activated, if possible, so that the server may be reconfig-
ured using it.
Fatal errors during server setup (for example, certain types of erro-
neous configuration) cause the server to restart itself in safe mode
rather than exiting, unless the use of safe mode has been disabled
with the --no-safe-mode option.
To exit safe mode, send a restart CC command.
NOTE: If you fix an erroneous configuration with

update-server, the server restarts itself automatically.
-s|--syslog-facility When logging to syslog, use the specified syslog facility
instead of the default facility, "daemon".
Table 2-1 ans Command-line Options
Nominum
Command Line Option Description

-r|--root directory chroot() to the specified directory when the server runs. Specify-
ing this option without also specifying a non-root user with the
-u option offers no additional protection.
All paths, including the configuration file, are interpreted relative

to the specified root.
NOTE: The root option is not compatible with safe mode, as

entering safe mode involves re-executing the server binary, which
is typically not available after chroot() has been called. If an event
that would trigger safe mode occurs in a chroot()ed server, it will
attempt to enter safe mode, fail, and exit with non-zero status.
-u|--user username setuid() to the specified username, and change permissions for
username after the server binds its sockets. The setuid() occurs
after the server binds its sockets, and after this command, the
server must be restarted to open new socket interfaces.
NOTE: -u and --user require the specified user to have the

right to create files not only in the ANS working directory, but also
in the directory containing the ANS configuration database. For
that reason, it’s often convenient to simply put the ANS configu-
ration database in the ANS working directory, and use -c or
--configuration to specify the filename when starting ANS.
--usage Display a usage message and exit.
-v, --version Display the version of the server and exit.
-V, --check The server’s configuration is read and the server exits. If the exit
status is 0, the configuration was valid.
Table 2-1 ans Command-line Options (continued)
Starting Nominum ANS in the Foreground

Occasionally, you may wish to see Nominum ANS’s logging uncluttered by other syslog entries. You can
do so by running ANS in the foreground. To run ANS in the foreground instead of as a daemon, use the
-f option, such as:
# /usr/local/nom/sbin/ans -f
ANS: info: starting Nominum ANS <version>
ANS: info: configuration file is '/etc/ans.conf'
ANS: info: working directory is '/var/nom/ans'
ANS: info: opening subprocess databases
Nominum
Additional Technical Background 11
ANS: info: opening threaded databases

ANS: info: opened database 'master', driver='vdb'
ANS: info: opened database 'slave', driver='vdb'
ANS: info: listening on 127.0.0.1#53
ANS: info: listening on ::1#53
ANS: info: listening on fe80::20e:a6ff:fe54:d8ea%2#53
ANS: info: listening on 10.0.0.1#53
ANS: info: listening for commands on 127.0.0.1#9353
ANS: info: loading
ANS: info: imported 0 zones for view 'default' from db 'master'
ANS: info: imported 0 zones for view 'default' from db 'slave’'
ANS: info: maintaining 0 slave zones for view 'default'
ANS: info: loading zone maintenance state for view 'default'
ANS: info: imported a total of 0 zones
ANS: info: maintaining a total of 0 slave zones
ANS: info: imported a total of 0 nodes into view caches
ANS: info: running
The log messages show that ANS initialized itself in its working directory, /var/nom/ans, started listening
for DNS requests on both IPv4 and IPv6 interfaces, and found no zones to load in its standard master and
slave databases.
The Configuration File

Nominum ANS does not require a configuration file. If you are happy with the default configuration set-
tings of the server, you don’t need a configuration file.
If a configuration file does not exist, ANS uses a default configuration, which:
• Listens on all interfaces using port 53.
• Uses the default view.
• Listens for Nominum Command Channel requests on the ans channel as defined in /etc/chan-
nel.conf (by default on port 9353 of the loopback address).
• Uses two VDB databases, master and slave.
However, if you wish to change one of these defaults, do so via the /etc/ans.conf file. If you choose to
utilize a configuration file, this section describes the server configuration file for ANS and what it can con-
tain.
The configuration file is read before any setuid() or chroot() functions requested on the command line
are executed, and if no configuration file is specified on the command line when the ans command is
given, the server tries to load /etc/ans.conf.
Nominum
An ANS configuration file is a sequence of lines. Blank lines and lines starting with # are ignored. A con-
figuration line contains an option name, possibly followed by whitespace and then a value. If present, the
value is all of the remaining text on the line, including any non-leading whitespace.
A configuration file contains options and their values. Options may apply to the whole server or to a par-
ticular view. The server, view, and zone option, their formats and descriptions, are listed in Chapter 5,
"Server, View and Zone Options".
Sample Configuration File

An ans.conf configuration file could look like the following example:
foreground
directory /var/nom/ans
listen-on 127.0.0.1#53
listen-on 128.177.193.79#53
db master vdb base=master
db slave vdb base=slave
import-view "internal"
import-view "default"
Views
Views are an integral part of how ANS presents data. ANS allows multiple views of the DNS namespace to
be presented, and selects the appropriate view based on the address of the requestor, and/or the address
of the service. That is, a query from one client can be directed to a specific view and see the data in that
view, while a different query can be directed to different data in a different view.
A view configuration file named viewname.vc will exist for every view imported by the server configura-
tion—ANS automatically creates any missing .vc files on startup.
View configuration files are text files with the same basic form as the server configuration file. The
options which may be configured are described in Table 5-3 on page 41.
Nominum recommends using the Command Channel to modify view configurations, but you may also
edit the view configuration files directly when the server is not running. Note that comments in a view
configuration file will be lost if the view is subsequently updated via the Command Channel.
Nominum
3
Zones and Templates
This chapter provides information on the key concepts of zones and templates in ANS
Zones
This section provides a brief overview of the various zone types in ANS. A zone type describes the
source(s) of the zone’s data. A zones may be only of one type.
There are four types of zones, distinguished by how each obtains its data:
• Master zones—The zone’s DNS content is authoritative.
• Slave zones—The zone’s DNS content is obtained from elsewhere (such as a “master” server).
• Instance zones—The zone’s DNS content is obtained by combining customized data with tem-
plate data.
• Alias zones—The zone’s DNS content is copied from a zone with the same name in another
view.
Nominum 13
14 Chapter 3: Zones and Templates
Zone Versions and Zone Serial Numbers

In Nominum ANS, each version of a zone has its own ANS zone version as well as a DNS serial number
(shown in the SOA record).
The version number of a zone is an ANS construct, not a DNS construct, and changes every time a change
is made to the zone in the database. Version numbers possess much stronger properties than the DNS
serial number. DNS serial numbers, because they are under user control, may be left unchanged and even
decremented, but the zone version number increments if the database changes. Zone versions always
increase, and are 64-bit numbers to avoid overflowing.
The SOA serial numbers of instance zones are controlled by ANS and generated using the SOA serial from
either the customization or the template. By default, the SOA serial from the customization (if present) is
used—otherwise the SOA serial is that of the template.
Master Zones
A master zone is loaded into ANS by the operator (it is not transferred from another host). Master zones
contain both configuration information and zone data. Configuration information is typically information
such as which servers to notify when updates occur. Zone data is Resource Record information, such as
the Name Server (NS) for the zone.
The key difference between master and slave zones is that master zones define “the truth”, and slaves ask
a master for a definition of “the truth”. Master zones, unlike slave zones, do not expire (for a definition of
expiration, see ”Slave Zones”).
Slave Zones
A slave zone contains data transferred from a single master server, chosen from a group of one or more
master servers that should (under normal circumstances) all contain identical data. If a slave zone is
unable to contact its master for the amount of time specified in the expire field of its SOA record, it’s
subject to expiration—the ANS server believes that the slave zone doesn’t contain valid data, and thus
cannot be served.
Slave zones must have a masters configuration element defined. This element specifies the IP addresses
from which the local server should copy its information. That is, the address of the master server that the
salve (local) server contacts for authoritative data.
Nominum
Zones 15
Instance Zones
Instance zones get their data from two sources—data templates and customization, which means data
customized for a particular zone instance. For more information on templates in ANS, see ”Templates” on
page 19.
You can think of an instance zone as a master zone whose data has been combined with that from a data
template. An instance zone can have its own configuration information and zone data and the zone data
from a data template. In this case, the zone data defined specifically for the instance zone itself is called a
customization or customized data (because it applies only to the instance zone itself). The instance may
also have no customization; that is, its data is identical to that of the data template.
NOTE Instance zones may not be updated using DDNS.
The information in the data template can be applied to more than one instance zone. When a zone is
using a data template and customization data overlaps with information from the template, ANS first
looks for zone options in the instance zone’s own configuration, and then looks for zone options in the
data template. This choice is made at the RRset level, not the node level.
A zone is an instance zone if it has a data-template configuration element. If present, this element
specifies the name of the data template in which additional zone data is defined.
As explained in ”Templates” on page 19, any type of zone, including an instance zone, may have a con-
figuration template (that is, use a template for shared configuration data). As with data templates, when
a zone is using a configuration template, ANS first looks for zone options in the zone’s own configura-
tion, and then looks for zone options in its template.
Instance zones may not be transferred incrementally, but are always transferred in full, and this may both
substantially increase memory requirements for the slave server (see ”purge-zone” on page 79 for assis-
tance in alleviating this) and affect the server’s ability to transfer the resulting zone out again incremen-
tally.
Alias Zones
An alias zone is a zone whose contents are copied from a zone of the same name that is part of a differ-
ent view. Zone aliases permit content to be stored and cached only once for greater efficiency. Changing
the canonical copy instantly propagates the change to all of its aliases.
Alias zones allow a zone stored in one view to be visible in another view. This is useful in cases where mul-
tiple views are needed with identical zone content. Alias zones have a source-view configuration ele-
ment. This element specifies the name of the view in which the zone’s content is defined.
Nominum
Alias zones can’t be aliased, but master zones, slave zones, and instance zones can.
NOTE Aliases must have the same name as their canonical copies. Aliasing simply makes a zone
available in multiple views—it is not templating.
Alias Behavior
Any operation that can be performed on the source of an alias zone, with the exception of creating an
alias, may be performed on the alias zone as well. For example, an alias of a master zone will accept
DDNS updates, an alias of a template may be used as a data template, and so on.
Example
For this example, assume that two views exist, “internal” and “external”, and that the “example” zone in
the “external” view is to be visible in “internal” as well.
First, create the alias:
ans> add-zone view=internal zone=example source-view=external
As with any other zone, its configuration can be examined:
ans> show-zone view=internal zone=example

{
type => 'show-zone'
zone => 'example.'
zone-type => 'alias'
source-view => 'external'
view => 'internal'
}
Look at the canonical copy in view “external”—note the aliased-by-view field, which displays the
names of other views with aliases that refer to this zone:
ans> show-zone view=external zone=example

{
type => 'show-zone'
zone => 'example.'
zone-type => 'master'
db => 'master'
version => '3'
aliased-by-view => ('internal')
}
Nominum
Zones 17
The next example shows a zone aliased in more than one other view. First, create the zone in the default
view with ans_load:
# ans_load example /proj/data/example
Next, create a few new views and alias the zone within them:
# nom_tell ans
ans> add-view view=foo match-to=10.53.0.1
ans> add-view view=bar match-to=10.53.0.2
ans> add-zone view=foo name=example source-view=default
ans> add-zone view=bar name=example source-view=default
Display the alias zone:
ans> show-zone view=foo zone=example

{
type => 'show-zone'
zone => 'example.'
zone-type => 'alias'
source-view => 'default'
view => 'foo'
db => 'master'
version => '3'
}
Note that zone-type is set to alias, and that the source-view field indicates the source of the
zone’s content. The canonical zone can also be examined:
ans> show-zone name=example

{
type => 'show-zone'
zone => 'example.'
zone-type => 'master'
db => 'master'
version => '3'
aliased-by-view => ('bar' 'foo')
}
Note the aliased-by-view field, which provides a list of views that have an alias for this content—this
field isn’t present if a zone has no aliases.
Nominum
Deleting a Zone With Aliases
An attempt to delete a zone that has aliases produces the following error:
ans> delete-zone name=example

{
type => 'delete-zone'
err => 'in use'
}
Derived Zone Elements

ANS provides some assistance in figuring out what type of zone you are looking at and how a given zone
relates to other zones or templates. Certain zone elements can be seen when displaying a zone via the
Command Channel. These elements are derived from other zone information and, as such, cannot be set
by the user. However, they are useful in providing information about types of zone, and related informa-
tion. The Nominum Command Channel is discussed in .Chapter 6, ”Using the Command Channel with
ANS”
Derived Zone Element Description

aliased-by-view If any zones in other views are aliases of this zone, the
aliased-by-view element will contain a list of the views which
contain aliases of this zone.
conf-template-of If this zone is a template, and any other zones are using this zone as a
configuration template, the conf-template-of element will con-
tain a list of those other zones.
data-template-of If this zone is a template, and any other zones are using this zone as a
data template, the data-template-of element will contain a list of
those other zones.
db If all or some of this zone’s content is stored in a database, the db
element will contain the name of the database.
fragmentable If all or some of this zone’s content is stored in a database, and the
zone’s content was initially created with either ans_load’s
--fragment or an update-data command where the zone already
existed as an instance or template, the zone will be considered a
zone fragment. A zone fragment is not required to have SOA or NS
records, but will only be used to serve DNS data in conjunction with
another zone providing the missing records (either as a template or
instance). If a zone is a zone fragment, the fragmentable element
will be set to yes.
Table 3-1 Derived Zone Elements
Nominum
Templates 19
Derived Zone Element Description

incomplete If this zone is fragmentable, its data can only be served if its data is
combined with that of another zone via templating. If the combined
content contains SOA and NS records at the zone origin, the zone is
considered complete. If not, the zone is considered incomplete, all
DNS queries to the zone will return REFUSED, and the incomplete
element will be set to yes.
maintenance If this is a slave zone, information about zone maintenance status will
be returned in the maintenance element. This information is in the
same form as the show-maintenance response.
oldest-version If all or some of this zone’s content is stored in a database, old-
est-version contains the zone’s oldest stored ANS version of the
zone. This version number is used by other ANS utility programs
which accept zone revision numbers for manipulating or displaying a
zone.
version If all or some of this zone’s content is stored in a database, the ver-
sion element will contain the zone’s ANS version of the zone. This
version number can be used by other utility programs which accept
zone revision numbers for manipulating or displaying a zone.
zone-type The zone-type element indicates the type of zone: either master,
slave, instance, alias, or template.
Table 3-1 Derived Zone Elements (continued)
Templates
You may want to have ten, hundreds or even hundreds of thousands of zones with identical (or nearly
identical) content. Zone templates make it possible to create multiple zones, each containing the default
zone data, without having to separately copy data that is identical for each of the zones into each zone.
Configuration Templates and Data Templates

There are two different types of templates, commonly referred to as “data templates” and “configuration
templates.” A configuration template denotes common configuration elements that may be shared by
several zones. A data template denotes common zone data that may be shared by several zones.
More precisely, these are really “a template with zone data” and “a template with configuration data.”
One template may actually feature both types of data, but when a template is applied to a zone, a tem-
Nominum
plate type is specified, and the zone is configured according to constraints of the template being applied.
So, if a template with both configuration data and zone data is applied to a zone as a configuration tem-
plate, only the configuration data is used. If the same template is applied as a data template, only the
zone data is used for the zone.
Data templates are only relevant to instance zones. Instance zones are zones that are made up of a com-
bination of customized data and zone template data. See ”Instance Zones” on page 15, for more infor-
mation on instance zones.
NOTE In zones that use a configuration template, the combined configuration must be inter-
nally consistent. That is, you can’t combine a zone that uses a
masters statement with a template that includes source-view statement, and so
forth.
Configuration Templates
If you have zones which share some common configuration elements, you can create a zone configura-
tion template to store the common elements, and have your zones refer to it instead of duplicating the
configuration. You can’t “stack” configuration templates, but any zone configuration element can be put
into a template.
When a zone is using a configuration template, ANS first looks for zone options in the zone’s own config-
uration, and then looks for zone options in its template.
Any type of zone may have a configuration template (that is, use a template for shared configuration
data).
Data Templates
Only instance zones use data templates. In some cases, an instance zone may contain only data from the
data template; in other cases, instance zones combine template data with data customized for the zone
itself. When responding to DNS queries and zone transfer requests, the customization and data template
are merged.
An important restriction of data templates is that they cannot be updated using Dynamic DNS (DDNS).
Where Data Comes From
Under normal circumstances, a zone query is answered with zone information from a single source—
canonical zone information from master zones, or, in the case of slave zones, canonical information that
has been obtained from an authoritative server.
Nominum
Templates 21
Whereas master zones must be “complete”, and contain all relevant information to answer DNS queries,
may be fragments, and individually contain only part of the zone’s total information. However, taken as a
whole, the combination of data from templates must comprise a complete zone.
Therefore, when a zone query is answered from a merger of instance data and template data, it is
answered from a “complete” zone.
Choosing From Multiple Sources
Inevitably, there will be situations where multiple sources of data are available from which to choose
when responding to a DNS query. The “tiebreaking algorithm” is to favor customization data related to an
instance zone over information from a data template.
This choice is made at the RRset level, not the node level. This means that A records for a name may
come from the customized data in the instance zone, while MX records for the same name may come
from the data template.
ANS does not combine Resource Records from different sources to make up a single RRset.
Templating In Action
Assume that you want example.com, example.net, and example.org all to have the same data (DNS con-
tent) and configuration. ANS allows this to be done with one edit instead of three, and without duplicat-
ing storage.
Note that “the same data”, in this case, means “the same data after relativizing to the zone origin”, that
is, looking at information at the node-level rather than the domain-level.
For example, if you look at:
www.example.com. 86400 IN A 192.168.1.204
from example.com, and at:
www.example.net. 86400 IN A 192.168.1.204
from example.net, you notice that if you look at just the node information, you have the same Resource
Record:
www 86400 IN A 192.168.1.204
So, how would we use templates to make example.com, example.net and example.org share common
information? The steps are:
1. Create a data template.
2. Load the zone with the data template.
Nominum
3. Make a configuration template that uses the data from the data template.
4. Apply the configuration template to the zones you want to share the information.
Create a Data Template
Start with the data content that is shared by the domains and put it in a file called example.data:
$TTL 3600
@ SOA ns1 hostmaster 1 3600 1800 2592000 3600
@ 172800 NS ns1
@ 172800 NS ns2
@ 172800 NS ns3
ns1 A 192.168.1.29
ns2 A 192.168.1.218
ns3 A 10.0.0.9
www 86400 A 192.168.1.204
Load a Zone
ANS requires that the zone name passed to data-template is that of an existing zone, so create a zone
called example.data by loading the template zone data into ANS. Because you are loading a template,
use the --is-template option to the command.
# ans_load --is-template example.data example.data
Make a Template
Next, construct a configuration template that uses example.data for data templating.
ans> add-zone zone-type=template zone=example.conf \

data-template=example.data
Apply the Configuration Template
Now instruct the example.com zone to use example.conf as a configuration template:
ans> add-zone zone=example.com conf-template=example.conf
Use show-zone to display the effects of what’s been done so far. This command will show all the zones
currently known.
ans> show-zone
{
type => 'show-zone'
zone => 'example.data.'
zone-type => 'template'
db => 'master'
version => '3'
Nominum
Templates 23
data-template-of => ('example.com.')

fragmentable => 'yes'
}
{
type => 'show-zone'
zone => 'example.conf.'
zone-type => 'template'
data-template => 'example.data.'
view => 'default'
conf-template-of => ('example.com.')
}
{
type => 'show-zone'
zone => 'example.com.'
zone-type => 'instance'
conf-template-of => 'example.conf.'
view => 'default'
}
A couple of notes:
• example.com shows a zone-type of “instance”, indicating that it has a data template.
• Note the data-template-of entries in example.data and example.conf and the conf-tem-
plate-of entry for example.com, respectively—they display the zones using the indicated
data or configuration template.
Next, query example.com:
# dig @localhost www.example.com.

; <<>> DiG 9.3.2 <<>> @localhost www.example.com.
; (1 server found)
;; global options: printcmd
;; Got answer:
;; QUESTION SECTION:
;www.example.com. IN A
;; ANSWER SECTION:
;; AUTHORITY SECTION:
example.com. 172800 IN NS ns1.example.com.
;; ADDITIONAL SECTION:
Nominum
ns1.example.com. 3600 IN A 192.168.1.29

example.com is a “pure” instance—it doesn’t have any data associated with the zone itself that would
override the information from the template. Therefore, all of the data shown comes from the template—
note how all the names that were previously subdomains of example.data in the template are now sub-
domains of example.com.
Changing the Template
If you want a change to happen to all the zones using a template, change the data in the template itself.
When the data template is changed, those changes will appear in each instance. For example:
ans> update-data zone=example.data add="everywhere 3600 A 10.0.0.1"
Changing an Individual Zone
If you want a change to apply only to one specific zone, you create what is called a zone customization.
A customization is DNS data that may be a complete zone, that is, it may have all the data a zone needs
to be served correctly in the DNS, or it may be just a fragment of a zone and need to combine with other
data to be complete.
Add some data with update-data:
ans> update-data zone=example.com add="just_com 3600 A 10.0.0.1"
Now, a query for just_com.example.com yields an answer, but a query for just_com.example.net or
just_com.example.org doesn’t. The various ans_* commands can be used to work with and edit the frag-
ment, if desired. For example:
# ans_dump example.com
just_com 3600 IN A 10.0.0.1
Those commands may also be used to edit the template.
It’s illustrative to compare this to the output of an AXFR of the instance—the view of the data via the DNS
for instance zones is always a fusion of the customized data and the template data.
# dig example.com. axfr

; <<>> DiG 9.3.2 <<>> @localhost example.com. axfr
; (1 server found)
example.com. 3600 IN SOA ns1.example.com. hostmas-
ter.example.com. 10 3600 1800 2592000 3600
Nominum
Templates 25
everywhere.example.com. 3600 IN A 10.0.0.1

just_com.example.com. 3600 IN A 10.0.0.1
example.com. 3600 IN SOA ns1.example.com. hostmas-
ter.example.com. 10 3600 1800 2592000 3600
Notice the SOA serial number—ANS controls this value when using templating. Regardless of whether
you change the data in the template, the customization data, or both, ANS ensures that a new and
greater serial number is associated with the new content—this is important for slaves of a templated
zone.
To add data to www.example.com:
ans> update-data zone=example.com add=("www 3600 A 10.0.0.2" \

"www 3600 A 10.0.0.3")
ans> show-data zone=example.com
{
type => 'show-data'
view => 'default'
node => 'www'
data => ('www 3600 IN A 10.0.0.2' 'www 3600 IN A 10.0.0.3')
}
To remove data from www.example.com:
ans> update-data zone=example.com \

delete=("www 3600 A 10.0.0.2" "www 3600 A 10.0.0.3")
ans> show-data zone=example.com
{
type => 'show-data'
}
Note that if the instance and the template both provide an RRset, the RRset of the instance is the one
used.
Nominum
Nominum
4
Database Drivers
Database Drivers
ANS supports a number of database drivers, which either store DNS data or provide access to sources of
DNS data. This section provides information about configuring drivers for the backend databases that can
currently be used with ANS. In addition, tips for backing up databases are included.
Overview
To indicate that you wish to use a particular database as your backend to ANS, you use the db option in
the ANS configuration file and supply the name of the database driver as its argument:
db master vdb base=master

db slave vdb base=slave
The available drivers are:
• vdb—The Nominum VDB driver.
• cc—A special pseudo-driver that uses the Command Channel protocol to communicate with
the ANS server.
• file—An ANS database driver that creates a virtual read-only ANS database.
Nominum 27
28 Chapter 4: Database Drivers
Note About Updating Databases
The engine always updates older database formats to the latest version of that database when you run it.
There are no database conversion steps needed. It is always good practice, however, to copy your data-
bases before you upgrade in case you decide later to back out of a release. Doing so permits easier down-
grading, if that becomes necessary.
The VDB Database Driver

The vdb database driver uses a Nominum VDB database to store DNS data. VDB is a high-performance
versioned memory-resident database.
When a VDB is opened, the database image is copied from disk to memory. When a VDB is closed, it is
written back to disk. VDB is fully transactional; all changes are journalled on disk, allowing automatic
recovery in the event of system or server failure. The vdb driver also periodically checkpoints the data-
base, to prevent excessive journal sizes on long-running systems.
The following driver arguments are available:
Argument Description
base=name Use name as the base when constructing database pathnames. The
default name is master. If name has a directory prefix, then the
base_dir will be that prefix, and the base_name will be name
minus the directory prefix. If there is no directory prefix, then
base_dir will be “.” and base_name will be name.
big Use vdb-40 instead of vdb-32 when creating a new database. The
VDB driver supports both “ordinary” (vdb-32) and “big” (vdb-40)
VDBs. A vdb-32 can store up to 2^32 bytes, while a vdb-40 can
store up to 2^40 bytes. vdb-40 is only available on 64-bit platforms
where ANS has been built in 64-bit mode.
Table 4-1 VDB Driver Arguments
The following files are used:
• base_dir/base_name.vdb—the data file.
• base_dir/base_name.vdb.vmi—the pageset info for the data file.
• base_dir/base_name.vdb.vmp—the pageset content for the data file.
• base_dir/base_name.vdi—the indexes file.
Nominum
Database Drivers 29
• base_dir/base_name.vdi.vmi—the pageset info for the indexes file.
• base_dir/base_name.vdi.vmp—the pageset content for the indexes file.
• base_dir/base_name.vdj*—transaction journal files.
• base_dir/base_name.vdl— lock file.
The cc Database Driver

The cc database driver uses the Nominum Command Channel to connect to a database on a running
ANS server.
NOTE When interacting with an ANS database over the Command Channel driver, the default
DB name is “master”. However, if you supply the channel= driver argument, the “data-
base” argument must also be explicitly specified. Should you fail to do so, the database
on which to operate is undefined, and an error is returned.
channel=service_name Use the command channel specified by service_name. The service
must be specified in /etc/channel.conf. The default service_name is
ans.
database Connect to the specified database on the ANS server. The default
database is master.
Table 4-2 cc Driver Arguments
Example
You can use the cc driver to help you run ANS utilities against a remote server.
For instance, if /etc/channel.conf contains the following entries:
local_ans 9353 secret1

remote_ans 10.177.198.18#9353 secret2
use the cc driverarg channel with the appropriate logical database name:
# ans_dump movie.edu channel=remote_ans master

# ans_load movie.edu /tmp/movie.edu.db channel=local_ans master
Nominum
This driver argument can also be used to add a zone to an instance of ANS that was not in the standard
location. If, for example, you had an /etc/channel.conf entry for a second instance of ANS as ans2 and
you wanted to load a zone called test from the directory config into a database called master, the com-
mand could be:
# ans_load test config/test channel=ans2 master
The file Database Driver

The file database driver creates a virtual, read-only ANS database containing the contents of a DNS
master file.
While this driver could be used with an ANS server, it is mostly useful with the ans_diff command to com-
pare the contents of an ANS database with that of a master file. See Chapter 7, ”The ANS Utilities”, for
more information on the ans_diff command.
file=file Use the specified master file as the source of data. This argument
must be specified.
base=file A synonym for file, for consistency with other drivers.
zone=zone The zone into which the master file should be loaded. This argument
must be specified unless URL syntax is used, in which case it will
default to the zone name specified in the URL.
For more information on URL syntax, see ”URL Syntax” on page 102
of Chapter 7, ”The ANS Utilities”.
view=view The view into which the master file should be loaded. The default
view is default.
Table 4-3 file Driver Arguments
Nominum
Database Drivers 31
Nominum
Nominum
Database Drivers 33
Nominum
Nominum
5
Server, View and Zone
Options
This chapter shows all the server, view and zone options that can be put in a configuration file. In addi-
tion, it explains the formats for the options.
Option Formats
The following formats apply to the option summaries in this chapter.
Format Description
addrport An IPv4 or IPv6 address, optionally including a # followed by a
port number. In some cases, which are noted, only IPv4 addresses
are allowed.
addrpat An IPv4 or IPv6 address, optionally followed by a “/” and a mask
length. The address may be prefixed with “!”, in which case
matching the pattern denies access instead of granting it.
range An IPv4 or IPv6 address, followed by a “-”, followed by an address
of the same family which is greater than or equal to the first one.
The range may be prefixed with “!”, in which case matching the
range will deny access instead of granting it.
Table 5-1 Option Formats
Nominum 35
36 Chapter 5: Server, View and Zone Options
Format Description
builtin-acl One of “any”, “none”, “localhost” or “localnets”. A matching pat-
tern grants access unless prefixed with “!”, in which case access is
denied. “any” grants access to all hosts. “none” denies access to
all hosts (equivalent to “!any”). “localhost” matches the address of
all interfaces of the host. “localnets” matches the networks of all
interfaces of the host.
aclpat One of an addrpat, a builtin-acl or a TSIG keyname (which may
be prefixed with “!”).
Table 5-1 Option Formats (continued)
Server Options
Following are the names and descriptions of the options at the server level, also called “global” options.
Option Description
checkpoint-interval interval For those database drivers that support it, ANS will start
a database checkpoint every interval seconds. The
default value is 86,400 (1 day). A value of 0 disables peri-
odic checkpointing.
Checkpointing speeds up server restart after a system
failure by limiting the number of transaction journal
entries which need to be replayed. Checkpointing is
interleaved with normal server operations, so the server
will continue to be available while checkpointing is in
progress.
Checkpointing can also be started manually with the

checkpoint command channel command.
command-channel string... A list of service names from /etc/channel.conf which
specifiy the address and port on which to listen for com-
mand channel messages, and the secret used to authen-
ticate command channel messages.
Table 5-2 ANS Server Options
Nominum
Server Options 37
Option Description
Alternately, a literal address, port, and secret may be
specified as <addr>#<port>#<secret>. (The secret
may be "*" to disable command channel authentica-
tion, but this is not recommended.)
Specifying the single command-channel "none" disables

the command channel.
commands-not-logged command Lists Command Channel message types that should not
be logged when command/executed logging is enabled.
For example, if a process frequently monitors statistics,

log clutter could be reduced by disabling logs for the
statistics command. Similarly, disabling logs for the
dbop command greatly reduces the number of log mes-
sages for systems that use external database utilities.
db name driver [arg...] Define a database of the given name. The driver
parameter is the name of the driver to use for this data-
base.
The remaining arguments, if any, are passed to the

driver’s database setup function. If no base argument is
explicitly specified, then the argument base=name will
be passed to the driver.
directory directory Use the specified directory as the working directory
of the server. This command takes effect immediately. At
most one directory statement may appear in a configura-
tion. The directory must be set before any
import-view statements. The default directory is
/var/nom/ans.
dns-port port Overrides the default DNS port (53) for all operations.
This option is intended for testing purposes—a DNS

server using a port other than 53 for DNS will not be able
to communicate with other DNS servers unless they are
also configured in the same way.
Table 5-2 ANS Server Options (continued)
Nominum
Option Description
driver name [filename] Registers a database driver with the server. If specified,
[filename] is the name of the shared object that
implements the driver. If not specified, the name and
location of the driver’s shared object are constructed
based on the specified name.
Registering a driver explicitly is required only if the

driver’s shared object is installed in a nonstandard loca-
tion.
import-view name Import the specified view. The server tries to load the
configuration from the file name.vc in the server’s
working directory. This statement must occur after the
directory statement, if a directory statement is
present.
View matching is done in the order in which views are

imported, with the exception that the default view is
always matched last.
listen-on addrport The IP address and (optionally) port on which to listen. If
a port is not specified, it defaults to the value of lis-
ten-on-port. More than one listen-on directive
may be specified. It is an error to try to listen on an
address that is not the address of one of the host’s inter-
face. Note: The listen-on and listen-on-match-
ing options cannot be used together.
listen-on-matching [port] The listen-on-matching statement specifies one or
pattern... more patterns to be used when selecting interfaces to lis-
ten on. It may be an addrpat or an interface name. For
example, eth0.
The first argument may also be a port, which will cause

that port to be used. Otherwise, or if the port is 0 (zero),
the port used is the listen-on-port value.
listen-on-matching may be specified multiple

times.
The listen-on-matching and listen-on options

cannot be used together.
Nominum
Server Options 39
Option Description
listen-on-port port The default port to listen on. The default port is used
when a listener address is specified via a lis-
ten-on-matching statement, or when it is specified by
a listen-on statement which does not specify a port.
The default value is 53 or the value of dns-port if one
is specified.
lock-filename Creates a file containing the server’s process ID (PID). The
server holds a write lock on this file while it is running.
The use of lockfiles is discouraged, but the capability is

provided for those who desire to use it. Nominum rec-
ommends using the much safer Command Channel
instead.
max-tcp-clients count Sets the maximum number of concurrent DNS TCP cli-
ents (for DNS queries, dynamic updates, and outbound
zone transfers). The default is 200.
max-udp-clients count Sets the maximum number of concurrent DNS UDP cli-
ents (for example, those used for DNS queries, dynamic
updates, and outbound zone transfers). The default is
1000.
setup-errors-fatal Normally, errors that occur while loading databases
when the server is started are not fatal; the server will log
an error and try to continue the startup process. How-
ever, if setup-errors-fatal is specified, any data-
base loading error that occurs during initialization will be
a fatal error and startup will fail.
syslog-facility facilityname Use the specified syslog facility instead of the default
facility, "daemon".
udp-buffer-size count Sets the desired socket receive buffer size for UDP sock-
ets.
The default is 200k bytes.

umask mask The umask to use when creating files. The default value
is 077.
Nominum
Option Description
versioncheck-interval interval ANS will periodically attempt to determine if there is a
newer version available than the running version. The
default value is 7 (days). The minimum value is 1 (day)
and the maximum value is 30 (days). If the version
checked is the same as the running version, the admin
will see nothing. If the version has been updated, a mes-
sage will be printed to standard output.
without-rmi without-rmi permits Remote Method Invocation (RMI)
to be disabled for all databases.
Database queries for some database types are normally

sent to a helper process. This mechanism is referred to as
RMI, is active by default, and allows the server to con-
tinue serving other requests while waiting for the data-
base to respond.
View Options
Nominum recommends using the Command Channel to modify view configurations, but you may also
edit the view configuration files directly when the server is not running. Note that comments in a view
Nominum
View Options 41
configuration file will be lost if the view is subsequently updated via the Command Channel. The View
options are listed here:
Option Description
cache-filename file The database stores data within RAM, in a more
compressed format than BIND or ANS stores data.
The cache stores a smaller subset of the data, in a
format that is not as compact, but is faster to
access and build responses than from RAM.
If cache-filename is specified, the server will try

to load the view’s cache from the specified file
when it starts, and will try to dump the view’s
cache to that file when it exits. If no file is speci-
fied, the server will use the name of the view fol-
lowed by “.cache.” To disable the persistent cache,
specify a filename of “none”.
cache-size size The database stores data within RAM, in a more
compressed format than BIND or ANS stores data.
The cache stores a smaller subset of the data, in a
format that is not as compact, but is faster to
access and build responses than from RAM.
Specify the maximum size (in bytes) of the author-

ity cache. A size of zero indicates no limit. If not
zero, the minimum value of this field is 1 megabyte.
The default size is 100 megabytes.
The value of this field is an integer optionally fol-

lowed by a scaling factor:
• K or k for kilobytes—1024.
• M or m for megabytes—1024*1024.
• G or g for gigabytes—1024*1024*1024.
gss-credentials principal Specify the Kerberos principal name for which the
server should try to acquire credentials, enabling
the server to authenticate GSS-TSIG signed
requests.
Table 5-3 ANS View Options
Nominum
Option Description
import database Import zones for this view from the specified
database. It it not necessary to import slave data-
bases defined with the slave-db option; they are
automatically imported. The database called mas-
ter is always imported, though it need not be
used.
key name [algorithm] secret Defines a shared secret. name must be a valid
DNS name, and secret is encoded in base64. The
shared secret is used when responding to
TSIG-signed queries.
If the algorithm is specified, it must be one of:
• hmac-md5
• hmac-sha1
• hmac-sha256
If the algorithm is not explicitly specified, it defaults

to hmac-md5.
keystore-filename file Defines the keystore used to find DNSSEC private
key data. The default is “keystore” in the ANS work-
ing directory.
log switch_name yes_or_no Set a logging control switch. ANS allows
fine-grained control over what is logged.
switch_name is the name of the switch, for exam-
ple, “update/refused”. yes_or_no is either yes
or no.
Table 5-3 ANS View Options (continued)
Nominum
View Options 43
Option Description
match pattern The match statement specifies the source informa-
tion used when determining which clients match
the current view. Each element may be one of the
following formats:
• addrpat
• range
• builtin-acl
• TSIG key name
Any of these elements may be prefixed with “!” to

indicate “not”.
The match option may be specified multiple times

per view.
match-to pattern The match-to statement specifies a destination
address pattern used to determine which clients
match the current view. pattern may be an
addrport or a builtin-acl. The match-to
option may be specified multiple times per view.
minimize-responses ANS normally generates responses like those of
BIND. These typically include many resource records
(RRs), which are not required but may be useful, in
the authority and additional data sections. If
minimize-responses is set, the server will gen-
erate only required RRs. This may increase perfor-
mance.
notify-rate rate Limit the maximum number of outbound notify
actions per second to rate. The default value is
100.
notify-source addrport Specify the default IPv4 zone notify source address
to use for this view. If not specified, the default
value is 0.0.0.0#0, which means “pick an appropri-
ate address and use a random port”.
notify-source-v6 addrport Specify the default IPv6 zone notify source address
to use for this view. If not specified, the default
value is ::#0, which means “pick an appropriate
address and use a random port”.
Nominum
Option Description
querylog-file file Specifies the name of a file (in the server’s cur-
rent working directory) to which queries are logged
when query logging is enabled (and configured
using the query/answered, query/refused,
and query/error log switches).
The file’s format consists of five fields:
• A timestamp in seconds since January 1, 1970

0:00 UTC, with a decimal part indicating milli-
seconds
• The client IP address and port, separated by a
hash (#) sign
• The view and zone, separated by a slash (/)
• The query name
• The query class
refresh interval Tell the server to check the view for changes (that
is, added or deleted zones) every interval sec-
onds. If not specified, the default value is 0, which
means that ANS will not explicitly check for
changes.
server-id string Set the identification (ID) string given out in DNS
queries for the server's ID. If a view configuration
does not contain a server-id, a Universal Unique
ID (UUID) will be generated, stored in the view con-
figuration, and used as the ID. If set to none, ANS
will refuse DNS queries for the server ID.
server-version string Set the version string given out in DNS queries for
the server’s version. If not specified, the default is
“Nominum ANS version” where version is the ver-
sion of the server software, for example, “2.8.2.0”.
If set to none, ANS refuses queries for its version.
slave-count-hint count Give the server a hint about how many slave zones
will be served, allowing it to pick appropriate sizes
for various internal data structures.
Nominum
View Options 45
Option Description
slave-db database Store all slave zones in the specified database. If not
specified, the default slave database name slave
will be used. If no db named slave is registered in
the configuration when all of the configuration has
been read, a default slave database will be created
automatically. Slave databases are automatically
imported into views.
soa-query-rate rate Limit the maximum number of zone maintenance
SOA queries per second to rate. The default value
is 100.
transfers-in count Allow a maximum of count simultaneous inbound
zone transfers. The default is 10.
transfer-source addrport Specify the default IPv4 zone transfer source
address to use for this view. If not specified, the
default value is 0.0.0.0#0, which means “pick an
appropriate address and use a random port”. The
IPv4 transfer source may be overridden on a
per-zone basis using the transfer-source zone
option.
transfer-source-v6 addrport Specify the default IPv6 zone transfer source
address to use for this view. If not specified, the
default value is ::#0, which means “choose an
appropriate address and use a random port”. The
IPv6 transfer source may be overridden on a
per-zone basis using the transfer-source-v6
zone option.
zone-count-hint count Give the server an educated guess on how many
zones will be served, allowing it to pick appropriate
sizes for various internal data structures.
zone-purge-age age The server retains data from prior versions of zones
so that it can respond to IXFR requests. When peri-
odic zone purging runs, prior version data older
than age seconds is deleted. The default value is
604,800 seconds (7 days). Purging can also be
done manually, using the purge-zone command
channel message.
Nominum
Option Description
zone-purge-interval interval Periodic zone purging will be performed no more
often than every interval seconds per zone. The
value 0 disables periodic zone purging. The default
value is 86,400 seconds (1 day).
zone-purge-max-versions max Instructs the server to retain no more than max
prior versions during an automatic zone purge. The
value 0 indicates that the number of prior versions
retained is unlimited.
The default value is 0.
To specify the maximum number of versions on a

per-zone basis, use the purge-max-versions
zone option.
NOTE: Purging is affected by both

zone-purge-age and zone-purge-max-ver-
sions: a prior zone is purged if it meets a criterion
for at least one of either zone-purge-age or
zone-purge-max-versions.
Zone Options
Following are names and descriptions of options that can be set at the zone level.
Nominum
Zone Options 47
Zone Option Element Description

allow-notify acl An Access Control List (ACL) that specifies which hosts are allowed
to send DNS notify messages to this server. If not specified, the
default is to only accept notifies from a known master of a zone.
allow-transfer acl allow-transfer specifies which hosts are allowed to transfer the
zone. If not specified, the default is to permit zone transfers from
any host.
allow-update acl The allow-update option is meaningful only for master zones. It
specifies which hosts are allowed to update the zone using the
DNS Dynamic Update protocol. If not specified, the default is to
deny updates from all hosts.
NOTE: The update-policy option (below) offers much more

fine-grained control over what updates will be granted or denied
and is the recommended way to specify update policy.
update-policy completely overrides allow-update if both
are specified.
WARNING!: Using IP addresses to authenticate dynamic

updates is not secure.
allow-update-forwarding acl The allow-update-forwarding option is meaningful only for
slave zones. It specifies which hosts’ Dynamic DNS updates will be
forwarded to a master of the zone. The default is none, which
means that no update forwarding will be performed. To enable
update forwarding generally, specify any.
NOTE: Specifying values other than none or any is usually coun-

terproductive because the responsibility for update access control
should rest with the master server, not the slaves.
WARNING!: Enabling the update-forwarding feature on a

slave server may make master servers that rely on unsecure
IP-address-based access control vulnerable to attacks.
Table 5-4 Zone options
Nominum

also-notify addrport The also-notify option specifies the addrports of nameserv-
ers to notify when a zone changes, in addition to those specified
in the zone's NS set. The default value is the empty list.
The value of each element in the list may be an addrport, or it

may be a two-element list. If a list, the first element is an
addrport, and the second is a TSIG key name. If a TSIG key name
is specified, it will be used when communicating with the nam-
eserver.
conf-template name The conf-template option specifies the name of the zone con-
figuration template to use for the zone.
When a zone has a configuration template, ANS looks for zone

options first in the zone’s configuration, and then in its template.
data-template name The data-template option specifies the name of the zone data
template to use for the zone.
When a zone has a data template, the contents of the zone itself
and its data template are merged when responding to DNS queries
and zone-transfer requests.
empty-nonterminals A boolean. When a zone has a name with multiple labels (for
example, the "a.b.example" name in the "example" zone), but
the parent name(s) have no records, then the parent name(s) are
considered to be empty nonterminals. In the above example,
"b.example" is an empty nonterminal if there are no records asso-
ciated with it.
Versions of ANS prior to 2.8.2.0 would return an NXDOMAIN

(name does not exist) response to a query for an empty nontermi-
nal. Newer standards require that empty nonterminals be treated
as names which do exist, which means that a NOERROR/NODATA
response (meaning the name exists, but there are no records of
the queried type) should be returned instead of an NXDOMAIN
response.
When the empty-nonterminals option is set to yes (the

default value), the new behavior will be used. When set to no,
the older behavior will be used.
Table 5-4 Zone options (continued)
Nominum
Zone Options 49

invisible-cnames A boolean. When set to True, when generating a response that
would normally include a CNAME, the CNAME record will be omit-
ted, and answer records will be synthesized that have the domain
name from the query and rdata from the CNAME's target name.
If the target of the CNAME is a name within the zone that does
not exist, or a name which exists but has no records of the query
type, an NXDOMAIN or NOERROR/NODATA with an empty answer
section will be returned. This response is identical to what would
be returned if the query was for the target of the CNAME.
If the target of the CNAME is a name outside of the zone, no syn-
thesis is done; the CNAME will be returned as if the invisi-
ble-cnames option was not specified.
If answers are synthesized from one or more CNAMEs and other

records, the TTL of the returned answers will be the minimum of
the TTL of any of the records involved in the synthesis.
With invisible-cnames set to True, the following response:
foo.example. CNAME bar.example.
bar.example. A 1.2.3.4
bar.example. A 2.3.4.5
would instead become:
foo.example. A 1.2.3.4
foo.example. A 2.3.4.5
NOTE: If DNS servers without this extension attempt to serve the

data, the synthesis won't be performed.
NOTE: The invisible-cnames zone option is incompatible

with DNSSEC.
The default is False.
Nominum

log-flags switch_name... The log-flags option overrides the view's logging policy. Only
the log switches specified in the list will be logged.
The following flags are not valid in this option:
• zone/added
• zone/deleted
• zone/loaded
• zone/modified
masters master... The masters option specifies the list of master servers for a slave
zone. Note that, unlike BIND configurations, there is no need to
explicitly declare a zone to be a slave zone. The presence or
absence of a masters option determines the type of zone.
The value of each master in the list may be an addrport, or it

may be a two element list. If a list, the first element is an
addrport, and the second is a TSIG key name. If a TSIG key name
is specified, it will be used when communicating with the master.
notify mode The notify option specifies the DNS NOTIFY policy for the zone.
mode may be yes, no, or explicit.
• yes—Any time the zone changes, DNS NOTIFY messages are

sent to the nameservers of the zone (other than the server
itself and the nameserver in the SOA MNAME field). In addi-
tion, DNS NOTIFY messages are sent to any hosts specified
with the also-notify option.
• no—No notifications are made for the zone.
• explicit—Notifications are sent only to hosts specified with
the also-notify option.
The default value is yes.
Nominum
Zone Options 51

notify-hold interval The minimum amount of time, in seconds, to wait between
NOTIFY messages for a zone. The default value is 2 seconds.
To reduce network traffic and not burden slaves, ANS will wait for
the hold interval before sending another NOTIFY message for the
zone. Once the hold interval has expired, ANS will send the next
Notify without delay.
For example, assume a zone has had no transactions for a few

hours, and then a burst of 100 DNS dynamic update transactions
occurs over a period of 3 seconds. ANS will send out a total of 3
NOTIFY messages to all interested parties. The first one goes out
immediately, since the zone had been idle for more than the hold
interval. The second goes out at +2 seconds, and the third at +4
seconds.
notify-source v4_addrport The notify-source option determines which local address will
be used when sending IPv4 NOTIFY messages for the zone.
If not specified, the default value is 0.0.0.0#0, which means

“choose an appropriate address and use the next available port
over 1023”.
notify-source-v6 v6_addrport The notify-source-v6 option determines which local address
will be used when sending IPv6 NOTIFY messages for the zone.
If not specified, the default value is ::#0, which means “choose

an appropriate address and use the next available port over 1023”.
purge-age age The server retains data from prior versions of zones so that it can
respond to IXFR requests. When periodic zone purging runs, prior
version data older than age seconds is deleted. The default value
is the value of the view's zone-purge-max-age option.
purge-interval interval Periodic zone purging will be done no more often than every
interval seconds per zone. The value 0 disables periodic zone
purging. The default value is the value of the view's
zone-purge-interval option.
Nominum

purge-max-versions max Instructs the server to retain no more than max prior versions dur-
ing a periodic zone purge. The value 0 indicates that the number
of prior versions retained is unlimited.
The default value is the value of the view's

zone-purge-max-versions option.
NOTE: Purging is affected by both purge-age and

purge-max-versions: a prior zone is purged if it meets a crite-
rion for at least one of either purge-age or purge-max-ver-
sions.
rrset-order value The rrset-order option controls how RRs are ordered when an
RRset is added to a response. The possible values are cyclic and
fixed and random. In cyclic ordering, a random starting
point in the list of RRs is chosen, and the RRs are then emitted,
wrapping around to the beginning of the list when the end is
reached. In fixed ordering, RRs are emitted in the order they are
stored in. In random ordering, a random permutation of the RRs is
chosen. The default is cyclic.
slave-db db-name This option is only meaningful for slave zones. It specifies which
database is used to store the zone. The value of the slave-db is
the name of an ANS database, as specified in a db statement in
the ans.conf file. If not specified, a slave zone will be stored in the
database specified by the view's slave-db option, or if that
option is not present, the slave database.
NOTE: When changing the database of an already-transferred

slave, you should delete the zone from the old database.
source-view name Specifies the name of a view containing zone data for a zone with
the same name, and defines this zone as an alias to the zone in the
source view.
statistics boolean Sets view or zone statistics. Setting this value to “true” enables
zone statistics collection, and setting this value to “false” disables
zone statistics collection.
Nominum
Zone Options 53

transfer-source v4_addrport The transfer-source option specifies the source address to use
when making inbound zone transfers for this zone using IPv4. If
not specified the view's transfer-source setting is used.
The address is also used for SOA refresh queries and forwarded
dynamic updates.
transfer-source-v6 The transfer-source-v6 option specifies the source address to
v6_addrport use when making inbound zone transfers for this zone using IPv6.
If not specified, the view's transfer-source-v6 setting is used.
The address is also used for SOA refresh queries and forwarded
dynamic updates.
update-policy rule The update-policy option specifies a fine-grained set of rules
for granting and denying DNS dynamic updates.
More About update-policy

The update-policy zone option specifies a fine-grained set of rules for granting and denying DNS
dynamic (DDNS) updates.
Each rule is a list of 5 items:
1. access-type—The access-type specifies whether the rule grants or denies access. The
possible values for this field are grant and deny.
2. identity——identity specifies a TSIG keyname pattern. The value may be an ordinary

domain name, or a wildcard name.
3. name-type—The name-type determines the kind of pattern matching which will be used.
The possible values are name, subdomain, wildcard, self, and self-subdomain.
• name matches when the owner name of an update is equal to the name field.
• subdomain matches when the owner name of an update is subdomain of the name field.
(Note that a name is a subdomain of itself.)
• wildcard matches when the owner name of an update matches the DNS wildcard name
in the name field.
Nominum
• self matches when the owner name of an update is equal to the identity field.
• self-subdomain matches when the owner name of an update is a subdomain of the

identity field.
4. name—The name field specifies the owner name of the zone data to which the rule applies.
5. types—The types field is a possibly-empty list of DNS RR types. ANY may be used to match all
types. The empty list means “use the default list”. The default is “all types except SOA, NS,
RRSIG, and NSEC”.
Each individual update action within a DNS dynamic update message is checked against the update-pol-
icy rules. The rules are checked in order, and the first matching rule determines access. A rule matches if
the identity of the update matches the identity field, the owner name of the individual update
matches the name field, and the RR type is contained in the types list.
For example:
((grant john.doe.key. subdomain john.doe.example. (A MX))

(grant jane.doe.key. subdomain lab.example. (ANY)))
Nominum
Zone Options 55
Nominum
Nominum
Zone Options 57
Nominum
Nominum
Zone Options 59
Nominum
Nominum
Zone Options 61
Nominum
Nominum
Zone Options 63
Nominum
Nominum
Zone Options 65
Nominum
Nominum
6
Using the Command
Channel with ANS
ANS accepts control commands using the Nominum Command Channel protocol, which specifies mes-
sage formats for communicating with Nominum software and defines how such messages are sent. This
chapter briefly describes the nom_tell program and describes the Command Channel commands specific
to ANS.
The commands in this chapter are the most useful for listing and deleting views and zones. Unless you are
working with the databases offline, these are the recommended commands to use for these functions.
To use this functionality, ANS must be configured to listen for Command Channel connections on a TCP
port. When ANS is installed, it is automatically configured to listen for Command Channel connections on
the loopback address (127.0.0.1) with the addition of an ans line to /etc/channel.conf. You can config-
ure Command Channels manually by editing /etc/channel.conf or by adding a command-channel state-
ment to ans.conf.
Nominum ANS ships with a utility program called nom_tell, an implementation of the Nominum Com-
mand Channel protocol. nom_tell can be used to communicate with a Nominum server while it is run-
ning.
In sending commands via nom_tell, responses for requests which failed contain an err tag indicating the
error; the absence of an err tag indicates success.
Requests which cause the server to restart itself after completion will contain a restart tag with a value
of 1.
Nominum 67
68 Chapter 6: Using the Command Channel with ANS
nom_tell
The nom_tell program is an implementation of the Nominum Command Channel specification that per-
mits control and monitoring of Nominum products from the command-line, or a Unix shell.
The basic nom_tell command is of the form:
% nom_tell service what
service is identified in the service description file, usually , and can be thought of as “Which service
needs to know this command (and where should it be sent)?” In Figure 6-1, the service consists of every-
thing on the ans line.
The what element is the part of the command that can be thought of as “What is the service being
told to do?” What nom_tell tells a service to do depends upon the type of server. The ANS-specific Com-
mand Channel commands are unique to each service and are discussed elsewhere in this document.
However, two commands that are understood by every Nominum server are stop and version.
For example:
ans> stop
ans> version
Service Description File

The file /etc/channel.conf identifies by name those services that use the Nominum command channel. In
order for nom_tell to communicate with a service, the service name must be mapped to a location
(host and port), and the proper shared secret must be listed and retrieved. This information is contained in
the file /etc/channel.conf. Each Nominum server has a generally used service name, default addrport
and optional secret that are used in this file.
ans 9253 R4Gtpp9m2qSw353xR4XNABHL
Figure 6-1 Example channel.conf entries
As shown in Figure 6-1, the format of a channel.conf file is a sequence of lines. Blank lines and lines start-
ing with "#" are ignored. A configuration line contains a service name followed by a addrport fol-
lowed by a secret. The items are separated by whitespace.
The service name is used to identify the service. Each server has a default service name, and can also be
configured to use alternative service names.
Nominum
nom_tell 69
The addrport has the form [<address>[%<scope>]#]<port>. For example, 9253 and
10.0.0.1#1111 are both valid addrports. If no address is specified, the loopback address (127.0.0.1) is
used. An address of 0.0.0.0 indicates that a server should listen on all interfaces, and that a client should
use the loopback address to communicate with that server.
The addrport flexibility means that If there is no entry for ans in the channel.conf file, a nom_tell com-
mand service element may take the form of an IP address and port number instead, as shown in the
following command for a Nominum ANS server.
# /usr/local/nom/sbin/nom_tell 127.0.0.1#53 stop
The secret must be quoted (with double quotes) if it contains whitespace. A quote or backslash in the
secret must be quoted by prefixing it with a backslash. Specifying a secret of "*" (without the quotes)
means "no secret".
The NOM_CHANNEL_CONF environment variable may be used to tell Nominum applications an addi-
tional location to look for service entries (e.g., NOM_CHANNEL_CONF=/example/path/channel.conf).
When looking up service entries, Nominum applications, such as nom_tell, may check a number of
locations. In order, the following paths are checked:
• a path from the NOM_CHANNEL_CONF variable
• ~/.nom/channel.conf
• /etc/channel.conf
The first one to be found which is readable is used.
Example
This example uses nom_tell to determine the version of Nominum ANS. It assumes the service ans has
been defined in /etc/channel.conf:
ans> version
{
type => 'version'
vendor => 'Nominum'
product => 'ANS'
platform => 'platform'
version => 'version'
}
Nominum
nom_tell Command Synopsis

nom_tell [ -e|--encrypt ][ -F | --fields ] [ -i | --interactive ]
[ -h | --help ] [ -q | --quiet ] [ -o | --one-line ]
[ -s | --secret secret ] [ --usage ] [ -v | --verbose ] [ --version ]
[ -w | --timeout timeout ] [ -x|--wait-for-exit ] who [ what ]
[ arg ... ]
Table 6-1 describes the options for the nom_tell command. Note that most options have two forms, a
short form preceded by a hyphen, and a longer form preceded by two hyphens.
Option Description
-e |--encrypt Require that command channel messages be encrypted. If the
service does not support encryption, an error will be returned.
If not specified, encryption will be requested for non-loopback

connections, but if the service does not support encryption, the
connection will proceed without encryption.
-F list | --fields list Cannot be used in interactive mode.
Specifies the fields to print.
list is a comma-separated list of field names. Instead of print-

ing out the entire response, only the specified fields will be
printed.
If only one field is specified, the output is the value of the field. If
more than one field is specified, then each field will be printed
on a separate line, and each line will consist of the field name fol-
lowed by ":" and the value of the field.
A field name which contains no periods is the name of a
top-level field in the response. A name which contain periods is a
path to a field contained in a sub-table in the response. All of the
components in the path other than the last must be tables.
This option cannot be used in interactive mode.
Verbosity options are ignored when this option is specified.
Table 6-1 nom_tell command-line options
Nominum
nom_tell 71
Option Description
-i | --interactive Instructs nom_tell to enter interactive mode after executing the
command specified by its command line arguments, if any.
In interactive mode, nom_tell prompts for a command, sends it,

and prints the response. Interactive mode continues until exited
by entering quit, exit, or the EOF character.
The form of an interactive command is :

what [tag=value ...].
The recipient of all interactive commands is the who value speci-
fied when nom_tell was invoked. Lines where the first
non-whitespace character is “;” or “#” are comments.
NOTE: In interactive mode, quotes are not needed around com-

plex data values. Therefore, if using examples from this manual,
delete quotes if the example is not in interactive mode but inter-
active mode is being used. Keeping the quotes could bring unde-
sired results.
-h | --help Displays a help message and exits.
-q | --quiet Specifies “quiet” mode—nom_tell will not generate output
unless a networking or operating system error occurs.
Command channel responses which have an error tag are not

networking or OS errors, and thus do not generate output in
quiet mode.
-o | --one-line Specifies “one line” mode, in which nom_tell emits tables on a
single line.
-s secret | --secret secret Specifies the secret to be used when signing a request or
authenticating a response.
NOTE: Specifying the secret on the command line is a poor

security choice—stronger security is provided by setting the
appropriate file permissions either on /etc/channel.conf or using
a private $HOME/.nom/channel.conf file and storing this infor-
mation there.
--usage Prints a usage message and exits.
Table 6-1 nom_tell command-line options (continued)
Nominum
Option Description
-v | --verbose Increases verbosity.
To print the complete request or response message, make ver-

bosity greater than zero. If verbosity is zero (the default),
nom_tell prints only the _data section of request or response
messages.
--version Displays the version of nom_tell and exit.
-w timeout | --timeout time- Specifies the maximum amount of time, in seconds, to wait for a
out request to complete. If the operation does not finish in the desig-
nated time, the program will exit with an error message and a
non-zero status.
If not specified, there is no timeout.

-x | --wait-for-exit Instructs nom_tell to wait for the service’s process to exit prior to
exiting.
This option should be used only with commands that cause a

given service to stop (for example, stop).
If the given service does not appear to be running locally, a warn-

ing is issued and the option ignored.
Table 6-1 nom_tell command-line options (continued)
Interactive Mode
With few exceptions, examples in this manual are given in nom_tell’s interactive mode. The prompt indi-
cates the mode. If the prompt is
ans>
nom_tell is in interactive mode. To exit interactive mode, type
ans> exit
Environment Variable
nom_tell has one environment variable: NOM_TELL_HISTFILE. This variable takes the name of the history
file used to remember commands between invocations of nom_tell. If unset, nom_tell will not keep a his-
tory. This feature is not available on Windows platforms.
Nominum
73
ANS-Specific Command Channel Commands

In Command Channel commands, items enclosed in square brackets (“[ ]”) are optional or have a default.
Items enclosed in parentheses (“( )”) denote a list.
NOTE Many Unix shells treat some characters specially—when necessary, quote those charac-
ters. For instance, if you are using the C shell, be sure to escape “!” in ACLs with a “\” to
prevent the C shell from doing history substitution.
Table 6-2 lists the commands that can be used as the what direction of a nom_tell command for ANS.
Some of the commands take required or optional arguments, which are not shown in the table.
Command Description
add-view Add a new view to the server’s configuration. See ”add-view” on
page 75.
add-zone Add a new zone configuration. See ”add-zone” on page 75.
checkpoint Start a database checkpoint for all databases which support it. If a
checkpoint is already running, it is canceled first. See ”checkpoint” on
page 76.
delete-view Delete a view from the server’s configuration. See ”delete-view” on
page 76.
delete-zone Delete a zone. See ”delete-zone” on page 77.
flush Flush the cache. See ”flush” on page 77.
force-maintenance Force zone maintenance for the specified zone. See ”force-mainte-
nance” on page 78.
force-notify Force DNS NOTIFY messages to be sent to the notification recipients
configured for a zone. See ”force-notify” on page 78.
force-transfer Force a zone transfer of the specified zone. See ”force-transfer” on
page 78.
list-events Returns a list of all event types supported by ANS. See ”list-events” on
page 78.
Table 6-2 ANS Command Channel messages
Nominum
Command Description
list-drivers Returns a list of all database drivers supported by ANS. See ”list-driv-
ers” on page 89.
purge-zone Cleanup old versions of a zone. See ”purge-zone” on page 79.
reopen-log-files Close and reopen any open log files. See ”reopen-log-files” on page
80.
request-events Registers events to be sent over the Command Channel connection.
See ”request-events” on page 80.
restart Restarts the server. See ”restart” on page 80.
show-data Shows the contents of a zone. See ”show-data” on page 81.
show-events Returns a list of all events currently registered for the Command
Channel connection. See ”show-events” on page 80.
show-maintenance Display the zone maintenance status of a slave zone. See
”show-maintenance” on page 82.
show-server Display the server’s global configuration. See ”show-server” on page
84.
show-view Display the current configuration of a view. See ”show-view” on page
85.
show-zone Display the current configuration of a zone. See ”show-zone” on
page 87.
statistics Get view or zone statistics. See ”statistics” on page 90.
stop Stop the server. See ”stop” on page 94.
update-data Update the content of a zone. See ”update-data” on page 94.
update-server Update the server’s global configuration. See ”update-server” on
page 96.
update-view Update a view’s configuration. See ”update-view” on page 96.
update-zone Update a zone’s configuration. See ”update-zone” on page 99.
version Return version information about the server. See ”version” on page
100.
Table 6-2 ANS Command Channel messages (continued)
A request that fails will contain an err tag indicating the error; the absence of an err tag indicates suc-
cess.
Nominum
add-view 75
add-view
Adds a new view to the server’s configuration. View options may be any option from Table 5-3, “ANS
View Options” on page 41.
Example
The specified options in the view are set to the values given. If the command is successful, the changes
are persistent, even across server restarts, and a corresponding import-view is added to the global con-
figuration.
ans> add-view view=example

{
type => 'add-view'
}
Figure 6-2 add-view Example
add-zone
Add a new zone configuration.
Example
ans> add-zone zone=internal.com view=internal notify=no
The values of several of the zone options are Access Control Lists (ACLs). An ACL is a list of aclpat val-
ues. The first matching pattern determines whether access is granted or denied. The behavior if no pat-
tern matches is specific to each zone option and is documented with the zone option.
An aclpat is either an addrpat or a TSIG keyname. A matching pattern grants access unless prefixed
with “!”, in which case access is denied.
An addrpat is an IPv4 or IPv6 address, optionally followed by a ”/” and a mask length. The address may
be prefixed with “!”, in which case the pattern will exclude matching interfaces. The pattern may also be
the name of an interface, such as eth0.
The values any, none, localhost and localnets may also be used. any grants access to all hosts.
none denies access to all hosts (none is equivalent to !any). localhost matches the address of all
interfaces of the host. localnets matches the networks of all interfaces of the host.
Nominum
Derived Zone Elements

In addition to the zone options listed in Table on page 46, there are zone elements that can be seen
when displaying a zone via the Command Channel. These elements are derived from other zone informa-
tion and, as such, cannot be set by the user. However, they are useful in providing information about
types of zone. More information about zone types can be found in Chapter 3, "Zones and Templates".
block-checkpoints
Ensures that a database checkpoint does not occur for a period of time, so that databases can be safely
backed up. The optional timeout parameter specifies the maximum amount of time (in seconds) that
checkpoint completion is to be blocked. If no timeout is specified, a reasonable default of 1 hour is used.
See ”unblock-checkpoints” on page 94 and ”checkpoint” on page 76 for more information.
Parameters
[timeout=time]
checkpoint
Starts a database checkpoint for all databases which support it. If a checkpoint is already running, it is
canceled first. See ”unblock-checkpoints” on page 94 and ”block-checkpoints” on page 76 for more
information.
delete-view
Deletes a view from the server’s configuration.
Example
If the view is not the default view, the view and all of its associated states are deleted, and the
import-view statement for the view is removed from the server’s global configuration.
ANS requires that a default view exist at all times. If the view being deleted is the default view, all state
associated with the view is deleted, and the view’s configuration is reset to the default. No view-related
events are sent.
Nominum
delete-zone 77
ans> delete-view view=example

{
type => 'delete-view'
}
Figure 6-3 Deleting a view from the server with nom_tell
delete-zone
Deletes a zone. All information about the specified zone is deleted. This includes both the zone’s configu-
ration and the actual contents of the zone. If not specified, the view defaults to default.
ans> delete-zone zone=zonename [view=viewname]
Example
ans> delete-zone zone=internal.com view=internal
The command yields the following message from the server logged as:
ANS: info: default/internal.com (master): deleted
If you use the ans_listzones command, you would see that this zone is not in the master database.
flush
This command flushes the local cache of data that has been fetched from an ANS database. Flushing the
cache is almost never needed or useful because the cache coherency with the backing database is auto-
matically maintained by the server. This command may be useful for debugging in some circumstances.
Example
ans> flush view=default
If a zone is specified, then only that zone is removed, otherwise all zones are removed. If not specified,
the view defaults to default.
ans> flush view=default

{
type => 'flush'
}
Figure 6-4 Flushing the cache
Nominum
force-maintenance
Force zone maintenance for the specified zone.
The zone maintenance process is started for the specified zone if it is not already running. The zone main-
tenance process causes an SOA query to be sent to the zone’s master(s), and if the zone is out of date, a
zone transfer will then be initiated. This command differs from force-transfer by doing the transfer only
when the zone is determined to be out of date. If not specified, the view defaults to default.
Example
ans> force-maintenance zone=internal.com view=internal
force-notify
This command forces DNS NOTIFY messages to be sent to the notification recipients configured for a
zone.
Example
ans> force-notify zone=internal.com view=internal
force-transfer
This command forces a zone transfer of the specified zone.
The zone transfer process is started for the specified zone if that process is not already running. This com-
mand differs from force-maintenance by doing the transfer unconditionally; that is, no up-to-date check
is made.
Example
ans> force-transfer zone=internal.com view=internal
list-events
Returns a list of all event types supported by a particular view in an ANS server. All views support a fixed
set of events, and the default view supports additional events not supported by other views.
Nominum
pid 79
Example
ans> list-events view=default
pid
Retrieve the server's process identifier.
process-information
Return the following information of the server:
• Start time, formatted as “seconds”.”milliseconds”
• Current time since the epoch, formatted as “seconds”.”milliseconds”
• Process identifier of the server process
• Arguments
• Current working directory
purge-zone
Cleans up old versions of a zone. ANS stores old versions of zones so that it may respond to IXFR (incre-
mental transfer) requests. This data is automatically purged on a periodic basis, but administrators desir-
ing greater control may use the purge-zone command.
The command takes an age parameter. Data older than age seconds will be eligible for purging. Note
that data that is eligible for purging will not be purged if it is use by an active outbound IXFR or AXFR. If
not specified, the view defaults to default. If not specified, the age defaults to 7 days.
ans> purge-zone zone=zonename [view=viewname] [age=seconds]
Example
ans> purge-zone zone=internal.com view=internal age=86400
Nominum
reopen-log-files
Close and reopen any open log files. This is intended for use by external log rotation programs. Currently,
there is only one log file: the query log file.
If not specified, the view defaults to default. This command must be executed separately for each view.
Example
ans> reopen-log-files [view=viewname]
restart
Restart the server.
ANS can only restart itself if it still has the privileges to do so. If it cannot restart itself, it will log a notice to
the syslog that a manual restart is required.
ans> restart
request-events
Registers events (asynchronous notifications) to be sent over this Command Channel connection.
Events are tied to connections; when this connection closes, all events will be implicitly deregistered.
A list of events may be specified, and the special values all or none can be used to indicate that all
events or no events are desired, respectively.
If not specified, the view defaults to default.
A list of zones may be specified, which can be used to indicate that matching events should only be sent
for zones matching those listed.
ans> request-events view=foo events=all
show-events
Returns the list of all events currently registered for this Command Channel connection.
The events tag contains the list of events as specified when requested; that is, it might contain the val-
ues all or none. The listening-for tag contains an explicit list of all events.
Nominum
show-data 81
request:
[ view => view ]
response:
events => events
listening-for => events
show-data
Shows the contents of a zone.
The contents of the requested node (or each node) is returned as a list of records, where each element is
a string containing the record’s name, ttl, class, type, and rdata, respectively.
By default, all names (owner names and names within rdata) in the data field of the response will be rel-
ativized with respect to the zone origin. If the absolute tag is present and has a True value, all names
will be absolute names instead.
By default, comments associated with Resource Records will be returned in the response, formatted in the
standard DNS master file format (each record will be followed by a semicolon and the comment). If the
no-comments tag is present and has a True value, comments will be omitted.
By default, if the zone is an instance, only data from the customized portion of the zone will be returned
in a show-data response. If the merge tag is present and has a True value, data from the constructed
zone will be returned.
If a node is not specified, information about all nodes is returned.
If a zone is not specified, the most specific zone containing the name of the node will be used.
Specifying neither a node nor a zone is an error.
Example
ans> show-data node=internal.com
{
type => 'show-data'
zone => 'internal.com.'
data => list of records
}
An example from the command line:
Nominum
# nom_tell ans show-data zone=example node=b merge=True
show-maintenance
Information about the current zone-maintenance state can be retrieved with the show-maintenance
command.
If no view is specified, the default view is used. If no zone is specified, status for all slave zones is
returned. Specifying a tag named “status” whose value is either a single status, or a list of statuses,
restricts the output to zones whose status matches the specified status(es). Figure 6-6, “show-mainte-
nance Command with Status Tag,” on page 84 shows an example using the “status” tag. The valid status
values are:
Maintenance Status Description

up-to-date The zone is up to date.
never-transferred Zone maintenance for this zone has never successfully
been done.
expired The slave server has gone longer than the SOA zone
expiration interval without successfully performing zone
maintenance (i.e., verifying that the zone is up-to-date,
or doing a transfer). The server will no longer answer
authoritatively for the zone until maintenance succeeds.
needs-maintenance The refresh timeout for this zone has expired, and the
server is waiting for the result of an SOA query to see
what to do next. This waiting encompasses both wait-
ing to do an SOA query as well as waiting for a
response to a query we've sent.
needs-transfer A transfer needs to be done for the zone, i.e., it is
known to be out-of-date. The server is waiting for its
turn to do the transfer.
Table 6-3 Zone Maintenance Status
Both “show-zone” and “show-maintenance”, use two state fields to explain in detail the current mainte-
nance state of the zone. These are:
• current-task
• next-task
current-task is always present, and is the current maintenance activity of the slave zone.
Nominum
show-maintenance 83
next-task is present when current-task is sleeping or soa-receive-wait, and reflects the task
that will execute when—or if, in the case of soa-receive-wait—a timeout occurs.
The tasks are:
Task Description
sleeping Waiting until the time specified in the sleeping-until field. When
that time arrives, next-task becomes the current-task.
soa-send-wait Waiting for its turn to send an SOA query to a master.
soa-receive-wait Waiting for the master to respond (or for a timeout if it doesn’t
respond).
transfer-start-wait Waiting for its turn to attempt a zone transfer.
transferring Zone transfer is in progress.
Table 6-4 Zone Maintenance Tasks
There are two additional states which are sometimes visible when using the Command Channel:
Task Description
destruction-wait Zone maintenance has been terminated for this slave by com-
mand of the user, but it has not yet been garbage collected.
schedule-wait The server is starting up and will start maintenance services for
this zone when it is ready to do so.
Table 6-5 Zone Maintenance Tasks Reflected Via The Command Channel
Nominum
ans> show-maintenance zone=example.com. view=default

{
type => 'show-maintenance'
status => 'never-transferred'
serial => '0'
refresh => '1800'
retry => '600'
expire => '0'
now => '1086313444'
last-maintenance => '0'
current-task => 'sleeping'
sleeping-until => '1086313552'
next-task => 'soa-send-wait'
}
Figure 6-5 Displaying a Zone’s Maintenance State With show-maintenance
Figure 6-11 illustrates another example of maintenance status output.
ans> show-maintenance status=never-transferred

{
type => 'show-maintenance'
zone => 'april.'
serial => '0'
refresh => '1800'
retry => '600'
expire => '0'
now => '1113513450'
}
Figure 6-6 show-maintenance Command with Status Tag
show-server
Displays the server’s global configuration. By default, only explicitly configured values are returned. If the
all tag is present and has a True value, the full configuration is returned.
If the server is running in safe mode, the safe-mode option will be present in the response and set to
yes.
Nominum
show-view 85
Response returns:
[global_option=global_option_value]
ans> show-server
{
type => 'show-server'
checkpoint-interval => '86400'
directory => '/var/nom/ans'
foreground => 'no'
foreground-with-syslog => 'no'
listen-on-matching => (('0' '127.0.0.1/32' '192.168.1.207/32'))
listen-on-port => '53'
max-tcp-clients => '200'
setup-errors-fatal => 'no'
syslog-facility => 'local4'
umask => '077'
versioncheck-interval => '7'
without-rmi => 'no'
}
Figure 6-7 Displaying the Server’s Global Configuration With show-server
show-view
Display the current configuration of a view. By default, only explicitly configured values are returned. If
the all tag is present and has a True value, the full configuration is returned.
If an update-view was recently done, and the update has not completed, the reload-pending option
will be present and have the value 1.
Nominum
To see what results, first examine the following sample contents of a default.vc file, the data file for the
default view:
import master
import slave
cache-filename "default.cache"
zone-conf-filename "default.zc"
server-id "1304882d-551b-4e39-9ce9-53b3cc425c0f"
slave-db slave
soa-query-rate 80
transfers-in 10
transfer-source 0.0.0.0#0
transfer-source-v6 ::#0
notify-source 0.0.0.0#0
notify-source-v6 ::#0
zone-purge-interval 86400
zone-purge-age 604800
log notify-in/received yes
log notify-in/refused yes
log notify-out/acknowledged yes
log notify-out/sent yes
log query/answered yes
log query/error yes
log update/granted yes
log update/denied yes
log xfr-out/granted yes
log xfr-out/denied yes
log zone/added yes
log zone/deleted yes
log zone/loaded yes
log zone-maintenance/success yes
log zone-maintenance/failure yes
log zone-maintenance/up-to-date yes
log zone-maintenance/xfr-details yes
Figure 6-8 Sample default.vc File
Now type the command show-view in nom-tell interactive mode to request to see the data in the
default view.
Nominum
show-zone 87
The following output for the sample default.vc file shown above, is displayed:
ans> show-view view=default

{
type => 'show-view'
view => 'default'
import => ('master' 'slave')
cache-filename => 'default.cache'
zone-conf-filename => 'default.zc'
server-id => '304882d-551b-4e39-9ce9-53b3cc425c0f'
transfers-in => '10'
slave-db => 'slave'
soa-query-rate => '80'
transfer-source => '0.0.0.0#0'
transfer-source-v6 => '::#0'
notify-source => '0.0.0.0#0'
notify-source-v6 => '::#0'
zone-purge-interval => '86400'
zone-purge-age => '604800'
log => (('notify-in/received' 'yes') ('notify-in/refused' 'yes') \
('notify-out/acknowledged' 'yes') ('notify-out/sent'\
'yes') \
('query/answered' 'yes') ('query/error' 'yes') \
('update/granted' 'yes') ('update/denied' 'yes') \
('xfr-out/granted' 'yes') ('xfr-out/denied' 'yes') \
('zone/added' 'yes') ('zone/deleted' 'yes') \
('zone/loaded' 'yes') ('zone-maintenance/success' 'yes') \
('zone-maintenance/failure' 'yes') \
('zone-maintenance/up-to-date' 'yes') \
('zone-maintenance/xfr-details' 'yes'))
}
Figure 6-9 Output of nom_tell show-view Command for Default View
show-zone
Displays the current configuration of a zone.
If a zone-type is specified, zones not matching that type will be ignored.
If a zone is not specified, information about all zones (that match the zone-type) is returned.
Note that the response to this command can contain the additional parameter:
[derived_zone_element = derived_zone_element value]
Nominum
The derived zone elements are not settable by users but provide information about zone types.
NOTE show-zone results also return any zone options set on the zone. See Table 5-4 on page
47, ”Zone options”, for a list of possible zone option elements.
By default, if the zone uses a configuration template, only the configuration of the zone itself, not config-
uration from the template, will be returned. If the merge tag is present and has a True value, configura-
tion from the template will also be included.
Example
This command, which does not specify a specific zone, could display output such as the following:
ans> show-zone
{
type => 'show-zone'
zone => 'a-example.com.'
}
{
type => 'next'
zone => 'movie.edu.'
}
{
type => 'next'
zone => 'b-example.org.'
}
{
type => 'next'
}
Figure 6-10 show-zone Results for Default Zone
Nominum
list-drivers 89
A command that specifies a zone, such as the following, could return output as shown:
ans> show-zone zone=example.org

{
type => 'show-zone'
zone => 'example.org.'
zone-type => 'slave'
masters => ('10.2.0.129#53' '10.2.0.130#53')
maintenance => {
serial => '0'
refresh => '1800'
retry => '600'
expire => '0'
now => '1091733999'
}
}
Figure 6-11 show-zone Results for a Specific Zone
Using delete with update-zone or update-view

Both update-zone and update-view take a delete argument, which may contain a list of options to
delete.
For example, to delete the allow-update option from the zone a-example.com:
ans> update-zone zone=a-example.com delete=(allow-update)
list-drivers
Returns a list of all database drivers supported by ANS.
Example
ans> list-drivers
Nominum
statistics
Instructs ANS to get server, view or zone statistics.
Statistics values are 64-bit integers, reset to zero either on command or whenever the server is loaded.
Statistics are also kept on the query type (for example, the number of MX queries), and only statistics with
values greater than zero are returned, unless the all tag is set to true.
All statistics queries return the time the statistics were last reset (reset-time) and the current time
(current-time) in seconds since the epoch (00:00 UTC, January 1, 1970). Current time may also be
returned in a high-resolution format (current-time-hires) as seconds and microseconds since the
epoch.
The time the statistics were last reset, and the current time are returned in all statistics queries. Both times
are in seconds since the epoch (00:00 UTC, January 1, 1970). The current time is also returned in a
high-resolution format as seconds and microseconds since the epoch.
The amount of CPU time consumed by the ANS process, as reported by the getrusage system call, is
returned in all statistics queries. User CPU time is returned in user-time, and system CPU time in sys-
tem-time.
Specifying a tag named “reset” with any value will cause the counters to be zeroed.
Statistics Scope
Unless otherwise specified, statistics values are for the specified (or default) view as a whole.
• If server is set to true, statistics are returned for the server as a whole.
• If a zone is specified in the command, statistics are returned only for that zone—note that sta-
tistics are only kept at the zone level if the zone has the statistics zone attribute set to yes.
• If a client is specified in the command, statistics are returned only for that client — note that
statistics are only kept at the client level if the view has the per-client-statistics view
attribute set to include the client.
Statistics are kept for:
• Total queries
• Successful queries
• Referrals
• NXRRSET responses
Nominum
statistics 91
• NXDOMAIN responses
• Refused queries
• FORMERRs
• Failed queries
• Total DDNS updates
• Successful DDNS updates
• Failed DDNS updates
• Refused DDNS updates
• NOTAUTH (not authoritative) DDNS updates
• Notifies
• Requests with unknown opcodes
Parameters
[zone=name] [view=name] [reset=any_value] [client=address]
[server=boolean] [all=boolean]
In addition, individual statistics are available for the query type (qtype) for all types less than 50, as well
as type ANY. All other qtypes are combined into one qtype statistic called other.
To request statistics for a view, the general command format is:
ans> statistics [zone=name] [view=name] [reset=any_value] [client=

address] [server=boolean] [all=boolean]
Request:
[ server => boolean ]
[ zone => name ]
[ view => name ]
[ reset => any value ]
[ all => boolean ]
Response:
[ view => string ]
[ zone => string ]
[ reset-time => uint32 ]
[ oldest-version => uint64]
[ current-time => uint32 ]
[ current-time-hires => string ]
Nominum
[ view-load-time => uint32 ]

[ server-start-time => uint32 ]
[ user-time => string ]
[ system-time => string ]
[ zone-count => uint32 ]
[ slave-zone-count => uint32 ]
[ success => int64 ]
[ referral => int64 ]
[ nxrrset => int64 ]
[ nxdomain => int64 ]
[ refused => int64 ]
[ formerr => int64 ]
[ failure => int64 ]
[ notify-total => int64 ]
[ update-total => int64 ]
[ update-success => int64 ]
[ update-failure => int64 ]
[ update-refused => int64 ]
[ update-notauth => int64 ]
[ update-forwarding-success => int64 ]
[ update-forwarding-failure => int64 ]
[ update-forwarding-refused => int64 ]
[ unknown-opcode => int64 ]
[ cache-hit => int64 ]
[ cache-miss => int64 ]
[ query-total => int64 ]
[ cc-update-success => int64 ]
[ cc-update-failure => int64 ]
[ zone-modifications => int64 ]
[ qtypes => int64_table ]
To see view-wide statistics for the default view:
ans> statistics view=default

{
type => 'statistics'
reset-time => '1086308586'
current-time => '1086311955'
view-load-time => '1086308586'
server-start-time => '1086308586'
formerr => '2'
qtypes => {
}
}
Figure 6-12 Using nom_tell to Generate Statistics for a View
Enable Statistics for a Zone

To enable statistics for a zone, the general command format is:
Nominum
statistics 93
ans> update-zone zone=name [view=name] [statistics=yes]
For example, to enable per-zone statistics for the example.com zone:
ans> update-zone zone=example.com. view=default statistics=yes

{
type => 'update-zone'
}
Figure 6-13 Enabling Per-Zone Statistics With update-zone
Fetching Statistics From an Enabled Zone

To fetch zone statistics from the now-enabled example.com zone:
ans> statistics zone=bobs-sports.com. view=default

{
type => 'statistics'
reset-time => '1086312350'
current-time => '1086312547'
view-load-time => '1086308586'
server-start-time => '1086308586'
qtypes => {
}
}
Resetting Statistics
It is possible to clear statistics counters over the Command Channel. Reloading a view resets all statistics
counters for both the view and all of its zones to zero.
To read and clear a single set of counters, add reset=yes to the statistics command. The following
example will return the current values of zone example’s counters, and then set them to zero:
ans> statistics zone=example reset=yes
The registers can be cleared at either the zone or the view level, as suggested by the following com-
mands:
ans> statistics view=internal zone=example.com reset=yes
ans> statistics view=internal reset=yes
Nominum
stop
To stop ANS, use nom_tell with the stop command. On shutdown, ANS writes the entire database to
disk, compacting it as it goes. If there have been many changes, the database will be proportionately big-
ger when dumped since multiple versions of the data are kept and shutdown may be slower.
Example
ans> stop
The command produces the following output:
ans> stop
info: 'ans' closed the connection
Figure 6-14 Stop ANS With nom_tell
uuid
Return the UUID (universal unique identifier) of the server. Note that this is different from the per-view
server-id.
unblock-checkpoints
Unblocks any blocked checkpoints. This is not an error if checkpoints are not currently blocked. See
”block-checkpoints” on page 76 and ”checkpoint” on page 76 for more information.
update-data
Update the contents of a zone.
The specified changes are made to the zone's contents, in an atomic and persistent manner. Changes are
made as either adds or deletes, and replacement is performed by providing both deletes and adds. Delete
operations are always applied first.
Records are added using the add tag, which may contain either one record or a list of records. Each
record is a string corresponding to a single line in DNS master file format—that is, it has a name, type,
and rdata. If not explicitly specified in the record being added, a TTL must also be present.
Nominum
update-data 95
Records are deleted using the delete tag, which should contain either one element or a list of elements.
Each element is a string corresponding to a single line of extended DNS master file format, and will be
treated as if preceded by $DELETE.
A default TTL may be provided with the ttl tag—it is treated as if the records were preceded by a $TTL
statement. The TTL for any updated RRset is aligned to the lower of either the existing or the new RR’s
TTL.
When this command is used to create a zone's contents (as opposed to update the existing contents), the
database in which to store the zone can be specified with the db tag. It is an error to specify this tag
when updating zones that already have content. If no database is specified when creating a zone's con-
tents, the “master” database is used.
If the ignore-serial tag is present and true, changes to the SOA serial number are ignored. This is use-
ful when merging changes made against an earlier version of the zone, and prevents the serial number
from going backwards. After successful completion, the zone's serial number will be one greater than it
was before the update.
If not specified, the view defaults to “default”.
Example
When using nom_tell to issue an update-data command, the interactive mode is preferred (see Table
6-1, “nom_tell command-line options” on page 70 for more information). An update-data command
can be run from a normal nom_tell non-interactive session, but many characters (quotes, parentheses)
will require escaping.
ans> update-data zone=example ttl=3600 add=('x A 1.2.3.4' 'y A 1.2.3.4')
The command produces the following output:
Response:
{
type => 'update-data'
}
Figure 6-15 update-data with nom_tell interactive mode
Other examples of update-data commands that show various actions. The response for each of these
will match that shown in Figure 6-15.
ans> update-data zone=example add='x 3600 A 1.2.3.4'

ans> update-data zone=example ttl=3600 add='x.example. A 1.2.3.4'
ans> update-data zone=example ttl=3600 delete='x' add='x A 1.2.3.4'
ans> update-data zone=example ttl=3600 delete='x' add='x A 1.2.3.4'
ans> update-data zone=example ttl=3600 delete='x A' add='x A 1.2.3.4'
Nominum
ans> update-data zone=example ttl=3600 delete='x A 1.2.3.3' \

add='x A 1.2.3.4'
ans> update-data zone=example ttl=3600 add='x TXT "hello there"'
update-server
Updates the server’s global configuration.
The specified global options are set to the values given. If the delete tag is present, then it should give
the name (or a list of names) of options to delete from the configuration. See Table 5-2 on page 36, ”ANS
Server Options” for the list of options supported in an update-server command.
NOTE The response section of nom_tell requests that shows whether the server restarted itself
contains a restart tag with a value of 1.
ans> update-server import-view=test

{
type => 'update-server'
restart => '1'
}
Figure 6-16 Update Server using nom_tell
To import more than one view and update the view order, the command would be:
ans> update-server import-view=('foo' 'bar' 'cha')
update-view
Update a view’s configuration.
The specified options in the view are set to the values given. If the delete tag is present, then it should
give the name, or a list of names, of options (from the list in Table 5-4, “Zone options” on page 47) to
delete from the view’s configuration.
If the command is successful, the changes are persistent, even across server restarts. Views imported via
the global option import-view or created with ans_import (or imported implicitly, in the case of the
default view), may be updated. If not specified, the view defaults to default.
See Table 5-3, “ANS View Options” on page 41 for values that can be used for [view_option].
Nominum
update-view 97
For example, update the view internal. First, show the view, then update it to change the trans-
fers-in value.
ans> show-view view=internal

{
type => 'show-view'
view => 'internal'
keystore-filename => 'keystore'
server-id => '133e14c1-8501-4962-bf1d-ba389696acec'
cache-size => '104857600'
slave-db => 'slave'
}
ans> update-view view=internal transfers-in=20

{
type => 'update-view'
}
Figure 6-17 Adding a View Option with update-view
If you now show the internal view you just updated, you will see the new value for the trans-
fers-in option (shown in bold type for convenience).
Nominum
ans> show-view view=internal

{
type => 'show-view'
view => 'default'
cache-size => '104857600'
slave-db => 'slave'
}
Figure 6-18 Using show-view to see the Results of an Update
To update the logging switches set on a view, use the log view option.
View logging configuration can be specified. For example,
ans> update-view view=internal log+=(query/refused query/answered)
To set a log option to its default state:
ans> update-view view=internal log-=(update/details)
To completely deactivate logging for a given view:
ans> update-view view=internal log+=(zone/loaded no)
or
ans> update-view view=internal log+='!zone/loaded'
Nominum
update-zone 99
The following example shows adding the log option zone/loaded via update-view and then showing
that it is set with the show-view command. See Appendix C, ”Logging Switches” for a list of logging set-
tings.
ans> update-view view=default log+='(zone/loaded)'

{
}
ans> show-view view=default

{
type => 'show-view'
view => 'default'
cache-size => '104857600'
slave-db => 'slave'
log => (('zone/loaded' 'yes'))
}
Figure 6-19 Setting a Log Switch with update-view
update-zone
This command updates a zone’s configuration.
The specified options in the zone are set to the values given. If the delete tag is present, then it should
give the name, or a list of names, of options to delete from the zone’s configuration. If the command is
successful, the changes are persistent, even across server restarts. If not specified, the view defaults to
default. If the zone configuration doesn’t exist, it will be created. The update-view command and the
update-zone command will accept differential updates where one can use a plus sign (+) to specify an
addition to a list or a minus sign (-) to indicate the subtraction of an item from a list.
ANS will return “unknown view” if the view you specify (either explicitly or implicitly) does not exist;
“unknown zone” will be returned if the view exists, but the zone does not.
Nominum
See ”Zone Options” on page 46, for a list of possible zone options.
Example
ans> update-zone zone=internal.com view=internal \
delete=(allow-update) also-notify=(11.3.4.4 10.1.2.3) \
masters+=10.0.0.1
version
Return version information about the server.
ans> version
This is the resulting output:
response:
{
type => 'version'
vendor => 'Nominum'
product => 'ANS'
platform => 'rhel-4-i386'
version => '2.8.3.0'
}
Figure 6-20 version command output
Nominum
7
The ANS Utilities
This chapter describes the utility programs provided with ANS. Using these utilities, you can:
• Load, import and dump ANS data—See ”ans_load” on page 104, “ans_import” on page 110,
and “ans_dump” on page 113.
• List or delete zones or views—See ”ans_listzones” on page 115, “ans_delete” on page 116 and
“ans_listviews” on page 116.
• Load or dump zone templates—See ”ans_loadzoneconf” on page 117 and

”ans_dumpzoneconf” on page 118.
• Copy data between different databases—See ”ans_copy” on page 118.
• Compare zones—See ”ans_diff” on page 120.
• Edit a zone in the ANS database—See ”ans_edit” on page 122.
• List the versions of a zone in the ANS database—See ”ans_versions” on page 123.
This chapter also briefly explains how to execute these utilities from a machine that is remote from the
one on which ANS is running.
Nominum 101
102 Chapter 7: The ANS Utilities
A Note On Service Definitions in channel.conf

All of the ans_* commands, where “*” is a utility (for example, ans_load) use the Nominum Command
Channel protocol for interaction with ANS, if ANS is running. This becomes important if a given service,
like ANS, is not defined in /etc/channel.conf, the configuration file for the Nominum Command Channel.
For example, you might use the command:
# ans_listzones
to retrieve zone names from the master database. See Chapter 6, "Using the Command Channel with
ANS", for more information on setting up the channel.conf file with the name of a service.
Syntax
There are two ways to specify the database to use, “ordinary” and “URL” syntax.
Programs that require multiple inputs only support URL syntax—programs that only require a single input
support both syntaxes.
Ordinary Syntax
In “ordinary” syntax, the database driver defaults to cc, and can be overridden with the -d option. The
view name defaults to default, and can be overridden with the -v option. The zone name is specified
as the first non-optional argument, and any driver arguments are specified at the end of the non-optional
arguments.
Some programs, such as ans_load, may have other positional arguments between the zone name and
driver arguments, and some programs may also allow a zone revision to be specified with the -r option.
For example, to load the zone file “zone.example” into view “default” of the running ANS server,
# ans_load zone.example
To dump the contents of revision 10 of zone “example” in view “external” from the offline VDB database
“ans-master”.
# ans_dump -d vdb -v external -r 10 example base=ans-master
URL Syntax
In “URL” syntax, the database (and optional view, zone, and zone revision) are specified in a form
similar to a URL, which is the first non-optional command line argument. The first component of the URL
Nominum
Syntax 103
is the driver name, which must be followed by a colon, and may be followed by a list of comma-delimited
driver arguments.
If the URL is not specifying the entire database, the driver specification is followed with a double slash and
the view name. If not specifying the entire view, the view is followed with a single slash and then the
zone name. The zone name may optionally be followed with @revision.
Depending on the program, only some of these forms may be allowed. For example, ans_load would
require the view name and zone name to be present, and disallow a zone revision, while with ans_copy,
the view and zone can be omitted.
For example, to copy the entire database (all views and zones) from the running ANS server to a VDB
database called “backup”:
# ans_copy cc: backup:
To run the ans_diff command on the zone “example” in the default view of the running ANS server with
revision 1 of zone “example” in view “external” in VDB database “backup” (note that an empty view
name is equivalent to the default view):
# ans_diff cc:///example vdb:base=backup//external/example@1
When using URL syntax in a program that supports ordinary syntax as well, do not specify any of the
--driver, --view, or --revision command line options, or URL syntax will be disabled.
Versions
Database versions, either in ordinary or URL syntax, may be specified using several formats. If no version is
explicitly specified, the current version is used.
Syntax Description
num, version=num An absolute version. The version is a 64-bit number that increments
by one each time a change is made.
-num, version=-num A relative version. -1 indicates the current version, -2 the previous ver-
sion, -3 the next previous version, and so forth.
serial=num An SOA serial number. As an SOA serial number may be reused, this
argument is defined to match the most recent version with the given
serial.
Table 7-1 Database revision flags
Nominum
Common Configuration Elements

The following configuration elements are common to many of the commands described below.
Element Description
driver The name of a backend driver for Nominum ANS. Currently, the valid drivers
are vdb and cc.
vdb is the default.

driverarg An arbitrary string. The meaning of driverarg varies by driver, and typi-
cally provides configuration information to the database.
The definitions of what may be contained in each driver’s driverarg may

be found in the documentation for each driver: see Chapter 4, "Database
Drivers".
view The name of a view. If a view is not explicitly specified, the command will
apply to the default view.
zone The fully-qualified domain name of a zone.
Table 7-2 Common Configuration Elements
It is possible to use defaults for most values. The defaults can be overridden using command line options.
For example, here is an ans_load command that loads the zone example from the master file exam-
ple.db into the default view on the running server.
# ans_load example example.db
The example follows these rules for the default values:
• If no driver is specified, the cc driver is used.
• If no view is specified, the view is default.
• If no driver arguments have been supplied and the cc driver is being used, master is used as
the driver argument.
ans_load
The ans_load command loads a zone stored in DNS master file format into a Nominum ANS database.
Nominum
ans_load 105
ans_load [ -c | --check ] [ --directory directory ]

[ -d | --driver drivername ] [ -f | --force ] [ -F|--fragment ]
[ --is-template] [ --ignore-serial ] [ -m | --merge ]
[ --restore-attributes ] [ --root directory ] [ -u | --update ]
[ -v | --view view ]
[ --version ] zone [ zonefile ] [ driverarg... ]
Most values have defaults, which can be overridden using command line options. The following com-
mand loads zone example from the file example.db into the default view on the running server.
# ans_load example example.db
If no driver is specified, the cc driver will be used. For example, the cc driver argument can be used to
add a zone to an instance of ANS that was not in the standard location. If you had an /etc/channel.conf
entry for a second instance of ANS as ans2 and you wanted to load a zone called test from the directory
config into a database called master, the command could be:
# ans_load test config/test channel=ans2 master
If no view is specified, the view will be default. If no zone filename is specified, then the zone will be
read from standard input. Reading from standard input may also be indicated by using “-” for zone-
file.
Option Description
-c | --check Check the zone for correctness, but do not load it.
--directory directory Use the specified directory as the working directory
for relative pathnames in any $INCLUDE state-
ments. If not specified, the default is to use the
working directory that was in effect when
ans_load was invoked.
This option is mainly for use by ans_import, and

should seldom be necessary when using ans_load
directly.
-d | --driver drivername Use the specified ANS driver. If no driver is specified
via this option, then the default driver cc, will be
used.
-f | --force Completely destroy any prior instance of the zone
before loading. See ”Forcing” on page 108.
Table 7-3 ans_load Options
Nominum
Option Description
-F | --fragment If --fragment is specified, then ans_load will
allow the loaded content to be a “zone fragment”.
A “zone fragment” is a zone missing records (for
example, NS and SOA at the origin) that are
required for normal operation. Without this option,
ans_load will emit an error and refuse to load the
zone.
Enabling fragmentation is useful when the content

is going to be used along with a template.
This option cannot be specified together with

--update or --merge. When merging or updat-
ing, the fragment status of the zone remains
unchanged.
--is-template --is-template instructs ans_load to use the
content provided in zone file to define a zone tem-
plate that will provide data common to all zones
using this template. This content need not consti-
tute a complete zone, but the combination of zone
content and template content must together con-
stitute a complete zone.
NOTE: A zone template contains data common to

all zones that use the template. At load time, ANS
can either load the zone content in its entirety, or
construct the content from the zone’s template plus
the content specific to that zone.
This option may not be specified when updating an

existing zone.
--is-template implies --fragment.
Table 7-3 ans_load Options (continued)
Nominum
ans_load 107
Option Description
--ignore-serial Ignore changes to the SOA serial number when
doing incremental updates to the zone. This is use-
ful when merging changes that were made against
an earlier version of the zone, and prevents the
serial number from going backwards. After success-
ful completion, the zone’s serial number will be one
greater than it was before the load.
This option is only valid if the --update or

--merge option is also specified.
-m | --merge Apply any changes between the current version of
the zone and the file into the zone.
When merge is used, the loader loads the file into

memory, computes differences between the current
version of the zone and the loaded zone, and
applies these changes incrementally.
The advantage of merge is that since the changes

are applied incrementally, the ability to IXFR is main-
tained. The disadvantage is that merging is a signif-
icantly slower process than normal loading.
--restore-attributes Restores the zone attributes set in a zone file when
it is created by ans_dump with the
--list-attributes option. This option cannot
be used with the --fragment, --is-template,
--update, or --merge options.
--root directory Use the specified directory as the filesystem root (as
in chroot()) for all pathnames. If not specified,
the default is “/”. Note that “all pathnames” specif-
ically includes the pathname of the master file that
is specified in the ans_load invocation.
If you specify a root directory, you must also specify

a --directory.
This option is mainly for use by ans_import, and

should seldom be necessary when using ans_load
directly.
Nominum
Option Description
-u | --update Update an existing zone instead of replacing it.
Update mode enables the same kind of changes
that can be made with the DNS Dynamic Update
protocol, but using the familiar master file format
and without transaction size limitations. See
”Updating”.
-v | --view viewname Load into the specified ANS view. If no view is spec-
ified via this option, then the default view,
default, will be used.
--version Display the version of the program and exit.
Forcing
ans_load normally marks any existing zone content as old if the zone already exists, but it does not delete
it immediately. This is important when dealing with larger zones, because it allows the server to keep serv-
ing the existing content while new content is being loaded. The entire load is an atomic transaction, and
none of the newly loaded content will be visible in the DNS until all the data is loaded. The old data will
be reclaimed at a later time by a periodic maintenance process. When the --force option is used, the
loader immediately destroys any prior zone content.
NOTE If the --force option is used on a database being used by the nameserver, the server is
unable to answer authoritatively until the load completes. Therefore, Nominum recom-
mends that --force be used only on offline databases.
Merging
If a merge operation makes any changes to the zone's content, but does not change the serial number,
the serial number will automatically be incremented when the transaction is committed. However, this
will not happen if the serial number changes or the merge has no effect.
Updating
Update mode enables the same kind of changes that can be made with the DNS Dynamic Update proto-
col, but using the familiar master file format and without transaction size limitations. (An atomic DNS
dynamic update is limited to the maximum DNS message size of 65535 bytes. There is no limit to the size
of an atomic update made via ans_load.)
Nominum
ans_load 109
The syntax of an update is the standard master file syntax, augmented by the $DELETE and
$UNGENERATE directives. All the other master file directives (for instance, $GENERATE, $TTL, $INCLUDE,
and $ORIGIN) remain available.
When a Resource Record is read from an update file, the RRdata is merged into the existing contents (if
any) of the RRset with the specified owner name. For example, assume the database has an RR entry of:
example A 10.0.0.1
Now assume an update file includes:
example A 10.0.0.2
example A 10.0.0.3
and that this file is submitted to ANS via ans_load in update mode. After the update, the A RRset at node
example is:
example A 10.0.0.1
example A 10.0.0.2
example A 10.0.0.3
The ans_load command can upload comments if they are present. If you have a comment in your record,
it must appear on the same line as the RR to which it applies. ANS will not preserve comments on lines by
themselves or comments which span multiple lines.
$DELETE
A $DELETE directive has the following form:
$DELETE [name] [ttl] [rdclass] [rdtype] [rdata]
Specifying a TTL in a $DELETE directive is permitted, but has no effect. If a class is specified, it must
match the class of the zone. $DELETE can be used to delete an individual RR, all the RRs of a given type,
or all of the RRs with the specified owner name.
For example:
$DELETE example A 10.0.0.1; delete the A RR '10.0.0.1' at 'example'

$DELETE example A; delete all A RRs at 'example'
$DELETE example; delete all RRs at 'example'
Update operations are applied in the order they occur in the master file. To replace an RRset instead of
merging new data into it, simply execute a $DELETE of the type before the replacement data.
For example, assume the database has:
example A 10.0.0.1
Nominum
Now assume an update file has:
$DELETE example A
example A 10.0.0.2
example A 10.0.0.3
and is read into ANS via ans_load in update mode. After the update, the A RRset at node “example” is:
example A 10.0.0.2
example A 10.0.0.3
Zone changes made via update mode create change entries in the database which allow ANS to give
slave servers an incremental zone transfer (IXFR) instead of requiring a full zone transfer (AXFR).
It is not necessary to explicitly update the SOA serial number when using update mode. The server will
automatically increment the serial number when the transaction is committed if it has not already been
changed by the transaction.
$UNGENERATE
A $GENERATE statement in a DNS master zone file facilitates bulk creation of RRs. ANS is unique in sup-
porting an $UNGENERATE statement. $UNGENERATE is permitted in master files when they are loaded in
--update mode. The effect is to delete the same RRs that the corresponding $GENERATE would create.
For example, the following statement in a master zone file, when read inans_load --update mode,
would delete the indicated records.
$UNGENERATE 20-30 $.100.168.192.in-addr.arpa. PTR host$.example
ans_import
The ans_import command imports BIND 8 or BIND 9 configuration data, including views, zones and
zone configuration information, and converts that data to the format used by ANS.
ans_import [-c | --configuration file] [-d | --driver driver]

[-k | --keep-going] [-m | --merge] [-p | --progress]
[ -r |--root directory] [--version] config [ driver ]
config is a BIND 8 or 9 configuration file, typically named.conf. Zone configuration information about
master and slave zones is taken from that file and converted into the ANS zone configuration format.
Master zones specified in the BIND configuration are loaded into an ANS database called master.
Nominum
ans_import 111
WARNING! ans_import must only be used when the server (or any BIND server from which
data will be imported) is not running.
You should “cd” to the directory you want ANS to run in before running ans_import.
One view configuration file is generated per view listed in the BIND configuration. The names of the files
will be of the form viewname.zc, where viewname is the name of the view. If no view is specified in the
BIND configuration, default is used as the view name.
The importer will also generate an ans.conf file and it may also generate master.db if one does not
already exist.
NOTE You must run the ans_import program from the directory where the databases are
stored. A typical location is the default ANS working directory, /var/nom/ans.
A BIND configuration can be re-imported into a directory where ans_import had been previously exe-
cuted. The import will compute the difference between the old and new configurations, and then exe-
cute zone loads or deletes only for the changed zones. Saved server state (such as zone maintenance info,
slave zone contents) is preserved for unchanged zones. See Chapter D, "Examples of Server and View
Operations", for examples of importing a BIND configuration.
Option Description
-c | --configuration Write the configuration to the specified file instead of the default
file configuration file, /etc/ans.conf.
-d, --driver drivername Use the specified ANS database drivername. The default is vdb for
new imports, and the driver used previously when re-importing. The cc
driver may not be used.
-k | --keep-going If a load or delete fails, skip the failing zone and continue loading,
instead of stopping the import immediately.
-m | --merge Enable merge mode. By default, the view zone configuration files are
replaced with content generated from the named configuration file. In
this mode, however, the view zone configuration files are merged
instead of replaced. This mode may be used to merge content from
several named configuration files into one ANS zone configuration set.
Table 7-4 ans_import Options
Nominum
Option Description
-p | --progress At every 5000 zones, print a +/- for each 100 zones loaded/deleted,
and the count so far.
-r | --root directory Simulate a chroot() to the specified directory when processing all BIND
pathnames. This option is used when importing a named.conf that was
run chrooted. Note that “all BIND pathnames” specifically includes the
pathname of the named.conf that is specified in the ans_import invo-
cation.
Table 7-4 ans_import Options (continued)
The importer converts only those portions of the BIND configuration that correspond to ANS configura-
tion parameters. BIND items which are not relevant or otherwise not supported by ANS are silently
ignored.
The items converted from BIND are currently:
Global/View Configuration Imported Values

• TSIG keys
• notify-source
• notify-source-v6
• transfer-source
• transfer-source-v6
• listen-on
Zone Configuration Imported Values

• type (master or slave only)
• masters
• notify
• also-notify
• allow-transfer
Nominum
ans_dump 113
• allow-update
• allow-update-forwarding
• update-policy
Zone content—the DNS data for the zone—is imported for master zones, and therefore the zone files
must be readable. The BIND directory option is used to determine the directory in which the zone files
are found. ANS will transfer any slave zones when it runs. In the case of a re-import, only changed slave
zones are imported.
ans_dump
The ans_dump command dumps a zone stored in an ANS database to DNS master file format.
ans_dump [ -a|--absolute ] [ -d |--driver driver ]

[ --list-attributes ] [ --no-comments ] [ -o |--output filename ]
[ -p|--pretty ] [ -r|--revision revision ] [ -v|--view view ]
[ --version ] zone [ driverarg... ]
mand dumps zone example from the default view on the running server.
# ans_dump example
If no driver is specified, the cc driver will be used. If no view is specified, the view will be default. If no
driver arguments have been supplied and the cc driver is being used, master will be used as the driver
argument.
For example, to dump the contents of revision 10 of zone example in view external from the offline
VDB database ans-master.
Nominum
# ans_dump -d vdb -v external -r 10 example base=ans-master
Option Description
-a | --absolute Enable absolute names mode. Normally ans_dump “relativizes” all
domain names that are subdomains of the zone’s origin. For example, if
the zone is test.example. then node a.text.example. will be relativ-
ized to a.
When absolute mode is enabled, domain names are not relativized to the
zone’s origin.
-d | --driver driver- Use the specified ANS database drivername. If no driver is specified via
name this option, then the default driver, cc, will be used.
--list-attributes Prints the zone attributes as the first line of the output, formatted as a
master file comment, with the attributes as a comma-separated list.
--no-comments Do not emit comments. Normally, ans_dump outputs comments
attached to rdata when they are stored in the ANS database. This option
disables comment printing.
-o | --output filename The output filename. If not specified, the zone will be dumped to stan-
dard output.
-p | --pretty Generate “prettier” output. Normally ans_dump outputs each RR fully
specified (that is, containing the name, TTL, class, type, and rdata).
When pretty mode is enabled, ans_dump will use name defaulting, tabs,
and $TTL to produce more elegant output.
-r | --revision revi- Use the specified revision of the zone, which can be specified by
sion absolute or relative ANS version or SOA serial number. See ”Revisions” on
page 115 for more information.
-v | --view viewname Use the specified ANS view. If no view is specified via this option, then
the default view, default, will be used.
Table 7-5 ans_dump Options
Nominum
ans_listzones 115
Revisions
The database revision, either in ordinary or URL syntax, may be specified in several formats. If no revision
is specified, the current version is used.
Option Description
num, version=num An absolute ANS version. The ANS version is a 64 bit number that incre-
ments by one each time a change is made.
-num, version=-num An relative ANS version. -1 indicates the current version, -2 the previ-
ous, and so on.
serial=num An SOA serial number. As an SOA serial number may be reused, this is
format defined as matching the most recent version with this serial num-
ber.
Table 7-6 ans_dump --revision Formats
ans_listzones
The ans_listzones command lists the zones in a view in an ANS database.
ans_listzones [-d|--driver driver] [-v|--view view] [--version]

[driverarg...]
Most values have defaults which can be overridden using command line options. The following command
lists the zones in the default view on the running server.
# ans_listzones
argument.
Option Description
-d | --driver Use the specified ANS database driver. If no driver is specified via this
drivername option, then the default driver, cc, will be used.
-v | --view viewname Use the specified ANS view. If no view is specified via this option, then the
default view, default, will be used.
Table 7-7 ans_listzones Options
Nominum
ans_listviews
The ans_listviews command lists the views in an ANS database.
ans_listviews [ -d|--driver driver ] [--version] [ driverarg... ]
mand lists the views on the running server. This command will not display views listed in the configuration
file if they have no zones.
# ans_listviews
If no driver is specified, the cc driver will be used. If no driver arguments have been supplied and the cc
driver is being used, master will be used as the driver argument.
Option Description
-d|--driver Use the specified ANS database driver. If no driver is specified via this
Table 7-8 ans_listviews Options
ans_delete
The ans_delete command deletes the contents of a zone stored in an ANS database.
ans_delete [-d|--driver driver] [-f|--force] [-v|--view view]

[--version] zone [driverarg...]
mand deletes zone example from the default view on the running server.
# ans_delete example
Nominum
ans_loadzoneconf 117
argument.
Option Description
-d | --driver driver- Use the specified ANS database driver. If no driver is specified via this
name option, then the default driver, cc, will be used.
-f | --force Normally ans_delete prints an error message and exits with non-zero
status if the zone does not exist in the database. When the --force
option is present, trying to delete a nonexistent zone does not cause an
error and the program will exit with a zero status.
-v | --view viewname Use the specified ANS view. If no view is specified via this option, then
the default view, default, will be used.
Table 7-9 ans_delete Options
ans_loadzoneconf
The ans_loadzoneconf command converts a text-formatted ANS zone configuration such as those pro-
duced by ans_dumpzoneconf (see ”ans_dumpzoneconf” on page 118) into an ANS zone configuration
file for use with ANS.
ans_loadzoneconf [ -u | --update ] [--version] input_text_filename

output_zoneconf_filename
input_text_filename may be “-”, in which case the text zone configuration is read from standard
input.
Option Description
-u | --update Updates the contents of the zone configuration file with the specified file
instead of replacing.
Table 7-10 ans_loadzoneconf Options
Nominum
ans_dumpzoneconf
The ans_dumpzoneconf command converts an ANS zone configuration file into text:
ans_dumpzoneconf [--version] input_zoneconf_filename

[output_text_filename]
output_text_filename may be omitted, or may be specified as “-”. In both cases, the text zone con-
figuration is sent to standard output.
Option Description
Table 7-11 ans_dumpzoneconf Options
ans_copy
The ans_copy command copies zones and/or views between ANS databases.
ans_copy [ -m|--max-versions versions ] [ -s|--shallow ]

[ -v|--verbose ] [ --version ] source target
Nominum
ans_copy 119
source and target take URL syntax (see ”Syntax” on page 102) where the view and zone are optional.
A zone revision may be specified for the source, but not the target, and, if so, only that version will be
copied.
Option Description
-m, --max-versions Normally when copying a zone, ans_copy copies all existing ver-
versions sions of that zone. This uses more space, but retains the ability to
do IXFRs involving extant prior versions of the zone using the target
database. If --max-versions is specified, the number of versions
per zone copied can be limited.
-s | --shallow Normally when copying a zone, ans_copy copies all existing ver-
sions of that zone. This uses more space, but retains the ability to
do IXFRs involving extant prior versions of the zone using the target
database. If -s or --shallow is specified, then only the most
recent version will be copied.
This is equivalent to the --max-versions option, with a limit of

1.
-v, --verbose Show what is being copied.
Table 7-12 ans_copy Options
Examples
For example, to copy all views from the VDB database “customers” to the VDB database “customers-old”:
# ans_copy vdb:base=customers vdb:base=customers-old
To copy the view “default” from the VDB database “master” to the VDB database “master-backup”:
# ans_copy vdb://default vdb:base=master-backup
Note that the default database is master, and that if the target view name is the same as the source, it
need not be repeated.
To copy the “internal” view zone “example” to the view “internal1” in the VDB database “master”:
# ans_copy vdb://internal/example vdb://internal1
Nominum
ans_diff
The ans_diff command determines differences between two zones or two versions of a zone, producing
an output file suitable for ans_load -u.
ans_diff [ -a|--absolute ] [ -d|--driver driver ]

[ -g|--granularity granularity ] [ --no-comments ]
[ -o|--output filename ] [ -r|--revisions revisions ]
[ -v|--view view ]
[ --version ] zone [ zone2 ]
Most values have defaults, which can be overridden using command line options. If no driver is specified,
the “cc” driver will be used. If no view is specified, the view will be default.
The zone and zone2 parameters may use URL syntax (see ”Syntax” on page 102) where the view and
zone are required, and the zone revision is optional. In this mode, two zones must be specified.
Option Description
-a | --absolute Enable absolute names mode.
Normally ans_diff relativizes all domain names which are subdomains

of the zone’s origin. For example, if the zone is “test.example.” then
node “a.text.example.” will be relativized to “a”.
When absolute mode is enabled, domain names are not relativized to

the zone’s origin.
-d | --driver drivername Tells ANS to use the specified ANS database driver. If no driver is spec-
ified via this option, then the default driver, “cc”, is used.
-g|--granularity file- The granularity of the diff, which can be NODE, RRSET, or (the default)
name RR. At NODE granularity, any changes to a node will delete the old
node and fully specify the replacement data. At RRSET granularity, any
changes to an RRset will delete the old RRset and fully specify the new
one. At RR granularity, changes to an RRset will delete and add the
individual changed records.
Note that at all granularities, deleting a node will emit a $DELETE

statement deleting the entire node, and at RRSET and RR granularities,
deleting an RRset will emit a $DELETE statement deleting the entire
RRset.
Table 7-13 ans_diff Options
Nominum
ans_diff 121
Option Description
--no-comments Do not emit comments.
Normally ans_diff outputs comments attached to rdata when they

are stored in the ANS database. This option disables printing of com-
ments.
-o | --output filename The output filename. If not specified, the diff will be dumped to the
standard output.
-r | --revisions revi- Compare the specified revision(s) of the zone, which can be specified
sions by absolute or relative ANS version or SOA serial number.
Unlike most other ANS utilities, this option may specify two revisions
to compare, separated by a colon.
If only one revision is specified, it is compared against the current ver-

sion.
-v | --view viewname Use the specified ANS view. If no view is specified then the default
view, “default”, will be used.
Table 7-13 ans_diff Options (continued)
Examples
For example, to diff the zone called “example” in the “internal” view from the VDB “master“ database’s
“example” zone in the “external” view:
# ans_diff -r10:11 -v internal example
To diff the “default” view’s “example” zone from a running server with the master file “example.db”:
# ans_diff cc://default/example \
file:file=example.db//default/example
Additionally, multiple versions of a single zone may be compared if URL syntax is not used. For example,
to diff versions 10 and 11 of the “internal” view’s “example” zone in a running server:
# ans_diff -r10:11 -v internal example
To diff the current version of the “default” view’s “example” zone against the version with serial number
1000 in a running server:
# ans_diff -rserial=1000 example
Nominum
ans_edit
The ans_edit command edits a zone in an ANS database.
ans_edit [ -d|--driver driver ] [ -v|--view view ] [ --version ]

zone [ driverarg... ]
ans_edit invokes the user’s preferred editor on a zone stored in an ANS database. When editing is com-
plete, ans_edit loads the updated zone into the database.
The changes are merged back into the database with RRset granularity. In particular, this means that
ans_edit can be used to edit a zone which is “live” on the nameserver and being updated with DNS
Dynamic Update. (DDNS)
argument.
Option Description
-d, --driver driver- Use the specified ANS database driver. If no driver is specified via this
name option, then the default driver, cc, will be used.
-v, --view viewname Use the specified ANS view. If no view is specified via this option, then the
Table 7-14 ans_edit Options
To determine which editor to invoke, ans_edit looks for the following environment variables, in the listed
order:
• ANS_EDITOR
• VISUAL
• EDITOR
If none of the above variables exist, ans_edit attempts to invoke vi.
Nominum
ans_versions 123
ans_versions
The ans_versions command lists the versions of a zone in an ANS database.
ans_versions [-c | --count ] [ --current ]

[ -d | --driver driver ] [ -q | --quiet ] [ -r | --reverse ]
[ -u | --utc ] [ -v | --view view ]
[ --version ] zone [ driverarg... ]
Here is sample output from an ans_versions command:
version serial created

-------------------- ---------- --------
49753 100071822 2006-12-24 20:06:37
49754 100071823 2006-12-24 21:06:37
49755 100071824 2006-12-24 21:06:37
49756 100071825 2006-12-27 07:53:30
49757 100071826 2006-12-27 07:53:30
49758 100071827 2006-12-27 08:26:31
49759 100071828 2006-12-27 08:26:31
By default, creation times are printed in local time, and versions are printed from oldest to newest.
If the zone has no SOA record (which may be the case if it is a zone template or uses a zone template),
the serial number will be printed as a single dash.
If the creation time of a version cannot be determined, both date and time will be printed as a single
dash.
argument.
Option Description
-c, --count Print a simple count of the number of versions in the database instead of
information about all versions of a zone.
--current Print information only about the current version of a zone instead of all
versions of the zone.
-d, --driver Use the specified ANS database driver. If no driver is specified via this
-q, --quiet Omits the column headers in the displayed output.
-r, --reverse Print zones starting with the newest zone instead of the oldest zone.
Table 7-15 ans_versions Options
Nominum
Option Description
-u, --utc Prints times in UTC rather than local time.
-v, --view viewname Use the specified ANS view. If no view is specified via this option, then the
Table 7-15 ans_versions Options (continued)
Executing ans_* Commands From A Remote Machine

It is possible to control ans_* commands commands from a remote machine. The examples given
assume the following:
• The machine with the “target” ANS server is called target. The machine from which com-
mands will be issued is called controller.
• The two machines are connected by a network that permits traffic to pass on an ANS com-
mand-channel port, 9353 by default. This port is normally defined with an ans service entry in
/etc/channel.conf.
Take the following steps to execute ans_* commands from a “remote” machine:
1. Stop ANS on target.
2. Configure ANS on target to listen on a Command Channel port exposed to network traffic.
This is necessary because ANS listens by default only on 127.0.0.1.
For example, modify /etc/channel.conf to replace the line:
ans 9353 Fo4POynNdNRHqtb31AfZD7pc
with the line
ans 192.168.0.1#9353 Fo4POynNdNRHqtb31AfZD7pc
3. Restart ANS.
4. Copy the new ans service entry from /etc/channel.conf on target to a file named
~/.nom/channel.conf on controller, where ~ represent’s the user’s home directory.
Nominum
Executing ans_* Commands From A Remote Machine 125
5. Confirm that an ANS instance including the ans_* commands is installed on controller.
6. Execute an ans_* command on controller.
For example:
controller# ans_load example.com example.com.db
where example.com is a zone, and example.com.db is a zone file in master file format, on
controller.
Nominum
Nominum
8
Examples of Zone
Operations
This chapter presents examples of common operational tasks that an ANS administrator may encounter.
These scenarios provide examples of various methods of communicating with ANS. This chapter high-
lights operations that pertain to zone management. See Chapter D, Examples of Server and View Opera-
tions, for examples of operations that pertain to server and view management.
Adding Zones
Add a Master Zone
To add a master zone, first create the zone:
# ans add-zone view=default zone=test.com
Figure 8-1 Adding a Master Zone
Nominum 127
128 Chapter 8: Examples of Zone Operations
Then add an SOA Resource Record (RR) and an NS RR. The SOA and NS records must exist before you can
add other RRs to a zone.
# ans update-data zone=test.com view=default \

add=('@ IN SOA ans.test.com. admin.test.com. \
2006053101 600 120 3600000 300' '@ IN NS ns.test.com.') \
ttl=3600
Figure 8-2 Adding Data to a Master Zone Using update-data
Finally, you can add additional data. In this example, we add a node called www with the address
10.3.4.5 (shown in its A record).
# ans update-data zone=test.com add=('www IN A 10.3.4.5')\ ttl=3600
If we now show the data for this zone, we see the updates we’ve done.
# ans
{
type => 'show-data'
view => 'default'
zone => 'test.com.'
node => '@'
data => ('@ 3600 IN SOA test.com admin 2006053101 600 120 3600000
300' '@ 3600 IN NS ns')
}
{
view => 'default'
zone => 'test.com.'
node => 'www'
data => ('www 3600 IN A 10.3.4.5')
}
Add a Slave Zone

To add a slave zone, add a zone that has a masters field and value. The following example creates the
zone test2.example, which has the master server with the IP address of 10.1.0.1.
Because you provide the address of a master server via the masters field, ANS adds this zone into its
slave database.
ans> add-zone zone=test2.example.com masters=10.1.0.1
Figure 8-3 Add a Slave Zone
ANS will log that it does not have the zone, that it will have to perform a zone transfer, and the actual
transfer itself:
Nominum
Deleting a Zone 129
ANS: info: command: {type => 'add-zone', zone => 'test2.example.com',

masters => '10.1.0.1'}, by root
ANS: info: maintenance: default/tst2.example.com (10.1.0.1#53): zone
does not exist yet, doing initial AXFR
ANS: info: default/example.org (slave): added
ANS: info: maintenance: default/test2.example.com (10.1.0.1#53): trans-
fer succeeded, serial = 2003071600
The first log entry records the command that was issued, and the user id that issued it. The
maintenance entries are informational messages about the progress the server is making slaving the
zone.
It’s important to note that the success of this command means only that the server agreed to slave the
zone. If there is a network problem or the master is down, ANS might not be able to transfer the zone
immediately. If this occurs, ANS continues to try, and reports its progress in the log.
The slave-db zone option can be used when adding a slave zone to specify a slave database different
than the default.
For example, the following command would store the big.example. zone in the database called big.
ans> add-zone zone=big.example.com. \

masters=(10.0.0.1, 10.0.0.2) slave-db=big
Note that the database must have been previously created with a db statement in the ans.conf file, and it
must have been previously imported into the view to which the slave zone is being added.
Converting a Slave Zone Into a Master

Sometimes you may find a need to convert a slave zone into a master. For example, the master server may
become unreachable for a period of time, and there's no sign of it coming back before the zone expires.
Fortunately, ANS allows you to make this change very easily. All you need to do is delete the masters
statement from the options for that zone.
To make the zone c-example.net a master zone rather than a slave zone, use the following command:
ans> update-zone zone=c-example.net delete=(masters)
Deleting a Zone
To completely delete a zone, use nom_tell to send a delete-zone command:
ans> delete-zone zone=example.org
Nominum
Purging Zones
The server retains data from prior versions of zones so that it can respond to IXFR requests. When peri-
odic zone purging runs, prior version data older than a set number of seconds is deleted. Purging can also
be done manually, using the purge-zone command channel message.
There are three zone purging View options supported by ANS:
zone-purge-age
zone-purge-interval
zone-purge-max-versions
The following options are compatible and can be used together:
zone-purge-age
zone-purge-interval
The following option must be used as a stand-alone command, and must not be used with other zone
purge options:
zone-purge-max-versions
This means if you specify the zone-purge-age and zone-purge-interval options, you must not
specify the zone-purge-max-versions option (or set the value to 0), and vice versa.
The following are some example scenarios where these options can be useful.
• Specify a value for the zone-purge-max-versions option to enable the server to check for
old versions each time an update is done, and to purge if necessary.
• Specify values for the zone-purge-age and zone-purge-interval options to minimize

the risk of slowdown that may be seen if you have a zone that is receiving frequent small
updates (such as a DDNS-updated zones receiving updates from a DHCP server). As a general
guideline, set both of the options to the same value.
Updating Zones
Several aspects of zone configuration can be updated, of course. This section shows a few examples that
hightlight the use of the update-zone Command Channel command. The next section shows an example
of updating a zone via the ans_load command used with the --update option.
Displaying Zone Configuration Information

To display the configuration information for a zone, use nom_tell to send a show-zone command:
Nominum
Updating Zones 131

{
type => 'show-zone'
masters => ('192.168.1.1#53')
maintenance => {
status => 'up-to-date'
serial => '2003071600'
refresh => '3600'
retry => '1800'
expire => '604800'
now => '1082420770'
}
}
NOTE For information on next-task and its values, see ”show-maintenance” on page 82.
Because example.org is a slave zone, ANS also includes information about the zone maintenance state of
the zone. The status field is particularly useful. For example, the message:
indicates that the zone is up-to-date. If there were problems transferring the zone, the status would
be different. For example, if you configured an incorrect master by mistake, you would see:
It’s important to note that show-zone only shows you fields which have been explicitly configured by the
administrator. If you do a show-zone for zone example, you can see that it has the default configuration:
ans> show-zone zone=example

{
type => 'show-zone'
}
It’s not an error to specify configuration information for a master zone you have not yet loaded. This lets
you set up the zone the way you’d like, and when you’re ready you can then use ans_load to load the
DNS data and have ANS start serving it.
If you don’t specify a zone when you issue a show-zone command, the server will return information for
all zones in the default view.
Nominum
Updating Zone Configuration Information

To change a zone’s configuration, use nom_tell to send an update-zone command. The following exam-
ple updates the example.org zone to set the notify parameter to no.
ans> update-zone zone=example.org notify=no

{
}
The result of the last command is evident when you show the zone.

{
type => 'show-zone'
masters => ('192.168.1.1#53')
notify => 'no'
}
You can specify as many options as you like with a single update-zone command. Zone options are listed
in Table 5-4, “Zone options,” on page 47.
ans> update-zone zone=example.org notify=no \

masters=(10.2.0.129 10.2.0.130) also-notify=10.2.0.140
{
}

{
type => 'show-zone'
masters => ('10.2.0.129#53' '10.2.0.130#53')
notify => 'no'
also-notify => ('10.2.0.140#53')
}
Fields whose values are lists, such as the masters field, can be updated differentially. For example, to
add master 10.2.0.131, you can say:
ans> update-zone zone=example.org masters+=10.2.0.131

{
}

{
type => 'show-zone'
Nominum
Updating Zones 133
masters => ('10.2.0.129#53' '10.2.0.130#53' '10.2.0.131#53')

notify => 'no'
also-notify => ('10.2.0.140#53')
}
NOTE To perform a differential delete instead of an addition, simply change “+=” to

“-=” in the example given. To determine which fields are lists, see the descriptions in
Table 5-4, “Zone options,” on page 47.
Finally, you can delete fields by listing them as the values of the special delete field:
ans> update-zone zone=example.org delete=masters

{
}

{
type => 'show-zone'
}
Updating via ans_load

Another way to update zone configuration information is via the ans_load command with its --update
option. The syntax is:
# ans_load --update example example.update
where example is a zone and example.update is a DNS master file.
NOTE For more on ans_load, see ”ans_load” on page 104
“Update” mode:
• Enables the same kind of changes that can be made with the DNS Dynamic (DDNS) Update
protocol.
• Uses the familiar master file format.
• Removes transaction size limitations. (Ordinarily, using anything other than ans_load, an
atomic DNS dynamic update is limited to the maximum DNS message size of 65535 bytes.)
Nominum
The syntax of an update is the standard master file syntax, augmented by the $DELETE directive.
$DELETE can be used to delete:
• A specific RR.
• All the RRs of a given type at a name.
• All the RRs at a name (which also results in the removal of the name).
When an RR is read from the master file in update mode, it is merged into the existing contents (if any) of
the RRset with the specified owner name.
Command Description
$DELETE example A 10.0.0.1 Delete the A RR 10.0.0.1 at example.
$DELETE example A Delete all A RRs at example.
$DELETE example Delete all RRs at example.
Table 8-1 $DELETE Directives
For example, this update is in a file called example.update:
$TTL 3600
host1 A 10.2.0.1
$DELETE host2 A 10.2.0.2
$DELETE host2 MX
$DELETE host3
$DELETE host4 A
host4 A 10.4.0.4
This update adds the A RR 10.2.0.1 to host1, deletes the 10.2.0.2 A RR from host2, deletes all MX
records from host2, deletes all host3 entries, and replaces host4’s A RRset with a new set containing
the A RR 10.4.0.4.
To apply it, use ans_load in update mode:
# ans_load --update example example.update
The server logs that the zone has been modified:
ANS: info: default/example (master): modified
The results:
# ans_dump example
@ 3600 IN NS ns1
Nominum
Updating Zone Policies 135
@ 3600 IN NS ns2
@ 3600 IN SOA ns1 hostmaster 101 3600 1800 604800 3600
host1 3600 IN A 10.1.0.1
host1 3600 IN A 10.2.0.1
host2 3600 IN A 10.1.0.2
host4 3600 IN A 10.4.0.4
host4 3600 IN MX 0 mail1
host4 3600 IN MX 10 mail2
mail1 3600 IN A 10.0.0.3
mail2 3600 IN A 10.0.0.4
ns1 3600 IN A 10.0.0.1
ns2 3600 IN A 10.0.0.2
NOTE ANS increments the zone’s serial number for all changes, even if the user
type => 'show-zone'
Updating Zone Policies

The update-policy zone option controls which machines have access to data updates from your
server. The arguments for this option are:
(grant | deny) identity nametype name [ type ]
identity—the name of the TSIG key that a client will use to authenticate itself with the server.
nametype—may be one of name, subdomain, wildcard or self.
name—matches what is attempted to be updated.
type—is the type of Resource Records that can be updated.
Using TSIG Authentication
To set an update policy that allows any client identifying itself with the TSIG key lab. to update A records
for any host in the domain a-example.com, use the following command:
ans> update-zone zone=a-example.com \

update-policy=((grant lab. subdomain a-example.com. (A)))
Nominum
This command maps to the arguments of the update-policy zone option in this way:
Argument Value in Example

{grant | deny } grant
identity lab.
nametype subdomain
name a-example.com
type A
Table 8-2 update-policy Zone Option Examples
Check the output from show-zone to see if the A record has been added.
ans> show-zone zone=a-example.com.

{
type => 'show-zone',
zone => 'a-example.com.',
update-policy => (( 'grant' 'lab.' 'subdomain' 'a-example.com.'
('A'))
}
Figure 8-4 Verifying an Added Option with show-zone
Using Host-based Authentication

It is not necessary to use transaction signatures (TSIG). For a less secure way of allowing updates, you can
use host-based authentication. You can grant “localhost”, for example, permission to perform updates.
Use update-zone with the allow-update zone option. With this option, use grant and then an IP
address followed by a subnet mask, in a notation similar to Classless Inter-Domain Routing (CIDR). 32 bits
set in the subnet mask refers to the actual IP address you specified.
ans> update-zone zone=a-example.com. allow-update=((grant \

127.0.0.1 32))
{
}
Figure 8-5 Adding a Host-based allow-update Option Using update-zone
Nominum
Updating Zone Policies 137
Nominum
Nominum
9
SNMP in ANS
Simple Network Monitoring Protocol (SNMP) is the primary protocol used by network management soft-
ware to monitor and control networked systems and devices.
SNMP-aware software can be used to monitor and manage Nominum products such as ANS engines.
Nominum assumes that this chapter will be used in conjunction with the documentation for Net-SNMP,
available at http://www.net-snmp.org/.
SNMP Concepts and Architecture

In the simplest possible terms, an SNMP-managed network has three main components: a network man-
agement application (manager), agents (including master agents and subagents), and the managed sys-
tems, such as ANS engines.
Managers
A management application (or “manager”) is any one of an array of SNMP-aware tools used for monitor-
ing and managing the status of networked systems, issuing requests for management operations and
perhaps also receiving unsolicited alerts (“notifications” or “traps”) from agents.
Nominum ANS 139

140 Chapter 9: SNMP in ANS
Agents
An agent is “go-between” software running on a managed system. Agents can be “master agents”
and/or “subagents”. A master agent communicates directly with the manager; a subagent handles spe-
cialized communication for each type of managed system. Every managed system requires its own sub-
agent. Messages can travel in either direction: managers can query agents for information, and agents
can also supply unsolicited information to managers.
MIBs
For each type of managed system, the relevant details are defined in a set of hierarchical tables called
Management Information Bases (MIBs). MIBs are defined using a common interface language; they spec-
ify the information exchanged between agents and managers. MIBs are discussed in detail in RFC 1155.
Traps (Notifications)
SNMP subagents can be configured to generate alarms when specified events occur in the managed sys-
tems. These alerts are referred to as SNMP “traps”. In SNMP version 2 and greater, traps are properly
called “notifications”.
To set up a notification, you will have to specify a master agent destination, or “trap sink”, in your agent’s
configuration file.
So, to summarize: SNMP-aware network managers send requests via agent software; specialized sub-
agents read and write data in each managed system’s set of MIBs, and can also convey unsolicited alerts
(traps) for master agents to relay back to the network manager.
General Notes on SNMP for Nominum Products

To use an SNMP-based management application for monitoring and managing Nominum products such
as ANS engines, you will need to install Nominum’s SNMP agent, nom_snmpagent, on the host computer
running the engine you plan to monitor. nom_snmpagent can process inbound requests from an SNMP
management application and outbound trap notifications.
nom_snmpagent is built on top of Net-SNMP and links to Net-SNMP’s agent library. Net-SNMP is included
with the operating systems supported by Nominum products. Nominum assumes that this chapter will be
used in conjunction with the documentation for Net-SNMP, available at http://www.net-snmp.org/.
nom_snmpagent can serve a variety of functions:
• In a straightforward installation, nom_snmpagent works as a subagent to NetSNMP’s master

agent, snmpd. This is the default case. In the simplest instance, with snmpd running, no addi-
tional configuration is necessary.
Nominum ANS
nom_snmpagent 141
• nom_snmpagent can work as a subagent to master agents other than snmpd as long as they
use the AgentX protocol for communication with subagents.
• nom_snmpagent can be set up to function as a master agent. If you’re setting up an

SNMP-aware manager exclusively for Nominum products, you can use nom_snmpagent in the
master agent and subagent roles. nom_snmpagent can also work with other subagents that
support the AgentX protocol. In either case, as a master agent, nom_snmpagent requires a
configuration file, typically /var/nom/snmpagent/snmpagent_master.conf.
• If necessary, nom_snmpagent can coexist as a master agent with a third-party master agent
running on the same host computer. To do this, you’ll have to configure one of the two master
agents to use a non-standard port, and also configure your management application accord-
ingly to send SNMP traffic to the correct port.
The nom_snmpagent package installs MIBs specific to Nominum products, along with associated docu-
mentation. For details, see “Nominum-specific MIBs” on page 143.
nom_snmpagent
The Nominum SNMP Agent (nom_snmpagent) provides SNMP notifications that correspond to events
sent by Nominum engines, and SNMP GET access to engine statistics.
Synopsis
nom_snmpagent [ -c file ] [ -f ] [ -F ] [ -h|--help ]
[ -m|--masteragent ] [ -r|--root directory ]
[ -s|--syslog-facility facility ] [ -u|--user username ]
[ --usage ] [ -v|--version ]
Options
Option Description
-c | --configuration file Reads configuration information from the specified file
instead of the default configuration file
(/etc/nom_snmpagent.conf).
If a file is specified using -c and that file cannot be found,

nom_snmpagent exits with an error message.
-f | --foreground Prevents the agent from daemonizing, and sends output to
stderr.
Table 9-1 nom_snmpagent options
Nominum ANS
Option Description
-F | --foreground-with-syslog Prevents the agent from daemonizing, and sends output to
both stderr and syslog.
-h | --help Displays a help message and exits.
-m | --masteragent Starts the agent as an SNMP master agent.
-r | --root directory chroot()s to the specified directory when the agents runs.
To fully provide the necessary protection, a non-root user
must also be specified with the --user option.
-s|--syslog-facility When logging to syslog, use the specified syslog facility
instead of the default facility, daemon.
-u | --user username Executes a setuid() to the specified username. If using this
option, make sure that whatever user is indicated is able to
write to the directory from which nom_snmpagent is run.
--usage Displays usage information and exits.
-v | --version Displays the agent version and exits.
Table 9-1 nom_snmpagent options (continued)
Configuration Files
nom_snmpagent can run as either an SNMP master agent or as an SNMP subagent. By default it runs as
a subagent.
In a simple, fresh installation with Net-SNMP’s snmpd functioning as a master agent, nom_snmpagent
can run as a subagent without further configuration. If your environment is more complex — for
instance, if you are running nom_snmpagent as a master agent or adding it to an existing NetSNMP
installation that has already been customized — more configuration will be involved.
Agent Configuration Information

nom_snmpagent configuration information is specified in two locations:
• The /etc/nom_snmpagent.conf file contains configuration options specifying how

nom_snmpagent behaves as a daemon. This behavior can also be specified using the Com-
mand Channel.
These options are described in this manual, in “The nom_snmpagent Configuration File” on
page 146 and “Using the Command Channel with nom_snmpagent” on page 150.
Nominum ANS
Nominum-specific MIBs 143
• The /var/nom/snmpagent/snmpagent_master.conf and

/var/nom/snmpagent/snmpagent_subagent.conf files contain options pertaining to
nom_snmpagent’s SNMP configuration. A minimal, insecure sample snmpagent_master.conf
file is displayed in “Running as a Master Agent” on page 145. Options and further details are
beyond the scope of this chapter. Please see the Net-SNMP documentation (available from
http://www.net-snmp.org).
NOTE If you’re configuring traps, be sure to configure nom_snmpagent to send notifications in

SNMP version 2 format. Configure trap sinks in snmpd.conf or snmpagent_master.conf
using trap2sink, not trapsink.
Nominum-specific MIBs
The nom_snmpagent package installs MIBs specific to Nominum products, along with their associated
documentation. The documentation is in /usr/local/nom/doc/snmpagent, and the MIBs themselves are in
/usr/local/nom/share/snmp/mibs.
The relevant MIBs are:
• NETWORK-SERVICES-MIB.txt—Defines a MIB containing the elements common to the monitor-

ing of any network service application.
• NOMINUM-AGENT-CAPS-MIB—Defines a set of agent capabilities that convey an inventory of

management objects exposed by SNMP agents for Nominum products.
• NOMINUM-MDR-MIB—Describes managed objects related to Mandated Domain Redirection in

Nominum products.
• NOMINUM-NSM-MIB—Describes managed objects that expose operational status and statistics

for the Nominum Server, Nominum View and Nominum Zone entities that comprise Nominum
Name Server products.
• NOMINUM-NSN-MIB—Describes managed objects and notifications for the asynchronous

reporting of events observed on Nominum Name Server products.
• NOMINUM-PCS-MIB—Describes managed objects exposing per-client operational status and

statistics.
• NOMINUM-QRS-MIB—Describes managed objects exposing query rate statistics and

notifications.
Nominum ANS
• NOMINUM-SMI-MIB—Defines the top level structure of management information and adminis-

trative registrations within the Nominum private enterprise namespace.
• NOMINUM-TC-MIB—Defines a set of textual conventions that concisely convey the syntax and
semantics of MIB objects as defined in Nominum enterprise MIB modules.
Using SNMP with ANS

This section describes how to use SNMP to monitor the events defined for ANS.
If you anticipate a large number of updates, consider disabling the update/success event in the inter-
ests of performance: the corresponding SNMP notification is nnsnZoneEventUpdateSuccess.
Running as a Subagent
By default, nom_snmpagent runs as a subagent, typically in conjunction with NetSNMP’s master agent,
snmpd. In the simplest instance, this may not require any configuration at all.
If your environment is more complex — for instance, if you are running a master agent other than
Net-SNMP’s snmpd, or if you are extending an existing NetSNMP installation that has already been cus-
tomized — more configuration may be involved. Nominum assumes that you are familiar with Net-SNMP
and that you have access to its documentation at http://www.net-snmp.org/.
For SNMP configuration file options, see “The nom_snmpagent Configuration File” on page 146.
Details specific to atypical installations are beyond the scope of this chapter, but the following broadly
outlines the necessary steps:
1. Install the nom_snmpagent package that is provided as part of the distribution.
2. Ensure that the installation supports the AgentX protocol. See ”Configuration Files” on page
142.
3. Ensure that an SNMP daemon is running.
4. Configure Nominum-specific options for nom_snmpagent by creating the

/etc/nom_snmpagent.conf file and adding the following line:
driver ans ans
5. Ensure that a master SNMP agent is configured and running on the same machine, and that the
SNMP agent supports the AgentX protocol.
6. Perform any Net-SNMP configuration necessary for your specific environment. For details on
configuring Net-SNMP, see the Net-SNMP documentation (available from
Nominum ANS
Using SNMP with ANS 145
http://www.net-snmp.org).
To make use of the (optional) configuration file, create a

/var/nom/snmpagent/snmpagent_subagent.conf file and populate it with the relevant
Net-SNMP configuration data.
7. Start the SNMP agent:
# /etc/init.d/nom_snmpagent start
8. If your installation requires it, configure your SNMP management application to interact with
the provided MIBs and the events they define.
Running as a Master Agent

An SNMP configuration file is mandatory when the SNMP agent is operating in master mode. See ”The
nom_snmpagent Configuration File” on page 146.
Nominum assumes that you are familiar with Net-SNMP and that you have access to its documentation at
http://www.net-snmp.org/.
For complete SNMP configuration file options, see “The nom_snmpagent Configuration File” on
page 146.
Details are beyond the scope of this chapter, but the following broadly outlines the necessary steps:
1. Install the nom_snmpagent package that is provided as part of the distribution.
2. Configure Nominum-specific options for nom_snmpagent by creating the

/etc/nom_snmpagent.conf file and adding the following lines:
masteragent
driver ans ans
3. Perform any Net-SNMP configuration necessary for your specific environment, adding relevant
Net-SNMP configuration data to /var/nom/snmpagent/snmpagent_master.conf. You can do
this either by hand-editing the file or by using the Net-SNMP snmpconf utility (part of the
Net-SNMP package) to do so.
A minimal, insecure sample /var/nom/snmpagent/snmpagent_master.conf is displayed below.

(This is for illustration only; the user is “fflintstone”, passwords are test, and traps and notifica-
tions are sent to the local host.)
Further details on configuring Net-SNMP are beyond the scope of this chapter.
syslocation “This building"
Nominum ANS
sysservices 12
rwuser fflintstone
rwcommunity test
trap2sink localhost
master agentx
4. Start the SNMP agent:
# /etc/init.d/nom_snmpagent start
5. If your installation requires it, configure your SNMP management application to interact with
the provided MIBs and the events they define.
The nom_snmpagent Configuration File

Upon startup, nom_snmpagent tries to read either /etc/nom_snmpagent.conf or the file specified using
the -c command-line option.
If there are no driver directives present in the configuration file, nom_snmpagent tries to read /etc/chan-
nel.conf and monitor any currently running Nominum engines. If driver directives are present in the con-
figuration file, nom_snmpagent doesn’t search /etc/channel.conf.
NOTE If you want nom_snmpagent to scan /etc/channel.conf to discover engines, then all the
engines to be monitored must be running before nom_snmpagent starts. First start the
engines, make sure they’re running, and then start nom_snmpagent.
A nom_snmpagent configuration file is a sequence of lines. Blank lines and lines starting with the # com-
ment character are ignored. Each configuration line contains an option name, optionally followed by
whitespace and a value. If a value is present, it is set to the remaining text on the line, including any
non-leading whitespace.
command-channel
command-channel who [secret]
Specifies the address and port to use for Command Channel messages. If no secret is
specified, then who specifies the name of a service in /etc/channel.conf. If a secret is
specified, then who specifies an addrport (restricted to IPv4 addresses), and a port must
be specified.
If secret is anything other than “*”, only Command Channel requests signed with
secret are allowed to execute, and Command Channel responses are signed with the
Nominum ANS
The nom_snmpagent Configuration File 147
secret. If secret is specified as “*”, then Command Channel messages are neither val-
idated nor signed.
Specifying
command-channel none
disables use of the Command Channel.
NOTE This address and port setting has nothing to do with how nom_snmpagent communi-
cates with the engines it monitors. It is only relevant to interaction with the Command
Channel.
directory
directory directory
Instructs the agent to use the specified directory as the working directory of the
server. This command takes effect immediately. Only one directory statement may appear
in a configuration.
The default directory is /var/nom/snmpagent.
driver
driver engine engine-type [args...]
Instructs the agent to load an SNMP agent driver for a given Nominum engine. The
engine-type is the type of Nominum engine specified, such as ans. It connects to the
engine corresponding to the appropriate
/etc/channel.conf entry, sends SNMP notifications when the monitored engine sends
events, and presents the engine’s statistics via SNMP.
Any remaining arguments are passed to the driver’s setup function, and multiple driver
statements may be specified.
At this time, the only valid arg is a comma-separated list of events to request from the
engine and convert into SNMP notifications. If unspecified, all events are requested.
log
log switch_name yes_or_no
Nominum ANS
Instructs the agent to set a logging control switch. snmpagent allows fine-grained con-
trol over what is logged.
switch_name is the name of the switch:
• command/executed - Logs details about the valid Command Channel commands exe-
cuted by the agent. The default value of this switch is “no”.
• command/unknown - Logs details about unknown Command Channel commands

received by the agent. The default value of this switch is “no”.
• snmp/get - Logs SNMP GET requests. The default value of this switch is “no”.
• snmp/set - Logs SNMP SET requests. The default value of this switch is ”no”.
• snmp/trap - Logs SNMP traps and notifications. The default value of this switch is
“no”.
• snmp/status - Logs SNMP status changes. The default value of this switch is “no”.
• ans/event - Logs details of events received from ANS. The default value of this switch
is “no”.
yes_or_no is either
• yes - Enables logging.
• no - Disables logging.
masteragent
masteragent
Starts the agent as an SNMP master agent.
minseverity
minseverity severity
Sets the minimum severity assigned to a Nominum notification. A notification will not be
sent if it has a severity less than the specified severity. severity is specified as a number
from zero to six, as defined in the NominumPerceivedSeverity textual convention in
NOMINUM-TC-MIB.
This has no effect on clearing notifications (for example, those with a severity of
cleared(1)).
Nominum ANS
The nom_snmpagent Configuration File 149
observer-address
observer-address addrport
Instructs the agent to include the specified address and (optional) port in SNMP notifica-
tions. If not specified, no address or port is included in SNMP notifications.
setseverity
setseverity notification severity
Sets the severity assigned to a Nominum notification. notification must be the name
of one of the notifications defined in NOMINUM-NSN-MIB, such as “nnsnServerEvent-
Stop”. severity is specified as a number from zero to six, as defined in the Nominum-
PerceivedSeverity textual convention in NOMINUM-TC-MIB.
This has no effect on clearing notifications (for example, those with a severity of
cleared(1)).
syslog-facility
syslog-facility facility
Instructs the agent to use the specified syslog facility instead of the default facility
(daemon).
Driver-Specific Configuration Options

The ANS SNMP driver accepts additional configuration elements.
These configuration elements are useful when:
• The agent has no trap sinks configured and hence does not need to receive most events from
the engines it is monitoring.
• The engines are generating large numbers of events, causing the SNMP agent to use CPU
cycles needlessly.
NOTE Do not enable request-minimal-events if you wish the SNMP agent to send SNMP
traps or notifications.
Nominum ANS
events
A comma-separated list of events to be requested from the engine and converted into
SNMP notifications. If this value is not specified, all events are requested.
For example:
driver ans ans events=configuration-save,cache-flush
request-minimal-events
request-minimal-events permits you to control the number of events you receive from the
ANS SNMP driver.
If “yes”, the driver requests only the minimal set of events needed to keep applTable
up to date. This supersedes the events configuration element.
For example:
driver ans ans request-minimal-events=yes
Using the Command Channel with nom_snmpagent

The agent accepts control commands sent using the Nominum Command Channel protocol. Examples
are given using the nom_tell Command Channel client in interactive mode.
load-driver
Loads an SNMP agent driver for a Nominum engine.
nom_snmpagent connects to the engine corresponding to the appropriate service entry

in /etc/channel.conf, sends SNMP notifications when the monitored server sends events,
and presents the engine’s statistics via SNMP.
If the engine name is anything other than the default for the given engine,
engine-type must also be specified, and any additional arguments are passed on to
the driver.
It is also possible to use the events argument to restrict the list of events to be
requested from the engine and converted into SNMP notifications. If this value is not
specified, all events are requested.
snmpagent>load-driver name=<EngineName>\
[engine-type=ans] [events=events]
Nominum ANS
Using the Command Channel with nom_snmpagent 151
Response:
name => engine_name
[engine-type => engine_type] [events => events]
pid
Returns the process identification for the agent process.
snmpagent>pid
Response:
pid => pid
process-information
Retrieves process information for the server.
Response:
[ arguments => ( string ... ) ]

pid => pid
current-time => time
start-time => time
[ working-directory => string ]
stop
Stops the agent.
snmpagent>stop
show-drivers
Shows the currently loaded drivers. The Command Channel result contains a list of driv-
ers, and each driver-list item contains a list of currently instantiated drivers for that driver
type.
snmpagent> show-drivers
{
type => 'show-drivers'
drivers => {
ans => ('ans')
}
}
Nominum ANS
uuid
Returns the UUID (Universal Unique IDentifier) of the agent.
snmpagent>uuid
Response:
uuid => uuid
unload-driver
Unloads an SNMP agent driver.
snmpagent>unload-driver name
Response:
name => engine_name
version
Returns version information about the agent.
snmpagent>version
Response:
type = > 'version'
vendor => 'Nominum'
product => 'snmpagent'
platform => 'platform'
version => 'version'
Using Net-SNMP Command-line Tools with nom_snmpagent

Net-SNMP, the basic structure on which nom_snmpagent relies, includes a set of command-line tools for
examining and testing your SNMP setup. Many of these tools are bundled with the nom_snmpagent
package: snmpget, snmpwalk, snmptrap, snmptranslate, snmpbulkget, snmpgetnext, snmpinform,
snmpset, snmptable, snmpusm, snmpvacm, and snmptrapd.
If you have installed the nom_snmpagent package, all the MIBs and driver libraries will be where both
nom_snmpagent and the Net-SNMP tools expect them to be. However, you will still have to configure
the command-line tools to use all the MIBs. You can do that by calling the tools with the -m ALL option
each time, or more neatly by adding the following line to /etc/snmp/snmp.conf:
mibs +ALL
If you built the tools yourself rather than by installing nom_snmpagent, you will also have to set the mib-
dirs environment variable by including the following line:
Nominum ANS
Using Net-SNMP Command-line Tools with nom_snmpagent 153
mibdirs +/usr/local/nom/share/snmp/mibs
It is beyond the scope of this chapter to discuss the Net-SNMP tools in detail. A few examples are pro-
vided for each of the most useful tools: snmptranslate, snmpwalk, snmpget, and snmptrapd. Please see
the Net-SNMP documentation at http://www.net-snmp.org/.
In all examples below that require a hostname, localhost is used. If nom_snmpagent is not running on
the local host, you can replace this with the hostname or IP address of the appropriate host computer.
snmptranslate
To verify that the tools can find what they need, use snmptranslate:
> snmptranslate -IR applTable
NETWORK-SERVICES-MIB::applTable
and
> snmptranslate -IR nnsmViewTable
NOMINUM-NSM-MIB::nnsmViewTable
You can also display full object identifiers (OIDs), in numeric or symbolic form:
> snmptranslate -IR -On nnsmViewTable
.1.3.6.1.4.1.5901.4.5.1.2.2
> snmptranslate -IR -Of nnsmViewTable
.iso.org.dod.internet.private.enterprises.nominum.nominum-
Mibs.nominumNsmMib.nnsmObjects.nnsmViewObjects.nnsm-
ViewTable
snmpwalk
The applTable shows which Nominum engines nom_snmpagent is monitoring.
> snmpwalk -v 2c -c test localhost -IR applTable
NETWORK-SERVICES-MIB::applName.1 = STRING: ans
NETWORK-SERVICES-MIB::applDirectoryName.1 = STRING:
NETWORK-SERVICES-MIB::applVersion.1 = STRING: 2.6.0.0.d
NETWORK-SERVICES-MIB::applUptime.1 = Timeticks: (0)

0:00:00.00
NETWORK-SERVICES-MIB::applOperStatus.1 = INTEGER: up(1)
Nominum ANS
NETWORK-SERVICES-MIB::applLastChange.1 = Timeticks: (0)

0:00:00.00
NETWORK-SERVICES-MIB::applDescription.1 = STRING: Authorita-

tive Name Server
NETWORK-SERVICES-MIB::applURL.1 = STRING:
This example assumes that your “community string” (SNMP password) is test, and that nom_snmpagent
is running on the localhost.
One crucial piece of information the applTable provides is a mapping from the human-readable server
name (ans in this example) to the application ID (in this case, 1). The application ID is the number after
each column name (applName.1). The application ID will appear in the indexes of all Nominum SMI
objects, and provides the only reference to which Nominum engine a given SMI object refers.
snmpwalk can dump any table in the set of MIBs that nom_snmpagent supports. This includes a large
number of standard MIBs in addition to Nominum’s MIBs.
To dump a view table in ANS:
> snmpwalk -v 2c -c test localhost -IR nnsmViewTable
NOMINUM-NSM-MIB::nnsmViewName.1.1 = STRING: default
NOMINUM-NSM-MIB::nnsmViewType.1.1 = INTEGER: auth(1)
All Nominum tables (5901 is Nominum’s enterprise OID):
> snmpwalk -v 2c -c test localhost .1.3.6.1.4.1.5901
NOMINUM-NSM-MIB::nnsmViewNameToViewID.1."default" = Gauge32:
1
NOMINUM-NSM-MIB::nnsmViewName.1.1 = STRING: default
NOMINUM-NSM-MIB::nnsmViewType.1.1 = INTEGER: auth(1)
NOMINUM-NSM-MIB::nnsmViewAuthLoadTime.1.1 = STRING:
27136-7-25,17:24:20.0
NOMINUM-NSM-MIB::nnsmViewAuthZonesActive.1.1 = Gauge32: 2
DNS zones
NOMINUM-NSM-MIB::nnsmViewAuthSlavesActive.1.1 = Gauge32: 0
DNS zones
snmpget
You can use snmpget to retrieve single instances. To get the zone name and zone type indexed by appli-
cation ID 2, view ID 1, and zone ID 2:
Nominum ANS
Using Net-SNMP Command-line Tools with nom_snmpagent 155
> snmpget -v 2c -c test localhost NOMINUM-NSM-MIB::\

nnsmZoneName.2.1.2
NOMINUM-NSM-MIB::nnsmZoneName.2.1.2 = STRING: cat.com.
and
> ./snmpget -v 2c -c test localhost NOMINUM-NSM-MIB::\

nnsmZoneType.2.1.2
NOMINUM-NSM-MIB::nnsmZoneType.2.1.2 = INTEGER: master(4)
To get the zone name to zone ID mapping for example.com, look in the
nnsmZoneNameToZoneIdTable. This one is a bit trickier since the zone name is encoded as an index, as
the number of characters followed by the ASCII codes for each letter. In this example, the 2.1 following
nnsmZoneNameToZoneID refer to the application ID (2) and the view ID (1).
> ./snmpget -v 2c -c test localhost NOMINUM-NSM-MIB::\

nnsmZoneNameToZoneID.2.1.8.99.97.116.46.99.111.109.46
NOMINUM-NSM-MIB::nnsmZoneNameToZoneID.2.1."example.com." =
Gauge32: 2
snmptrapd
You can use snmptrapd to display traps. With some configuration, snmptrapd can also take action on
them.
To configure snmptrapd you’ll need the same security information you configured your trap sink with in
snmpagent_master.conf. To be consistent with the sample configuration file given in “Running as a Mas-
ter Agent” on page 145, for example, you would add the following to /etc/snmp/snmptrapd.conf:
authCommunity log test
Run snmptrapd in the foreground (-f) with logging redirected to stderr (-Le). Since you’ve installed
the nom_snmpagent package, your MIBS and MIBDIRS environment variable will already be where
snmptrapd expects them to be).
> ./snmptrapd -f -Le
Here is what a typical trap looks like when displayed by snmptrapd. (This example was triggered by a Van-
tio server reload event.)
2008-01-09 17:07:51 <UNKNOWN> [UDP: [127.0.0.1]:50084]:
DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (53405)\

0:08:54.05
Nominum ANS
SNMPv2-MIB::snmpTrapOID.0 = OID: NOMINUM-NSN-MIB::nnsn\

ServerEventReload
NOMINUM-NSN-MIB::nnsnEventPerceivedSeverity = INTEGER:\
information(0)
NOMINUM-NSN-MIB::nnsnEventDateAndTime = STRING:\
27648-1-9,17:7:51.0
NOMINUM-NSN-MIB::nnsnEventReferenceID = Gauge32: 0
NETWORK-SERVICES-MIB::applName.1 = STRING: vantio
NETWORK-SERVICES-MIB::applVersion.1 = STRING: 3.2.0.1.d
NOMINUM-NSN-MIB::nnsnEventSerialNumber = Counter64: 2
Nominum ANS
10
Secret Key Transaction
Authentication (TSIG)
This chapter provides an overview of authentication in ANS. Specifically, this chapter shows how to use
both TSIG and GSS-TSIG with ANS.
DNS TSIG
RFC 2845, “Secret Key Transaction Authentication for DNS (TSIG)”, provides transaction level authentica-
tion. TSIG is an additional RR type, used to cryptographically sign a DNS packet. The standard specifies
the use of shared secrets and one-way hashing to accomplish authentication. It does not provide a distri-
bution mechanism for the shared secrets, but suggests “an out of band mechanism such as example.net.”
To remedy the lack of a key distribution mechanism for DNS TSIG, a TKEY RR was proposed in RFC 2930,
“Secret Key Establishment for DNS (TKEY RR)”. The TKEY proposed standard provides a means for the
resolver and server to agree on secret material for use with TSIG without their communication being
secret.
Using DNS TSIG With ANS

ANS implements the standard DNS TSIG message authentication protocol. TSIG key names, strings used
to uniquely identify keys, can be used in access control lists (ACLs) to limit access to zone transfers and
dynamic updates. ANS can also be configured to authenticate inbound zone transfers (for example, when
ANS is a slave for the zone), and TSIG keys can be used in view selection, allowing clients with knowledge
of a given key access to privileged views.
Nominum 157
158 Chapter 10: Secret Key Transaction Authentication (TSIG)
TSIG secrets are typically represented as Base64-encoded strings. For example:
6JA7IxydIGPkr3Tw5ij0pQ==
If you have imported a BIND configuration with TSIG keys in it, ANS will know about them. If you would
like to define a key specifying the key name and secret, jump to ”Defining a TSIG Key” below.
Generating a TSIG Secret

To generate a new random TSIG secret, you can use the nom_maketsigsecret utility. See
”nom_maketsigsecret” on page 168 of Chapter 11, ”Supporting Programs” for information about this
program.
# nom_maketsigsecret
8+a3Y5plhddf603oIVITTw==
If you run on a platform that does not have /dev/random, or if it can’t provide enough randomness, you’ll
see something like this instead.
# nom_maketsigsecret
Random data is needed to generate a shared secret for use by the nom_tell
program. Please type a secret phrase least 40 characters long, or at
least 40 random characters. Each character will be echoed as "*".
There is no need to remember what you typed.
***************************************************************
EdIfNV4FxxAiWfnNxgu3iQ==
You should enter something uncommon and secret—random characters are best—but you don’t need to
remember what you entered, since it will be hashed with the MD5 algorithm to produce a value suitable
for TSIG. The nom_maketsigsecret program is also summarized in Chapter 11, "Supporting Programs".
TSIG Key Names

The TSIG key name must be a valid domain name, but beyond that restriction it may be anything you like,
though you and anyone you wish to talk to using the key must agree on both the name and the TSIG key.
One common style of naming is peer-peer—a key used between hosts ns1 and ns2, for example, might
be called ns1-ns2.
Defining a TSIG Key

Let’s define key ns1-ns2. with secret 8+a3Y5plhddf603oIVITTw==:
ans> update-view key+=(('ns1-ns2.' '8+a3Y5plhddf603oIVITTw=='))

{
}
Nominum
DNS TSIG 159
Note that you used the “+=” differential update syntax to say that you wanted to add to the key list and
not replace it. Display the key with the show-view command:
ans> show-view
{
type => 'show-view'
view => 'default'
key => (('ns1-ns2.' '8+a3Y5plhddf603oIVITTw=='))
server-id => 'bf20b630-7e18-411a-8ab2-a09d5f6caa41'
cache-size => '16777216'
slave-db => 'slave'
log => nil
}
If you prefer, you can stop the server and add a key line to the view’s configuration file instead. Since
you’re using the default view, you’d edit /var/nom/ans/default.vc.
Here’s what the configuration file for the view shown above looks like:
# cat /var/nom/ans/default.vc
import master
import slave
cache-size 16777216
cache-filename "default.cache"
zone-conf-filename "default.zc"
server-id "bf20b630-7e18-411a-8ab2-a09d5f6caa41"
slave-db slave
transfers-in 10
key ns1-ns2. 8+a3Y5plhddf603oIVITTw==
Nominum
Using a TSIG Key For A Master Zone

For information on using a TSIG key for a master zone, see ”Limiting Zone Transfers from ANS” on page
194.
Using a TSIG Key When Slaving a Zone

To authenticate your server when it transfers zones from a master, associate a TSIG key name with the
master’s IP address in the masters field of the zone. For example, let’s try to use the ns1-ns2. key when
slaving example.net from 192.168.1.1:
ans> add-zone zone=example.net masters=((192.168.1.1 ns1-ns2.))
Using a TSIG Key for View Selection

TSIG keys may also be used to select which view is used to satisfy queries from clients and apply dynamic
updates.
When used in this fashion, TSIG keys also apply to zone transfers and dynamic updates, and in order to
select the correct view, the key may also need to be specified in the match statement.
Specifying a TSIG key in an ACL (such as allow-* or an update policy) does not automatically force the
selection of the view containing that ACL. ACLs referring to the same key may appear in several views.
ANS applies the normal “first-match” semantics to view selection—a match on the key used to sign a
query or update or a match on the source address immediately terminates the selection process.
In this example, access to the privileged view is:
• Denied to any client that signs queries with otherkey, regardless of source-address.
• Granted to any client signing queries with privkey, regardless of source-address.
• Denied to queries from network 192.168.0.0/16, unless queries are signed with privkey.
• Granted to all clients in the 10.0.0.0/8 network, unless queries are signed with otherkey.
ans> update-view view=privileged \

match=(!otherkey, privkey. !192.168.0.0/16, 10.0.0.8))
Nominum
GSS-TSIG 161
GSS-TSIG
RFC 3645, “GSS Algorithm for TSIG (GSS-TSIG)” specifies a Generic Security Service API. RFC 2743,
“Generic Security Services Application Program Interface” provides a uniform, high-level API to security
services like authentication and confidentiality.
GSS-TSIG uses the GSS-API, TKEY and DNS TSIG to establish security context between a DNS Client and a
DNS server. This security context can then be used to authenticate, for example, dynamic updates as used
in Microsoft™ Active Directory™.
Using GSS-TSIG with ANS

In environments that have deployed Microsoft™ Active Directory™, it is necessary to use GSS-TSIG to
secure dynamic updates. To allow Microsoft™ Windows™ clients to securely update from ANS, or to other-
wise allow ANS to interoperate with Windows™ DNS using GSS-TSIG, take the following steps:
1. Set up MIT Kerberos on the machine running ANS to point at the Microsoft™ domain controller
by editing the krb5.conf file. MIT Kerberos may be obtained from http://web.mit.edu/kerbe-
ros/www/.
2. Follow the Microsoft™ procedures for setting up Kerberos on the Windows™ system.
3. Tell ANS to get the appropriate Kerberos credentials.
4. Tell ANS to grant update rights to the Windows™ system.
These steps are described in more detail in the following sections.
Set up Kerberos
First, set up Kerberos, pointed at the Microsoft™ domain controller, on the host running ANS.
The following is an example krb5.conf file—change OUTBACK.EXAMPLE.COM to the realm of the Micro-
soft™ domain controller, and change 10.2.0.128 to the IP address of the Microsoft™ domain controller.
[logging]
default = FILE:/var/log/krb5libs.log
kdc = FILE:/var/log/krb5kdc.log
admin_server = FILE:/var/log/kadmind.log
[libdefaults]
ticket_lifetime = 24000
default_realm = OUTBACK.EXAMPLE.COM
dns_lookup_realm = true
dns_lookup_kdc = true
Nominum
[realms]
OUTBACK.EXAMPLE.COM = {
kdc = 10.2.0.128:88
admin_server = 10.2.0.128:749
default_domain = outback.example.com
}
[domain_realm]
.outback.example.com = OUTBACK.EXAMPLE.COM
outback.example.com = OUTBACK.EXAMPLE.COM
[kdc]
profile = /var/kerberos/krb5kdc/kdc.conf
[appdefaults]
pam = {
debug = false
ticket_lifetime = 36000
renew_lifetime = 36000
forwardable = true
krb4_convert = false
}
Set up Kerberos on Windows™

Follow the procedures described in http://www.microsoft.com/WINDOWS2000/techinfo/planning/secu-
rity/kerbsteps.asp to set up Kerberos on the Windows™ system.
1. Create two users, one for the ANS server, and one for the DNS service, via the Account tab of
the User Properties command box.
In the examples below, the examples used are host/linux.outback.example.com for the ANS
server and DNS/linux.outback.example.com for the DNS service. These are the names entered
in the User Logon field of the Account tab. The linux.outback.example.com portion is the
domain name of the ANS server. The OUTBACK.EXAMPLE.COM portion is the Kerberos realm
and is entered in another field in the Account tab.
In the General tab on the same User Properties command box, the Display Name field is where
the value for -mapuser is entered. These can also be referred to as “Kerberos names.” In the
examples below, hostuser and dnsuser are used.
2. Once these users are configured, type the following from a command shell on the Windows™
system, carefully entering each as one long line to Windows™. Case is significant—in particular
“DNS” should be capitalized:
C:\>ktpass -princ \
host/linux.outback.example.com@OUTBACK.example.COM -mapuser\
hostuser -pass the_password_here -out host.keytab
Nominum
GSS-TSIG 163
C:\>ktpass -princ \
DNS/linux.outback.example.com@OUTBACK.example.COM -mapuser\
dnsuser -pass the_password_here -out dns.keytab
3. Next, list linux.outback.example.com in the SOA MNAME field of a zone, and in the zone’s NS
records. If the Windows™ system needs to update that zone, it will use GSS-TSIG to do it.
Get the Kerberos Credentials

1. Copy the two .keytab files previously created to the system running ANS. su to root. After
doing so, copy the key tabs into /etc/krb5.keytab. Issue the following command:
# /usr/kerberos/sbin/ktutil
Ktutil will prompt you with ktutil. Enter the following commands, pressing return after each
one. If you have an existing /etc/krb5.keytab you’d like to preserve, read it in with:
ktutil>rkt /etc/krb5.keytab
2. If you have no existing keytab, issue the following commands:
ktutil>rkt /wherever/you/put/it/host.keytab
ktutil>rkt /wherever/you/put/it/dns.keytab
ktutil>wkt /etc/krb5.keytab
ktutil>q
3. Create a simple ans.conf file in the directory where you want to run ANS. For example, the
directory /wherever/you/like.
4. To test whether your configuration is correct to this point, from the ANS server host, type:
# kinit host/linux.outback.example.com@OUTBACK.EXAMPLE.COM
You will be asked for a password. Enter the password for this user as you did for the -pass
option above. If you do not receive an error, your setup is correct. Repeat the command to test
the DNS user.
5. Start ANS:
# /usr/local/nom/sbin/ans -c /wherever/you/like/ans.conf
Nominum
6. Tell ANS to get credentials:
# /usr/local/nom/sbin/nom_tell ans update-view \

gss-credentials='DNS/linux.outback.example.com'
If everything has worked, you’ll see
GSS credentials acquired for 'DNS/linux.outback.example.com'
in syslog on the ANS server.
Grant Update Rights to the Windows™ System

Finally, grant update rights to the Windows™ system. Provided you have loaded the
0.2.10.in-addr.arpa. zone into ANS (using the ans_load command), the following command
allows any valid GSS-TSIG identity to make an update to PTR records in the 0.2.10.in-addr.arpa.
zone:
# nom_tell ans update-zone zone=0.2.10.in-addr.arpa \

update-policy=((grant *. subdomain 0.2.10.in-addr.arpa. (ptr)))
Here’s what the domain controller at 10.2.0.124, updating its own PTR RR to bark.outback.exam-
ple.com, looks like in the log:
10.2.0.128#1030: update 39367: default/0.2.10.in-addr.arpa, unsigned

10.2.0.128#1030: update 39367: update-policy denies delete
128.0.2.10.in-addr.arpa PTR
10.2.0.128#1030: update 39367: refused
10.2.0.128#1030: update 31685: default/0.2.10.in-addr.arpa, using key
bark\$\@OUTBACK.EXAMPLE.COM
10.2.0.128#1030: update 31685: granted delete 128.0.2.10.in-addr.arpa
PTR
10.2.0.128#1030: update 31685: granted add 128.0.2.10.in-addr.arpa PTR
bark.outback.example.com
10.2.0.128#1030: update 31685: succeeded
Nominum
11
Supporting Programs
This chapter describes utility programs intended to complement the use of ANS. Several programs sup-
port authentication.
ans_signer
The ans_signer program is a DNS zone signer that takes a zone in standard DNS master file format as
input, and produces a DNSSEC signed zone as output. DNSSEC is a security protocol designed to sign DNS
data to protect it from unauthorized modification, and ans_signer’s output is generated in accordance
with the DNSSEC specification.
NOTE ans_signer is currently limited to signing with RSA keys (either RSA-MD5 or RSA-SHA1),
as there is no way to obtain the high-quality entropy necessary for secure DSA signatures.
ans_signer should only be used to sign zone files, not to maintain existing signed zone files, as it will drop
any existing RRSIG and NSEC records on load. Existing signed zones can be maintained by using DNS
Dynamic update to ans to update the contents of those zones.
ans_signer [-f outfile] [-o origin] [-s starttime][-e endtime] [-t] [-d
directory] [-k dskeyid] [-K keystore] [-v] [-h] [--version]
zonefile [keyid...]
Nominum 165
166 Chapter 11: Supporting Programs
ans_signer will look for keyset files at delegation points, which are named keyset-name, where name is
the name of the delegation point, from which to generate DS records. It will also generate a keyset file for
the zone being signed. If the keyset contains more than one key, then the keyset file will also contain sig-
natures of the keyset made by each key; this facilitates non-emergency rollover.
The zonefile parameter specifies the input master file. If specified as stdin, standard input will be
used. The keyid parameters list the keys used to sign the zone. If no keys are specified on the command
line, all zone keys from the master file will be used. If there are keys specified on the command line and
none in the master file, the keys will be added to the signed output file. The key ids are specified on the
command line; the keys are stored in the keystore file.
Option Description
-d directory The directory where keyset files are located. If not specified, the current
directory is used.
-e endtime The date and time when the generated SIG records expire. This can be
either absolute, relative to the start time, or relative to the current time. As
with starttime, an absolute time is indicated by YYYYMMDDHHMMSS
notation. A time relative to the start time is indicated by +N, and a time rel-
ative to the current time is indicated by now+N, where N is a number of
seconds. If no endtime is specified, 30 days from the start time is used.
-f outfile Specify the output file name. If specified as -, output will be written to
standard output. If not specified, the default is to append .signed to the
input file name, or to the zone origin if reading from standard input.
-h Print help and exit.
-k dskeyid The keyid of a key-signing key (KSK) for the zone. This option may be speci-
fied more than once. If any KSKs are specified, then they will be used to
sign the zone keyset and no other records, and will be the only keys put into
the output keyset file.
If no KSKs are specified, then ans_signer looks for keys with the secure
entry point (SEP) flag set. If any SEP keys are found, then they are used as
the KSKs. Otherwise, all of the keys specified are used as KSKs.
-K keystore The location of the keystore file containing the zone keys. If not specified, it
will default to a file called “keystore” in the current directory. The keystore
file is manipulated with nom_keytool. See ”nom_keytool” on page 161.
-o origin The zone origin. If not specified, the name of the zone file is assumed to be
the same as the origin.
Table 11-1 ans_signer Options
Nominum
nom_keytool 167
Option Description
-s starttime The date and time when the generated SIG records become valid. This can
be either an absolute or relative time. An absolute start time is indicated by
a number in YYYYMMDDHHMMSS notation; 20020530144500 denotes
14:45:00 UTC on May 30th, 2002. A relative start time is indicated by +N,
where N is a number of seconds. If no starttime is specified, the current
time is used.
-t Generate statistics and print them at completion.
-v Verbose mode. Among other things, this enables a one-line progress bar.
Table 11-1 ans_signer Options (continued)
nom_keytool
The nom_keytool program maintains a keystore file and supports generating, importing, exporting, delet-
ing and listing keys. If a keystore filename is not specified with the --keystore option, the default file-
name keystore in the current working directory will be used.
NOTE --sep is a key signing key that sets the Secure Entry Point flag on a key.
nom_keytool list [--keystore keystore] [--help] [--usage] [--version]
Subcommand Description
delete Deletes a key from the keystore.
generate Generates a key and adds it to the keystore. The key id is printed to stan-
dard output.
list Lists all keys in the keystore, printing the key name and id.
make-ds Print a DS RRset containing the SHA-256 and SHA-1 hashes of the specified
key to standard output.
to-bind-dnskey Creates BIND style .key and .private files containing the key as a DNSKEY
RR.
to-bind-key Creates BIND style .key and .private files containing the key as a KEY RR.
Table 11-2 nom_keytool Subcommands
Nominum
Subcommand Description
to-dnskey Prints the rdata of a DNS DNSKEY record to standard output.
to-key Prints the rdata of a DNS KEY record to standard output.
from-bind-key Imports a key from BIND style .key and .private files containing the key in
the form of a KEY RR.
from-bind-dnskey Imports a key from BIND style .key and .private files containing the key in
the form of a DNSKEY RR.
Table 11-2 nom_keytool Subcommands (continued)
nom_maketsigsecret
The nom_maketsigsecret program creates a new shared secret to be used to create DNS TSIG (transaction
signatures). The shared secret will be generated from /dev/random if it is available. Otherwise, the user
will be prompted to make up a secret.
Nominum ANS does not require a keyname.
nom_maketsigsecret [keyname]
If keyname is present, the program will output a TSIG key statement suitable for use with the Nominum
ANS server. If keyname is not present, a base64-encoded secret is produced.
nom_nanny
The Nominum Nanny (“the Nanny”) monitors the state of Nominum products. It may be configured either
using the Nominum Command Channel or with a configuration file.
Starting the Nanny

To start the Nominum Nanny, type:
# nom_nanny
Command-Line Options
nom_nanny [ -c|--configuration file ] [ -f|--foreground ] \
[ -F|--foreground-with-syslog ] [ -h|--help ] [ -v|--version ]\
[ -V|--check ]
Nominum
nom_nanny 169
Option Description
-c , --configuration file Loads additional configuration from the configuration file.
Multiple configuration statements may appear.
-f, --foreground Runs the Nanny in the foreground, directing logging to the
terminal.
-F, --foreground-with-syslog Runs the Nanny in the foreground, directing logging to the
terminal as well as syslog.
-h, --help Displays the Nanny’s help message.
-v, --version Displays the version of the Nanny and exits.
-V, --check Reads and checks the Nanny's configuration for validity, and
exits. A 0 status indicates a valid configuration.
Table 11-3 nom_nanny Command-Line Options
nom_nanny Command Channel Messages

Command Channel (CC) messages may be sent to the Nanny through the nom_tell program. There are
two ways to send Command Channel messages. You can type them one at a time via the nom_tell pro-
gram:
# nom_tell nanny message
Or you can use nom_tell’s interactive mode, which is easier for sending several messages. To do so, type
the following to get to the nanny> prompt. Once at the nanny> prompt, you can type messages as
shown in the examples listed for each command. To start interactive mode, type:
# nom_tell nanny
nanny>
Nominum
Requests that fail return an error to the terminal.
Command Description
deregister Deregisters a child process. The syntax is:
deregister name
where name is the name of the child process.
nanny> deregister name=ans

die Causes the Nanny to exit cleanly.
nanny> die
kill Signals a child. If the signal tag is not specified, SIGTERM is
sent. If name is not specified, all child processes are signaled.
The syntax is:
kill name [signal]
nanny> kill name=ans

nanny> kill signal=SIGINT
nanny> kill signal=SIGHUP name=ans
The following Unix signals are understood by the Nanny:
• SIGINT—The Nanny sends SIGINT to all children, and exits

cleanly when they have all exited.
• SIGTERM—The Nanny sends SIGTERM to all children, and
exits cleanly when they have all exited.
• SIGHUP—Unlocks the Nanny.
lock Locks the nanny to prevent child registration or deregistra-
tion.
nanny> lock
pid Returns the process ID of nom_nanny.
nanny> pid
process-information Retrieves process information for nom_nanny.
nanny> process-information
Table 11-4 nom_nanny Command Channel Commands
Nominum
nom_nanny 171
Command Description
register Registers a child. The syntax is:
register name command
nanny> register name=ans

restart Restarts a child. If the name tag is not specified, all running
children are restarted. The syntax is:
restart [name]
nanny> restart
nanny> restart name=ans
start Starts a child. If the child is not already registered, the start com-
mand registers it and sets the auto-deregister option. The syntax
is:
start name
nanny> start name=ans

status Gets the status of a child process or of all child processes
(“children”). The syntax is:
status [name]
where name is the name of a child process. If no name is

specified, the status of all children is returned.
nanny> status
nanny> status name=ans
Table 11-4 nom_nanny Command Channel Commands (continued)
Nominum
Command Description
stop Stops a child process. If wait is a value interpreted as true,
the response isn’t sent until the child has stopped.
The syntax is:
stop name [wait=yes|no]
nanny> stop name=ans

nanny> stop name=ans
uuid Returns the uuid of nom_nanny.
nanny> uuid
version Returns the version of nom_nanny.
nanny> version
Table 11-4 nom_nanny Command Channel Commands (continued)
nom_nanny Configuration File

A nom_nanny configuration file is a sequence of lines that instruct the Nanny how it should configure
itself.
NOTE A configuration file is not required, and is loaded only when directed by the user.
A configuration line contains an option name, possibly followed by whitespace and then a value. If pres-
ent, the value is all of the remaining text on the line, including any non-leading whitespace. Blank lines
and lines starting with # are ignored.
Option Description
auto-deregister Deregisters the current child when it is stopped. The Nanny
“forgets” everything about this child after a stop command
for it is sent.
command value Sets the command to be executed for the current child to
value.
Table 11-5 nom_nanny Configuration File Options
Nominum
nom_nanny 173
Option Description
command-channel who secret Specifies the address and port to which Command Channel
commands should be sent.
If no secret is specified, who is the name of a service in

/etc/channel.conf. If a secret is specified, then who is an
addrport, and a port must be specified.
If secret is not “*”, only Command Channel requests
signed with secret are permitted to execute, and all Com-
mand Channel responses are signed with secret.
If specified as “*”, then Command Channel messages are not

validated or signed.
Specifying command-channel none disables the Com-

mand Channel.
configuration Loads additional configuration from the specified file.

Multiple configuration statements may appear.
core-size-limit Sets the default maximum corefile limit to either a value of
bytes or “unlimited”. The default is unlimited.
default-max-starts Sets the default maximum start count. See max-starts
below for more information. The default is 30.
default-restart-delay Sets the default restart delay. The default is 5 minutes.
defer-launch Instructs the Nanny not to launch the current child when the
Nanny starts. An explicit start command is required to start
the child.
directory path If specified before the first child statement, sets the Nanny’s
working directory to path. If specified in the context of a
child, the child is executed in path.
foreground Instructs the Nanny to run in the foreground, logging to the
terminal.
foreground-with-syslog Instructs the Nanny to run in the foreground, logging to the
terminal as well as syslog.
kill-delay delay Instructs the Nanny to wait delay seconds after it sends
SIGTERM to its children before sending SIGKILL.
Table 11-5 nom_nanny Configuration File Options (continued)
Nominum
Option Description
lock Locks out Command Channel changes that register or dereg-
ister children.
This is important for security, as otherwise any authorized

Command Channel client can use the Nanny to run any com-
mand as root.
max-starts value Instructs the Nanny to refuse to start a service if it restarts
more than value times in a minute.
restart-delay delay Instructs the Nanny to wait delay minutes to restart a “spin-
ning” child.
stderr Appends the standard error of the child to file. The default
standard error file is the file used for standard output.
stdout Appends the standard output of the child to file. The default
standard output file is /dev/null.
stop-on-clean-exit Instructs the Nanny to treat children that exit with status
code 0 (a “clean exit”) as if a stop command was issued for
the child.
username Executes the child using user id name.
Table 11-5 nom_nanny Configuration File Options (continued)
Nominum
A
Statistics
This chapter lists the statistics supported by the server.
The following statistics are available:
Name Description
cache-hit The number of cache lookups that found an existing node.
cache-miss The number of cache lookups that did not find an existing node.
cc-update-failure The number of Command Channel update-data messages that
resulted in a failure.
cc-update-success The number of Command Channel update-data messages that
resulted in success.
current-time The current time. Returned in all statistics queries, expressed as seconds
since the epoch (00:00 UTC, January 1, 1970).
current-time-hires The current time, in high resolution format. Returned in all statistics
queries, expressed as seconds since the epoch (00:00 UTC, January 1,
1970).
failure The number of queries that result in a failure response other than those
listed as specific types.
formerr A format error that resulted in a FORMERR response.
Table A-1 Statistics types
Nominum 175
176 Appendix A: Statistics
Name Description
notify-total The number of notifies received.
nxdomain The number of queries that result in an NXDOMAIN response.
nxrrset The number of queries that result in a NOERROR response with no data.
qtypes The number of queries of each type, such as MX queries.
referral The number of queries that resulted in referral responses.
refused A query to which a REFUSED response is returned.
reset-time The time of the last reset. Returned in all statistics queries and expressed
as seconds since the epoch (00:00 UTC, January 1, 1970).
query-total The number of queries received.
server-start-time The time the server was started, expressed as seconds since the epoch
(00:00 UTC, January 1, 1970).
slave-zone-count The number of slave zones in View.
success The number of successful queries made to the server or zone. A suc-
cessful query is defined as a query that returns a NOERROR response
other than a referral response.
system-time The amount of system CPU time consumed by the ANS process.
unknown-opcode The number of messages that contained an unknown opcode.
update-failure The number of failed DDNS updates.
update-forwarding-fail- The number of forwarded updates that failed.
ure
update-forward- The number of forwarded updates that were refused.
ing-refused
update-forwarding-suc- The number of forwarded updates that succeeded.
cess
update-notauth The number of DDNS updates that were not authoritative.
update-refused The number of DDNS updates that were refused.
update-success The number of successful DDNS updates.
update-total The number of updates received.
user-time The amount of user CPU time consumed by the ANS process.
view-load-time The time of last view load, expressed as seconds since the epoch (00:00
UTC, January 1, 1970).
Table A-1 Statistics types (continued)
Nominum
177
Name Description
zone-count The total number of zones being served.
zone-modifications The number of zone data changes by methods other than DDNS and
command-channel.
Table A-1 Statistics types (continued)
In addition, individual statistics are available for the query type (qtype) for all types less than 50, as well
as type ANY. All other qtypes are combined into one qtype statistic called other.
Nominum
178 Appendix A: Statistics
Nominum
B
ANS Events
This chapter describes the ANS events that can be requested by Command Channel clients. These events
are useful for organizations wishing to integrate ANS with other programs, or with an existing SNMP
(Simple Network Management Protocol) monitoring system.
When various interesting events occur, ANS will send a Nominum Command Channel event message to
all Command Channel clients which have requested that event. See the Nominum Command Channel API
manual for more information about the structure of event messages.
Each ANS Command Channel connection has an event subscription list. When the connection is estab-
lished, its initial subscription list will be empty. To request that events be sent, the client sends a
request-events command. This command can either be used to explicitly specify the desired events, or to
incrementally change the list. The show-events command displays the currently requested events. The
list-events command returns the list of all the events which ANS can generate.
Clients may dedicate a connection to receiving events, or they can use a single connection for both ordi-
nary traffic and events.
Below are some examples of how to use these commands using nom_tell in interactive mode. Since
events are sent over an existing connection, nom_tell in non-interactive mode would have no effect, as
the connection would be immediately closed when nom_tell exited.
Enter interactive mode with nom_tell so you see the ans> prompt.
# nom_tell ans
ans>
Nominum 179
180 Appendix B: ANS Events
Set the list of requested events to server-stop and server-reload:
ans> request-events events=(server/stop server/reload)
Additionally request the xfr-out/denied and update/refused events:
ans> request-events events+=(xfr-out/denied update/refused)
Turn off reporting of update/refused events:
ans> request-events events-=(update/refused)
List the currently registered events (the response will contain an events tag, as shown):
ans> show-events
{
type => 'show-events'
events => ('server/stop' 'server/reload' 'xfr-out/denied')
listening-for => ('server/stop' 'server/reload' 'xfr-out/denied')
}
The events item specifies the current recipe for choosing events, and the listening-for item tells
you the exact set of events the recipe specifies. In this case, they’re the same, but more complex recipes
are possible.
The special event names all and none represent all events and no events, respectively. Event names can
be preceded with a! character to indicate that they are explicitly not desired. For example, to request “all
events except update/refused” you would say:
ans> request-events events=(all !update/refused)

ans> show-events
{
type => 'show-events'
events => ('all' '!update/refused')
listening-for => ('zone-maintenance/up-to-date' 'update/failure'
'zone-maintenance/failure' 'update/not-auth'
'zone-maintenance/success' 'update/success' 'server/reload'
'xfr-out/denied' 'update/refused' 'server/stop'
'xfr-out/granted' 'server/restart')
}
Events typically contain additional context about what happened. For example, here are two sample
event messages about slave zone status, one for a zone which has just been validated as still up-to-date,
and another for a zone which is having trouble talking to its master:
{
type => 'zone-maintenance/up-to-date'
view => 'default'
zone => 'good.example'
Nominum
181

serial => '2004080600'
}
{
type => 'zone-maintenance/failure'
view => 'default'
zone => 'bad.example'
master => '127.0.0.2#53'
detail => 'too many SOA query retransmits'
}
Detailed information about the fields in events, including type information, is available in the ANS SNMP
MIB. The MIB nominum.txt is part of the package containing the nom_snmpagent program; the ans.txt
MIB is included as part of the ANS package. See Chapter 9, SNMP in ANS for more information about this
program.
Table B-1, “ANS Events,” describes the defined events:
Event Description
update/failure Sends events for all failed dynamic updates.
• client—The address and port of the client.

• view—The view containing the zone being updated.
• zone—The zone being updated.
• identity—The identity of the client performing the update.
update/not-auth Sends events for all update attempts for zones for which the server is
not authoritative.

update/refused Sends events for all refused dynamic updates. Refused updates are
those updates denied by the update authorization policy.

Table B-1 ANS Events
Nominum
Event Description
update/success Sends events for all successful dynamic updates.

• version—The database version number of the zone being
updated after the update completes.
view/modified Send events whenever a view’s configuration is modified.
• view—The view being modified.

xfr-out/granted Sends events whenever a zone transfer request is granted.

• view—The view containing the zone being transferred.
• zone—The zone being transferred.
xfr-out/denied Sends events whenever a zone transfer request is denied.

• view—The view containing the zone being transferred.
• zone—The zone being transferred.
• detail—Additional information about the cause of the denial.
zone/added Sends events whenever a zone is added to a view.
• view—The view containing the zone being added.

• zone—The zone being added.
• db—The database to which the zone is being added.
• zone-type—The type of the zone.
zone/deleted Sends events whenever a zone is deleted from a view.
• view—The view containing the zone being deleted.

• zone—The zone being deleted.
• db—The database from which the zone is being deleted.
• zone-type—The type of the zone.
Table B-1 ANS Events (continued)
Nominum
183
Event Description
zone/modified Sends events whenever a zone is modified.
• view—The view containing the zone being modified.

• zone—The zone being modified.
• db—The database containing the zone being modified.
• zone-type—The type of the zone being modified.
• content-changed—If present, indicates that the change was
to the zone’s content.
• configuration-changed—If present, indicates that the
change was to the zone’s configuration.
zone-maintenance/failure Sends an event when a zone transfer fails for a zone that needed
updating.
• view—The view containing the zone being maintained.

• zone—The zone being maintained.
• status—The current zone maintenance status.
• master—The master zone being used.
• detail—More information about the cause of the failure.
zone-maintenance/success Sends an event when a zone transfer succeeds for a zone that
needed updating.

• serial—The current serial number of the zone.
• master—The master zone being used.
zone-mainte- Sends events whenever a zone is determined to be up-to-date with
nance/up-to-date respect to all of its masters.

• serial—The current serial number of the zone.
Table B-1 ANS Events (continued)
Nominum
The following events are not view-specific, but rather are global options for the server. They are config-
ured in the default view for convenience.
Event Description
server/modified Sends events when the server’s configuration is modified.
server/reload Sends events when the server reloads.
server/restart Sends events when the server restarts.
server/stop Sends events when the server stops.
view/added Sends events when a view is added to the server.
• view—The view being added.

view/deleted Sends events when a view is deleted from the server.
• view—The view being deleted.
Table B-2 Non-View-Specific Events
Nominum
C
Logging Switches
ANS allows fine-grained, per-view control over what is logged. In addition, the view logging policy can be
overridden on a per-zone basis if needed.
To set logging, use the
log switch_name yes_or_no
view option, described in Table C-1 on page 185. For example,
log update/failure yes
This section describes the logging switches which may be configured.
Option Description
gsstsig/info Log additional information about GSS-TSIG failures.
notify-in/received Log DNS Notify messages received by the server, and for which
the server is authoritative. The default value of this switch is “no”.
notify-in/refused Log DNS Notify messages refused by the server because it is not
authoritative for the zone. The default value of this switch is
“no”.
Table C-1 Logging switches
Nominum 185
186 Appendix C: Logging Switches
Option Description
notify-out/acknowledged Log acknowledgements to DNS Notify messages sent by the
server when they are received. The default value of this switch is
“no”.
notify-out/sent Log DNS Notify messages when they are sent. The default value
of this switch is “no”.
query/answered Log DNS queries answered by the server. The default value of this
switch is “no”.
query/error Log DNS queries for which the server responded with an error
result other than “refused”. The default value of this switch is
“no”.
query/refused Log DNS queries refused by the server because it is not authorita-
tive for the question. The default value of this switch is “no”.
update/details Log detailed information about the content of an update, includ-
ing the names and types of updated data, and/or the reason an
update was refused. The default value of this switch is “yes”.
update/failure Log failed dynamic updates. The default value of this switch is
“yes”.
update/not-auth Log update attempts for zones for which the server is not author-
itative. The default value of this switch is “yes”.
update/refused Log refused dynamic updates. Refused updates are those updates
denied by the update authorization policy. The default value of
this switch is “yes”.
update/success Log successful dynamic updates. The default value of this switch
is “yes”.
update-forwarding/failure Log failed dynamic update forwarding.
The default value of this switch is “yes”.

update-forwarding/refused Log when dynamic update forwarding is refused.

update-forwarding/success Log successfully forwarded dynamic updates.

xfr-out/denied Log outbound zone transfer requests which are denied. The
default value of this switch is “yes”.
Table C-1 Logging switches (continued)
Nominum
187
Option Description
xfr-out/granted Log outbound zone transfer requests which are granted. The
default value of this switch is “yes”.
zone/added NOTE: Not usable with the zone option log-flags.
Log whenever a zone is added to a view. The default value of this

switch is “yes”.
zone/deleted NOTE: Not usable with the zone option log-flags.
Log whenever a zone is deleted from a view. The default value of

this switch is “yes”.
zone/loaded NOTE: Not usable with the zone option log-flags.
Log whenever a zone is loaded into a view as a result of process-

ing the view's import statements. The difference between
zone/loaded and zone/added is that the former logs zones when
they are loaded, and the latter when an incremental change is
made (e.g., via the command channel). Sites with large numbers
of zones may wish to turn off this option to improve loading per-
formance and reduce log clutter. The default value of this switch
is “yes”.
zone/modified NOTE: Not usable with the zone option log-flags.
Log whenever a zone's content or configuration is modified via

the command channel. The default value of this switch is “yes”.
zone-maintenance/failure Log failed zone maintenance attempts. The default value of this
switch is “yes”.
zone-maintenance/success Log successful zone transfers. The default value of this switch is
“yes”.
zone-maintenance/up-to-date Log whenever a zone is determined to be up-to-date with respect
to all of its masters. The default value of this switch is “no”.
zone-maintenance/xfr-details Log details about a zone transfer attempt, e.g., whether IXFR or
AXFR was used. The default value of this switch is “yes”.
Table C-1 Logging switches (continued)
Nominum
188 Appendix C: Logging Switches
The following log switches are not view-specific, but rather are global options for the server. They are
configured in the default view for convenience.
Option Description
command/executed Log details about valid Command Channel commands executed
by the server. The default value of this switch is “no”.
command/unknown Log details about unknown Command Channel commands
received by the server. The default value of this switch is “no”.
Table C-2 Global Logging Switches
Logging may also be set via a Command Channel command to update the view. See ”update-view” on
page 96 for more information and an example of setting logging switches over the Command Channel.
Nominum
D
Examples of Server and
View Operations
This chapter presents examples of common operational tasks that an ANS administrator may encounter.
These scenarios provide examples of various methods of communicating with ANS. This chapter high-
lights operations that pertain to the server itself and to views. It also describes how to run the server in a
“chroot() jail”, and some miscellaneous operations. See Chapter 8, Examples of Zone Operations, for
examples of operations that pertain to zone management.
Server Operations
Backing Up and Restoring ANS
Nominum recommends that you back up and archive your entire ANS data set and configuration on a
regular basis to minimize data loss in the event of a system or hardware failure. A comprehensive backup
involves the following files:
• The contents of the /var/nom/ans directory
• Two key configuration files
NOTE There is no need to shut down ANS in order to back up data. However, Nominum
strongly recommends that you not back up or restore files while ANS is performing a
checkpoint. See ”Best Practices” on page 191 for details.
Nominum 189
190 Chapter D: Examples of Server and View Operations
To back up ANS:
1. Issue a block-checkpoints command to forestall a checkpoint during the backup:
# nom_tell ans block-checkpoints timeout=7200
2. Use tar to back up the relevant files:
# tar czf <name>.tgz /var/nom/ans/* /etc/ans.conf /etc/channel.conf
NOTE A configuration file is optional for server operation. If there is no /etc/ans.conf file, just
back up /etc/channel.conf.
3. Issue an unblock-checkpoints command to re-enable checkpointing:
# nom_tell ans unblock-checkpoints
Restoring
To restore your files:
1. Stop the ans server:
# /etc/init.d/ans stop
2. Change to the root directory:
# cd /
3. Extract the files contained in the backup from which you wish to restore:
# tar xf ans-backup.tar
4. Start the ans server:
# /etc/init.d/ans start
NOTE When restoring your data, you will see additional log messages related to that restore;
this is normal when recovering from a backup.
Nominum
Server Operations 191
Best Practices
Nominum strongly recommends that you not back up or restore ANS files while a checkpoint is in pro-
cess. While you cannot have complete control over when ANS runs a checkpoint process, you can signifi-
cantly reduce the odds of the backup and the checkpoint colliding by running a manual checkpoint
before backing up. See ”checkpoint” on page 76.
Listening and Not Listening

When it comes to listener syntax, there are three different configuration statements that have influence
on the end result.
The three ans.conf listener commands are:
• listen-on-port port
• listen-on addrport
• listen-on-matching port pattern
NOTE You can have listen-on, or listen-on-matching, but not both.
listen-on-port establishes port as the default port. Subsequent listen-on or lis-

ten-on-matching statements that do not specify a port will use the listen-on-port port.
If there is no explicit listener configuration, the default is equivalent to
listen-on-port 53
listen-on-matching 0.0.0.0/0
If there are no listen-on or listen-on-matching statements, but there is a listen-on-port, then a

show-server command will include
listen-on-port => ‘port’
If one or more listen-on statements are present, then show-server will include
listen-on => listen-on-list
where listen-on-list is a list of strings, and each string is either a port number or an IP address (v4 or
v6). The port number is the port to use for subsequent IP addresses in the list. The default port is 53, so if
the list starts with an IP address, it means that address, port 53.
Some examples:
Nominum
(‘127.0.0.1’ ‘5354’ ‘::1’ ‘10.1.0.1’ ‘5355’ ‘10.2.0.1’)
This is equivalent to:
listen-on 127.0.0.1
listen-on-port 5354
listen-on ::1
listen-on 10.1.0.1
listen-on-port 5355
listen-on 10.2.0.1
and also equivalent to:
listen-on 127.0.0.1#53
listen-on ::1#5354
listen-on 10.1.0.1#5354
listen-on 10.2.0.1#5355
If one or more listen-on-matching statements are present, then show-server will include
listen-on-matching => listen-on-matching-list
where listen-on-list is a list of pattern, and pattern is one of:
port
none
[!](network-prefix-pattern | interface-pattern | special)
and special is
('any' | 'localhost' | 'localnets' )
The port number is used in the same way as listen-on above. It cannot be negated.
localhost means “any of this host’s interface addresses”. localnets means “any address on any net-
work this host is directly connected to”. none is the same as !any and cannot itself be negated.
A network-prefix-pattern has the form
address [‘/’ prefix-length]
If prefix-length is not specified, it defaults to 32 for IPv4 and 128 for IPv6. If the pattern starts with
“!”, it means “anything matching this pattern should not be listened-on”.
An interface name is operating-system specific, but is typically something like eth0. Interface patterns
match both IPv4 and IPv6 addresses on the matching interface.
For example:
('::1' 'eth1' '5354' '!10.0.0.0/8' 'any')
Nominum
is equivalent to:
listen-on-matching ::1
listen-on-matching eth1
listen-on-port 5354
listen-on-matching !10.0.0.0/8
listen-on-matching any
As another example, suppose the following interfaces are active on the following IP addresses:
eth0: 10.1.1.1
eth1: 10.2.1.1
eth2: 10.3.1.1
eth3: 10.4.1.1
eth4: 10.5.1.1
If so, the statement
will listen on all of the above interfaces/addresses.
Note that the OS limits on the number of IP addresses/interfaces that can be listened on in total still apply.
It’s not literally possible to listen on the tens of thousands of addresses in a /8 network. ANS can create up
to 600 listening sockets, however.
Table D-1 contains examples of sets of listening commands, and the effect they have. The descriptions of
the effects of the statements assume that the lines which are grouped together in the table are the only
listening statements in the configuration file.
Configuration Effect
No listen-on statement (Default) Listen on port 53 on all interfaces.
listen-on-port 5354 Listen on port 5354 on all interfaces.
listen-on-port 5354 Listen on port 5354 on interfaces whose addresses
match 10.0.0.0/8.
listen-on-port 5354 Listen on port 5354 on interfaces whose addresses
match 10.0.0.0/24 or 127.0.0.0/8.
listen-on-matching lo0 Listen on port 53 with the addresses of the inter-
face named lo0.
Table D-1 Listen-on Configuration Statement Examples
Nominum
Configuration Effect
listen-on-matching 10.0.0.0/8 Listen on port 53 on interfaces whose addresses
match 10.0.0.0/8.
listen-on-port 1234 Listen on port 1234 with the addresses of the inter-
face named eth0.
listen-on 127.0.0.1#5354 Listen on 127.0.0.1#5354.
listen-on-port 5354 Listen on 127.0.0.1#5354.
listen-on 127.0.0.1
Table D-1 Listen-on Configuration Statement Examples (continued)
It is not recommended that ANS be configured with listen-on 0.0.0.0 because if the ANS server has
several interfaces, it’s possible that queries sent to one of those aliased IP addresses will be returned from
a different address and thus likely ignored by the client. The statement listen-on-matching
0.0.0.0/0, however, is fine.
Forcing Zone Maintenance

“Zone Maintenance” is the process of keeping slave zones up-to-date with their masters. ANS will period-
ically poll the masters for a slave to see if anything has changed. ANS implements the DNS Notify proto-
col, and schedules a slave zone for updating if it receives a notification that the zone has changed.
There are times, however, when you want to update a slave immediately instead of waiting for a Notify or
the periodic poll. Perhaps a network failure caused ANS to miss Notify messages, or the administrator of
the master did not arrange for your server to get notification. The force-maintenance command sched-
ules a slave zone for maintenance as soon as possible. Here’s an example:
ans> force-maintenance zone=example.org
Limiting Zone Transfers from ANS

ANS allows zone transfers by default. The allow-transfer zone option allows you to specify which
hosts or TSIG keys are granted or denied the right to do zone transfers. For example, to allow zone exam-
ple to be transferred to any IP address on net 10 and anyone who can sign a request with the ns1-ns2.
TSIG key, you’d say:
ans> update-zone zone=example \

allow-transfer=(10.0.0.0/8 ns1-ns2.)
We can also deny transfers to specific addresses. For example, to allow transfers from 10.0.0.0/8
except for from 10.1.0.0/24, you could say:
Nominum
ans> update-zone zone=example \

allow-transfer=(!10.1.0.0/24 10.0.0.0/8)
NOTE If you’re using csh as your shell, you’ll need to escape ‘!’ with a ‘\’.
To forbid zone transfers altogether, simply specify an empty allow-transfer list:
ans> update-zone zone=example allow-transfer=()
Enabling or Disabling DNS Notify

ANS sends DNS Notify messages when zones change by default. Additional servers to be notified are
specified with the also-notify zone field. For example, to notify hosts 10.0.0.1 and 10.0.0.2
when zone example changes:
ans> update-zone zone=example also-notify=10.0.0.1,10.0.0.2
To turn off Notify, set the notify field to no:
ans> update-zone zone=example notify=no
To turn it back on, specify notify=yes.
Offline Loading, Dumping, and Deletion

It’s also possible to do load, dump, and delete master zones more efficiently by writing directly to the
database, rather than doing these operations while the server is running. Direct updates to the database
can only be done when the server is not running, however. Nothing bad happens if you accidentally try to
work with a database directly while the server is running. Here’s an example:
# ans_dump -d vdb example dbfile=big.db

ans_dump: critical: could not register or load driver for 'vdb', or could
not initialize database: in use
You’ve added -d vdb to tell ans_dump that you want to use the VDB driver instead of the default driver,
which is the pseudo-driver cc. (The cc driver uses the Nominum Command Channel to provide a remote
procedure call interface to databases loaded in an ANS server.) When using the vdb driver, you must also
Nominum
provide a dbfile=filename parameter if you want to access a database other than the default data-
base master.db. Let’s load zone example into the big database.
# cd /etc/init.d/ans
# ans_load -d vdb example example.master dbfile=big.db
When used with the vdb driver the database files are read or written from the current working directory,
so you had to connect to /var/nom/ans—that’s where your databases are.
Using server-id to Identify Servers

You can use dig in combination with the server-id view option to identify what nameserver you’re
communicating with, particularly if your network involves multiple nameservers behind a load balancer, or
you are in an anycast environment:
[ns1~]$ dig @192.168.1.0 id.server chaos txt
; <<>> DiG 9.2.2 <<>> @192.168.1.0 id.server chaos txt

;; Got answer:
;; QUESTION SECTION:
;id.server. CH TXT
;; ANSWER SECTION:
id.server. 0 CH TXT "15024c22-c97b-4cc8-95cd-6f7779f431f0"
;; Query time: 456 msec

;; SERVER: 192.168.1.0#53(192.168.1.0)
;; WHEN: Mon Aug 2 10:24:24 2004
;; MSG SIZE rcvd: 76
Running Nominum ANS in a chroot() Jail

To limit damage resulting from attacks, many security-conscious nameserver administrators prefer to run
BIND in a chroot() “jail” where only a subset of the host's filesystem is available to the named process.
Nominum ANS provides command-line options which allow the ans process to operate in the same way.
Solaris
To create a chroot() jail for ANS on Solaris:
1. Login as a superuser—permissions will be changed at the completion of jail construction.
Nominum
Running Nominum ANS in a chroot() Jail 197
2. Create the base directory of the jail if it does not already exist. For this example, it’s assumed to
be /chroot/ans:
# mkdir -p /chroot/ans
3. Create a ans user and group:
# groupadd ans
# useradd -g ans -d /chroot/ans -s /bin/true ans
4. “Lock” the ans user account. This account has no login.
# passwd -l ans
5. Make the jail the working directory:
# cd /chroot/ans
6. Create the jail hierarchy:
# mkdir dev
# mkdir etc
# mkdir -p usr/local/
# mkdir -p usr/share/lib/zoneinfo
# mkdir -p var/nom/
# mkdir -p /chroot/ans/proc
7. Copy the /etc/channel.conf file:
# cp /etc/channel.conf etc
8. Copy the ans.conf file. If one does not exist, it must be created. A simple file consists of the sin-
gle statement directory /var/nom/ans:
# cp /etc/ans.conf etc
9. ANSansansCopy the ANS executable files:
# cp -r /usr/local/nom usr/local/
10. Copy the time-zone files, or syslog will contain timestamps for GMT. This example is for the
United States—modify the command for the timezone as needed.
# cp -r /usr/share/lib/zoneinfo/US usr/share/lib/zoneinfo
11. Create devices null, random, poll and zero in the jail. Use the ls -lL command to determine
the major and minor device numbers for the system as suggested by the following example:
# ls -lL /dev/conslog /dev/log /dev/null /dev/zero /dev/random

crw-rw-rw- 1 root sys 21, 2 Oct 27 11:28 /dev/conslog
Nominum
crw-rw-rw- 1 root sys 21, 0 Oct 27 11:28 /dev/log

crw-rw-rw- 1 root sys 13, 2 Oct 27 11:28 /dev/null
crw-r--r-- 1 root sys 197, 0 May 29 2003 /dev/random
crw-rw-rw- 1 root sys 13, 12 May 29 2003 /dev/zero
# mknod dev/null c 13 2
# mknod dev/random c 197 0
# mknod dev/poll c 138 0
# mknod dev/zero c 13 12
# mknod dev/log c 21 5
# mknod dev/conslog c 21 0
12. As noted above, ownership/permissions issues were deferred. Set privileges now.
# chown -R ans .
# chgrp -R ans .
# chmod o etc/channel.conf
13. Start the “jailed” copy of ANS as the ans user:
# /chroot/ans/usr/local/nom/sbin/ans --user ans \

--root /chroot/ans -c /etc/ans.conf
14. For completeness, this startup command must be put into the service script
/etc/init.d/ans so that the nameserver is properly started (as user ans) when the host
reboots.
Restarts When Running as a Non-Root User
When running as a non-root user, ANS does not restart itself when the following Com-
mand-Channel-based configuration changes are made:
• delete-view (when the view is the default view)
• update-server
• restart
In these cases, the administrator must restart ANS manually or the changes will not take
effect, and ANS logs an error message.
Red Hat Enterprise Linux

1. Login as a superuser—permissions will be changed at the completion of jail construction.
2. Create the base directory of the jail if it does not already exist. For this example, it’s assumed to
be /chroot/ans:
# mkdir -p /chroot/ans
Nominum
Running Nominum ANS in a chroot() Jail 199
3. Create a ans user and group:
# groupadd ans
# useradd -g ans -d /chroot/ans -s /bin/true ans
4. “Lock” the ans user account. This account has no login.
# passwd -l ans
5. Make the jail the working directory:
# cd /chroot/ans
6. Create the jail hierarchy:
# mkdir dev
# mkdir etc
# mkdir -p usr/local/
# mkdir -p var/nom/
7. Copy the /etc/channel.conf file:
# cp /etc/channel.conf etc
8. Copy the ans.conf file. If one does not exist, one must be created. A simple file consists of the
single statement directory /var/nom/ans):
# cp /etc/ans.conf etc
9. ANSans# ansMake sure that the file uuid exists in the jail after the copy:
# ls -l var/nom/ans
If the uuid file does not exist, copy it over:
# cp -r /var/nom/ans/uuid var/nom/ans
10. Copy the ANS executable files:
# cp -r /usr/local/nom usr/local/
11. Copy the time-zone files, or syslog will contain timestamps for GMT.
# cp /etc/localtime etc
12. Create devices null, random and zero in the jail. Use the ls -lL command to determine the
major and minor device numbers for the system as suggested by the following example:
# ls -lL /dev/null /dev/zero /dev/random

crw-rw-rw- 1 root root 1, 3 Sep 15 2003 /dev/null
Nominum
crw-r--r-- 1 root root 1, 8 Sep 15 2003 /dev/random

crw-rw-rw- 1 root root 1, 5 Sep 15 2003 /dev/zero
# mknod dev/null c 1 3
# mknod dev/zero c 1 5
# mknod dev/random c 1 8
13. Modify syslogd so that logging happens within the jail, as ANS won't have access to logging
outside the jail. Edit /etc/sysconfig/syslog to replace the line
SYSLOGD_OPTIONS="-m 0"
with
SYSLOGD_OPTIONS="-m 0 -a /chroot/ans/dev/log"
Then stop and restart syslogd:
# /etc/rc.d/init.d/syslog stop
# /etc/rc.d/init.d/syslog start
This will create the file /chroot/ans/dev/log to which ANS will log.
14. As noted above, ownership/permissions issues were deferred. Take care of that now:
# chown -R ans .
# chgrp -R ans .
# chmod o= etc/channel.conf
15. Start the “jailed” copy of ANS as the ans user:
# /chroot/ans/usr/local/nom/sbin/ans --user ans --root /chroot/ans -c

/etc/ans.conf
16. For completeness, this startup command must be put into the service script /etc/init.d/ans so
that the nameserver is properly started (as user ans) when the host reboots.
View Operations
Creating A View
ANS supports the concept of multiple views of the DNS that was introduced in BIND 9. Many organiza-
tions would like to keep the details of their namespace private, except to their internal systems. There are
thus two views of the company’s namespace: an internal full view, and an external view of a typically very
restricted namespace, often just a few servers providing essential services such as WWW, mail, and DNS
to the Internet.
Nominum
View Operations 201
Up until this point, you’ve only been using a single view, named default, which ANS provides when no
views have been configured by the administrator.
Let’s assume your organization uses network 10 addresses on its internal network, and that you want to
give your internal clients a different view of the organization’s DNS than that given to the Internet.
First, create the internal view:
ans> add-view view=internal match=(10.0.0.0/8)
In addition to creating a view configuration object, this command also adds an import-view statement
to the server’s global configuration file and restarts the server.
The order of import-view statements in the server configuration file is important. When a client
request arrives, ANS tries to find a view from which to answer, examining views in the order in which they
were imported until one matches. If no view matches, the request is refused. The default view, how-
ever, is always tried last.
NOTE import-view statements must appear before any per-view statements in the configu-
ration file. If a per-view statement executes without any prior import-view, the
per-view statement will fail.
Clients can be matched by one, or both, of their source IP address and their target IP address (“IP” means
both IPv4 and IPv6 here). The match item in the command above matches any client whose source is on
the /8 network 10.0.0.0.
You could also have specified the same set of addresses using a range like this:
ans> update-view view=internal match=(10.0.0.0-10.255.255.255)
Note that when you want to refer to a view other than the default, you must add a view=viewname
clause to the command. More complicated rules are possible, including “negative matches” which
exclude clients from the view explicitly.
For example, let’s say you wanted to put all of network 10 except for 10.1.0.0/24 into the internal
view:
ans> update-view view=internal match=(!10.1.0.0/24 10.0.0.0/8)
The other kind of matching is based on the destination address of the client’s request. Maybe you have a
nameserver with two interfaces, one to the internal network and one to the external network. In that
case, you might want to match requests to the internal interface to the internal view like this:
ans> update-view view=internal match-to=10.2.0.128
Nominum
Negative matching works for match-to as well. If you configure both match-to and match rules for the
same view, then clients will only be served from that view if both rules are positive matches.
Be careful with IP address matching. In particular, you need to make sure that your firewalls have appro-
priate rules to block packets with internal addresses from external networks, because ANS cannot tell
where a packet came from, just what address it has.
Once you’ve created views and set up the matching rules, all you need to do is add zones to the views like
you did to the default view earlier. The only differences are that for nom_tell commands you should
add a view=<viewname> clause, and for database commands such as ans_load you should add
--view <viewname>. You can use -v instead of --view if you prefer. For example:
# ans_load --view internal example example.master
Deleting a View
You can delete the internal view created above by running:
ans> delete-view view=internal
Importing a BIND Configuration

An existing BIND 8 or BIND 9 configuration can be imported into ANS with the ans_import command.
Assume the following BIND configuration in named.conf:
options {
directory "/var/named";
listen-on { 10.0.0.0/8; };
};
zone "example" {
type master;
file "example.master";
notify no;
};
zone "example.org" {
type slave;
file "example.org";
masters { 192.168.1.1; };
};
To import the configuration, do the following:
1. If ANS is currently running, shut it down. ans_import can only be issued when the server is not
running.
Nominum
View Operations 203
2. Connect to the directory which has ans and import the named.conf file.
# cd /etc/init.d/ans
# ans_import /etc/named.conf
You will see the following messages:
Loading master zones...

/usr/local/nom/sbin/ans_load -d vdb default example
/var/nom/named/example.master base=master notxn
Done.
The import process issues an ans_load command for every master zone in the BIND configuration, and
loads the data into the master database. You may have noticed that the ans_load command used by the
importer looks a bit different from what you’ve seen so far—this is an example of offline loading. See
”Offline Loading, Dumping, and Deletion” on page 195 for more information.
NOTE By default, importing replaces any existing configuration with the imported configura-
tion, so if you have added some additional zones as part of experimenting with
ans_load, ans_dump or nom_tell, you will see some zone deletions before the Loading
master zones message.
The importer creates or modifies a number of files in the current directory, as well as creating
/var/nom/ans.conf. In general, ANS server configurations imported from BIND will include the following
lines:
directory /var/nom/ans
For an explanation of listen-on-matching, see ”Listening and Not Listening” on page 191.
Reimporting a BIND Configuration

ans_import can be used to re-import a previously imported BIND configuration. Re-importing is for cus-
tomers who have software or procedures that expect to store DNS configuration information in the BIND
style. If you’re in this situation, you can continue using your existing processes and re-import the data into
ANS rather than immediately convert to the way ANS does things.
ans_load, as executed by ans_import, tries to be intelligent when re-importing, comparing the new con-
figuration to the existing configuration, and making only those changes required to turn the existing con-
figuration into the new configuration. In particular, it will not reload DNS master files which have not
Nominum
been updated, and it does not discard slave zones which have at least one master in common with the
new configuration.
There is no additional syntax for re-importing; just run ans_import again from the same directory and
with the same arguments.
WARNING! Make sure the server is not running when you issue this command.
Nominum
E
ANS Files
Introduction
ANS works with a number of different file types, all of which are described briefly in this chapter.
The ANS Working Directory

DNS configuration and zone data are stored in the ANS working directory, which is /var/nom/ans by
default. A different working directory may be specified using the directory option in the global config-
uration file.
Nominum 205
206 Appendix E: ANS Files
ANS Files Quick Reference

File Name Description
/etc/ans.conf May also be specified by the file name in the “-c” or “--configu-
ration” option when ANS is started.
Server configuration file (a.k.a. “global configuration”). Includes

listen-on, syslog configuration, database definitions, etc. This is a
text file whose form is described in the ANS man page. The
server must be restarted for changes to take effect.
See ”The Server Configuration File” on page 208.

base.vdb VDB database data
base.vdi VDB database indexes
base.vdl VDB lock file (need not be backed up, but harmless to do so)
base.vdjid VDB journal file. id is the journal file id number. For example,
0000000001. There may be many journal files—they accumu-
late until the database is closed or checkpointed.
viewname.vc View configuration. This is a text file whose form is described in
the ANS man page. It may be edited by the user when the server
is not running. (When the server is running, use a nom_tell
update-view command.)
See ”The View Configuration File” on page 208.

viewname.zc Configuration information for all zones in a view. This is a binary
file. It can be converted to and from a textual format with the
ans_dumpzoneconf and ans_loadzoneconf commands.
See ”The Zone Configuration Files” on page 209.

viewname.zc.membak Backup copy of the view’s .zc file. Used along with the .memjnl
file to recover changes made to zone configuration in case of a
system failure. Do not remove .membak files unless you are
destroying the view.
Table E-1 ANS Files Quick Reference
Nominum
ANS Files Quick Reference 207
File Name Description

viewname.zc.memjnl Transaction journal of zone configuration changes. Used along
with the .membak file to recover changes made to zone configu-
ration in case of a system failure. Do not remove .memjnl files
unless you are destroying the view.

viewname.zc.memlock Lock file for zone configuration. Do not remove .memlock files
unless you are destroying the view.

viewname.cache View DNS authority cache. When not running, the server stores
its authority cache. Removing this file is harmless, but will cause
the server to do extra work to fill its cache the next time it is
started.
See ”The Database Cache” on page 209.

viewname.zmaint Zone maintenance state. When not running, the server stores
information about the maintenance state of the slave zones for
each view.
See ”The Zone Maintenance State” on page 210.

viewname.mtimes Master file modification times. Used by ans_import’s re-import
feature in order to avoid reloading master zones which have not
changed since the prior import.
viewname.sizes Size hints for various internal tables. Used by the server to reduce
startup time.
.cc_dups Used when the server is not running to store duplicate suppres-
sion information about recent Command Channel messages.
See ”VDB Database Files” on page 210.

/etc/channel.conf Configuration information for the Nominum Command Channel.
Used by ANS to determine the Command Channel TCP port ANS
should listen on, and the secret it should use.
See ”VDB Database Files” on page 210.
Table E-1 ANS Files Quick Reference (continued)
Nominum
The Server Configuration File

The ANS server configuration file, also called the global configuration, is used to configure all the options
that apply to the server as a whole. By default, ANS gets its server configuration from /etc/ans.conf. An
alternative configuration file may be specified by adding -c filename or --configuration file-
name to the command line when starting the server.
The server configuration file is optional. If a configuration file was not specified on the command line,
and /etc/ans.conf does not exist, ans uses a default configuration, which:
• listens on all interfaces using port 53
• uses the default view
• listens for Nominum Command Channel requests on the ans channel
• uses two VDB databases, master and slave
The server configuration file may be edited while the server is running. Changes do not take effect until
the server is restarted.
directory /dns
db mydb vdb dbfile=mydb.db
import-view internal
import-view external
syslog-facility local0
Figure E-1 Sample Server Configuration File
View Files
Several files have the form viewname.suffix. For example, internal.vc is the view configuration file for
view internal, and external.zmaint is the zone maintenance state file for view external. Only the
“.vc” file is human-readable and editable. View files should only be modified or removed in accordance
with the rules for the file type, as described below.
The View Configuration File

Every view has a configuration file named “viewname.vc”. View configuration files are ordinary text files
containing view options as described in Chapter 2, Getting Started With ANS.
Nominum
View Files 209
WARNING! Do not edit .vc files while the server is running. Use the Nominum Command Chan-
nel to make the desired changes.
When the server receives a Nominum Command Channel message changing a view’s configuration, it
updates that view’s configuration file automatically. It is thus important not to make changes by hand
since they will be overwritten if the server writes the view configuration. For more information on view
configuration file syntax, see “Views” on page 12.
import master
import slave
cache-filename default.cache
server-id c17a775a-0ff6-46b3-a110-823cffd7c0c1
slave-db slave
transfers-in 10
log notify-out/sent yes
Figure E-2 Sample View Configuration File
The Zone Configuration Files

All zone configuration information for a view, e.g., lists of master servers, update policies, notification set-
tings, etc. are stored in the viewname.zc file. This file is in a binary format so it can be loaded very
quickly.
While the server is running, there will also be files with names of the form viewname.zc.suffix, for
example default.zc.membak, default.zc.memjnl, and default.zc.memlock. These files are used to make
zone configuration changes transactional. Deleting these files is safe only if you are deleting the entire
view.
Nominum recommends that changes to zone configuration be made using the Command Channel.
The Database Cache

ANS caches DNS data retrieved from its databases, which can greatly increase the performance of the
server. When ANS exits, it writes the cache to disk in a file called viewname.cache. The next time the
Nominum
server starts, it reloads the cache. If the new query load is similar to the old query load, the server will be
starting with a “hot” cache and be at its best immediately.
It is always safe to delete this file, but the server’s query-per-second rate may be lower while it acquires a
new cache.
It is not necessary to delete this file if you make changes to an ANS database while the server is offline,
for example by running ans_load or ans_import. The server examines all cached data when it loads the
cache, and any data which is no longer current will be discarded.
The Zone Maintenance State

While ANS is running, it keeps information about each slave zone, for example, whether the zone is cur-
rent or not, and when the last transfer attempt for the zone occurred. When the server is shut down, it
creates a zone maintenance state file for each view. The filename has the form viewname.zmaint. When
ANS next starts, it will load this state, adjust for any time that elapsed while it was not running, and then
resume maintenance.
To force zone maintenance to occur for a given zone, issue a force-maintenance or force-transfer com-
mand.
The Master File Import Times

When the ans_import command is used to import a BIND configuration, it creates files with names of
the form viewname.mtimes. These files allow the importer to do “intelligent re-import” of a configura-
tion, loading only those master files which have changed since the prior import. See ”ans_import” on
page 110 for more information on this feature.
VDB Database Files

Following are the files you will see when using a VDB database. None of the files should be deleted,
unless you’re trying to destroy the database, in which case they all should be deleted.
In the table below, base denotes the base name of the VDB, such as master or slave.
Filename Description
base.vdb database data
base.vdi database indexes
Table E-2 VDB Database Files
Nominum
ANS and the Nominum Command Channel 211
Filename Description
base.vdl lock file
base.vdj<id> journal file.
The <id> value is the journal file id number, for
example 0000000001. There may be many journal
files—they accumulate until the database is closed
or checkpointed.
Table E-2 VDB Database Files (continued)
ANS and the Nominum Command Channel

By default, ANS looks for an ans service entry in the file /etc/channel.conf to get the TCP port and secret
to use for Command Channel connections to it. Alternate service names, ports, and secrets may be spec-
ified in the ANS server configuration file.
ANS creates a file called .cc_dups in its working directory when it exits. This file contains information
about recently received Command Channel messages, and is used to guard against replay attacks.
Nominum
Nominum
Index
A B
absolute version flag 103 backend driver name 104
aclpat 36 BIND 43, 196
addrpat 35 block-checkpoint 76
addrport 35 builtin-acl 36
add-view 73
options
log185 C
add-zone 73, 75 cache-filename option 41
allow-notify option 47 cache-size option 41
allow-transfer option 47 cc 27
allow-update option 47 cc pseudo-driver 27
allow-update-forwarding option 47 changing configuration information using
also-notify option 48 update-zone 130
ans channel.conf
command-line options 9 alternate service definitions in 102
-c 9 defining an ANS instance other than ans in 102
chroot() and 10 channel.conf file 68—69, 71
-F 9
example entries 68
-f 9
-h 9
nom_tell behavior in the absence of entries 69
-r 10 security considerations with 71
-u 10 checkpoint 73, 76
--usage 10 checkpoint-interval global option 36
-V 10 child argument 172
-v 10 chroot() 11, 196
ans command 9 command-line options and 10
ANS logging switches on Solaris 196
gsstsig/info 185 RHEL and 198
ans_import 96 clear statistics counters 93
ans_load client match 43
command options command 188
--check 105 command argument 172
options command channel 67
-c 105
Command Channel commands
--check 105
add-view 73
ans_signer options 166
add-zone 73, 75
ans_signer program 165
checkpoint 73, 76
authoritative DNS cache 41
delete-view 73, 76
auto-deregister argument 172
delete-zone 73, 77
Nominum ANS 213

214 Index
flush 73, 77 DDNS restrictions for 20

force-maintenance 73, 78 database
force-notify 73, 78 matching to an SOA 103
force-transfer 73, 78 specifying a relative version for 103
list-drivers 74, 89 specifying an absolute version for 103
list-events 73, 78 database driver
pid 79 cc pseudo 27
process-information 79 Command Channel 29
purge-zone 74, 79 file 27, 30
reopen-log-files 74, 80 database driver name 104
request-events 74, 80 database revision flags 103
restart 80 db global option 37
show-data 74, 81 DCS
show-events 74, 80 SNMP and 144
show-maintenance 74, 82 DDNS
show-server 74, 84 restrictions on data templates 20
show-view 74, 85 update policy 76
show-zone 74, 87 DDNS update policy 76
statistics 74, 90 defining an alternate ANS instance
stop 74 in channel.conf 102
update-data 74, 94 $DELETE 109, 134
update-server 74, 96 directive forms of 134
delete
update-view 74, 96
using in combination with update-zone or
update-zone 74, 99
update-view 89
uuid 94
delete-view 73, 76
version 74, 100
delete-zone 73, 77
Command Channel database driver 29 destruction-wait 83
command-channel 146
differential updates 99
command-channel argument 173
directory 147
command-channel global option 36 directory global option 37
command/executed 188
displaying a product’s version using nom_tell 69
commands-not-logged global option 37
displaying help for 169
command/unknown 188 displaying nom_tell’s version 72
configuration argument 173
DNS master file format 113
configuration file content merging 111 dns-port
configurations listen-on-port and 39
validating 169
dns-port global option 37
conf-template option 48 DNSSEC
converting a slave zone into a master with defining private key keystores for 42
update-zone 129
keystore-filename and 42
core-size-limit argument 173 driver 147
creating a chroot() jail 196
driver argument 104
current-task 82
driver global option 38
driverarg argument 104
D driver-specific configuration options 149
data templates
Nominum ANS
Index 215
E gss-credentials option 41
gsstsig/info 185
empty-nonterminals option 48
entering one-line mode in nom_tell 71
/etc/channel.conf H
See configuration file
help
events 150, 179
nom_nanny 169
expired maintenance status 82
hmac-md5 42
external file
hmac-sha1 42
logging queries to 44
F I
import database 41—42
file database driver 27, 30
flags import option 42
database revision 103 import-view global option 38
flush 73, 77 inbound zone transfer count 45
force-maintenance 73, 78 $INCLUDE 109
force-notify 73, 78 increasing verbosity using nom_tell 72
interactive mode
force-transfer 73, 78
determining using nom_tell 72
fully qualified domain name of zone 104
invisible-cnames option 49
G K
$GENERATE 109—110
key option 42
global configuration 208
keystore-filename
global options
DNSSEC and 42
checkpoint-interval 36
keystore-filename option 42
command-channel 36
commands-not-logged 37
db 37 L
directory 37
dns-port 37 list-drivers 74, 89
driver 38 listen-on global option 38
import-view 38 listen-on-matching global option 38
listen-on-port
listen-on 38
dns-port and 39
listen-on-matching 38
listen-on-port global option 39
listen-on-port 39
list-events 73, 78
lock-filename 39
load a configuration file
max-tcp-clients 39
nom_nanny 169
max-udp-clients 39
load-driver 150
setup-errors-fatal 39
lock-filename global option 39
syslog-facility 39
log 147
udp-buffer-size 39
log option 42, 185
umask 39
log switch syntax 98
versioncheck-interval 40
log-flags option 50
without-rmi 40
logging switches 185
Nominum ANS
216 Index
command/executed 188 MIBs, Nominum-specific 143

command/unknown 188 minimize-responses option 43
notify-in/received 185 minseverity 148
notify-in/refused 185
notify-out/acknowledged 186
notify-out/sent 186 N
query/answered 186 needs-maintenance maintenance status 82
query/error 186 needs-transfer maintenance status 82
query/refused 186 Net-SNMP command-line tools 152
update/details 186 Net-SNMP command-line tools, snmpget 154
update/failure 186 Net-SNMP command-line tools, snmptranslate
update-forwarding/failure 186 153
update-forwarding/refused 186 Net-SNMP command-line tools, snmptrapd 155
update-forwarding/success 186 Net-SNMP command-line tools, snmpwalk 153
update/not-auth 186 NETWORK-SERVICES-MIB.txt 143
update/refused 186 never-transferred maintenance status 82
update/success 186 next-task 82
xfr-out/denied 186 Nominum Command Channel 67, 73, 102, 179
xfr-out/granted 187 NOMINUM-AGENT-CAPS-MIB 143
zone/added 187 NOMINUM-NSM-MIB 143
zone/deleted 187 NOMINUM-NSN-MIB 143
zone/loaded 187 NOMINUM-PCS-MIB 143
zone-maintenance/failure 187 NOMINUM-QRS-MIB 143
zone-maintenance/success 187 NOMINUM-SMI-MIB 144
zone-maintenance/up-to-date 187 Nominum-specific MIBs 143
zone-maintenance/xfr-details 187 NOMINUM-TC-MIB 144
zone/modified 187 nom_keytool 167
nom_keytool subcommand
delete 167
M from-bind-dnskey 168
masteragent 148 from-bind-key 168
masters option 50 generate 167
match address statement 43 list 167
match option 43 make-ds 167
match-to option 43 to-bind-dnskey 167
max-tcp-clients global option 39 to-bind-key 167
max-udp-clients global option 39 to-dnskey 168
MIBs 140 to-key 168
NETWORK-SERVICES-MIB.txt 143 nom_keytool Subcommands 167
NOMINUM-AGENT-CAPS-MIB 143 nom_maketsigsecret 168
NOMINUM-MDR-MIB 143 nom_nanny 168—169
NOMINUM-NSM-MIB 143 command channel messages
NOMINUM-NSN-MIB 143 deregister 170
die 170
NOMINUM-PCS-MIB 143
kill 170
NOMINUM-QRS-MIB 143 lock 170
NOMINUM-SMI-MIB 144 pid 170
NOMINUM-TC-MIB 144
Nominum ANS
Index 217
register 170 validating configuration 169

restart 171 nom_snmpagent 140—141
server-time 171 command synopsis 141
start 171 configuration file 146
status 171 command-channel 146
stop 172 directory 147
uuid 172 driver 147
version 172 log 147
command-line options masteragent 148
-c 169 syslog-facility 149
--check 169
--configuration flag 141
--configuration 169
-F 169
configuring 142
-f 169 --foreground flag 141
--foreground 169 --foreground-with-syslog flag 142
--foreground-with-syslog 169 --help flag 142
-h 169 location of MIBs 143
--help 169 manipulating via the Command Channel 150
-V 169 --masteragent flag 142
-v 169 MIB documentation 141, 143
--version 169 --root flag 142
configuration file 169 specifying configuration information 142
configuration file options --usage flag 142
--user flag 142
core-size-limit 173 --version flag 142
auto-deregister 172 nom_snmpagent, using with Net-SNMP
child 172
command-line tools 152
command 172
nom_snmpagent.conf 142
command-channel 173
configuration 173 nom_tell 179
default-max-starts 173 basic command structure 68
default-restart-delay 173 behavior in the absence of channel.conf entries
defer-launch 173 69
directory 173 displaying nom_tell’s version using 72
foreground 173 displaying product version using 69
foreground-with-syslog 173 increasing verbosity 72
kill-delay 173 interactive mode 72
lock 174 one-line mode 71
max-starts 174 options
nom_nanny --fields 70
stop-on-clean-exit 174 -h 71
restart-delay 174 --help 71
stderr 174 -i 71
stdout 174 --interactive 71
username 174 -o 71
displaying the version of 169 --one-line 71
load a configuration file 169 -q 71
loading additional configurations 169 --quiet 71
-s 71
logging to syslog 169
--secret 71
logging to terminal 169
Nominum ANS
218 Index
--timeout 72 purge-age option 51

--usage 71 purge-interval option 51
-v 72 purge-max-versions option 52
--verbose 72 purge-zone 74, 79
--version 72
purge-zone command channel message 45
-w 72
--wait-for-exit 72
-x 72 Q
overview 68
quiet mode 71 query logging to an external file 44
service 68 query/answered 186
specifying a secret with 71 query/error 186
specifying timeout using 72 querylog-file option 44
specifying wait time using 72 query/refused 186
specifying which fields to print 70 quiet mode
synopsis 70 entering in nom_tell 71
using IP and port instead of a channel.conf entry quiet mode in nom_tell 71
69
using the prompt to determine interactive mode
72 R
what 68 range 35
nom_tell options Red Hat Enterprise Linux 198
-F 70 refresh interval 44
notify option 50 refresh option 44
notify-hold option 51 relative database version flag 103
notify-in/received 185 reopen-log-files 74, 80
notify-in/refused 185 request-events 74, 80
notify-out/acknowledged 186 request-minimal-events 150
notify-out/sent 186 reset statistics 93
notify-rate option 43 restart 74, 80
notify-source option 43, 51 revision
notify-source-v6 option 43, 51 database 103
RHEL 198
chroot() jails on 198
O rrset-order option 52
observer-address 149
one-line mode
in nom_tell 71 S
options 141 schedule-wait 83
$ORIGIN 109 secret
specifying with nom_tell 71
security
P increasing using channel.conf 71
parentheses, use of 73 server-id option 44
pid 79, 151 server/reload 184
private keystores server/restart 184
defining for DNSSEC 42 server/stop 184
process-information 79, 151, 170 server-version option 44
Nominum ANS
Index 219
service definitions matching to a database version 103

using alternates in channel.conf 102 soa-query-rate option 45
setseverity 149 soa-receive-wait 83
setuid() 11 soa-send-wait 83
setup-errors-fatal global option 39 Solaris
show-data 74, 81 chroot() jails on 196
show-drivers 151 source-view option 52
show-events 74, 80 specifying a secret using nom_tell 71
show-maintenance 74, 82 specifying a timeout using nom_tell 72
status tag 84 specifying database revisions 103
show-maintenance example 89 specifying the fields to print using nom_tell 70
show-server 74, 84 specifying wait time using nom_tell 72
show-view 74, 85 Statistics
show-zone 74, 87 resetting 93
in use statistics 74, 90
displaying a zone’s maintenance state 84 statistics option 52
verifying an added option 136 stop 74, 151
slave database 44—45 syslog
slave zone database 45 directing nom_nanny to 169
slave-count-hint option 44 syslog-facility 149
slave-db option 45, 52 syslog-facility global option 39
sleeping 83
SNMP 179
agent configuration information 142 T
agents 140 terminal
concepts and architecture 139 directing nom_nanny to 169
configuration file 142 timeout
DCS and 144 specifying using nom_tell 72
managers 139 transferring 83
master agent transfers-in option 45
running as 145 transfer-source option 45, 53
network management applications 139 transfer-source-v6 option 45, 53
running as a master agent 145 transfer-start-wait 83
running as a subagent 144 TSIG 42
traps defined 140 $TTL 109
with Nominum products, general notes 140
SNMP agents 140
SNMP concepts and architecture 139 U
SNMP traps 140 udp-buffer-size global option 39
snmpagent_master.conf 141, 143 umask global option 39
snmpagent_master.conf sample file 145 $UNGENERATE 109—110
snmpagent_subagent.conf 143 unload-driver 152
snmpget 154 update policy in DDNS 76
snmptranslate 153 update-data 74, 94
snmptrapd 155 update/details 186
snmpwalk 153 update/failure 181, 186
SOA update-forwarding/failure 186
Nominum ANS
220 Index
update-forwarding/refused 186 notify-source 43

update-forwarding/success 186 notify-source-v6 43
update/not-auth 181, 186 querylog-file 44
update-policy 76 refresh 44
update-policy option 53 server-id 44
update/refused 181, 186 server-version 44
update-server 74, 96 slave-count-hint 44
update/success 182, 186 slave-db 45
update-view 74, 96 soa-query-rate 45
adding a log switch 98 transfers-in 45
differential updates with 99 transfer-source 45
setting a view option 97 transfer-source-v6 45
update-zone 74, 99 zone-count-hint 45
changing configuration information with 130 zone-purge-age 45
converting a slave zone into a master with 129 zone-purge-interval 46
differential updates with 99 zone-purge-max-versions 46
up-to-date maintenance status 82 view/added 184
uuid 94, 150, 152 view/deleted 184
views 12
V
validating nom_nanny configuration 169 W
VDB 28 wait time
vdb 27 specifying using nom_tell 72
vdb database driver 27 without-rmi global option 40
verbosity
increasing with nom_tell 72
version 74, 100, 152 X
nom_nanny 169 xfr-out/denied 182, 186
versioncheck-interval global option 40 xfr-out/granted 182, 187
view 12
expanded definition of 12
view argument 104 Z
view name 104 zone argument 104
view options zone maintenance status
addrport and 43 expired 82
cache-filename 41 needs-maintenance 82
cache-size 41 needs-transfer 82
gss-credentials 41 never-transferred 82
import 42 up-to-date 82
key 42 zone maintenance tasks
keystore-filename 42 destruction-wait 83
log 42 schedule-wait 83
match 43 sleeping 83
match-to 43 soa-receive-wait 83
minimize responses 43 soa-send-wait 83
notify-rate 43 transferring 83
Nominum ANS
Index 221
transfer-start-wait 83
zone name 104
zone options
allow-notify 47
allow-transfer 47
allow-update 47
allow-update-forwarding 47
also-notify 48
conf-template 48
empty-nonterminals 48
invisible-cnames 49
log-flags 50
masters 50
notify 50
notify-hold option 51
notify-source option 51
notify-source-v6 51
purge-age 51
purge-interval 51
purge-max-versions 52
rrset-order 52
slave-db 52
source-view 52
statistics 52
transfer-source 53
transfer-source-v6 53
update-policy 53
zone transfers 45
zone/added 182, 187
zone-count-hint option 45
zone/deleted 182, 187
zone/loaded 187
zone-maintenance/failure 183, 187
zone-maintenance/success 183, 187
zone-maintenance/up-to-date 183, 187
zone-maintenance/xfr-details 187
zone/modified 187
zone-purge-age option 45
zone-purge-interval option 46
zone-purge-max-versions option 46
Nominum ANS
222 Index
Nominum ANS

ANS 2.8.3 Manual 20081107 PDF

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

ANS 2.8.3 Manual 20081107 PDF

Hochgeladen von

Copyright:

Verfügbare Formate

Nominum

Product Version 2.8.3

Navitas and Vantio are trademarks of Nominum, Incorporated.

All other trademarks are the property of their respective companies.

2 Getting Started With ANS.....................................................5

3 Zones and Templates ..........................................................13

4 Database Drivers ................................................................27

5 Server, View and Zone Options...........................................35

Server Options ...............................................................................................36

6 Using the Command Channel with ANS..............................67

7 The ANS Utilities .............................................................101

Executing ans_* Commands From A Remote Machine................................124

8 Examples of Zone Operations ...........................................127

9 SNMP in ANS ...................................................................139

10 Secret Key Transaction Authentication (TSIG) .................157

E ANS Files .........................................................................205

Nominum ANS vii

Table 8-2 update-policy Zone Option Examples ...................................................................136

• Flexible, fast reconfiguration.

• Rapid start times, reducing downtime when ANS must be restarted.

• Enhances uptime by reducing situations in which a restart is required.

• Ability to use Nominum’s VDB to store DNS data.

Communicating with ANS

About This Manual

Chapter 3, ”Zones and Templates”, provides information on zone types in ANS.

Chapter 4, ”Database Drivers”, describes each of the supported drivers.

Chapter 9, ”SNMP in ANS”, describes the SNMP functionality included in ANS.

Appendix A, Statistics, lists the statistics supported by this server.

Appendix C, Logging Switches, covers the logging switches for ANS.

Convention Use Example

Table 1-1 Typographical Conventions

ans> update-zone zone=example.com \

is rendered without carriage returns in actual use:

ans> update-zone zone=example.com also-notify=10.0.0.3

1. Start the server.

2. Load DNS data.

Starting the ANS Server

Start the Nominum ANS server as follows:

1. Start the nom_nanny program as root:

2. Start the ANS server process:

3. (optional) Start the snmpagent and/or SOAP API services, if appropriate.

Confirming That ANS is Running Using nom_tell

Loading a DNS Master File

First, here are the contents of the example.master file:

Figure 2-1 Example DNS Master file

# ans_load example example.master

ANS: info: default/example (master): added

# dig @::1 example. soa

; <<>> DiG 8.3 <<>> @::1 example. soa

;; Total query time: 26 msec

Additional Technical Background

The ans Command

ans [-c|--configuration file] [-f |--foreground]

Command Line Option Description

In safe mode, as much as possible of the configuration is loaded,

To exit safe mode, send a restart CC command.

NOTE: If you fix an erroneous configuration with

Table 2-1 ans Command-line Options

Command Line Option Description

All paths, including the configuration file, are interpreted relative

NOTE: The root option is not compatible with safe mode, as

NOTE: -u and --user require the specified user to have the

Table 2-1 ans Command-line Options (continued)