Vantio-CacheServe-7 0 2

Vantio CacheServe
Administrator's Manual
Version 7.0.2 October 6th, 2014

Copyright ©2002-2014 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
Centris, Navitas, and Vantio are trademarks of Nominum, Incorporated.

Table of Contents
Table of Contents 1
Chapter 1: Introduction 13
Caching name servers 13
High performance 13
A note about chroot() 13
What's in the manualhelp system 14
Chapter 2: Migrating from Vantio CacheServe 5 15
Migration guidelines 15
Migration procedure 15
Chapter 3: Performance tuning 17
Limit the number of TCP connections 17
Increase the number of recursion contexts 17
Use a preferred system 18
Ramp up your network 18
Chapter 4: Differences between CacheServe and Vantio 21
Notable features 21
Changed features 22
Removed features 23
Vantio CacheServe Administrator's Manual NOMINUM CONFIDENTIAL

2 Table of Contents
Changed fields 24
Removed fields 24
Changed commands 25
Removed commands 25
Changed events 25
Removed events 26
Changed statistics 26
Removed statistics 27
Chapter 5: Controlling CacheServe with the Command Channel 29
Engine Interaction 29
Common Object Methods 31
Using nom_tell 32
The /etc/channel.conf file 33
Interactive Mode 34
Chapter 6: Basics of the CacheServe policy engine 35
NXDOMAIN redirection 35
Malicious domain redirection 39
Chapter 7: Simple rate-limiting 43
In CacheServe 5 43
In CacheServe 7 43
Chapter 8: Rate-limiting DNS amplification attacks 45
How DNS amplification attacks work 45
Characteristics of amplification attacks 45
Mitigating amplification attacks 45
Dealing with purpose-built amplification domains 46
Managing ANY queries 48
Managing dual-use domains 49

Table of Contents 3
Rate-limiting amplification traffic 50
Chapter 9: ID spoofing attacks 53
How ID spoofing attacks work 53
How CacheServe defends against ID spoofing attacks 53
Important ID-spoofing-related CacheServe configuration parameters 54
Caveats 54
Chapter 10: The cacheserve process 55
CacheServe service scripts 55
--channel 56
-c, --configuration 56
--directory 56
--dns-port 56
--fd-limit 56
-F, --foreground-with-syslog 57
-f, --foreground 57
-h, --help 57
--license 57
--no-statmon 57
-r, --root 57
--statmon-directory 58
-s, --syslog-facility 58
--usage 58
-u, --user 58
-v, --version 59
Chapter 11: The CacheServe utilities 61
Supported objects 61
The CacheServe configuration file format 62
NOMINUM CONFIDENTIAL Vantio CacheServe Administrator's Manual

4 Table of Contents
Editing with cacheserve-editconf 63
Loading data with cacheserve-loadconf 65
Dumping data with cacheserve-dumpconf 66
cacheserve-deleteconf 68
cacheserve-stats 69
Chapter 12: The CacheServe objects 73
address-list 73
address-node 75
binding 77
connection 79
dns64 80
layer 83
name-list 86
name-node 88
policy 90
ratelimiter 92
resolver 94
server 105
view 110
view-selector 112
Chapter 13: Command reference 115
address-list.load 120
address-list.mget 121
address-list.replace 123
address-list.update 124
address-node.add 125
address-node.delete 126

Table of Contents 5
address-node.get 126
address-node.list 127
address-node.mget 129
address-node.replace 130
address-node.update 131
binding.add 132
binding.delete 135
binding.get 136
binding.list 137
binding.mget 138
binding.replace 140
binding.update 142
connection.get 145
connection.replace 145
connection.subscribe-all 146
connection.update 146
dns64.add 147
dns64.delete 148
dns64.get 149
dns64.list 150
dns64.mget 151
dns64.replace 152
dns64.update 154
instance-information 156
layer.add 157
layer.clear-fault 158
layer.delete 158

6 Table of Contents
layer.get 159
layer.list 159
layer.mget 161
layer.reimage 162
layer.replace 162
layer.update 164
name-list.add 165
name-list.delete 166
name-list.dump 167
name-list.get 167
name-list.list 168
name-list.load 169
name-list.mget 170
name-list.replace 172
name-list.update 173
name-node.add 174
name-node.delete 175
name-node.get 176
name-node.list 177
name-node.mget 178
name-node.replace 179
name-node.update 181
policy.add 182
policy.delete 184
policy.get 184
policy.list 185
policy.mget 186

Table of Contents 7
policy.replace 188
policy.simulate 189
policy.update 191
process-information 192
ratelimiter.add 193
ratelimiter.delete 195
ratelimiter.get 196
ratelimiter.list 196
ratelimiter.mget 198
ratelimiter.replace 199
ratelimiter.statistics 201
ratelimiter.update 202
resolver.add 204
About lame delegations 207
Be careful what you wish for 207
resolver.delete 215
resolver.flush 216
resolver.get 217
resolver.inspect 217
resolver.inspect-delegation 220
resolver.list 221
resolver.mget 223
resolver.recursing 224
resolver.replace 225
resolver.statistics 235
resolver.update 237
restart 248

8 Table of Contents
server.add 248
server.all-errors 252
server.block-checkpoints 252
server.checkpoint 252
server.get 253
server.replace 260
server.statistics 263
server.unblock-checkpoints 265
server.update 266
stop 269
uuid 270
version 270
view-selector.add 271
view-selector.delete 272
view-selector.get 273
view-selector.list 274
view-selector.mget 275
view-selector.query 276
view-selector.replace 277
view-selector.update 278
view.add 280
view.delete 281
view.get 282
view.list 282
view.mget 284
view.replace 285
view.update 286

Table of Contents 9
Chapter 14: Events reference 289
address-list.changed 289
address-node.changed 289
binding.changed 290
dns64.changed 290
layer.changed 290
layer.provisioning-connected 291
layer.provisioning-connection-failure 291
layer.provisioning-disconnected 291
layer.provisioning-reimaging 292
layer.provisioning-update-failure 292
layer.provisioning-update-success 292
name-list.changed 292
name-node.changed 293
policy.changed 293
policy.hit 293
ratelimiter.abate 294
ratelimiter.changed 296
ratelimiter.onset 296
resolver.changed 298
resolver.flush 298
resolver.id-spoofing-suspected 299
server.changed 299
server.configuration-error 299
server.formerr-loop 300
server.restart 300
server.stop 300

10 Table of Contents
server.tcp-client-limit 300
server.udp-recursion-limit 300
view-selector.changed 300
view.changed 301
Chapter 15: Command Channel fields and types reference 303
ACLs 303
exclude-fields 303
fields 303
acl-element 304
acl-element4 304
acl-element6 304
addr 304
addr-or-name 304
addr6 304
addrpat 305
addrpat6 305
addrport 305
addrport4 305
addrport6 305
addrrange 305
anonymization-key-file-path 305
boolean 305
dns-flag 306
dns-rcode 306
edns-flag 307
event-name 307
float-seconds-since-epoch 307

Table of Contents 11
inspect-delegation-servers 307
integer 308
ipv4netlen 308
ipv6netlen 308
monitor-log-switch 308
name 309
name-empty-ok 309
name-label-count 309
policy-action 309
policy-calendar-selector 312
policy-result-type 313
policy-selector 313
positive-integer 317
provisioning-status 317
ratelimiter-statistics 318
rdata 319
rdataclass 319
rdatatype 319
report-max-memory-arg 319
resolver-statistics 319
seconds-since-epoch 321
server-statistics 321
sizeval 322
std-layered-edit-operation 322
string 323
string-empty-ok 323
threshold-abate 323

12 Table of Contents
threshold-duration 323
threshold-onset 323
time-in-microseconds 323
time-in-seconds 323
ttl 324
uint16 324
uint64 324
unparsed 324
uuid 324
versioncheck-days 324
Index 325

Chapter 1: Introduction
Vantio CacheServe is a high-performance caching name server.
Caching name servers

A caching server is one of several types of DNS nameserver. When a caching server receives a
DNS query, it retrieves its answer from authoritative master servers (like Nominum ANS), and
stores the response data locally until a time-to-live (TTL) expires.
While the data is cached, the caching server doesn't need to go back and re-query authoritative
servers, and this increases the efficiency of local DNS responses (like those that come from your
end-users).
High performance
Vantio CacheServe is the next generation of caching name server in the Vantio line, re-
engineered to take advantage of multi-core hardware. In testing environments, CacheServe
has performed at 2,000,000 queries per second.
We've put together some performance tuning guidelines to help you take advantage of
CacheServe's capabilities.
A note about chroot()

For the best security, you should run CacheServe in a chroot() "jail", with its own user. Here's
how:
1. Create the directory in which you're going to run CacheServe. You can use
/var/nom/cacheserve if that's convenient.
2. Choose the user as which you're going to run CacheServe (create the user, if necessary).

14 What's in the manualhelp system
3. Make sure that the chroot directory and all the files in it are owned by that user:
%> chown -R username chroot-directory
4. Make sure that the directory has the right permissions for that user:
%> chmod 700 chroot-directory
5. Edit the /usr/local/nom/etc/sysconfig/cacheserve file, and add or edit the following entries:
CACHESERVE_OPTIONS="--directory /"
CACHESERVE_ROOTDIR="chroot-directory"
CACHESERVE_USER="username"
6. Start CacheServe.
Note: If you stop the server and modify files in the chroot directory using something like
cacheserve-loadconf, you should repeat steps 3 and 4 to make sure ownership and
permissions are correct.
What's in the manualhelp system

The manual includes comprehensive reference information for Vantio CacheServe.
It also includes:
l Quick-start configuration guides based on common CacheServe operations.

l Performance-tuning tips to get the most out of CacheServe.

Chapter 2: Migrating from
Vantio CacheServe 5
If you're using Vantio 5, you'll need to migrate your configuration to the Vantio 7 format. We've
provided a conversion tool, cacheserve-convertconf, to help you migrate your database.
Migration guidelines
1. Don't convert your database in the working directory. Convert your database some-
where other than /var/nom/cacheserve, like /tmp. Only move the converted database once
you're sure the conversion is complete and the results are to your liking.
2. Not all parts of a Vantio configuration can be automatically converted; more com-
plicated Vantio configurations may require additional help.
Migration procedure
To migrate from Vantio 5.x to Vantio CacheServe 7.0:
1. Disable or remove any automatic startup processes for Vantio.

2. Create a text-format dump of Vantio's configuration file:
shell> /usr/local/nom/sbin/vantio_dumpconf --all -o <file>
3. Import the dumped Vantio data into the CacheServe database:

shell> /usr/local/nom/sbin/cacheserve-convertconf -c
/var/nom/cacheserve/cacheserve <file>
where <file> represents the name of the file containing the dumped Vantio data.
4. If you are satisfied with the results of the import, stop Vantio and start CacheServe:

16 Migration procedure
shell> /usr/local/nom/sbin/nom_tell vantio stop
shell> /usr/local/nom/sbin/nom_tell cacheserve start
5. If you encounter unresolvable problems, you can revert to your previous Vantio install-
ation by restoring any changes that you made to startup scripts in step 1, and starting
Vantio.

Chapter 3: Performance
tuning
CacheServe is a high-performance application, and to get the most out of it, you should
consider some or all of these suggestions.
Limit the number of TCP connections

Certain types of DNS attacks, including pseudo-random subdomain attacks, can cause
authoritative servers to rate-limit caching server traffic.
If this rate limiting involves responses being truncated, the caching server can rapidly exhaust
its supply of file descriptors. The resolver max-tcp-recursions option limits the number of
TCP connections the server can make at one time during resolution. The default value is 1000,
which should be sufficient for most use cases
Increase the number of recursion contexts

In addition to the max-tcp-recursions option, Nominum recommends configuring at least
20,000 recursion contexts, and up to 50,000, depending on your available RAM. Each recursion
context requires approximately 32K of RAM.
Configure the number of recursion contexts with the server's max-recursive-clients setting, up
to a maximum of 50,000:
cacheserve> server.update max-recursive-clients=50000

18 Use a preferred system
Use a preferred system

The best system for CacheServe is a multi-core physical server running RHEL 6.5, CentOS 6.5, or
a Linux distribution with a 3.9 kernel or higher. Systems that match these specifications allow
CacheServe to make full use of the SO_REUSEPORT feature, where the kernel distributes load
from a single IP address and port to multiple sockets. CacheServe will do this automatically.
If you don't have a preferred system

If you're not running Linux, or don't have a modern Linux kernel, you can improve CacheServe
performance by manually configuring the system to listen on multiple sockets, and then
routing traffic for CacheServe through a load balancer. For details on configuring these
listeners, see listen-on-matching.
A good rule of thumb for the number of sockets is to use the number of "real" CPU cores
available to you (versus the number of real cores plus virtual, hyperthreaded cores). On Linux
systems, an easy way to find out how many cores you have is:
[shell ~]# lscpu
Architecture: x86_64
CPU op-mode(s): 32-bit, 64-bit
Byte Order: Little Endian
CPU(s): 1
On-line CPU(s) list: 0
Thread(s) per core: 1
Core(s) per socket: 1
CPU socket(s): 1
NUMA node(s): 1
Vendor ID: AuthenticAMD
CPU family: 16
Model: 8
Stepping: 1
CPU MHz: 2100.147
BogoMIPS: 4200.29
L1d cache: 64K
L1i cache: 64K
L2 cache: 512K
L3 cache: 6144K
NUMA node0 CPU(s): 0
Multiply the number of cores by the sockets to get the number of cores. In this case, there's 1
core (1*1).
Ramp up your network

A single 1G Ethernet network will be saturated well before CacheServe approaches its limits.
Instead, use either 10G ethernet or as many 1G ethernet connections as you can.

Ramp up your network 19

20 Ramp up your network

Chapter 4: Differences
between CacheServe and
Vantio
There are significant differences between CacheServe and Vantio. This document enumerates
those differences.
Notable features
The following features have been added or improved in CacheServe:
listen-on-matching
Listen-on-matching has replaced listen-on, and provides the ability to listen on multiple
interfaces. See listen-on-matching for details.
Rate-limiting
Ratelimiting is discussed in two places:
l Simple rate-limiting covers a simple rate-limiting scenario.

l Rate-limiting DNS amplification attacks covers a more complex rate-limiting configuration
designed to thwart DNS amplification attacks.
Many of the ratelimiting features from earlier CacheServe releases have changed:
l rate-limiting, rate-limiting-max-qps, and rate-limiting-unenforced have been removed;

use a ratelimiter object with a policy and server binding instead.

22 Changed features
l rate-limiting-by-response-size, rate-limiting-by-response-size-name and rate-limiting-by-

response-size-threshold have been removed; use a ratelimiter object with a policy and
server binding instead.
l rate-limiting-truncate-factor has been removed; packets matching a rate limiter can now
be dropped or truncated with the drop or truncate policy-action.
l rate-limiting-by-response-size-action has been removed; use a response-size policy-
selector in combination with an action instead.
l rate-limiting-exclusions and rate-limiting-by-response-size-exclusions have been
removed; these functions are now available as policy-selectors.
Added Server features
l Command Channel connections are now represented by a connection object.
l server-time no longer exists.
l Read-only connections now respond to commands with "read-only connection"
instead of "unknown command".

l "Broken" objects now return an "errors" field that provides detail on what's wrong. See
server.all-errors for more information.
l Checkpoints are now automatically carried out at 3 hours and 5 minutes past midnight at
local server time. To add additional checkpoints, use server.checkpoint.
Added Binding features
l Bindings now have a when field, which defines the point in the query process (prequery,
postquery or presend) at which the binding is effective.
l Presend occurs after the answer is composited but before it is sent.
l This also replaces the postquery selector.
Changed features
The following features have been changed in CacheServe from their Vantio equivalents:
Monitoring changes
Monitoring functions are now provided entirely by the Nominum statmon utility, supported by
CacheServe with the auth-monitoring and monitoring configuration elements.
Both the auth-monitoring and monitoring elements are pre-configured in CacheServe.
For detailed information about monitoring in CacheServe, including the commands available
for both the auth-monitoring and monitoring elements, please consult the Nominum
monitoring manuals: Monitoring Query and Request Data on Nominum Engines and Nominum
statmon Utility and Query Store Command Reference.
Changed DNS64 features

l dns64 has been simplified, and integrated into the policy engine.

Removed features 23
Changed Server features

l record-data-origin is always on, and cannot be reconfigured.
l id-spoofing-defense is always on, and cannot be reconfigured.
l The cache cannot be dumped. Use resolver.inspect instead.
l When the server restarts, it generates a server.restart event.
l Layering and ordering:
l Layer order is now determined by layer priority.
l The default DNS port may only be specified on the command line.
l EDNS0 defaults to "on".
l You cannot configure a single address/port combination to accept both queries and
responses.
l Only IN classes are supported (with the exception of magic CHAOS TXT queries)
l Statistics other than simple counters should be obtained using the Nominum statmon
utility.
l QNAME case randomization has been simplified:
l off, unenforced and silent-enforced default to "off".
l An exception list applies.
l Mismatches are logged in both unenforced and enforced modes.
Changed View features

l View names are no longer limited to 255 characters.
l You may preload any RR type.
l Vantio's lwviews have been replaced by CacheServe's views.
l View selection is determined by view-selectors.
l Every view must have an associated resolver.
l Inspection is now resolver-specific, with the following changes:
l Domains are specified with the domain argument.
l Immortal's value is now a boolean value, and the unknown name response is now
"domain not found".
Removed features
The following features have been removed entirely from CacheServe:
Removed Binding features

l The selectors field has been renamed to selector.
Removed LVP features
l LVP no longer exists. The following changes have been made:
l lvp-policy is now policy.
l lvp-binding is now binding.
l lvp-list is now either address-list or name-list, depending on the list contents.

24 Changed fields
l lvp-node is now either address-node or name-node depending on the node type.

l lvp-ip-node has been replaced by address-node.
l list-bindings and composite lists no longer exist, including the LVP exact selector.
l The log action has been removed; use the Nominum statmon utility instead.
Removed Server features
l EDNS client hints are no longer processed, and view-selectors no longer support select-
ing views based on them.
l MDR, NXR and UAR don't exist in CacheServe. "Basics of the CacheServe policy engine"
provides a walkthrough to create NXR-style redirection in CacheServe.
l There is no support for old-style vantio.conf text format configuration files. If you are
using a vantio.conf file, you should migrate it into Vantio 5, and then follow the migration
procedure in Migrating from Vantio CacheServe 5
l dnsauth isn't supported.
l Lockfiles aren't supported.
Removed View features
l Query logging no longer exists; use the Nominum statmon utility.
Changed fields
The following fields have been changed in CacheServe from their Vantio equivalents:
Changed Resolver fields

l The format of the trusted-key statement has changed to be a list of (name, list of DNS
rdata).
Changed Server fields
l listen-on has been replaced by listen-on-matching.
l The syntax of listen-on-matching has also changed from a list of tuples to a list of
tables. See listen-on-matching for details.
Removed fields
The following fields have been removed entirely from CacheServe:
Removed Server fields

l The check-responses field has been removed.
l The blackhole-clients field has been removed, as the same effect can be achieved using
the dropaction in a policy.

Changed commands 25
Removed View fields

l delegation-only has been removed.
l The clients field has been removed, as the same functionality can be obtained using an
additional policy-selector.
l query-source and query-source-v6 have been removed.
l filter-aaaa-on-v4 has been removed; use the type-exists-at-qname policy-selector
instead.
Changed commands
The following commands have been changed in CacheServe from their Vantio equivalents:
Changed View commands

l All managed-keys commands have been replaced by a resolver object managed-keys
field. State is indicated by the resolover managed-keys-state field, which is returned by
get or mget methods.
Changed Policy commands
l Policies can process dns64 with the dns64 and dns64-reverse actions.
l "lvp_query" has been replaced by policy.simulate.
Changed Server commands
l server.checkpoint does not cancel an already running checkpoint.
Removed commands
The following commands have been removed entirely from CacheServe:
Removed View commands

l The recursing command.
Removed Server commands
l server.hidden-layers has been removed. To determine which layers are hidden, use the
layer.mget command. Hidden layers are indicated by hidden=true.
l block-checkpoints, unblock-checkpoints and checkpoint are now called server.block-
checkpoints, server.unblock-checkpoints, and server.checkpoint.
Changed events
The following events have been changed in CacheServe from their Vantio equivalents:

26 Removed events
Changed Provisioning/Layer events

l Provisioning events are now in the layer namespace; for example, "layer.provisioning-con-
nected" replaces "provisioning-connected".
Changed Server events
l server-stop is now server.stop.
l udp-recursion-limit and tcp-client-limit are now server.udp-recursion-limit and serv-
er.tcp-client-limit.
Changed View events
l The following view events are now resolver events:
l id-spoofing-suspected
l dnssec-validation-failed no longer exists.
Removed events
The following events have been removed entirely from CacheServe:
Removed Server events

l server-reload, request-no-view and server.layer-order.
Changed statistics
The following statistics have been changed in CacheServe from their Vantio equivalents:
Changed Server stastistics

l max-cache-size is now a per-resolver statistic, not per-server.
l cache-memory-in-use is now a per-resolver statistic, returned by resolver.statistics; in
Vantio, it was a server-wide value.
Changed View statistics
l The following view statistics are now resolver statistics:
l log-lame
l log-id-spoofing
l inspect
l inspect-type-info
l inspect-delegation
l id-spoofing-suspected is now resolver.id-spoofing-suspected. The fields of the statistic

are now "name", "qname" and "qtype".

Removed statistics 27
Removed statistics
The following statistics have been removed entirely from CacheServe:
Removed Server statistics

l rate-limiting-drops, rate-limiting-truncated, and rate-limiting-detections; these statistics
are now tracked by the ratelimiter object.
Removed View statistics
l view statistics as a whole.
l keep-statistics-by-client and keep-statistics-by-domain; use the Nominum statmon utility
instead.
l keep-statistics-by-type; use the Nominum statmon utility instead.

28 Removed statistics

Chapter 5: Controlling
CacheServe with the Com-
mand Channel
Engine Interaction
The primary means of interacting with the Nominum Proxy Server is by using the Nominum
Command Channel protocol.
Command Channel Basics

The Nominum Command Channel (CC) is a protocol used to send specially-formatted messages
to Proxy, either from a command-line interface or using a script. The CC sends both commands
and configuration settings to Proxy.
Proxy comes with a Nominum-provided Command Channel client called nom_tell, which is used
in examples throughout the manual.
CC Message Types
There are three types of Command Channel messages.
REQUESTS are messages from clients that require a response.
RESPONSES are messages sent from servers in response to requests from clients. A response is
sometimes a sequence of several messages. Responses to failed requests contain an err tag
indicating the error that led to the failure.
EVENTS are messages sent from servers with no expectation of a response and cannot be
responded to.

30 Engine Interaction
CC Message Formats
Command Channel messages are formatted three ways: as strings, lists, or tables.
STRINGS are a sequence of zero or more octets, and can take several forms.
String Format Example

Unquoted
foo
(May be terminated with a space, tab, newline, or the ( ) { } ; or = characters)
Single-quoted 'foo'
Double-quoted "foo"
Hexadecimal \x66\x6f\x6f
Hexadecimal string binary:666f6f
To escape a character in a quoted string, use a backslash ( \ ) in front of the character. A

backslash
( \ ) followed by an x and two hexadecimal digits includes the character with that value (for
example, a NUL: \x00).
LISTS are parenthesized values, optionally separated by commas, containing any of the basic
Command Channel formats (strings, lists, or tables).
(foobarbaz)
(1, 2, 3)
( ('one', 'two') ('A', 'B') )
TABLES are key/value pairs, optionally separated by commas, = or =>, inside curly braces ( { } ).
Table keys are strings, and table values can be any of the basic Command Channel formats
(strings, lists, or tables).
Basic Command Channel Messages

The following Command Channel messages are understood by all Nominum products,
including the Nominum Proxy Server.
Command Usage
stop Shuts down the server
version Retrieves version information for the server
instance-information Retrieves instance id
Retrieves process information for the server, including licens-
process-information
ing, working directory, process id, and system time

Common Object Methods 31
Common Object Methods

The following methods can be used with most - but not necessarily all - top-level server objects.
Add
The add method creates a new object. The arguments needed for this command are the initial
values of the object's required fields and any optional fields that you want to set when creating
the object.
Delete
The delete method deletes an object. Depending on the type of object, you will need to specify a
name or other key field to determine which object to delete.
Get
The get method retrieves the values of an object's fields. Depending on the type of object, you
will need to specify a name or other key field to determine which objects to retrieve.
List
The list method retrieves all instances of a specific class of objects. This method will return a
sequence of one or more responses, depending on the number of objects listed.
Mget
The mget method retrieves all instances of a specific class of objects and the values of their
fields. This method will return a sequence of one or more responses, depending on the
number of objects listed.
Replace
The replace method will create a new object in place of a chosen object, with the new object's
fields set to the specified values. Any unspecified fields will either be unset or set to the default
value, even if they were set in the original object.
Update
The update method will update the values for the specified fields for a chosen object while
leaving any unspecific fields unchanged.
+/Append
When using the update method, you can use the append syntax to add new values to the end
of a list in an object's fields.

32 Using nom_tell
-/Remove
When using the update method, you can use the remove syntax to remove specified values
from a list in an object's fields.
List and Table Slicing

When using the update method, you can use the following syntaxes to add values to specific
position in a list, replace values in specific positions with a new value, or remove values in a
specific position in a list by making use of slice notation.
Operation Command Before After

Add x[+0]=foo x=(bar baz) x=(foo bar baz)
x[+1]=foo x=(bar baz) x=(bar foo baz)
Replace x[1]=foo x=(bar baz) x=(bar foo)
x[1:2]=goo x=(foo bar baz) x=(foo goo)
Remove x[0]=() x=(foo bar baz) x=(bar baz)
Using nom_tell
The nom_tell Command Channel client ships with the Proxy. All of the examples in this manual
use nom_tell in its interactive mode, which is the simplest way to send Command Channel
messages to a Nominum engine.
From the Shell

Command Channel commands can be sent to Nominum engines directly from the command
line with nom_tell, using the following format:
# nom_tell service_name command [ parameters ]
To send a 'version' command to nom-proxy, use the following command:

# nom_tell nom-proxy version
When sending parameters in a list using nom_tell from the shell prompt, you will need to
enclose each list entry in quotes, in order for the command to be parsed properly.
Interactive Mode
In order to enter nom_tell interactive mode, send a nom_tell command with an engine or service
name specified, but no further commands or paramters. This will open a Command Channel
connection which will be used for subsequent commands.
# nom_tell nom-proxy
nom-proxy>

The /etc/channel.conf file 33
From this prompt, you can send commands to the Proxy by typing them at the prompt, and
nom_tell will return to the interactive prompt after the Command Channel response is returned.
When using interactive mode, you do not need to enclose field values in quotes.
nom_tell also features tab completion when accessed in its interactive mode, which can be
useful when entering commands with complex syntax.
Note: If you leave your nom_tell interactive mode window idle for a few minutes, you may
receive this message:
error: 'nom-proxy' closed the connection
This is normal behavior. The next command you send via the nom_tell prompt will automatically
reopen the connection.
Retaining History for nom_tell

You can set nom_tell to retain history even while exiting and re-entering the interactive prompt
by setting the NOM_TELL_HISTFILE environment variable prior to invoking nom_tell. You can also
add this variable to your shell configuration file (e.g. .bashrc or .profile).
The /etc/channel.conf file

The /etc/channel.conf file uses service names to identify services that use the Nominum
Command Channel protocol. The channel.conf file translates a service name into a location (a
host and a port), and identifies the shared secret that should be retrieved.
A channel.conf file is formatted as a sequence of lines, where blank lines and lines starting with
the # character are ignored. Each configuration line defines a service-name, followed by an
addrport, followed by a secret, followed by optional properties (each item is separated by
whitespace):
l service-name—A string used to identify the service. Each server has a default service
name, and can also be configured to use alternative service names.
l addrport—An address taking 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.
l secret—A string, specified with double quotes if it contains whitespace and within which
explicit quotation marks or backslashes are quoted with a backslash. Specifying a secret
of * is interpreted as no secret.
l Optional properties—Each optional property is a key-value pair of the form key=value.

34 Interactive Mode
The supported properties are:
l acl—A list of addresses and/or networks that may make connections to this
channel. The list is a comma-separated list of addresses with optional prefix length
specifiers. For example: acl=127.0.0.1,10.0.0.0/8
l encrypt-only—If set to 1, encrypt-only mandates that all connections made to this

service must be encrypted.
An example entry might resemble:

cacheserve 9434 pbZmkTJprEOCLNd9DfIlChUs2EBT5ShcuirylKpD2VSsaPiF
Interactive Mode
nom_tell’s interactive mode opens a single Command Channel connection and uses it for
subsequent Command Channel messages:
[testbed etc]# nom_tell cacheserve
nom_tell 3.0.39.0.d, interactive mode
cacheserve>
In interactive mode, send commands to ANS by typing them at the prompt—note that nom_tell
returns to the interactive prompt after the Command Channel response is returned:
cacheserve> version
{
type => 'version'
vendor => 'Nominum'
product => 'Vantio CacheServe'
platform => 'rhel-6-x86_64'
version => '7.0.1.0.d'
expiration => 'Fri Aug 1 00:03:03 2014'
}
cacheserve>
All of the manual’s examples are given in interactive mode.

Chapter 6: Basics of the
CacheServe policy engine
The CacheServe policy engine is a simple, flexible and powerful tool for managing specific types
of DNS traffic.
Vantio handled NXDOMAIN redirection and malicious domain redirection with specialized

modules (NXR and MDR).
In CacheServe, the same abilities are provided by a single feature, the policy engine. This section
shows you how to achieve those same features with the policy engine, and provides a good
foundation for more advanced goals, like defending against DNS amplification attacks.
NXDOMAIN redirection
Vantio used the NXR module to redirect NXDOMAIN responses. In CacheServe, the policy
engine provides this functionality.
The following example configures CacheServe to redirect everything except queries and
prefixes that match entries on two lists.
The example covers the following:
l Creating a policy.
l Adding a redirection policy-action to the policy.
l Making lists of domains and prefixes that you don't want to redirect.
l Adding a policy-selector that executes the redirection for anything that isn't on the
"don't-redirect" lists.
l Binding the policy to a view.

36 NXDOMAIN redirection
Create the NXDOMAIN policy

Policies provide a way to associate actions with the results of a DNS query. Since we're
implementing NXDOMAIN redirection, we'll use the name nxdomain-redirect-policy.
1. In CacheServe, create a policy:

cacheserve> policy.add name=nxdomain-redirect-policy
{
type => 'policy.add'
}
Add an NXDOMAIN action

Next, add the action that you wish to accomplish to the policy (we'll cover how the action is
applied a little later, in Make an NXDOMAIN policy selector
1. In Vantio, retrieve the view that contains the redirection you want to accomplish, and
look for the redirect-nxdomain-replace value:
vantio> view.get name=nxdomain-redirect-view
{
type => 'view.get'
name => 'nxdomain-redirect-view'
class => 'IN'
redirect-nxdomain-replace => ((('.') ('192.168.1.1')))
redirect-nxdomain-prefix-only-prefixes => ('www')
}
2. You will need both the IPv4 and IPv6 addresses (you may need to convert the IPv4
address. In this case, those addresses are:
192.168.1.1
2001:db8:f61:a1ff:0:0:0:80
3. In CacheServe, add the redirection action to the policy you created earlier, using the IPv4
and IPv6 addresses you looked up:
cacheserve> policy.update name=nxdomain-redirect-policy action=
(answer ((A 192.168.1.1)(AAAA 2001:db8:f61:a1ff:0:0:0:80)))
{
type => 'policy.update'
}
Make NXDOMAIN redirection lists

In this step, you'll first create a list that holds the names you want to exempt from redirection,
and then you'll create a list that holds the prefixes you want to exempt from redirection.

NXDOMAIN redirection 37
1. In Vantio, retrieve the view that contains the redirection you want to accomplish, and, this
time, look for the redirect-nxdomain-exclusions value:
{
type => 'view.get'
class => 'IN'
redirect-nxdomain-exclusions => ("example.org" "example.net"
"example.com")
redirect-nxdomain-prefix-exclusions => ("www" "ldap" "smtp")
}
2. In CacheServe, create a name-list. This name-list will contain the names of queries you
want to exempt from redirection:
cacheserve> name-list.add name=nxdomain-redirect-domains
{
type => 'name-list.add'
}
3. In CacheServe, add the names you want to exempt as name-nodes in the name-list you
just created (for large lists, you should consider extracting the list contents into a file and
using name-list.load to populate the list):
cacheserve> name-node.add list=nxdomain-redirect-domains
name=example.com
{
type => 'name-node.add'
}
4. Repeat the process for the redirect-nxdomain-prefix-exclusions entries. In Vantio:

{
type => 'view.get'
class => 'IN'
redirect-nxdomain-prefix-exclusions => ("www" "ldap" "smtp")
}
5. In CacheServe, create another name-list. This name-list will contain the names of prefixes
you want to exempt:

38 NXDOMAIN redirection
cacheserve>name-list.add name=nxdomain-do-not-redirect-prefixes
{
}
6. In CacheServe, add the prefixes you want to exempt as name-nodes in the name-list you
cacheserve> name-node.add list=nxdomain-do-not-redirect-prefixes
name=www
{
}
Make an NXDOMAIN policy selector

You've defined the action you want to take (redirection) and you've defined lists of domains and
prefixes that you don't want redirect.
Note: You'll notice three unusual clauses in the policy:
(and ((result (nxdomain)) (qtype (A AAAA)) (not (synthesized))
Since this policy is implementing NXDOMAIN redirection, we want it to apply only to A/AAAA
queries that received "organic" NXDOMAIN results; that is, NXDOMAIN results came from
resolution, but that weren't synthesized by other policies.
Now you need to link them together in the policy you created in the beginning.
1. Add a policy-selector that combines the action you created (redirect A and AAAA queries)
with the lists you created, and associate the selector with a policy:
cacheserve> policy.update name=nxdomain-redirect-policy selector=(and
((result (nxdomain)) (qtype (A AAAA)) (not (synthesized)) (not
((qname (nxdomain-redirect-domains subdomain )))) (not ((qname-prefix
nxdomain-do-not-redirect-prefixes)))))
{
}
2. Check the results:

cacheserve> policy.get name=nxdomain-redirect-policy
{
type => 'policy.get'
name => 'nxdomain-redirect-policy'

selector => ('and' (('result' ('nxdomain')) ('qtype' ('A' 'AAAA'))

('not' ('synthesized')) ('not' (('qname' ('nxdomain-redirect-domains'
'subdomain')))) ('not' (('qname-prefix' 'nxdomain-do-not-redirect-
prefixes')))))
}
Bind the NXDOMAIN policy to a view

The policy won't do anything unless it's bound to a view (and that view is bound to a view-
selector):
1. Bind the policy you created to the appropriate view, having the policy execute post-query
(because that's when you'll get an NXDOMAIN response from resolution) and giving the
policy a high priority:
cacheserve> binding.add view=world policy=nxdomain-redirect-policy
when=postquery priority=1
{
type => 'binding.add'
}
Malicious domain redirection

As with NXR, the functionality of Vantio's MDR module can be duplicated using CacheServe's
policy engine.
The following examples will look similar to the NXDOMAIN examples; that's because most of the
elements that we use in NXDOMAIN redirection, we also use to redirect malicious domains:
The following example configures CacheServe to redirect queries and prefixes that match
entries on two lists.
The example covers the following:
l Creating a policy.
l Adding a redirection action to the policy.
l Making a list of domains that you want to redirect.
l Adding a policy selector that executes the redirection for anything that's on the "mali-
cious domains" list.
l Binding the policy to a view.
Create the malicious redirection policy
As before, since we're implementing malicious domain redirection, we'll use the name mdr-
redirect-policy.

40 Malicious domain redirection
1. In CacheServe, create a policy:

cacheserve> policy.add name=malicious-redirect-policy
{
}
Add a malicious redirection action

Next, add the action that you wish to accomplish to the policy (we'll cover how the action is
applied a little later, in "Make a malicious redirection policy selector
1. In Vantio, retrieve the mdr-category value from the server:

vantio> server.get
{
type => 'server.get'
...
mdr-category => (('malicious' ('192.168.1.1.'))
...
}
2. You will need both the IPv4 and IPv6 addresses (you may need to convert the IPv4
address. In this case, those addresses are:
192.168.1.1
2001:db8:f61:a1ff:0:0:0:80
3. In CacheServe, add the redirection action to the policy you created earlier, using the IPv4
and IPv6 addresses you looked up:
cacheserve> cacheserve> policy.update name=malicious-redirect-policy
action=(answer ((A 192.168.1.1)(AAAA 2001:db8:f61:a1ff:0:0:0:80)))
{
}
Make malicious redirection lists

In this step, you'll first create a list that holds the names you want to exempt from redirection,
and then you'll create a list that holds the prefixes you want to exempt from redirection.
1. In Vantio, retrieve the domains for the relevant views:

vantio> mdr-list-domains view=world
{
type => 'mdr-list-domains'

name => 'infect-internet-explorer.com'

category => 'malicious'
}
{
name => 'infect-chrome.com'
category => 'malicious'
}
2. In CacheServe, create a name-list. This name-list will contain the names of queries you
want to redirect:
cacheserve> name-list.add name=redirect-malicious-domains
{
}
3. In CacheServe, add the names you want to redirect as name-nodes in the name-list you
cacheserve> name-node.add list=redirect-malicious-domains
name=infect-internet-explorer.com
{
}
Make a malicious redirection policy selector

You've defined the action you want to take (redirection) and you've defined lists of domains and
prefixes that you want to redirect.
Note: You can redirect any query type; just substitute the appropriate type for A or AAAA in
the example.
Now you need to link them together in the policy you created in the beginning.
1. Add a selector that combines the action you created (redirect A and AAAA queries) with
the list you created, and associate the selector with a policy:
cacheserve> policy.update name=malicious-redirect-policy selector=
(and ((qtype (A AAAA)) (qname (redirect-malicious-domains
subdomain))))
{
}
2. Check the results:

42 Malicious domain redirection
cacheserve> policy.get name=malicious-redirect-policy

{
type => 'policy.get'
name => 'malicious-redirect-policy'
selector => ('and' (('qtype' ('A' 'AAAA')) ('qname' ('redirect-
malicious-domains' 'subdomain'))))
}
Bind the malicious redirection policy to a view

The policy won't do anything unless it's bound to a view (and that view is bound to a view-
selector):
1. Bind the policy you created to the appropriate view, having the policy execute prequery
(because you want to redirect before the query is resolved) and giving the policy a high
priority:
cacheserve> binding.add view=world policy=malicious-redirect-policy
when=prequery priority=1
{
}

Chapter 7: Simple rate-lim-
iting
The following walkthrough demonstrates a simple rate-limiting use case, both as defined in
Vantio CacheServe 5 and in Vantio CacheServe 7.
In CacheServe 5
In CacheServe 5, traffic was rate-limited using the following configuration (please note that the
return has been edited for conciseness):
vantio> server.get
{
rate-limiting => 'true'
rate-limiting-max-qps => '10'
rate-limiting-unenforced => 'false'
rate-limiting-truncate-factor => '0'
}
This configuration limits traffic to 10qps, and does not truncate traffic.
In CacheServe 7
In CacheServe 7, rate-limiting is accomplished using policies.
1. Define a ratelimiter that constrains QPS to 10, and applies to each client:
cacheserve> ratelimiter.add name=overall-qps10 qps=10 \
fields=((client-network (32 128)))
2. Define a policy to drop traffic which exceeds the qps limit, using the new ratelimiter:

44 In CacheServe 7
cacheserve> policy.add name=rl10 action=drop \

selector=(ratelimiter overall-qps10)
3. Bind the policy to the server with an appropriate priority:

cacheserve> binding.add policy=rl10 server=1 priority=10

Chapter 8: Rate-limiting
DNS amplification attacks
A Domain Name System (DNS) amplification attack indirectly permits an attacker to increase
their own bandwidth by overloading the bandwidth available to a victim’s DNS resolver.
How DNS amplification attacks work

The attacker sends a small query, often with a spoofed source address, which results in a large
response. With most attacks, the attacker’s intention is to take down a network, web site, or ISP.
Amplification attacks center on the response size; it's particularly important to note that a DNS
amplification attack may have a low queries-per-second (qps) rate, but still consume a
tremendous amount of bandwidth.
Characteristics of amplification attacks

Amplification attacks possess some characteristics that can help you identify them:
l "Purpose-built" attack domains with large numbers of A or TXT records that hover right
around the 4000-byte boundary.
l Domains with large numbers of A or TXT records that only make sense in the context of
an attack. For instance, large quantities of A records pointing to the same IP, or large
quantities of TXT records containing bizarre or arbitrary counters.
Mitigating amplification attacks

This section of the manual will walk you through several use cases:

46 Dealing with purpose-built amplification domains
1. Dealing with purpose-built amplification domains:

l Identifying purpose-built amplification domains
l Adding purpose-built amplification domains to lists
l Creating a policy that excludes purpose-built amplification domains.
2. Managing ANY queries to legitimate domains:

l Rate limiting ANY traffic
l Creating a policy that manages ANY queries to legitimate domains
3. Managing dual-use domains that are legitimate, but can also be used for an attack:
l Rate limiting dual-use domain traffic
l Creating a policy that manages dual-use domains.
4. Rate-limiting traffic that exceeds a certain qps threshold or maximum response size.
Dealing with purpose-built amplification

domains
To recap: purpose-built amplification domains are domains constructed specifically for use in
DNS amplification attacks. Queries for these domains usually possess the characteristics in
“Characteristics of amplification attacks.”
Identifying purpose-built amplification domains

Nominum's statmon utility is useful for finding out what domains are being used to attack you,
as well as what types of query are being used.
Note: The full capabilities of the statmon utility are beyond the scope of this manual; consult
the "Monitoring Query and Request Data on Nominum Engines" manual for comprehensive
details.
The best time to identify purpose-built amplification domains is when you suspect an attack is
in progress.
1. Make sure you're using the statmon command-line interface:

[testbed etc]# nom_tell statmon
statmon>
2. Identify the top domains by response size over the last hour:
statmon> querystore.top-domains-by-response-size duration=1h
If you see domains that you wouldn't expect to see in your top querying domains, make
note of them.
2. Further constrain results to just large packets (over 1024 bytes in size):

Dealing with purpose-built amplification domains 47
statmon> querystore.top-domains-by-response-size duration=1h filter=

((response-size-ge (true (1024))))
3. Identify which query types these domains are being asked for:
statmon> querystore.group-count group-by=(name query-type) filter=
((response-size-ge (true (1024))))
Adding purpose-built amplification domains to lists

Once you've identified your suspect domains, you should add them to lists. You're going to
create two lists: one for exact domains, and one for subdomains.
Using lists allows you to easily keep the list of domains updated, and to preemptively drop all
queries to any domain on the list, as well as any subdomains of a domain on the list.
Creating the domain list
1. Create a source file for the domains (for the file syntax, see name-list.load), and put it
somewhere you can find it. For the purposes of this example, we'll assume the list is /tm-
p/droppurpose-exact-list.
2. Make sure you're using the cacheserve command-line interface:
cacheserve>
3. Create the "exact match" name-list:

cacheserve> name-list.add name=droppurpose-exact
{
}
4. Using name-list.load, add the contents of your domain-name file to the name-list:
cacheserve> name-list.load name=droppurpose-exact
file=/tmp/droppurpose-exact-list
{
}
Creating the sub-domain list
1. Create a source file for the subdomains (for the file syntax, see name-list.load), and put it
somewhere you can find it. For the purposes of this example, we'll assume the list is /tm-
p/droppurpose-sub-list.
2. Make sure you're using the cacheserve command-line interface:

48 Managing ANY queries

cacheserve>
3. Create the "subdomains" name-list:

cacheserve> name-list.add name=droppurpose-sub
{
}
4. Using name-list.load, add the contents of your subdomain file to the name-list:
cacheserve> name-list.load name=droppurpose-sub
file=/tmp/droppurpose-sub-list
{
}
Creating and binding a policy for purpose-built amplification domains

Now that you've created lists for both purpose-built amplification domains and their
subdomains, you'll incorporate those lists into a policy, and bind that policy to the widest
possible view.
1. Create the policy, which will drop any query that matches an entry on the droppurpose-
exact or droppurpose-sub lists:
cacheserve> policy.add name=droppurpose action=drop selector=(or
((qname (droppurpose-exact exact)) (qname (droppurpose-sub subdomain
)) ))
{
}
2. Bind the policy to the server:

cacheserve> binding.add policy=droppurpose server=1 priority=10
{
}
Managing ANY queries

When you're dealing with DNS amplification attacks, you may see ANY queries used as part of
the attack.

Managing dual-use domains 49
Unfortunately, these queries can be directed to legitimate domains, which makes it difficult to
exclude these queries purely on the basis of size. For example, a legitimate domain could be
using DNSSEC, which would result in a lot of records at the top of the zone, some of them very
large (like DNSKEY).
A good workaround is to limit ANY queries on the basis of queries per second (qps). Although
limiting ANY queries on the basis of qps will cause those responses to be truncated, a querying
server that really needs the information can repeat the query over TCP.
1. Create a ratelimiter that constrains traffic on the basis of qps:

cacheserve> ratelimiter.add name=rateany qps=10 fields=(query-type )
2. Add a policy that truncates any response to a query that matches the ratelimiter:
cacheserve> policy.add name=truncate-rate-any selector=(and ((qtype
(ANY))(ratelimiter rateany))) action=truncate

cacheserve> binding.add server=1 policy=truncate-rate-any priority=20
Managing dual-use domains

Dual-use domains are domains that can both pass legitimate traffic or be used for an attack.
The management strategy for these domains centers around two things:
l Identifying certain types of queries that are likely to be used in amplification attacks.
l Truncating responses to those query types when the qps rate exceeds a given threshold.
In this example, you'll create exact-match lists and subdomain lists, and associate them with a
qps-rate-based ratelimiter.
Managing your lists
In "Creating the domain list", you created the droppurpose-exact list.
Here's how you add and delete entries from that list.
1. To add an entry to the list:

cacheserve> name-node.add list=droppurpose-exact name=netfirms.com
2. To remove an entry from the list:

cacheserve> name-node.delete list=droppurpose-exact name=netfirms.com

50 Rate-limiting amplification traffic
Rate-limiting traffic that matches your lists
1. Create the ratelimiter:

cacheserve> ratelimiter.add name=ratelarge qps=10 fields=(query-type
)
2. Add your list(s):

cacheserve> name-list.add name=ratelarge-a-exact
cacheserve> name-list.add name=ratelarge-a-sub element-type=name
3. Add a policy that truncates large responses to any domain on either of the lists:
cacheserve> policy.add name=truncacteratelarge action=truncate
selectors=(and ((qtype (A)) (or ((qname (ratelarge-a-exact exact))
(qname (ratelarge-a-sub subdomain ) ) )) (ratelimiter ratelarge)))

cacheserve> binding.add server=1 policy=truncacteratelarge
priority=30
Rate-limiting amplification traffic

As a final part of defending against amplification attacks, rate-limiting the traffic involved is one
of the most effective tools at your disposal.
Rate-limit clients that exceed qps thresholds

The following example rate-limits any client that exceeds 100 qps.
1. First, create a ratelimiter that applies to the entire client population, and constrain it to
100 qps:
cacheserve> ratelimiter.add name=clientlimiter qps=100
unenforced=true fields=((client-network (32 128)))
2. Next, add the ratelimiter to a policy that drops the response to any client matching the
rate limiter:
cacheserve> policy.add name=droprate-limitedclients action=drop
selector=(ratelimiter clientlimiter)
3. Finally, bind the policy to the server:

cacheserve> binding.add policy=droprate-limitedclients server=1
priority=10

Rate-limiting amplification traffic 51
Rate-limit queries by size

The following example rate-limits traffic based on the size of the response; note that this
ratelimiter is applied after the query response is created, but before it's sent.
1. First, create a ratelimiter that applies to all query types, and constrain it to 250 qps:
cacheserve> ratelimiter.add name=ratesize qps=250 fields=(query-type
)
2. Next, add the ratelimiter to a policy that truncates the response if any query exceeds
1500 bytes:
cacheserve> policy.add name=truncateoversize action=truncate
selector=(and ((response-size 1500) (ratelimiter ratesize)))
3. Finally, bind the policy to the server, specifying that the policy should execute before the
response is sent:
cacheserve> binding.add when=presend policy=truncateoversize server=1
priority=40

52 Rate-limiting amplification traffic

Chapter 9: ID spoofing
attacks
ID spoofing attacks are also known as ID guessing attacks or brute-force spoofing attacks.
How ID spoofing attacks work

In these attacks, the attacker sends forged DNS response packets to a caching server's query
source port, in an attempt to get the caching server to accept a forged packet in lieu of a
legitimate packet from an authoritative server.
The attack only succeeds if the random 16-bit value in the ID field of a forged packet matches
that of a legitimate packet. Therefore, an extremely large number of packets are required, each
containing a different guess for the ID value.
How CacheServe defends against ID spoofing

attacks
When CacheServe is waiting for a legitimate response from an authoritative server, and instead
gets a response with an incorrect ID value, it takes this as possible evidence that an ID spoofing
attack is underway. To protect itself, CacheServe repeats the query using TCP instead of UDP,
because TCP queries aren't vulnerable to the attack.
CacheServe sends each outgoing query from a randomly chosen port , selected from a pool of
ports.
This makes the server more resilient against ID spoofing attacks, as the attacker has to guess
both the query ID and the port.

54 Important ID-spoofing-related CacheServe configuration parameters
Important ID-spoofing-related CacheServe con-

figuration parameters
The following configuration parameters are important for controlling how CacheServe
responds to ID spoofing attacks.
l log-id-spoofing: this parameter controls when and how CacheServe issues warnings

about suspected ID spoofing attacks.
l qname-case-randomization: this parameter controls when and how CacheServe ran-
domizes the case of requests, making it harder for an attacker to correctly match a query.
l qname-case-randomization-exclusions: excludes certain queries from case ran-
domization.
l query-source-pool: this parameter controls the pool of available IPv4 ports from which
CacheServe can send outgoing queries.
l query-source-pool-v6: this parameter controls the pool of available IPv6 ports from
which CacheServe can send outgoing queries.
Caveats
Under normal circumstances, CacheServe gets some responses with incorrect IDs even
though no attack is in progress. This can be attributed to things like software errors in
authoritative servers, or extreme network delays that cause a response to show up long after
CacheServe has forgotten about the original query.
To prevent lots of spurious log messages, the conditions for issuing a log message are
necessarily more stringent than those for activating the defense mechanism itself. As a result,
it's normal for the ID spoofing defense mechanism to be triggered every so often, and you
shouldn't take it as ironclad evidence that an attack is underway. You should start investigating
if you start seeing log messages.

Chapter 10: The cacheserve
process
The cacheserve process is the main CacheServe software process.
By default, the cacheserve executable is installed in the /usr/local/nom/sbin directory.
CacheServe service scripts

A set of scripts are provided for convenience in starting and stopping CacheServe.
These scripts are installed in /etc/init.d, and are executed as arguments to the cacheserve
initialization script.
Script Description
cacheserve
Starts CacheServe.
start
cacheserve
Stops CacheServe.
stop
cacheserve
Displays CacheServe's operational status.
status
cacheserve con- Restarts CacheServe if CacheServe is running, but does not restart
drestart CacheServe if CacheServe isn't running.
cacheserve
Restarts CacheServe.
restart

56 --channel
--channel
shell# /usr/local/nom/sbin/cacheserve --channel channel-name
Specifies one or more Command Channel services on which CacheServe will listen. Each service
specified must be defined in the /etc/channel.conf file.
If no channel is specified, CacheServe listens on the cacheserve channel.
-c, --configuration
shell# /usr/local/nom/sbin/cacheserve --configuration /path/to/file
Use the specified configuration database instead of the default configuration database,
/var/nom/cacheserve/cacheserve.vdb2.
--directory
shell> /usr/local/nom/sbin/cacheserve --directory directory
Changes the current working directory of the cacheserve process to directory.
If no argument is specified, cacheserve runs from /var/nom/cacheserve.
If CacheServe is operating in a chroot() jail, directory is interpreted relative to the chroot() jail.
--dns-port
shell# /usr/local/nom/sbin/cacheserve --dns-port port-number
Sets the default UDP/TCP port CacheServe will use for DNS protocol traffic.
This option is mainly intended for server testing; a server us ing a port other than 53 will not be
able to communicate with the global DNS.
--dns-port controls both the port upon which the server listens for DNS queries and the port to
which outbound DNS queries (to other DNS servers) are sent.
--fd-limit
shell# /usr/local/nom/sbin/cacheserve --fd-limit 1000
Sets the maximum number of open file descriptors to the specified value, or fail.
If --fd-limit isn't specified, CacheServe will try to raise the limit to an appropriate value. If that
fails, CacheServe will raise the soft limit to the hard limit.

-F, --foreground-with-syslog 57
-F, --foreground-with-syslog
shell# /usr/local/nom/sbin/cacheserve --foreground-with-syslog
Configures CacheServe to run in the foreground and log messages to both standard error and
syslog.
CacheServe normally runs as a background daemon and logs to syslog.
-f, --foreground
shell# /usr/local/nom/sbin/cacheserve --foreground
Configures CacheServe to run in the foreground and log messages to standard error.
CacheServe normally runs as a background daemon and logs to syslog.
-h, --help
shell# /usr/local/nom/sbin/cacheserve --help
Prints a detailed help message.
--license
shell# /usr/local/nom/sbin/cacheserve --license license-path
Specifies a path to the product license file. The default license location is
/usr/local/nom/etc/cacheserve.license.
--no-statmon
shell> /usr/local/nom/sbin/cacheserve --directory directory
Configures CacheServe to not use the Nominum statmon utility.
Warning! This disables both auth-monitoring and monitoring functionality.
-r, --root
shell# /usr/local/nom/sbin/cacheserve --rootdirectory
Configures CacheServe to run under the specified directory. All paths, including that of the
configuration database, are interpreted relative to the specified root.

58 --statmon-directory
A nanny process continues to run with the original root directory, and changes the server's
root directory before starting the server.
Warning! -root provides no added security unless you also specify a non-root user with the -u,
--user option.
--statmon-directory
shell# /usr/local/nom/sbin/cacheserve --statmon-directorydirectory
Configures the directory that the Nominum statmon utility should use for locks and IPC files. By
default, this is /var/nom/statmon.
--directory must be set to the same value for the statmon process.
This argument has no effect on the location of querystore files; those settings are controlled
using querystore configuration in statmon and the CacheServe monitoring objects.
-s, --syslog-facility
shell# /usr/local/nom/sbin/cacheserve --syslog-facility facility
Specifies the syslog facility to which CacheServe should log.
The supported facilities are cron, daemon, kern, lpr, mail, news, user, uucp, local0, local1, local2,
local3, local4, local5, local6, local7, and on some plaforms ftp.
The default is daemon.
--usage
shell# /usr/local/nom/sbin/cacheserve --usage
Displays a brief usage message.
-u, --user
shell# /usr/local/nom/sbin/cacheserve --user username
Configures CacheServe to run as the specified user.
A nanny process continues to run as the original user, and changes the user ID of the server
process before starting the server.

-v, --version 59
-v, --version
shell# /usr/local/nom/sbin/cacheserve --version
Displays the CacheServe version.

60 -v, --version

Chapter 11: The
CacheServe utilities
CacheServe ships with several utilities:
l cacheserve-deleteconf, cacheserve-dumpconf, cacheserve-editconf and cacheserve-

loadconf, utilities that allow you to view or modify CacheServe's configuration outside
nom_tell (for more on nom_tell, see "Using nom_tell").
l cacheserve-stats, a utility which allows you to collect certain CacheServe statistics.
Supported objects
All of the CacheServe utilities support changes to the following configuration objects.
Note: Some of these objects may not be available unless you have a license for them.
Element Description
Provide containers for address-nodes and rep-

address-list
resent addresses and networks.
Represent bindings between policies and the server

binding
or views.
dns64 Represent DNS64 translation layers.
Represent setsof configuration information that can

layer
be selectively enabled or disabled.
name-node Represent all data associated with a single name in a

62 The CacheServe configuration file format
Element Description
name-list.
Execute specific actions based on the results from

policy
processing a DNS query.
Constrain traffic, using query or response fields to

ratelimiter group queries into buckets, and apply limits to those
buckets.
Represent a DNS cache and a set of properties

resolver
related to DNS resolution.
Represent complete CacheServe configurations.

Changes made to a server globally affect all other
server
configuration elements within the scope of that
server's influence.
view Provide customizable DNS namespaces.
Map DNS requests to views based on the source and

view-selector
destination addresses of the request.
The CacheServe configuration file format

A CacheServe configuration file is the text representation of the CacheServe configuration. It
takes the same form as the output of nom_tell commands (for more on nom_tell, see "Using
nom_tell").
The full configuration is surrounded by curly braces ({ and }), and each field is displayed as
key => value
value can be anything from a simple string all the way up to complicated data structures like
policy-actions or policy-selectors.
Whether it's a string or something more complicated, the value of each field consists of three
types of entry:
l lists, which are variable-length lists of elements where each element is of the same type;
l tuples, which are fixed-length elements where each element is of a different type;
l tables, which are variable-length tables of fields where each field is a key => value pair.
Each element in a list or tuple, and each value in a table, can also be a string, list, tuple, or table.
For example, take this resolver configuration:

Editing with cacheserve-editconf 63
{
preload => ((’localhost’ ’A’ ’127.0.0.1’))
log−dnssec => "true"
}
The whole thing is a table:

{
}
The preload field is a list consisting of 1 element:

{
}
The preload field's single element is a tuple of 3 values (the name, the type, and the data):
{
}
Finally, the log-dnssec field is a simple boolean value represented as a string:

{
}
Editing with cacheserve-editconf

cacheserve-editconf gives you a way to edit Cacheserve's configuration without using nom_tell.
Two ways to edit

cacheserve-editconf can edit in two ways:
l By updating a running server, or

l By updating a configuration database.
By default, cacheserve-editconf updates a running server; if you want to edit the configuration
database instead, use the --configuration option.
How it works
You use cacheserve-editconf from the command line, using command-line arguments to
specify the CacheServe configuration element you want to edit.

64 Editing with cacheserve-editconf
cacheserve-editconf options
Option What it does Syntax
--address
--address Changes the value of the element's address field.
value
Instructs cacheserve-editconf to communicate with the

running server using a different /etc/channel.conf value
than the default. --channel chan-
--channel
nel
The named channel must already exist in /etc/channel.conf:
see "The /etc/channel.conf file"
Instructs cacheserve-editconf to modify the designated --

configuration database instead of communicating with the configuration
-c or
running server. database-
--con-
name or
figuration CacheServe must not be using the database at the same -c database-
time you use cacheserve-editconf to edit the database. name
--destination-
--destination- Changes the value of the element's destination-address
address
address field.
address
Instructs cacheserve-editconf to the use the configuration

--layer from the specified layer instead of the default (operator) --layer layer
layer.
--list Changes the element's list value. --list list
--name Changes the element's name value. --name name
Required. -t type or
-t or
Instructs cacheserve-editconf to edit an element of this --object-type
--object-type
type. type
--policy Changes the value of the element's policy field. --policy policy
--server Changes the value of the element's server field. --server server
--source-
--source-
Changes the value of the element's source-address field. address
address
address
--version Displays cacheserve-editconf's version and exits. N/A

Loading data with cacheserve-loadconf 65
--view Changes the value of the element's view field. --view view
Loading data with cacheserve-loadconf

cacheserve-loadconf gives you a way to load Cacheserve configuration from text input.
Two ways to load data

cacheserve-loadconf can load data in two ways:

By default, cacheserve-loadconf updates a running server; if you want to load data to the
configuration database instead, use the --configuration option.
How it works
You use cacheserve-loadconf from the command line, using command-line arguments to
specify the CacheServe configuration element you want to load.
Configuration checking limitations

When it's updating an offline configuration database, cacheserve-loadconf does not check
configuration input as thoroughly as CacheServe itself.
This means it's possible for non-working configuration data to be accepted by cacheserve-
loadconf, but not be executeable by CacheServe.
If this happens, CacheServe will flag the problem in the errors field, but it reinforces the best
practice of making changes to your configuration database only when absolutely necessary,
and even then as infrequently as possible.
Loads multiple objects. If --object-type is specified, loads all

objects of that type.
--all --all does not attempt to reconnect if the connection is --all
dropped, and is therefore not recommended if you're
updating a running server.
Instructs cacheserve-loadconf to communicate with the --channel

--channel
running server using a different /etc/channel.conf value than channel

66 Dumping data with cacheserve-dumpconf
the default.

see The /etc/channel.conf file
Instructs cacheserve-loadconf to modify the designated --

configuration database instead of communicating with the configuration
-c or
running server. database-
--con-
name or
Instructs cacheserve-loadconf to check the configuration

--check --check
without actually loading it.
Instructs cacheserve-loadconf to the use the configuration

--layer from the specified layer instead of the default (operator) --layer layer
layer.
-t or
--object-type
--object-type Instructs cacheserve-loadconf to edit an element of this type. type
--version Displays cacheserve-loadconf's version and exits. N/A

Table 1: cacheserve-loadconf Options
Dumping data with cacheserve-dumpconf

cacheserve-dumpconf dumps configuration data about a CacheServe element to text.
Two ways to retrieve data

cacheserve-dumpconf can retrieve data in two ways:
l By querying a running server, or

l By querying a configuration database.
By default, cacheserve-dumpconf gets data from a running server; if you want to get
information from the configuration database instead, use the --configuration option.
How it works
You use cacheserve-dumpconf from the command line, using command-line arguments to
specify the CacheServe configuration element you want to retrieve.

Dumping data with cacheserve-dumpconf 67
Retrieves multiple objects. If --object-type is specified,

--all --all
retrieves all objects of that type.
--address
--address Retrieves the value of the element's address field.
value
Instructs cacheserve-dumpconf to communicate with the

running server using a different /etc/channel.conf value than
the default. --channel
--channel
channel
see "The /etc/channel.conf file" for more details.
Instructs cacheserve-dumpconf to retrieve data from the --

designated configuration database instead of configuration
-c or
communicating with the running server. database-
--con-
name or
--des-
--des-
Retrieves the value of the element's destination-address tination-
tination-
field. address
address
address
Instructs cacheserve-dumpconf to retrieve data from the

--layer --layer layer
specified layer instead of the default (operator) layer.
--list Retrieves the element's list value. --list list
Lists all elements or elements of a specific type.
If --object-type is specified, retrieves all objects of that type.

--list-all --list-all
The output of --list-all is formatted with one element to a line
if only a single element type is retrieved. If all elements are
retrieved, results are presented in a table.
--name Retrieves the element's name value. --name name
-t or
Instructs cacheserve-editconf to retrieve data for an --object-type
--object-type
element of a single type. type

68 cacheserve-deleteconf
If --all or --list-all are specified, restricts results to the

specified element type.
-o or Sends the output of cacheserve-dumpconf to a designated

--output file
--policy file. Otherwise, output goes to standard output.
--policy Retrieves the value of the element's policy field. --policy policy
--server
--server Retrieves the value of the element's server field.
server
--source-
--source-
Retrieves the value of the element's source-address field. address
address
address
--version Displays cacheserve-dumpconf's version and exits. N/A
--view Retrieves the value of the element's view field. --view view
cacheserve-deleteconf
cacheserve-deleteconf gives you a way to delete an element's configuration from without using
nom_tell.
Two ways to edit

cacheserve-deleteconf can modify data in two ways:

By default, cacheserve-deleteconf updates a running server; if you want to edit the

configuration database instead, use the --configuration option.
How it works
You use cacheserve-deleteconf from the command line, using command-line arguments to
specify the CacheServe configuration element you want to remove.
cacheserve-deleteconf options
Option What it does
--address
The address value of the element to be deleted..
address

cacheserve-stats 69
Option What it does
Instructs cacheserve-deleteconf to communicate with the running server

--channel chan- using a different /etc/channel.conf value than the default.
nel The named channel must already exist in /etc/channel.conf: see "The
/etc/channel.conf file".
-c database Instructs cacheserve-deleteconf to modify the designated configuration

or database instead of communicating with the running server.
--configuration CacheServe must not be using the database at the same time you use
database cacheserve-deleteconf to edit the database.
--destination-
The element's destination-address field.
address address
Instructs cacheserve-deleteconf to the use the configuration from the

--layer layer
specified layer instead of the default (operator) layer.
--list list The element's list value.
--name name The element's name value.
-t type
or Required.
--object-type Instructs cacheserve-deleteconf to remove an element of this type.
type
--policy policy The value of the element's policy field.
--server server The value of the element's server field.
--source-
The value of the element's source-address field.
address address
--version Displays cacheserve-deleteconf's version and exits.
--view view The value of the element's view field.
cacheserve-stats
The cacheserve-stats utility program retrieves statistics from a running CacheServe instance
and displays them in a tabular, human-readable form, emitting a new header every 24 lines.

70 cacheserve-stats
Options
Option Description
--channel Communicate with the running server using the specified channel as
channel configured in /etc/channel.conf) instead of the default, cacheserve.
-c, --
Specify that cacheserve-stats should display statistics at most this many times,
count
rather than running until interrupted.
count
Generate output in comma separated value form, rather than a table. In CSV
--csv form, a single header line is emitted, and the full statistics names are used, not
the abbreviated versions.
Specify which statistics to display. The names of the statistics are given as a
comma-separated list of statistic names.
The default is to display the following statistics:
l requests-received
-o, -- l responses-sent
statistics l requests-sent
statistics- l responses-received
list l user-time
l system-time
l cpu-time
l efficiency
l recursion-contexts-in-use
The special value "all" causes all supported statistics to be printed.
-v, --
Display the version of the server and exit.
version
-w, --wait Specify how long to wait between consecutive measurements, in seconds. The
interval default is 1 second.
Statistics
CacheServe provides the following statistics. Each statistic is documented with the name of the
statistic and the abbreviated description that's displayed as a column heading in the
cacheserve-stats output.
Most of the statistic names correspond directly to fields returned in server-statistics; the
exceptions are noted below.

cacheserve-stats 71
l requests-received (clnt req/s)

l responses-sent (clnt resp/s)
l requests-sent (auth req/s)
l responses-received (auth resp/s)
l tcp-requests-sent (tcp sent/s)
l rate-limited-requests (auth drop/s)
l requests-no-view (no view/s): These running packet counts are converted to packet rates
(packets/second).
l recursion-contexts-in-use (recur cntxs)
l tcp-clients (tcp clnts)
l memory-in-use (memory in-use): These instantaneous measurements are printed with
no postprocessing.
l user-time (user %cpu)
l system-time (sys %cpu): These running time measurements are converted into per-
centages of the total available CPU time.
l cpu-time (total %cpu): The sum of user-time and system-time.
l efficiency (q/cpusec): Indicates how many queries Vantio CacheServe has processed per
ssecond of CPU time used. This provides a measure of processing efficiency. To avoid
excessive roundoff errors, it is only displayed if Vantio CacheServe has used at least 1% of
the CPU time in the measurement interval.
l uptime (uptime): The amount of time that the Vantio CacheServe instance has been run-
ning, in seconds.

72 cacheserve-stats

Chapter 12: The
CacheServe objects
The objects, listed out and briefly explained.
address-list
address-lists contain nodes that represent addresses and networks. The contents of address-
lists are made up of address-nodes.
Commands
address-lists accept the following commands:
Command Description
address-list.add Creates a new address-list.
address-list.delete Deletes an address-list.
address-list.dump Dumps the contents of an address-list.
address-list.get Retrieves an address-list.
address-list.list Lists all address-lists.
address-list.load Populates an address-list with the contents of a file.
address-list.mget Retrieves multiple address-lists.
address-list.replace Replaces the values for an address-list.

74 address-list
Command Description
Updates an address-list with new values or resets val-

address-list.update
ues to their defaults.
Supported Fields
address-lists support the following fields:
count
integer
A read-only value that shows the number of elements in a list.
errors
Optional
string
A read-only field that indicates any problems with a specific object's configuration. errors will
only be present if there's a problem.
For example, an incorrectly configured resolver might return:

cacheserve> resolver.get name=my-resolver
{'errors': ['opening UDP source socket 0.0.0.0#51331: Too many open
files'], 'type': 'resolver.get', 'name': 'my-resolver'}
Use the server.all-errors command to display all misconfigured CacheServe elements.
name
Required
string
The name of the object.
post-edits
Optional
std-layered-edit-operation
Edits to be applied after the layer is composited.
pre-edits
Optional

address-node 75
Edits to be applied before the layer is composited.
Events
address-lists report the following events:
l address-list.changed
address-node
address-nodes represent all data associated with a single network in an address-list.
address-nodes accept the following commands:
Command Description
address-node.add Creates a new address-node.
address-node.delete Deletes an address-node.
address-node.get Retrieves an address-node.
address-node.list Lists all address-nodes.
address-node.mget Retrieves multiple address-nodes.
address-node.replace Replaces the values for an address-node.
Updates an address-node with new values or

address-node.update
resets values to their defaults.
Supported Fields
address-nodes support the following fields:
address
Required
addrpat
The address or network represented by this node.
count
integer

76 address-node
errors
Optional
string

list
Required
string
The list with which this object is associated.
post-edits
Optional
pre-edits
Optional
tag
Optional
string
An opaque tag associated with this object.

binding 77
Events
address-nodes report the following events:
l address-node.changed
binding
bindings represent bindings between policies and the server or views.
bindings accept the following commands:
Command Description
binding.add Creates a new binding.
binding.delete Deletes a binding.
binding.get Retrieves a binding.
binding.list Lists all bindings.
binding.mget Retrieves multiple bindings.
binding.replace Replaces the values for an address-node.
binding.update Updates a binding with new values or resets values to their defaults.
Supported Fields
Bindings take the following fields:
errors
Optional
string


78 binding
policy
Optional
string
The name of a policy.
post-edits
Optional
pre-edits
Optional
priority
Required
integer
The priority of a policy-binding operation. Priorities affect the execution order of policies.
Priorities are ranked by the lowest value, with 0 being the most important priority. Policies with
a lower priority value are executed before policies with a higher priority value.
As some policies execute before DNS resolution is performed, and other policies execute after
DNS resolution is performed, policies are only compared to other policies that are executing at
the same time.
If multiple bindings specify the same priority, the order of execution is considered undefined.
Therefore, you should consider specifying priorities with some flexibility to them. For example,
instead of using the priorities 0, 1, 2, 3, 4 and so on, you may want to consider using 0, 10, 20, 30,
40 or even 0, 100, 200, 300, 400.
server
Optional
boolean
May only be 1, and is mutually exclusive with the view field.

connection 79
Indicates that the binding target is the server object.
This binding matches all queries.
view
Optional
string
The view to which this object applies.
when
Optional
postquery prequery | presend
The default is prequery.
Specifies the time in the DNS processing cycle when a policy-binding operation should execute.
prequery
bindings are executed prior to cache lookup and/or resolution. DNS processing is aborted if a
prequery binding produces a response. If a CNAME or DNAME is followed, prequery bindings
may be executed multiple times for a single query.
postquery
bindings are executed after prequery bindings and/or normal DNS processing. If a CNAME or
DNAME is followed, postquery bindings may be executed multiple times for a single query.
presend
bindings are executed after the full DNS response has been constructed, immediately prior to
sending the response.
Events
bindings report the following events:
l binding.changed
connection
connections represent the properties of a Nominum Command Channel connection.
Connections never persist, and always refer to the Command Channel connection on which its
commands are sent.
connections accept the following commands:

80 dns64
Command Description
connection.get Retrieves a connection.
Subscribes a connection to all events, overriding

connection.subscribe-all
any existing list of events.
connection.replace Replaces the values of a connection.
Updates a connection with new values or resets

connection.update
values to their defaults.
SupportedFields
Connections take the following fields:
all-events
event-name
A read-only list of all supported events for this connection.
events
Optional
event-name
Lists the events currently registered by a connection.
idle-timeout
Optional
time-in-seconds
Specifies the amount of time before a connection will be closed in the absence of traffic.
Defaults to 5 minutes (300 seconds). If any events are specified for the connection, there is no
timeout.
dns64
dns64 objects represent DNS64 translation layers. dns64 objects only have an effect when
they're paired with active policies.
DNS64 translation layers map IPv4 addresses into IPv6 addresses as defined in RFC6147.

dns64 81
This enables additional processing for DNS AAAA queries; if no AAAA records exist for a queried
name, but A records exist, AAAA records can be generated from A records according to a set of
mapping rules. The synthesized answer is then returned to the client.
DNS64 also provides additional processing for PTR queries; if a PTR query is received for a
name that matches a defined DNS64 prefix, CacheServe will synthesize a CNAME which points
at the reverse map entry in the IPv4 reverse space.
dns64 objects accept the following commands:
Command Description
dns64.add Creates a new dns64 object.
dns64.delete Deletes a dns64 object.
dns64.get Retrieves a dns64 object.
dns64.list Lists all dns64 objects.
dns64.mget Retrieves multiple dns64 objects.
dns64.replace Replaces the values for a dns64 object.
dns64.update Updates a dns64 object with new values or resets values to their defaults.
Supported Fields
dns64 objects take the following fields:
errors
Optional
string


82 dns64
mapped
Optional
(acl-element ...)
Specifies an ACL instructing CacheServe to map only certain IPv4 A records into IPv6 AAAA
records.
Otherwise, all IPv4 addresses are mapped into IPv6 addresses.
name
Required
string
post-edits
Optional
pre-edits
Optional
prefix
Required
addrpat6
An addrpat6 specifying the IPv6 prefix for a dns64 configuration object.
The prefix must exactly match one of the following bit lengths:
l 32
l 40
l 48
l 56
l 64
l 96

layer 83
suffix
Optional
addr6
An addr6 specifying the bits that will trail IPv6 addresses constructed from IPv4 addresses.
Any bits specified in the suffix must not overlap bits in the prefix, reserved bits, or the mapped
IPv4 address.
Events
dns64 objects report the following events:
l dns64.changed
layer
layers are sets of configuration information that can be selectively enabled or disabled. One of
the primary uses for layers is to store CacheServe's critical configuration in an "operational
layer" that remains unchanged, and add services by adding layers that contain the
configuration for that service.
This operational layer is the operator layer, , it has a priority of 0 (the highest priority) and it
cannot be deleted.
layers accept the following commands:
Command Description
layer.add Creates a new layer.
Clears faults from a layer's provisioning session and

layer.clear-fault causes CacheServe to re-establish communication
with the authoritative server.
layer.delete Deletes a layer.
layer.get Retrieves a layer.
layer.list Lists all layers.
layer.mget Retrieves multiple layers.
Erases all data from the layer, and reloads layer data
layer.reimage
from the provisioning server.
layer.replace Replaces the values for a layer.

84 layer
Command Description
Updates a layer with new values or resets values to

layer.update
their defaults.
Layers and Provisioning

Layer ordering is controlled by the layer's priority field. Layers with higher priority (a lower
priority field value) take precedence over layers with a lower priority (a higher priority field
value).
When a layer is reimaged, either because it's the initial transfer of content or the database ID
has changed, CacheServe sends a layer.provisioning-reimaging event.
Provisioning connection attempts use exponential backoff: the first reconnection attempt is at

1 second, the second at 2 seconds, the third at 4 seconds and so forth up to a maximum of 32
seconds.
If you want to disable communications with a provisining server, unset the channel field on the
layer. The layer content will remain, and if you re-enable the channel field, provisioning will pick
up where it left off.
Supported Fields
Layers support the following fields:
channel
string
A Command Channel service name, as defined in the local channel configuration file (usually
/etc/channel.conf).
This service should point to a provisioning server, and may not coexist with the server field.
errors
Optional
string

layer 85

hidden
Optional
boolean
A value that indicates whether or not a layer affects the server's active configuration. Changing
this value forces an automatic server restart.
If hidden is set to true, the layer's contents do NOT affect the server's active configuration. For
provisioned layers, provisioning changes will be applied, but have no visible effect until the layer
is unhidden.
If hidden is set to false (the default), the layer's contents affect the server's active configuration.
name
Required
string
priority
Required
integer
The priority of a layer. Layers are ranked by the lowest value, with 0 being the most important
layer. Layers with a lower priority value take precedence over layers with a higher priority value.
The operator layer is always priority 0 and has precedence over all other layers: the operator
layer cannot be deleted.
provisioning
provisioning-status
A read-only field that reports the provisioning status of a layer.
server
Optional

86 name-list
addr-or-nameuint16, string-empty-ok
A composite of (addr-or-name, uint16, string-empty-ok) that defines a provisioning

server's DNS name (the addr-or-nameaddr-or-name and port (the uint16), along with a shared
secret (the string-empty-ok) to use in secure communications.
The system's resolver configuration is used to resolve the server's DNS name.
Events
layers report the following events:
l layer.changed
l layer.provisioning-connected
l layer.provisioning-connection-failure
l layer.provisioning-disconnected
l layer.provisioning-reimaging
l layer.provisioning-update-failure
l layer.provisioning-update-success
name-list
name-lists contain nodes that represent DNS names. The contents of name-lists are made up
of name-nodes.
name-lists accept the following commands:
Command Description
name-list.add Creates a new name-list.
name-list.delete Deletes a name-list.
name-list.dump Dumps the contents of a name-list.
name-list.get Retrieves a name-list.
name-list.list Lists all name-lists.
name-list.load Populates a name-list with the contents of a file.
name-list.mget Retrieves multiple name-lists.
name-list.replace Replaces the values for a name-list.
Updates a name-list with new values or resets values to

name-list.update
their defaults.

name-list 87
Supported Fields
name-lists support the following fields:
count
integer
errors
Optional
string

name
Required
string
post-edits
Optional
pre-edits
Optional

88 name-node
Events
name-lists report the following events:
l name-list.changed
name-node
name-nodes represent all data associated with a single name in an name-list.
name-nodes accept the following commands:
Command Description
name-node.add Creates a new name-node.
name-node.delete Deletes a name-node.
name-node.get Retrieves a name-node.
name-node.list Lists all name-nodes.
name-node.mget Retrieves multiple name-nodes.
name-node.replace Replaces the values for a name-node.
Updates a name-node with new values or resets values

name-node.update
to their defaults.
Supported Fields
name-nodes support the following fields:
encrypted
Optional
boolean
If this value is true, the node's name has been encrypted.
errors
Optional
string

name-node 89

list
Optional
string
name
Required
string
post-edits
Optional
pre-edits
Optional
tag
Optional
string
Events
name-nodes report the following events:
l name-node.changed

90 policy
policy
policies are a way for CacheServe to execute specific actions based on the results from
processing a DNS query. They are connected to the server or views with bindings.
policies consist of three things:
l A selector, which determines whether or not the policy should be applied to a query;
l An action, which is a CacheServe operation;
l Child policies, which are policies related to the current policy, and that execute after the
current policy completes.
policies accept the following commands:
Command Description
policy.add Creates a new policy.
policy.delete Deletes a policy.
policy.get Retrieves a policy.
policy.list Lists all policies.
policy.mget Retrieves multiple policies.
policy.replace Replaces the values for a policy.
policy.update Updates a policy with new values or resets values to their defaults.
Supported Fields
Policies support the following fields:
action
Optional
policy-action
The policy-action the policy should run when applied to a query. If this field is empty, no action
is taken.
children
Optional
string

policy 91
A list of strings identifying child policies attached to the current policy. All children are executed
immediately after the parent policy.
errors
Optional
string

name
Required
string
post-edits
Optional
pre-edits
Optional
Events
policies report the following events:
l policy.changed
l policy.hit

92 ratelimiter
ratelimiter
ratelimiters constrain traffic; they use query or response fields to group queries into buckets,
and apply limits to those buckets.
ratelimiters accept the following commands:
Command Description
ratelimiter.add Creates a new ratelimiter.
ratelimiter.delete Deletes a ratelimiter.
ratelimiter.get Retrieves a ratelimiter.
ratelimiter.list Lists all ratelimiters.
ratelimiter.mget Retrieves multiple ratelimiters.
ratelimiter.replace Replaces the values for a ratelimiter.
ratelimiter.update Updates a ratelimiter with new values or resets values to their defaults.
Supported Fields
Ratelimiters support the following fields:
bps
Optional
integer
Specifies the maximum bytes per second for the ratelimiter.
errors
Optional
string


ratelimiter 93
fields
Required
((’client‐network’ (ipv4netlen, ipv6netlen)) | (’query‐name’ (name-label-
count)) | ’query‐type’ ...)
string
Specifies the fields to use when grouping requests into entries. Each field specified increases
granularity.
For example, (client-network (32 128)) groups each client into its own entry.
If both client-network and query-type are used, a new entry is generated for that specific
combination, and the defined rate limits are applied to the combination.
maximum-entries
Optional
positive-integer
Specifies the maximum number of entries to track, which indicates how many field
combinations can be tracked.
The maximum value is unlimited and the default is 10,000.
name
Required
string
post-edits
Optional
pre-edits
Optional

94 resolver
qps
Optional
integer
Specifies the maximum queries per second for the ratelimiter.
unenforced
Optional
boolean
Enables statistics, log messages and events related to rate limiting without actually dropping or
truncating answers. Defaults to false.
Events
ratelimiters report the following events:
l ratelimiter.abate
l ratelimiter.changed
l ratelimiter.onset
resolver
resolvers represent a DNS cache and a set of properties related to DNS resolution.
resolvers accept the following commands:
Command Description
resolver.add Creates a new resolver.
resolver.delete Deletes a resolver.
resolver.get Retrieves a resolver.
resolver.list Lists all resolvers.
resolver.mget Retrieves multiple resolvers.
resolver.replace Replaces the values for a resolver.
resolver.update Updates a resolver with new values or resets values to their defaults.

resolver 95
Supported Fields
Resolvers support the following fields:
dnssec-aware
Optional
boolean
Indicates whether or not DNSSEC information should be requested and cached. The default is
false.
Note: dnssec-aware is automatically enabled when you enable either trusted-keys or

managed-keys.
DNSSEC signatures will not be verified unless trusted-keys or managed-keys are configured.
Requesting and caching DNSSEC information will significantly increase the amount of network
traffic.
errors
Optional
string

forward
Optional
(( name , 'first' | 'off' | 'only', (addrport...)) ...)
Causes queries within a specific domain to be forwarded to one or more specific recursive
name servers.
name specifies the domain; first, off or only specify the forwarding mode; and the final addrport is
a list of recursive name servers.

96 resolver
The forwarding mode parameter may take one of three options:
l first: First attempt to use the forwarders. If they do not respond, attempt to resolve the
query.
l off: Disable forwarding for a subdomain. If you specify off, you must leave the server
addrport empty.
l only: Use only the forwarders. If they do not respond, do not attempt to resolve the
query, and let it fail.
hints
Optional
(name, ((name, (addr ...)) ...))
Configures the resolver to use specific servers as root hints.
These servers are queried to discover the current set of root servers. If there is no hints field,
this resolver will use a compiled-in set of root hints. The name must always be . (the root
name), as providing hints for domains other than the root is meaningless.
ignore-first-referral
Optional
boolean
The default is true.
When ignore-first-referral is set to true and CacheServe is performing recursive resolution,

CacheServe ignores the first referral seen for each zone cut, and reissues the query to the
authoritative servers for that zone cut's parent.
Although it results in a small increase in network traffic, ignore-first-referral reduces the risk of
delegation-spoofing attacks.
log-dnssec
Optional
boolean
Useful for debugging DNSSEC validation failures.
When set to true, log-dnssec configures CacheServe to log detailed information about DNSSEC
validation failures. All messages related to DNSSEC validation are logged at priority LOG_INFO,
and log entries are prefixed with "dnssec:".
For log-dnssec to work, you must have DNSSEC trust anchors defined.

resolver 97
log-id-spoofing
Optional
boolean
Configures CacheServe to issue a log message when it suspects an ID spoofing attack. The log
message is only issued when there's a relatively strong suspicion that an actual attack is taking
place.
The id-spoofing-defense-queries statistic tracks the number of times the defense mechanism
has been triggered.
log-lame
Optional
(name ...)
A list of names. Causes CacheServe to log lame delegations and other configuration errors
detected in authoritative servers during resolution. log-lame domains should belong to your
own organization.
When log-lame is enabled, CacheServe will log other errors from authoritative servers in
addition to lame delegations, such as malformed responses, RCODES indicating a server error,
and NS records pointing at CNAMEs.
managed-keys
Optional
(( name , (rdata...)) ...)
A tuple of domain name and rdata that defines DNSSEC managed keys. Each managed-key
domain may include one or more keys, formatted as DNSKEYs (RFC4034).
Managed-keys are similar to trusted-keys, but are automatically maintained (as described in
RFC5011). The set of keys (as well as state) is persistently stored, and maintained over time,
including a periodic refetch of the DNSKEY set.
When managed-keys is initially configured, if there are any keys present for a domain,
CacheServe tries to verify signatures in the retrieved DNSKEY set. If it can't verify any of the
signatures, CacheServe considers the domain insecure.
Managed-keys are normally used only for the root zone, so CacheServe has the current root
key compiled in. If the root domain is specified in the managed-keys field, but no keys are
specified, CacheServe will use that root key to verify the root DNSKEY set.

98 resolver
For example, to update a managed-key for a resolver:

cacheserve> resolver.update name=r-int managed-keys=(("." ("257 3 8
AwEAAagAIKlVZrpC6Ia7gEza \
hOR+9W29euxhJhVVLOyQbSEW0O8gcCjFFVQUTf6v58 \
fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRk\
xoXbfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZx \
kjf5/Efucp2gaDX6RS6CXpoY68LsvPVjR0ZSwzz1ap \
AzvN9dlzEheX7ICJBBtuA6G3LQpzW5hOA2hzCTMjJPJ8LbqF \
6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relSQageu+ipAdTTJ \
25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulqQxA+Uk \
1ihz0=")))
managed-keys-state
Optional, read-only
((name, { expire => time-in-seconds
has-validated => boolean
keys => ({
created => time-in-seconds
key => string
keyid => integer
next => time-in-seconds
state => 'add-pending' | 'missing' |
'removed' | 'revoked' | 'start' | 'valid'
updated => time-in-seconds
} ...)
last-fetch => time-in-seconds
next-fetch => time-in-seconds
}) ...)
A read-only field that reflects the current managed-key state.
max-cache-size
Optional
sizeval
specifies the maximum amount of memory which can be used by this resolver's cache. The
default is 200M.
Values larger than 16G are treated as 16G, and values smaller than 64M are treated as 64M.
max-cache-ttl
Optional
time-in-seconds

resolver 99
Sets the maximum amount of time for which the server will cache ordinary (positive) answers.
The default is 604800 (7 days).
Values in excess of one year are treated as one year.
max-client-ttl
Optional
time-in-seconds
Specifies the maximum TTL that CacheServe will return in a response.
max-client-ttl only affects responses to DNS clients, not actual caching; a DNS record can
remain in the cache for the full amount of time even if clients receive a smaller value.
max-edns-udp-size
Optional
integer
Configures the advertised EDNS packet size. The default is 4096.
When this field is configured, CacheServe, when sending EDNS queries, advertises that packets
of up to this length (in bytes) can be reassembled. Values smaller than 512 and larger than 4096
are treated as 512 and 4096, respectively.
This option is particularly useful if a firewall or other network device is dropping IP fragments,
because for large packets, this would effectively result in timeouts and resolution failures.
max-ncache-ttl
Optional
time-in-seconds
Specifies the maximum amount of time that CacheServe will cache negative answers. Defaults
to 10800 (3 hours).
Values in excess of one week are treated as one week.
max-tcp-recursions
Optional
integer
Specifies the maximum number of in-progress TCP recursions. Defaults to 1000.
The default value should be sufficient for most use cases.

100 resolver
name
Required
string
negative-trust-anchors
Optional
(name ...)
Turns off DNSSEC validation for a domain, even if that domain is under a security root.
post-edits
Optional
pre-edits
Optional
prefetch-ratio
Optional
integer
Adjusts CacheServe's criteria for whether or not it issues prefetch queries. The default is 16.
Prefetching is normally performed when a query requests data that's already cached but is set
to expire soon from the cache. This prevents commonly-accessed data from ever expiring.
Note: Changing this value is not recommended, and you should only change it under the
direction of Nominum support.
preload
Optional
(( name , rdatatype, rdata) ...)

resolver 101
Preloads the cache with a fixed resource record, specified by a combination name, rdatatype
and rdata.
Note: preload is specifically intended to predefine reverse and/or forward mapping of either
localhost or the local host name, and should not be used for any other purpose.
For example, to preload localhost:

preload 1.0.0.127.in-addr.arpa PTR localhost
To preload the local host name:

localhost.example.com A 127.0.0.1
preload-nxdomain
Optional
(name ...)
Warning! preload-nxdomain is an option included for the sake of completeness. Don't use it
unless you're specifically told to by Nominum support!
A name that, like preload and preload-nxrrset, preloads the cache.
Note: preload-nxdomain affects only a single name; if you want to affect an entire domain, use
synthesize-nxdomain.
preload-nxrrset
Optional
((name, rdatatype) ...)
Note: preload-nxrrset is an option included for the sake of completeness. Don't use it unless
you're specifically told to by Nominum support!
Preloads CacheServe with an indication that no resource record of a given name and type
exists.
For example, to specify that no AAAA record exists for the local hostname:
preload-nxrrset host.domain AAAA
qname-case-randomization
Optional
'enforced' | 'off' | 'silent-enforced' | 'unenforced'

102 resolver
Indicates whether CacheServe should randomize letters in a query name when sending
queries to authoritative servers or forwarders. Defaults to off.
Enforced and silent-enforced modes trigger CacheServe's spoofing defense mechanism.

Modes other than silent-enforced create a log entry when the response does not preserve the
query's case.
qname-case-randomization-exclusions
Optional
(name ...)
Specifies exceptions to qname-case-randomization. Defaults to no exceptions.
query-source-pool
Optional
(uint16, addrport4)
Sets the address CacheServe will use to send outgoing IPv4 UDP queries, configuring
CacheServe to send from a randomly selected port within a pool of multiple source ports.
The uint16 specifies the number of ports. The maximum number of ports is 2048.
The addrport4 can be nonzero, zero, or empty:
l If the addrport4 is nonzero, ports are allocated sequentially, starting at that number.
l If the addrport4 is zero or empty, ports are chosen randomly.
This option is used in conjunction with CacheServe's ID spoofing defense mechanism,

described in "ID spoofing attacks".
If you don't specify query-source-pool, CacheServe creates a query source pool with a number
of ports that's appropriate for the OS.
Warning! When you're choosing the number of ports to use, make sure you don't exceed the
OS's file-descriptor limit. Each port uses a file descriptor, and additional file descriptors are
needed for listen-on-matching and things like outgoing and incoming TCP connections.
query-source-pool-v6
Optional
(uint16, addrport6)

resolver 103
Sets the address CacheServe uses to send outgoing IPv6 UDP queries, configuring CacheServe
to send from a randomly selected port within a pool of multiple source ports.

described in "ID spoofing attacks.
If you don't specify query-source-pool-v6 and CacheServe has been configured to use IPv6
transport (by including type AAAA in server-address-lookup-order), CacheServe creates a
query source pool with an appropriate number of ports for the OS.
Format:
rrset-order
Optional
'cyclic' | 'fixed' | 'random'
Sets the order in which resource records (RRs) in a resource record set (RRset) are added to a
response. The default is cyclic.
l cyclic configures CacheServe to use a random starting point in the list of RRs and wrap
around to the beginning of the list when the end is reached.
l fixed configures CacheServe to always emit RRs in the order in which they are stored.
l random configures CacheServe to use a random permutation of the RRs.
server-address-lookup-order
Optional
('A' | 'AAAA' ...)
Defines the order in which CacheServe should use IPv4 or IPv6 server addresses.
The argument is a list of address record types that may be either A or AAAA.

104 resolver
The default is A, which configures CacheServe to use only IPv4 addresses for nameserver
addresses, and thus IPv4 transport only for communications with the authoritative server.
The same value may not occur multiple times in the list, and only nameserver addresses of the
specified types are used, in the listed order.
For example, if your site has some IPv6 connectivity to the Internet, you can specify (A AAAA),
and CacheServe will attempt IPv4 first; if your site has mostly IPv6 connectivity, you can specify
(AAAA A) and CacheServe will attempt IPv6 first.
If you want to limit CacheServe to only IPv6 transport, specify (AAAA).
stub
Optional
(( boolean , (( boolean , (addrport ...)) ...)) ...)
Defines stub resolvers.
Queries within each domain are resolved as if the specified servers were delegated authority
for that domain.
Warning! A specific domain may only appear once per stub per resolver, and you can't have
the same entry in both stub and synthesize-nxdomain.
The main use for stub resolution is in situations where you need to resolve a domain using a
particular set of servers that haven't actually been delegated authority.
For example, if you're using RFC1918 private addresses (10.*), you might want to define a stub
for 10.in-addr.arpa, so that queries for that domain get directed to your own set of internal
authoritative servers.
synthesize-nxdomain
Optional
(name ...)
Configures CacheServe to return synthetic NXDOMAIN responses for all queries within the
specified domains.
synthesize-nxdomain is roughly equivalent to a stub element pointing at an authoritative

server that's configured with an empty zone.
Whereas preload-nxdomain affects only a single name, synthesize-nxdomain affects an entire

domain.

server 105
The primary utility of synthesize-nxdomain is to prevent unnecessary delays and pointless

external network traffic, caused by reverse lookups of RFC1918 private addresses, especially in
cases where there's no need to return a PTR record for those lookups.
Domains cannot appear in both stubs and synthesize-nxdomain.
Note: If you need to return PTR records for RFC1918 addresses, use a stub pointing at one or
more authoritative servers configured with the right reverse mapping data!
trusted-keys
Optional
((name, (rdata ...)) ...)
Defines DNSSEC trusted keys. Enabling this option automatically enables dnssec-aware, and
configures CacheServe to perform DNSSEC verification on all DNS data in a subdomain of a
security root.
The trusted−keys field can contain multiple key entries,each consisting of the key’s domain
name and rdata. If any trusted-keys are defined, DNSSEC information will be requested and
cached as if the dnssec−aware option were enabled.
Events
resolvers report the following events:
l resolver.changed
l resolver.flush
l resolver.id-spoofing-suspected
server
servers represent complete CacheServe configurations, and changes made to a server will
globally affect all other configuration elements within the scope of that server's influence.
servers accept the following commands:
Command Description
server.add Creates a new server.
server.block-checkpoints Activates checkpoint blocking for a server.
server.get Retrieves a server.
server.statistics Returns statistics for a server.

106 server
Command Description
server.unblock-checkpoints Deactivates checkpoint blocking for a server.
server.replace Replaces the values for a server.
Updates a server with new values or resets

server.update
values to their defaults.
Supported Fields
Servers support the following fields:
commands-not-logged
Optional
boolean
Specifies whether or not DNSSEC information should be requested and cached when log-
command-channel is enabled.
errors
Optional
string

listen-on-matching
Optional
({
instances => integer
patterns => (acl-element ...)
port => uint16
} ...)

server 107
Configures CacheServe to listen for incoming DNS queries on addresses which match specified
patterns and ports. If no listen-on-matching value is given, CacheServe listens on all interfaces
on the default port (53).If port is 0 or not specified, CacheServe listens on the port specified by
the --dns-port command-line option, which defaults to the standard DNS port of 53.
listen-on-matching can contain multiple elements, which allows different listener ports to be
specified.patterns defaults to an ACL which matches any address.To listen on all interfaces, use
a pattern of 0.0.0.0/0 (IPv4) or ::/0 (IPv6).instances takes advantage of certain relatively new Linux
features, which permit multiple sockets listening on a single address and port. If you have this
capability, set instances to the number of desired UDP sockets.
instances defaults to 0, which configures CacheServe to use the best number of UDP sockets for
maximum concurrency. If instances is set to 0 and the interface is a loopback interface, or an
IPv6 link-local address, only 1 socket will be created.
For example, here's how you specify listen-on-matching to use 16 instances on the IP address
192.168.1.1 and 1 instance on 127.0.0.1, port 5334:
cacheserve> server.update listen-on-matching=({patterns=(192.168.1.1)
instances=16}{patterns=(127.0.0.1) port=5354})
{
type => 'server.update'
}
cacheserve> server.get
{
listen-on-matching => (
{
patterns => ('192.168.1.1/32')
instances => '16'
}
{
patterns => ('127.0.0.1/32')
port => '5354'
}
)
}
log-command-channel
Optional
boolean
Controls whether or not Command Channel messages are logged. When set to true,
commands are logged at the LOG_INFO priority, and large commands are truncated.

108 server
max-recursive-clients
Optional
integer
An integer that specifies the maximum number of recursive UDP lookups that can occur at any
one time. The default is 5000, and values over 50,000 are capped at 50,000.
The limit applies equally to recursive lookups coming from UDP clients and lookups that are
generated internally.
Nominum recommends configuring at least 20,000 recursion contexts, and up to 50,000,

depending on your available RAM. Each recursion context requires approximately 32K of RAM.
Note: TCP lookups are controlled by max-tcp-clients.
max-tcp-clients
Optional
integer
Controls the maximum number of TCP client connections at any one time. The default is 4.
Note: UDP clients are controlled by max-recursive-clients.
preload
Optional
and rdata.



server 109
post-edits
Optional
pre-edits
Optional
server-id
Optional
string-empty-ok
The server ID used to populate the server.id and bind.id values in responses to DNS CH TXT
queries for the server's ID, as well as NSID EDNS responses.
If server-id is empty or set to the literal string "none", CacheServe will refuse all queries for the
server ID, and ignore NSID requests.
server-version
Optional
string-empty-ok
The server version used to populate the version.server and version.bind values in responses to
DNS CH TXT queries for version.server and version.bind.
If server-version is set to the literal string "none", CacheServe will refuse all queries for the
server version. If server-version is empty, CacheServe will respond with the actual software
version.
time-zone
Optional
string
Identifies the timezone CacheServe will use. Values must match an entry in the 'TZ' column of
the IANA tzdb.

110 view
versioncheck-interval
Optional
versioncheck-days
Specifies how often CacheServe should check for a newer version. Defaults to 7, with a
minimum of 1 and a maximum of 30.
Events
servers report the following events:
l server.changed
l server.configuration-error
l server.formerr-loop
l server.restart
l server.stop
l server.tcp-client-limit
l server.udp-recursion-limit
view
views represent a customizable DNS namespace.
views accept the following commands:
Command Description
view.add Creates a new view.
view.delete Deletes a view.
view.get Retrieves a view.
view.list Lists all views.
view.mget Retrieves multiple views.
view.replace Replaces the values for a view.
view.update Updates a view with new values or resets values to their defaults.
Supported Fields
Views support the following fields:

view 111
errors
Optional
string

name
Required
string
post-edits
Optional
pre-edits
Optional
time-zone
Optional
string
the IANA tzdb.
Events
views report the following events:

112 view-selector
l view.changed
view-selector
view-selectors map DNS requests to views based on the source and destination addresses of
the request.
view-selectors accept the following commands:
Command Description
view-selector.add Creates a new view-selector.
view-selector.delete Deletes a view-selector.
view-selector.get Retrieves a view-selector.
view-selector.list Lists all view-selector.
view-selector.mget Retrieves multiple view-selector.
Simulates a query, and returns the view that

view-selector.query
would be selected.
view-selector.replace Replaces the values for a view-selector.
Updates a view-selector with new values or

view-selector.update
resets values to their defaults.
Supported Fields
View-selectors take the following fields:
destination-address
Optional
addrport
Requires a view-selector's destination address to match this address.
If destination-address includes a port number, the view-selector's destination address must

match both the address and port number. Otherwise, only the address must match.
errors
Optional
string

view-selector 113

post-edits
Optional
pre-edits
Optional
source-address
Optional
addrpat
Requires a view-selector's source address to originate within this network.
view
Optional
string
Events
view-selectors report the following events:
l view-selector.changed

114 view-selector

Chapter 13: Command ref-
erence
address-list.add
Description and usage
Creates a new address-list.
Fields
name
Required
string
layer
Optional
string
The layer for this object.
post-edits
Optional

116 Chapter 13: Command reference
pre-edits
Optional
Examples
cacheserve> address-list.add name=my-list
{
type => 'address-list.add'
address-list.delete
Deletes an address-list.
Fields
name
Required
string
layer
Optional
string
Examples
cacheserve> address-list.delete name=my-list
{
type => 'address-list.delete'
}

address-list.dump
Dumps the contents of the specified list to the file address-list.dump in cacheserve's working
directory.
Fields
name
Required
string
Examples
cacheserve> address-list.dump name=my-list
{
type => 'address-list.dump'
}
cacheserve> quit
[root@test cacheserve]# pwd
/var/nom/cacheserve
[root@test cacheserve]# ls -al
total 1589004
drwxr-xr-x 3 root root 4096 Jun 24 11:13 .
drwxr-xr-x 6 root root 4096 Jun 24 02:28 ..
-rw-r--r-- 1 root root 0 Jun 24 13:27 address-list.dump
address-list.get
Retrieves an address-list, returning details of the list.
Fields
name
Required
string

118 Chapter 13: Command reference
exclude-fields
Optional
string
Defines the fields to exclude from a response.
fields
Optional
string
Defines the fields to include in a response.
layer
Optional
string
Examples
cacheserve> address-list.get name=my-list
{
type => 'address-list.get'
name => 'my-list'
count => '0'
}
address-list.list
Lists address-lists, optionally sorted by various criteria.
Fields
descending
Optional
string
Sorts returned values in descending order.

end
Optional
{
address => string
list => string
}
Defines the last value to be returned.
key
Optional
string
Defines the key by which results will be ordered.
layer
Optional
string
max-results
Optional
integer
Defines the maximum number of returned results.
skip-first
If present, omits the field specified by start.
start
Optional
{
address => string
list => string
}
Defines the first value to be returned.
Examples
cacheserve> address-list.list
{

120 address-list.load
type => 'address-list.list'

name => 'my-list'
}
address-list.load
Loads a set of address-lists from a file designated by the file parameter, optionally replacing
existing entries.
Source file format
Each line of file must contain a single entry, consisting of a sequence of two whitespace-
delimited tokens:
1. An IP network (an address, with an optional netmask length).

2. An optional '-', which indicates that the IP network should be deleted.
For example:
192.168.1.2/24
192.168.1.1/24 -
If there are any errors in file, the entire operation is cancelled and an error is returned.
Merging or replacing entries
The contents of file may match existing database entries.
To have address-list.load add the contents of file to the existing entries, and silently ignore
existing entries, set replace to false (the default).
To have address-list.load replace all existing entries with the contents of file, set replace to true.
Fields
name
Required
string
file
Required
string

The full path to the file containing new entries.
replace
Optional
boolean
Indicates whether the contents of file should merge with or replace existing entries.
Examples
cacheserve> address-list.load name=loadlist file=/tmp/address-list-load-file
{
type => 'address-list.load'
}
address-list.mget
Retrieves multiple address-lists.
Fields
descending
Optional
string
end
Optional
{
name => string
}
exclude-fields
Optional
string

122 address-list.mget
fields
Optional
string
key
Optional
string
layer
Optional
string
max-results
Optional
integer
skip-first
start
Optional
{
name => string
}
name
Required
string

Examples
cacheserve> address-list.mget
{
type => 'address-list.mget'
name => 'loadlist'
count => '1'
}
{
name => 'my-list'
count => '0'
}
address-list.replace
Replaces all fields of an address-list.
Fields
name
Required
string
layer
Optional
string
post-edits
Optional
pre-edits
Optional

124 address-list.update
address-list.update
Updates one or more fields of an address-list.
Fields
name
Required
string
layer
Optional
string
post-edits
Optional
pre-edits
Optional
unset
Optional
string
A list of values to unset.
Note: When unset is invoked upon a field, the field is emptied, and CacheServe will treat the
field as required (for instance, populating the field with a default value if necessary).

address-node.add 125
Examples
cacheserve> address-list.update name=my-list layer=operator
{
type => 'address-list.update'
}
address-node.add
Creates a new address-node.
Fields
address
Required
addrpat
layer
Optional
string
list
Required
string
post-edits
Optional
pre-edits
Optional

126 address-node.delete
tag
Optional
string
address-node.delete
Deletes an address-node.
Fields
list
Required
string
The address-list to which this address-node belongs.
name
Required
string
layer
Optional
string
address-node.get
Retrieves an address-node.

address-node.list 127
Fields
address
Required
addrpat
list
Required
string
exclude-fields
Optional
string
fields
Optional
string
layer
Optional
string
address-node.list
Lists address-nodes, optionally sorted by various criteria.
Fields
list
Optional

128 address-node.list
string
descending
Optional
string
end
Optional
{
address => addrpat
list => string
}
key
Optional
string
layer
Optional
string
max-results
Optional
integer
skip-first
start
Optional

address-node.mget 129
{
address => addrpat
list => string
}
address-node.mget
Retrieves multiple address-nodes.
Fields
list
Optional
string
descending
Optional
string
end
Optional
{
address => addrpat
list => string
}
key
Optional
string
layer
Optional

130 address-node.replace
string
max-results
Optional
integer
skip-first
start
Optional
{
address => addrpat
list => string
}
address-node.replace
Replaces all fields of an address-node.
Fields
address
Required
addrpat
list
Required
string

address-node.update 131
layer
Optional
string
post-edits
Optional
pre-edits
Optional
tag
Optional
string
address-node.update
Updates one or more fields of an address-node.
Fields
address
Required
addrpat
list
Required

132 binding.add
string
layer
Optional
string
post-edits
Optional
pre-edits
Optional
tag
Optional
string
unset
Optional
string
binding.add
Creates a new binding.

binding.add 133
Fields
name
Required
string
priority
Required
integer
the same time.
40 or even 0, 100, 200, 300, 400.
layer
Optional
string
policy
Optional
string
post-edits
Optional

134 binding.add
pre-edits
Optional
server
Optional
boolean
view
Optional
string
when
Optional
prequery
postquery
presend

binding.delete 135
binding.delete
Deletes a binding.
Fields
policy
Optional
string
layer
Optional
string
server
Optional
boolean
view
Optional
string

136 binding.get
binding.get
Retrieves a policy binding.
Fields
policy
Optional
string
exclude-fields
Optional
string
fields
string
layer
Optional
string
server
Optional
boolean
view
Optional

binding.list 137
string
binding.list
Lists policy bindings, optionally sorted by various criteria.
Fields
policy
Optional
string
descending
Optional
string
end
Optional
{
policy => string
server => '1'
view => string
}
key
Optional
string
layer
Optional
string

138 binding.mget
max-results
Optional
integer
server
Optional
boolean
skip-first
start
Optional
{
policy => string
server => '1'
view => string
}
view
Optional
string
binding.mget
Retrieves multiple bindings.

binding.mget 139
Fields
policy
Optional
string
descending
Optional
string
end
Optional
{
policy => string
server => '1'
view => string
}
key
Optional
string
layer
Optional
string
max-results
Optional
integer

140 binding.replace
server
Optional
boolean
skip-first
start
Optional
{
policy => string
server => '1'
view => string
}
view
Optional
string
binding.replace
Replaces all fields of a policy binding.
Fields
name
Required
string

binding.replace 141
priority
Required
integer
the same time.
40 or even 0, 100, 200, 300, 400.
layer
Optional
string
policy
Optional
string
post-edits
Optional
pre-edits
Optional

142 binding.update
server
Optional
boolean
view
Optional
string
when
Optional
prequery
postquery
presend
binding.update
Updates the fields of a policy binding.

binding.update 143
Fields
name
Required
string
priority
Required
integer
the same time.
40 or even 0, 100, 200, 300, 400.
layer
Optional
string
post-edits
Optional
pre-edits
Optional

144 binding.update
policy
Optional
string
server
Optional
boolean
when
Optional
prequery
postquery
presend
view
Optional
string

connection.get 145
unset
Optional
string
connection.get
Retrieves a connection configuration.
Fields
exclude-fields
Optional
string
fields
Optional
string
connection.replace
Replaces field values for a Command Channel connection configuration.
Fields
events
Optional
event-name

146 connection.subscribe-all
idle-timeout
Optional
time-in-seconds
timeout.
connection.subscribe-all
A boolean that when specified, subscribes this connection to all events, overriding any previous
list of requested events.
connection.update
Updates the fields of a Command Channel connection.
Fields
events
Optional
event-name
idle-timeout
Optional
time-in-seconds
timeout.
unset
Optional
string

dns64.add 147
dns64.add
Creates a new dns64 layer.
Fields
name
Required
string
prefix
Required
addrpat6
l 32
l 40
l 48
l 56
l 64
l 96
exclude
Optional
(acl-element6 ...)
If present, removes any IPv6 addresses (in AAAA records) matching this acl from responses
that contain them.
If no AAAA records remain after exclusion, the response is processed as if the original AAAA
query returned a NOERROR or NODATA response.

148 dns64.delete
layer
Optional
string
mapped
Optional
(acl-element ...)
records.
post-edits
Optional
pre-edits
Optional
suffix
Optional
addr6
IPv4 address.
dns64.delete
Deletes a dns64 configuration.

dns64.get 149
Fields
name
Required
string
layer
Optional
string
dns64.get
Retrieves a dns64 configuration.
Fields
name
Required
string
exclude-fields
Optional
string
fields
Optional
string
layer
Optional

150 dns64.list
string
dns64.list
Lists dns64 configurations, optionally sorted by various criteria.
Fields
descending
Optional
string
end
Optional
{
name => string
}
key
Optional
string
layer
Optional
string
max-results
Optional
integer

dns64.mget 151
skip-first
start
Optional
{
name => string
}
dns64.mget
Retrieves multiple DNS64 configurations.
Fields
descending
Optional
string
end
Optional
{
name => string
}
exclude-fields
Optional
string
fields
Optional
string

152 dns64.replace
key
Optional
string
layer
Optional
string
max-results
Optional
integer
skip-first
start
Optional
{
name => string
}
dns64.replace
Replaces values for a dns64 layer.
Fields
name
Required
string

dns64.replace 153
prefix
Required
addrpat6
l 32
l 40
l 48
l 56
l 64
l 96
exclude
Optional
(acl-element6 ...)
that contain them.
layer
Optional
string
mapped
Optional
(acl-element ...)
records.

154 dns64.update
post-edits
Optional
pre-edits
Optional
suffix
Optional
addr6
IPv4 address.
dns64.update
Updates fields for a dns64 layer.
Fields
name
Required
string
exclude
Optional
(acl-element6 ...)
that contain them.

dns64.update 155
layer
Optional
string
mapped
Optional
(acl-element ...)
records.
post-edits
Optional
pre-edits
Optional
prefix
Required
addrpat6
l 32
l 40
l 48
l 56

156 instance-information
l 64
l 96
suffix
Optional
addr6
IPv4 address.
unset
Optional
string
instance-information
Retrieves the server's instance ID and information about all instances of the server's partners.
A partner is typically a separate process such as statmon or dnsauth_helper.
Returns
instance-id
uuid
The instance identifier of the server process.
partners
integer
Returns instance information about the server's partners as a combination of (uuid, string,
string), where:
l The uuid is the instance-id of the partner process.

l The first string is the name of the partner process.

layer.add 157
l The second string is the role of the partner process.
layer.add
Creates a new layer.
Fields
name
Required
string
priority
Required
integer
channel
string
/etc/channel.conf).
hidden
Optional
boolean

158 layer.clear-fault
is unhidden.
server
Optional

Examples
cacheserve> layer.add name=second-layer priority=10
{
type => 'layer.add'
}
layer.clear-fault
If the layer's provisioning session has entered the faulted state, layer.clear-fault forces the
server to clear the fault and make an attempt to reestablish communications with the
provisioning server.
If there is no fault, this has no effect.
Fields
name
Required
string
layer.delete
Deletes a layer.

layer.get 159
Fields
name
Required
string
layer.get
Retrieves a layer.
Fields
name
Required
string
exclude-fields
Optional
string
fields
Optional
string
layer.list
Lists layers, optionally sorted by various criteria.

160 layer.list
Fields
descending
Optional
string
end
Optional
{
name => string
}
key
Optional
string
max-results
Optional
integer
skip-first
start
Optional
{
name => string
}

layer.mget 161
layer.mget
Retrieves multiple layers.
Fields
descending
Optional
string
end
Optional
{
name => string
}
exclude-fields
Optional
string
fields
Optional
string
key
Optional
string
layer
Optional

162 layer.reimage
string
max-results
Optional
integer
skip-first
start
Optional
{
name => string
}
layer.reimage
Reimages a layer, erasing all configuration data from the layer and then reloading the layer's
configuration from the provisioning server.
CacheServe will automatically restart after this operation.
Fields
name
Required
string
layer.replace
Replaces values for a layer.

layer.replace 163
Fields
name
Required
string
priority
Required
integer
channel
string
/etc/channel.conf).
hidden
Optional
boolean
is unhidden.
server
Optional

164 layer.update

layer.update
Updates values for a layer.
Fields
name
Required
string
priority
Required
integer
channel
string
/etc/channel.conf).
hidden
Optional
boolean

name-list.add 165
is unhidden.
server
Optional

unset
Optional
string
name-list.add
Creates a new name-list.
Fields
name
Required
string

166 name-list.delete
layer
Optional
string
post-edits
Optional
pre-edits
Optional
name-list.delete
Deletes a name-list.
Fields
name
Required
string
layer
Optional
string

name-list.dump 167
name-list.dump
Dumps the content of a list to the file name-list.dump in the server's current working directory.
Fields
name
Required
string
name-list.get
Retrieves a name-list.
Fields
name
Required
string
exclude-fields
Optional
string
fields
Optional
string
layer
Optional

168 name-list.list
string
name-list.list
Lists name-list configurations, optionally sorted by various criteria.
Fields
descending
Optional
string
end
Optional
{
name => string
}
key
Optional
string
layer
Optional
string
max-results
Optional
integer

name-list.load 169
skip-first
start
Optional
{
name => string
}
name-list.load
Loads a set of names to a name-list from a file designated by the file parameter, optionally
replacing existing entries.
Source file format
Each line of file must contain a single entry, consisting of a sequence of two whitespace-
delimited tokens:
1. A DNS name (names containing whitespace must be quoted or have their whitespace
escaped).
2. One or two optional parameters:
1. A '-', which indicates that the IP network should be deleted, or
2. X:t if the name has been encrypted.
For example:
example.net
example.org -
If there are any errors in file, the entire operation is cancelled and an error is returned.
Merging or replacing entries
The contents of file may match existing database entries.
To have name-list.load add the contents of file to the existing entries, and silently ignore existing
entries, set replace to false (the default).
To have name-list.load replace all existing entries with the contents of file, set replace to true.

170 name-list.mget
Fields
name
Required
string
file
Required
string
The full path to the file containing new entries.
replace
Optional
boolean
Indicates whether the contents of file should merge with or replace existing entries.
Examples
cacheserve> name-list.load name=loadlist file=/tmp/name-list-load-file
{
type => 'name-list.load'
}
name-list.mget
Retrieves multiple name-lists.
Fields
descending
Optional
string
end
Optional

name-list.mget 171
{
name => string
}
exclude-fields
Optional
string
fields
Optional
string
key
Optional
string
layer
Optional
string
max-results
Optional
integer
skip-first
start
Optional

172 name-list.replace
{
name => string
}
name
Required
string
name-list.replace
Replaces all fields of an name-list.
Fields
name
Required
string
layer
Optional
string
post-edits
Optional
pre-edits
Optional

name-list.update 173
name-list.update
Updates one or more fields of a name-list.
Fields
name
Required
string
layer
Optional
string
post-edits
Optional
pre-edits
Optional
unset
Optional
string

174 name-node.add
name-node.add
Creates a new name-node.
Fields
list
Required
string
name
Required
string
encrypt
Optional
boolean
If true, instructs CacheServe to encrypt the node's name before trying to find or define it.
encrypted
Optional
boolean
layer
Optional
string
post-edits
Optional

name-node.delete 175
pre-edits
Optional
tag
Optional
string
name-node.delete
Deletes a name-node.
Fields
encrypt
Optional
boolean
layer
Optional
string
name
Required
string

176 name-node.get
name-node.get
Retrieves a name-node.
Fields
list
Required
string
name
Required
string
encrypt
Optional
boolean
exclude-fields
Optional
string
fields
Optional
string
layer
Optional
string

name-node.list 177
name-node.list
Lists name-nodes, optionally sorted by various criteria.
Fields
descending
Optional
string
end
Optional
{
list => string
name => name
}
key
Optional
string
layer
Optional
string
list
Optional
string

178 name-node.mget
max-results
Optional
integer
skip-first
start
Optional
{
list => string
name => name
}
name-node.mget
Retrieves multiple name-nodes.
Fields
descending
Optional
string
end
Optional
{
list => string
name => name
}

name-node.replace 179
key
Optional
string
layer
Optional
string
list
Optional
string
max-results
Optional
integer
skip-first
start
Optional
{
list => string
name => name
}
name-node.replace
Replaces all fields of a name-node.

180 name-node.replace
Fields
list
Required
string
name
Required
string
encrypt
Optional
boolean
encrypted
Optional
boolean
layer
Optional
string
post-edits
Optional
pre-edits
Optional

name-node.update 181
tag
Optional
string
name-node.update
Updates one or more fields of a name-node.
Fields
list
Required
string
name
Required
string
encrypt
Optional
boolean
encrypted
Optional
boolean

182 policy.add
layer
Optional
string
post-edits
Optional
pre-edits
Optional
tag
Optional
string
unset
Optional
string
policy.add
Creates a new policy.

policy.add 183
Fields
action
Optional
policy-action
is taken.
layer
Optional
string
children
Optional
string
post-edits
Optional
pre-edits
Optional
selector
Required
policy-selector

184 policy.delete
A policy-selector that identifies selection criteria. The associated policy is applied to a query if
the selector criteria match, and the policy is bound to either the server object or the view
matching the query.
Selectors DO NOT affect child policies.
The boolean AND and OR selectors support lists of selectors, and the NOT selector inverts the
result of another selector.
The default is (qtype (A AAAA)), which matches all A and AAAA queries.
policy.delete
Deletes a policy.
Fields
name
Required
string
layer
Optional
string
policy.get
Retrieves a policy.
Fields
name
Required
string

policy.list 185
exclude-fields
Optional
string
fields
Optional
string
layer
Optional
string
policy.list
Lists policy configurations, optionally sorted by various criteria.
Fields
descending
Optional
string
end
Optional
{
name => string
}
key
Optional

186 policy.mget
string
layer
Optional
string
max-results
Optional
integer
skip-first
start
Optional
{
name => string
}
policy.mget
Retrieves multiple policies.
Fields
descending
Optional
string
end
Optional

policy.mget 187
{
name => string
}
key
Optional
string
layer
Optional
string
list
Optional
string
max-results
Optional
integer
skip-first
start
Optional
{
name => string
}

188 policy.replace
policy.replace
Replaces all fields of a policy.
Field
action
Optional
policy-action
is taken.
layer
Optional
string
children
Optional
string
post-edits
Optional
pre-edits
Optional

policy.simulate 189
selector
Required
policy-selector
matching the query.
policy.simulate
Simulates the execution of a policy, reporting on the result of each policy.
Note: Policy simulation isn't quite the same thing as policy execution. The key differences:
simulation only performs a single lookup (it doesn't follow CNAMEs), and simulation doesn't
actually construct the DNS response, which means the response-size policy-selector won't
work.
Fields
client
Optional
addr
The client address of the simulated query. If no client is specified, the client-address policy-
selector will never match.
initial-qname
Optional
name
The initial query name of the simulated query. You only need this if you're attempting to
simulate the subsequent part of a query that has followed a CNAME.

190 policy.simulate
qname
Optional
name
The query name of the simulated query.
qtype
Required
rdatatype
The query type of the simulated query.
start-time
Optional
seconds-since-epoch
The time at which the simulated query was received.
tcp
Optional
boolean
Indicates whether or not the simulated query should be processed as if it were received via
TCP.
view
Optional
string
The view within which the simulated query should be processed.
Returns
policy.simulate returns, in order, a list of evaluated policies, identifying the policy name and
whether it matched or not.
Policies directly associated with bindings return the object to which it's bound (view or server),
as well as the time at which it executes (prequery, postquery, or presend) and the priority.
Child policies also include the name of the parent policy.
Format:

policy.update 191
({
match => boolean
parent => string
policy => string
priority => integer
server => string
view => string
when => 'postquery' | 'prequery' | 'presend'
} ...)
policy.update
Updates all fields of a policy.
Field
action
Optional
policy-action
is taken.
children
Optional
string
layer
Optional
string
post-edits
Optional

192 process-information
pre-edits
Optional
selector
Required
policy-selector
matching the query.
unset
Optional
string
process-information
Retrieves process information for the server.
Returns
arguments
string
The arguments with which the server was started.

ratelimiter.add 193
current-time
float-seconds-since-epoch
The server's current time, in seconds and microseconds since the UNIX epoch (January 1, 1970,
0:00:00 UTC).
instance
integer
The instance identifier of this process, if any. The instance identifier can be set by passing the --
instance option to the server, if the server supports it.
license
unparsed
The contents of the license file in use by the server.
node-id
uuid
The node identifier of the system on which the server process is running.
pid
integer
The process identifier of the server process.
start-time
The time the server was started, in seconds and microseconds since the UNIX epoch (January
1, 1970, 0:00:00 UTC).
working-directory
string
The server's current working directory.
ratelimiter.add
Adds a ratelimiter.

194 ratelimiter.add
Fields
name
Required
string
fields
Required
string
bps
Optional
integer
layer
Optional
string
maximum-entries
Optional
positive-integer
post-edits
Optional

ratelimiter.delete 195
pre-edits
Optional
qps
Optional
integer
unenforced
Optional
boolean
ratelimiter.delete
Deletes a rate limiter.
Fields
name
Required
string
layer
Optional
string

196 ratelimiter.get
ratelimiter.get
Retrieves a ratelimiter.
Fields
exclude-fields
Optional
string
fields
Optional
string
layer
Optional
string
ratelimiter.list
Lists ratelimiters, optionally sorted by various criteria.
Fields
descending
Optional
string
end
Optional

ratelimiter.list 197
{
name => string
}
exclude-fields
Optional
string
fields
Optional
string
key
Optional
string
layer
Optional
string
max-results
Optional
integer
skip-first
start
Optional

198 ratelimiter.mget
{
name => string
}
ratelimiter.mget
Retrieves multiple rate limiters.
Fields
descending
Optional
string
end
Optional
{
name => string
}
exclude-fields
Optional
string
fields
Optional
string
key
Optional
string

ratelimiter.replace 199
layer
Optional
string
max-results
Optional
integer
skip-first
start
Optional
{
name => string
}
ratelimiter.replace
Replaces all values for a ratelimiter.
Fields
name
Required
string
fields
Required
string

200 ratelimiter.replace
bps
Optional
integer
layer
Optional
string
maximum-entries
Optional
positive-integer
post-edits
Optional
pre-edits
Optional
qps
Optional
integer

ratelimiter.statistics 201
unenforced
Optional
boolean
ratelimiter.statistics
Returns the current values for ratelimiter statistics along with general process statistics.
Fields
all
Optional
boolean
If set to true, instructs CacheServe to return the values of all tracked statistics, even those with a
value of 0.
reset
Optional
boolean
If set to true, instructs CacheServe to reset all counters to 0 after returning them.
Returns
current-time
The current time.
memory-in-use
uint64
The current amount of memory in use.
This value represents the amount of memory requested from the memory allocator and
memory used by the cache; it does not include overhead for allocator bookkeeping, rounding,
fragmentation or free lists.

202 ratelimiter.update
name
string
The ratelimiter's name.
reset-time
The last time statistics were reset.
server-start-time
The time when CacheServe was started.
statistics
{
all-indications => uint64
current-entry-count => uint64
current-limited-count => uint64
expiring-entry-age => uint64
indications-by-bps => uint64
indications-by-qps => uint64
uses => uint64
}
A set of counters. For a detailed explanation of each statistic, see ratelimiter-statistics.
system-time
time-in-microseconds
The amount of system CPU time used since the server started.
user-time
The amount of user CPU time used since the server started.
ratelimiter.update
Updates or resets values for a ratelimiter.

ratelimiter.update 203
Fields
name
Required
string
fields
Optional
string
bps
Optional
integer
layer
Optional
string
maximum-entries
Optional
positive-integer
post-edits
Optional

204 resolver.add
pre-edits
Optional
qps
Optional
integer
unenforced
Optional
boolean
unset
Optional
string
resolver.add
Creates a new resolver.
Fields
dnssec-aware
Optional
boolean

resolver.add 205
false.

managed-keys.
traffic.
errors
Optional
string

forward
Optional
name servers.
query.
l off: Disable forwarding for a subdomain. If you specify off, you must leave the server addr-
port empty.

206 resolver.add
hints
Optional
(name, ((name, (addr ...)) ...))
Optional
boolean

layer
Optional
string
log-dnssec
Optional
boolean
log-id-spoofing
Optional

About lame delegations 207
boolean
place.
has been triggered.
See ID spoofing attacks for more detail.
log-lame
Optional
(name ...)
own organization.
About lame delegations
The most common type of authoritative server configuration error is a lame delegation. Lame
delegations occur when a server's had authority over a zone delegated to it, but doesn't
actually have authoritative data for the zone.
Be careful what you wish for
It's technically possible to log errors occurring in any domain by specifying the root domain, but
this is a really bad idea.
First, you're going to get hammered with a huge volume of log message, and second, lame
servers are unfortunately very common, and a busy caching server will easily detect and log
lots of lame servers per second.
Logging these free-range lame servers generally doesn't serve any purpose, because it's not
practical to contact the administrators of all those domains and ask them to correct the error.
managed-keys
Optional
(( name , (rdata...)) ...)

208 Be careful what you wish for

1ihz0=")))
managed-keys-state
Optional, read-only
keys => ({
key => string
keyid => integer
} ...)
}) ...)

max-cache-size
Optional
sizeval
default is 200M.
max-cache-ttl
Optional
time-in-seconds
max-client-ttl
Optional
time-in-seconds
max-edns-udp-size
Optional
integer
max-ncache-ttl
Optional

time-in-seconds
to 10800 (3 hours).
max-tcp-recursions
Optional
integer
Optional
(name ...)
post-edits
Optional
pre-edits
Optional
prefetch-ratio
Optional
integer

How we determined the default value

prefetch-ratio defines the relationship between the time at which data expires and that data's
initial TTL. Given a prefetch-ratio value of n, CacheServe issues a prefetch query if the cached
data expires in less than 1/nof its initial TTL.
The default value of 16 is the thoroughly tested balance point betweeen improved
performance and the impact of additional queries; it results in a higher cache rate and better
average latency.
preload
Optional
and rdata.


preload-nxdomain
Optional
(name ...)

preload-nxrrset
Optional
exists.
Optional

query's case.
Optional
(name ...)
query-source-pool
Optional
(uint16, addrport4)


Optional
(uint16, addrport6)

Format:
rrset-order
Optional

Optional
('A' | 'AAAA' ...)
stub
Optional
for that domain.

resolver.delete 215
synthesize-nxdomain
Optional
(name ...)
specified domains.


domain.

trusted-keys
Optional
((name, (rdata ...)) ...)
security root.
resolver.delete
Deletes a resolver.

216 resolver.flush
Fields
name
Required
string
layer
Optional
string
resolver.flush
Flushes entries from the resolver's cache.
Fields
dnssec-aware
Optional
boolean
false.

managed-keys.
traffic.
target
Optional
('domain' name | 'name' name )
If present, and set to name, removes only that name.

resolver.get 217
If present, and set to domain, removes all names in that domain.
resolver.get
Retrieves a resolver.
Fields
name
Required
string
exclude-fields
Optional
string
fields
Optional
string
resolver.inspect
Retrieves information about a name in the resolver’s cache, returning the information in
various forms.
Fields
name
Required
string

218 resolver.inspect
domain
Required
name
The domain name you're inspecting.
Returns
domain
Required
name
The domain name you're inspecting.
exists
Optional
boolean
Indicates whether the entry is positive or negative.
immortal
Optional
boolean
Indicates whether or not an entry is persistent.
name
Optional
name
The name of the resolver.
nonexistence-proof
Optional
((name, {
<type> => {
data => (string ...)
sigs => (string ...)
ttl => integer
validated => boolean
}

...
}) ...)
For negative entries, nonexistence-proof displays the information that the server uses to prove
that the entry doesn't exist.
ttl
Optional
integer
An integer representing the number of seconds until the data expires. If there's no ttl, the data
never expires.
types
Optional
{ <type> => {
exists => boolean
immortal => boolean
nonexistence-proof => ((name, {
<type> => {
sigs => (string...)
ttl => integer
}
...
}) ...)
origin => addr
prefetches => integer
ttl => integer
wildcard-proof => ((name, {
<type> => {
ttl => integer
}
...
}) ...)
}
...
}
A table mapping DNS record types to subtables which contain information about those types.

220 resolver.inspect-delegation
validated
Optional
boolean
If the data has been DNSSEC validated, this field will be present and true.
resolver.inspect-delegation
Retrieves information about a delegation point in the resolver’s cache, returning the
information in various forms.
Fields
name
Required
string
domain
Required
name
The domain name of the delegation point you're inspecting.
Returns
domain
Required
name
The domain name of the delegation point you're inspecting.
immortal
Optional
boolean
If present, indicates whether or not an entry is persistent.

resolver.list 221
name
string
servers
Optional
inspect-delegation-servers
Contains information about the delegation point in the server's cache.
stub
Optional
boolean
If present, this entry corresponds to a stub.
synthetic
Optional
boolean
If present, this entry has been synthesized.
ttl
Optional
integer
Represents the number of seconds until the NS set data expires. If there's no ttl, the data never
expires.
resolver.list
Lists resolvers, optionally sorted by various criteria.
Fields
descending
Optional

222 resolver.list
string
end
Optional
{
name => string
}
key
Optional
string
layer
Optional
string
max-results
Optional
integer
skip-first
start
Optional
{
name => string
}

resolver.mget 223
resolver.mget
Retrieves multiple resolvers.
Fields
descending
Optional
string
end
Optional
{
name => string
}
exclude-fields
Optional
string
fields
Optional
string
key
Optional
string
layer
Optional

224 resolver.recursing
string
max-results
Optional
integer
skip-first
start
Optional
{
name => string
}
resolver.recursing
List the resolutions currently in progress.
Fields
name
Required
string
Returns
resolutions
Required
({
name => name
type => rdatatype
} ...)
Lists resolutions in progress.

resolver.replace
Replaces all values on a resolver with new values.
Fields
dnssec-aware
Optional
boolean
false.

managed-keys.
traffic.
errors
Optional
string

forward
Optional
name servers.

226 resolver.replace
query.
port empty.
hints
Optional
(name, ((name, (addr ...)) ...))
Optional
boolean

layer
Optional
string
log-dnssec
Optional

boolean
log-id-spoofing
Optional
boolean
place.
has been triggered.
log-lame
Optional
(name ...)
own organization.
managed-keys
Optional
(( name , (rdata...)) ...)


1ihz0=")))
managed-keys-state
Optional, read-only
keys => ({
key => string
keyid => integer
} ...)
}) ...)
max-cache-size
Optional
sizeval

default is 200M.
max-cache-ttl
Optional
time-in-seconds
max-client-ttl
Optional
time-in-seconds
max-edns-udp-size
Optional
integer
max-ncache-ttl
Optional
time-in-seconds
to 10800 (3 hours).

max-tcp-recursions
Optional
integer
Optional
(name ...)
post-edits
Optional
pre-edits
Optional
prefetch-ratio
Optional
integer


average latency.
preload
Optional
and rdata.


preload-nxdomain
Optional
(name ...)
preload-nxrrset
Optional

exists.
Optional

query's case.
Optional
(name ...)
query-source-pool
Optional
(uint16, addrport4)


Optional
(uint16, addrport6)

Format:
rrset-order
Optional

Optional
('A' | 'AAAA' ...)
stub
Optional
for that domain.
synthesize-nxdomain
Optional
(name ...)

resolver.statistics 235
specified domains.


domain.

trusted-keys
Optional
((name, (rdata ...)) ...)
security root.
resolver.statistics
Returns the current values for resolver statistics along with general process statistics.
Fields
all
Optional
boolean
value of 0.

236 resolver.statistics
reset
Optional
boolean
Returns
current-time
The current time.
memory-in-use
uint64
name
string
The resolver's name.
reset-time
server-start-time
statistics
{
cache-misses => uint64
dnssec-validations-failure => uint64
dnssec-validations-insecure => uint64
dnssec-validations-success => uint64
id-spoofing-defense-queries => uint64
ignored-referral-lookups => uint64

resolver.update 237
lookups => uint64

proactive-lookups => uint64
queries => uint64
rate-limited-requests => uint64
recursive-lookups => uint64
requests-sent => uint64
responses-by-rcode =>
{
<rcode> => uint64
...
}
tcp-requests-sent => uint64
}
A set of counters. For a detailed explanation of each statistic, see resolver-statistics.
system-time
user-time
resolver.update
Updates all values on a resolver with new values.
Fields
dnssec-aware
Optional
boolean
false.

managed-keys.
traffic.

238 resolver.update
errors
Optional
string

forward
Optional
name servers.
query.
port empty.
hints
Optional
(name, ((name, (addr ...)) ...))

resolver.update 239
Optional
boolean

layer
Optional
string
log-dnssec
Optional
boolean
log-id-spoofing
Optional
boolean
place.
has been triggered.

240 resolver.update
log-lame
Optional
(name ...)
own organization.
managed-keys
Optional
(( name , (rdata...)) ...)

1ihz0=")))

resolver.update 241
managed-keys-state
Optional, read-only
keys => ({
key => string
keyid => integer
} ...)
}) ...)
max-cache-size
Optional
sizeval
default is 200M.
max-cache-ttl
Optional
time-in-seconds
max-client-ttl
Optional
time-in-seconds

242 resolver.update
max-edns-udp-size
Optional
integer
max-ncache-ttl
Optional
time-in-seconds
to 10800 (3 hours).
max-tcp-recursions
Optional
integer
Optional
(name ...)
post-edits
Optional

resolver.update 243
pre-edits
Optional
prefetch-ratio
Optional
integer

average latency.
preload
Optional
and rdata.


244 resolver.update

preload-nxdomain
Optional
(name ...)
preload-nxrrset
Optional
exists.
Optional

query's case.
Optional

resolver.update 245
(name ...)
query-source-pool
Optional
(uint16, addrport4)

Optional
(uint16, addrport6)


246 resolver.update
Format:
rrset-order
Optional
Optional
('A' | 'AAAA' ...)
stub
Optional

resolver.update 247
for that domain.
synthesize-nxdomain
Optional
(name ...)
specified domains.


domain.

trusted-keys
Optional
((name, (rdata ...)) ...)

248 restart
security root.
unset
Optional
string
restart
Restarts CacheServe.
server.add
Creates a new server.
Fields
layer
Optional
string
commands-not-logged
Optional
boolean

server.add 249
errors
Optional
string

listen-on-matching
Optional
({
port => uint16
} ...)
{
}

250 server.add
{
{
patterns => ('192.168.1.1/32')
instances => '16'
}
{
patterns => ('127.0.0.1/32')
port => '5354'
}
)
}
log-command-channel
Optional
boolean
Optional
integer

max-tcp-clients
Optional
integer

server.add 251
post-edits
Optional
pre-edits
Optional
server-id
Optional
string-empty-ok
server-version
Optional
string-empty-ok
version.
time-zone
Optional
string
the IANA tzdb.

252 server.all-errors
Optional
versioncheck-days
server.all-errors
Displays all misconfigured CacheServe elements. Individual elements also return
troubleshooting information in the errors field.
Fields
max-results
Optional
integer
server.block-checkpoints
Prevents database checkpoints for a specified amount of time, which permits the database to
be backed up.
Fields
timeout
Optional
time-in-seconds
The duration in seconds for which checkpoints should be suspended. The default is 3600 (1
hour).
server.checkpoint
Forces CacheServe to immediately perform a database checkpoint operation.

server.get 253
server.get
Retrieves the server object's configuration.
Fields
exclude-fields
Optional
string
fields
Optional
string
layer
Optional
string
server.query
Processes a DNS query as if the server had received it.
All of the query attributes can be configured, along with additional configuration beyond the
normal parameters of a DNS query. For example, you can specify a view or resolver.
The response contains all of the normal DNS query response data along with:
l An indication of which view and resolver were used.

l An expanded description of how the server would respond to the query.
l A record of all policies encountered.
l (Optional) Trace data.

254 server.get
Warning! Do not use "live" customer IPs for test queries against a sensitive domain, as this will
be logged. Use a test IP address instead (such as a 192.168.* or 10.* address).
Fields
client-address
Optional
addrport
The client address from which the query originated.
edns-buffer-size
Optional
uint16
Indicates the advertised EDNS buffer size, limiting the size of the response.
If this field is present, it enables EDNS in the request as needed; if some other field enables
EDNS and edns-buffer-size is not present, CacheServe uses a buffer size of 4096.
edns-flags
Optional
edns-flag
Extended query flags.
flags
Optional
dns-flag
The DNS header flags. Defaults to (rd).
force-resolution
Optional
boolean
Indicates whether or not CacheServe should force resolution to occur. The default is false.
If force-resolution is true, CacheServe does not perform the initial cache lookup, and existing
resolutions are not joined.

server.get 255
Note: This does not exclude policy effects: if a terminal policy executes prior to the point at
which resolution would normally occur, it will prevent resolution.
qclass
Optional
rdataclass
The query class. Defaults to IN.
qname
Optional
name
The query name.
qtype
Optional
rdatatype
The query type. Defaults to A.
resolver
Optional
string
Instructs CacheServe to process a query in the context of the named resolver, versus a context
defined by a view-selector.
server-address
Optional
addrport
Specifies the server address to match against view-selectors or policies. Defaults to the target
address of the command.
start-time
Optional
seconds-since-epoch
The time at which the simulated query was received.

256 server.get
tcp
Optional
boolean
Indicates whether or not the simulated query should be processed as if it were received via
TCP.
tracing
Optional
boolean
Indicates whether or not tracing should be performed on this simulated query. Defaults to
false.
view
Optional
string
Instructs CacheServe to process a query in the context of the named view, versus a context
defined by a view-selector.
Returns
additional
((name, rdatatype, ttl, rdata) ...)
The records in the additional section of the response.
aliases
(name...)
Aliases for the query name encountered during query processing.
answer
The records in the answer section of the response.
authority
The records in the authority section of the response.

server.get 257
dropped
boolean
If true, no response is sent to this query.
flags
(dns-flag ...)
The flags set in the response.
policies
({
match => boolean
parent => string
policy => string
priority => integer
server => string
view => string
when => ’postquery’ | ’prequery’ | ’presend’
} ...)
The list of policies, in order, that were evaluated when processing this query. For each policy,
the policy name and whether or not it matched is included.
If a policy directly associated with a binding, the object it’s bound to (view or server) is included,
as well as the time at which it executes (prequery, postquery, or presend) and the priority. If the
policy is the child of another policy, the parent policy name is included.
Unlike with policy.simulate, this can include the results of multiple passes through the policy
engine, if a query is restarted (such as when following a CNAME).
qclass
rdataclass
The query class.
qname
name
The query name.
qtype
rdatatype
The query type.

258 server.get
rcode
dns-rcode
The DNS result code.
resolver
string
The resolver which processed this query.
response-size
integer
The size of the response packet that would have been sent to the client, in bytes.
response-time
The amount of time spent processing this query.
result
string
A more informative description of the response than the DNS rcode.
trace-messages
(string...)
If tracing is enabled, this field contains tracing messages related to processing this query. These
messages contain varying levels of detail, and may or may not be useful or understandable.
The specific messages are not guaranteed to be consistent between releases; this output is
purely designed for manual inspection.
view
string
The view which processed this query.
Example
cacheserve> server.query qname=www.nominum.com
{
type => 'server.query'
qname => 'www.nominum.com'
qtype => 'A'
rcode => 'NOERROR'

server.get 259
result => 'success'

flags => ('qr' 'rd' 'ra')
answer => (('www.nominum.com' 'A' '3600' '96.126.124.232'))
response-size => '49'
response-time => '0.316730'
resolver => 'world'
view => 'world'
}
Example (N2 environment)
# An example of server.query in a strict Engage
# Personal Internet environment where social
# media queries get redirected to Nom Proxy.
cacheserve> server.query client-address=10.0.0.1 qname=www.facebook.com

{
type => 'server.query'
qname => 'www.facebook.com'
qtype => 'A'
rcode => 'NOERROR'
result => 'success'
flags => ('qr' 'rd' 'ra')
answer => (('www.facebook.com' 'A' '0' '64.89.238.108'))
response-size => '50'
response-time => '0.000074'
resolver => 'pm-resolver'
view => '067e90f9-6c93-37ef-8859-e8cbba15b799'
policies => (
{
policy => 'global-whitelist'
when => 'prequery'
priority => '1000'
match => 'true'
}
{
policy => 'global-whitelist-1'
parent => 'global-whitelist'
match => 'false'
}
{
policy => 'global-blacklist'
when => 'prequery'
priority => '2000'
match => 'true'
}
{
policy => 'global-blacklist-1'
parent => 'global-blacklist'
match => 'false'
}
{

260 server.replace
policy => 'strict-067e90f9-6c93-37ef-8859-e8cbba15b799'

when => 'prequery'
priority => '10000'
match => 'true'
}
{
policy => 'strict-067e90f9-6c93-37ef-8859-e8cbba15b799-1'
parent => 'strict-067e90f9-6c93-37ef-8859-e8cbba15b799'
match => 'false'
}
{
match => 'false'
}
{
match => 'true'
}
)
}
cacheserve>
server.replace
Replaces values on a server.
Fields
layer
Optional
string
commands-not-logged
Optional
boolean

server.replace 261
listen-on-matching
Optional
({
port => uint16
} ...)
{
}
{
{
patterns => ('192.168.1.1/32')
instances => '16'
}
{
patterns => ('127.0.0.1/32')
port => '5354'
}
)
}
log-command-channel
Optional

262 server.replace
boolean
Optional
integer

max-tcp-clients
Optional
integer
post-edits
Optional
pre-edits
Optional

server-id
Optional
string-empty-ok
server-version
Optional
string-empty-ok
version.
time-zone
Optional
string
the IANA tzdb.
Optional
versioncheck-days
server.statistics
Returns the current values for server statistics along with general process statistics.

264 server.statistics
Fields
all
Optional
boolean
value of 0.
reset
Optional
boolean
Returns
current-time
The current time.
memory-in-use
uint64
name
string
The resolver's name.
reset-time
server-start-time

statistics
{
recursion-contexts-in-use => uint64
requests-no-view => uint64
requests-received => uint64
responses-received => uint64
responses-sent => uint64
tcp-clients => uint64
}
A set of counters. For a detailed explanation of each statistic, see server-statistics.
system-time
user-time
Example
cacheserve> server.statistics
{
type => 'server.statistics'
reset-time => '1404287789.143226'
current-time => '1404288409.721157'
server-start-time => '1404287788.816544'
user-time => '1.239811'
system-time => '0.341948'
memory-in-use => '63772684'
statistics => {
}
}
server.unblock-checkpoints
Unblocks any blocked database checkpoints.

266 server.update
server.update
Updates server fields.
Fields
layer
Optional
string
commands-not-logged
Optional
boolean
errors
Optional
string

listen-on-matching
Optional
({
port => uint16
} ...)

server.update 267
{
}
{
{
patterns => ('192.168.1.1/32')
instances => '16'
}
{
patterns => ('127.0.0.1/32')
port => '5354'
}
)
}
log-command-channel
Optional
boolean
Optional

268 server.update
integer

max-tcp-clients
Optional
integer
post-edits
Optional
pre-edits
Optional
server-id
Optional
string-empty-ok

stop 269
server-version
Optional
string-empty-ok
version.
time-zone
Optional
string
the IANA tzdb.
Optional
versioncheck-days
unset
Optional
string
stop
Stops CacheServe.

270 uuid
uuid
Retrieves CacheServe's uuid.
version
Retrieves information about CacheServe, including the vendor, product, platform and version
of the running server, as well as a list of currently loaded plugins and their expiration date, if
any.
Returns
product
Required
string
The name of the product: in this case, CacheServe.
expiration
Optional
string
The time at which CacheServe's license expires.
platform
Optional
string
The platform for which CacheServe was built. This will, with rare exceptions, be the same as the
platform CacheServe is running on, and takes the form OS name-OS version-CPU class
plugins
Optional
string
The list of loaded plugins.
vendor
Optional
string

The CacheServe vendor. Almost always Nominum.
view-selector.add
Creates a new view-selector.
Fields
name
Required
string
view
Required
string
destination-address
Optional
addrport

layer
Optional
string
source-address
Optional
addrpat

272 view-selector.delete
post-edits
Optional
pre-edits
Optional
view-selector.delete
Deletes a view-selector.
Fields
destination-address
Optional
addrport

layer
Optional
string
source-address
Optional
addrpat

view-selector.get 273
view-selector.get
Retrieves a view-selector.
Fields
destination-address
Optional
addrport

exclude-fields
Optional
string
fields
Optional
string
layer
Optional
string
source-address
Optional
addrpat

274 view-selector.list
view-selector.list
Lists view-selectors, optionally sorted by various criteria.
Fields
descending
Optional
string
end
Optional
{
destination-address => addrport
source-address => addrpat
}
key
Optional
string
layer
Optional
string
max-results
Optional
integer

view-selector.mget 275
skip-first
start
Optional
{
}
view-selector.mget
Retrieves multiple view-selectors.
Fields
descending
Optional
string
end
Optional
{
}
key
Optional
string

276 view-selector.query
layer
Optional
string
max-results
Optional
integer
skip-first
start
Optional
{
}
view-selector.query
Simulates the execution of a query, and returns the view-selector that would match.
Fields
destination-address
Optional
addrport


source-address
Optional
addrpat
Returns
resolver
string
The resolver that would be selected to answer the query.
view
string
The view that would be selected to answer the query.
view-selector
string
The view-selector that would be selected to answer the query.
view-selector.replace
Replaces values on a view-selector.
Fields
name
Required
string
view
Required
string

278 view-selector.update
destination-address
Optional
addrport

layer
Optional
string
source-address
Optional
addrpat
post-edits
Optional
pre-edits
Optional
view-selector.update
Updates values for a view-selector.

Fields
name
Required
string
destination-address
Optional
addrport

layer
Optional
string
source-address
Optional
addrpat
post-edits
Optional
pre-edits
Optional

280 view.add
view
Optional
string
unset
Optional
string
view.add
Creates a new view.
Fields
name
Required
string
resolver
Required
string
The name of the resolver associated with this view. All DNS operations are performed in the
context of the resolver.
layer
Optional
string

view.delete 281
post-edits
Optional
pre-edits
Optional
time-zone
Optional
string
the IANA tzdb.
view.delete
Deletes a view.
Fields
name
Required
string
layer
Optional
string

282 view.get
view.get
Retrieves a view.
Fields
name
Required
string
exclude-fields
Optional
string
fields
Optional
string
layer
Optional
string
view.list
Lists views, optionally sorted by various criteria.
Fields
descending
Optional

view.list 283
string
end
Optional
{
name => string
}
key
Optional
string
layer
Optional
string
max-results
Optional
integer
skip-first
start
Optional
{
name => string
}

284 view.mget
view.mget
Retrieves multiple views.
Fields
descending
Optional
string
end
Optional
{
name => string
}
exclude-fields
Optional
string
fields
Optional
string
key
Optional
string
layer
Optional

view.replace 285
string
max-results
Optional
integer
skip-first
start
Optional
{
name => string
}
view.replace
Replace values on a view.
Fields
name
Required
string
resolver
Required
string
The name of the resolver associated with this view. All DNS operations are performed in the
context of the resolver.

286 view.update
layer
Optional
string
post-edits
Optional
pre-edits
Optional
time-zone
Optional
string
the IANA tzdb.
view.update
Updates values on a view.
Fields
name
Required
string
layer
Optional

view.update 287
string
post-edits
Optional
pre-edits
Optional
time-zone
Optional
string
the IANA tzdb.
unset
Optional
string

288 view.update

Chapter 14: Events ref-
erence
address-list.changed
Indicates that an address-list has been modified.
Returns
name
string
The name of the address-list.
address-node.changed
Indicates that an address-node has been modified.
Returns
address
addrpat
The address or network that the address-node represents.
list
string
The list to which the node belongs.

290 binding.changed
binding.changed
Indicates that a ratelimiter has been modified.
Returns
policy
string
The name of the policy to which this binding refers.
server
'1'
Indicates that the binding target is the server, and that the binding matches all queries.
view
string
Indicates that the binding target is a view, and that this binding matches all queries handled by
that view.
dns64.changed
Indicates that a dns64 layer has been modified.
Returns
name
string
An arbitrary string that uniquely identifies the DNS64 instance.
layer.changed
Signals that a layer has changed.
Returns
name
Required
string

layer.provisioning-connected
Signals that a connection was (re)established to the provisioning server. layer.provisioning-
connected is only sent when a previous layer.provisioning-connection-failure event exists.
Returns
name
Required
string
layer.provisioning-connection-failure
Signals that a connection could not be established with the provisioning server, and that
CacheServe will continue to attempt to connect.
CacheServe signals a successful reconnection with layer.provisioning-connected
Returns
error
string
The name of the layer.
name
string
layer.provisioning-disconnected
Signals that the connection to the provisioning server was closed by the remote end of the
connection.
Returns
name
string

292 layer.provisioning-reimaging
layer.provisioning-reimaging
Signals that provisioning is reimaging, either because this is the first synchronization with the
provisioning server, or because the database ID of the provisioning server has changed.
Returns
name
string
layer.provisioning-update-failure
Signals that an update failed.
Returns
error
string
name
string
layer.provisioning-update-success
Signals that an update was successful.
name
string
name-list.changed
Indicates that a name-list has been modified.

Returns
name
string
The name of the name-list.
name-node.changed
Returns
list
string
The list to which the node belongs.
name
name
The name of the node.
policy.changed
Indicates that a policy has been modified.
Returns
name
string
The policy's name.
policy.hit
Indicates that a policy matched a query.
Returns
client
addrport
The client making the query.

294 ratelimiter.abate
name
string
The policy's name.
qname
name
The domain in the query.
qtype
rdatatype
The query type.
view
string
The view assigned to the query.
ratelimiter.abate
Signals that a previously limited ratelimiter entry has not hit its limit(s) for 5 minutes.
Returns
bps
integer
The maximum bytes-per-second for this ratelimiter.
client-network
addr
The network address for this entry.
client-network-family
ipv4 | ipv6
Indicates whether the entry is for IPv4 or IPv6 networks.
client-network-mask-length
ipv6netlen
The mask length for network addresses.

creation-time
The creation time of the ratelimiter.
entry-creation-time
The creation time of the entry.
fields
('client-network' | 'query-name' | 'query-type' ...)
Fields used to group requests into entries.
last-limited-time
The time at which this entry was most recently limited.
last-use-time
The time at which this entry was last used.
name
string
qps
integer
The maximum queries per second for this ratelimiter.
query-name
name
The portion of the query name for this entry.
query-name-labels
name-label-count
The number of labels used for this entry's query name.

296 ratelimiter.changed
query-type
rdatatype
The entry's query type.
unenforced
boolean
If this value is set, CacheServe will collect statistics, log messages and events related to rate-
limiting, but will not actually drop or truncate queries.
ratelimiter.changed
Returns
name
string
ratelimiter.onset
Signals that a previously limited ratelimiter entry has hit its limit(s).
Returns
bps
integer
The maximum bytes-per-second for this ratelimiter.
client-network
addr
The network address for this entry.
client-network-family
ipv4 | ipv6
Indicates whether the entry is for IPv4 or IPv6 networks.

client-network-mask-length
ipv6netlen
The mask length for network addresses.
creation-time
The creation time of the ratelimiter.
entry-creation-time
The creation time of the entry.
fields
('client-network' | 'query-name' | 'query-type' ...)
Fields used to group requests into entries.
last-limited-time
The time at which this entry was most recently limited.
last-use-time
The time at which this entry was last used.
name
string
qps
integer
The maximum queries per second for this ratelimiter.
query-name
name
The portion of the query name for this entry.

298 resolver.changed
query-name-labels
name-label-count
The number of labels used for this entry's query name.
query-type
rdatatype
The entry's query type.
unenforced
boolean
If this value is set, CacheServe will collect statistics, log messages and events related to rate-
limiting, but will not actually drop or truncate queries.
resolver.changed
Indicates that a resolver has been modified.
Returns
name
string
resolver.flush
Indicates that the resolver has flushed its cache.
Returns
name
string
target
('domain' name) | ('name' name)
The target of the flush.

resolver.id-spoofing-suspected
Indicates that CacheServe suspects an an ID spoofing attack; this event is issued under the
same conditions as the log message enabled by log-id-spoofing.
Returns
name
string
qname
name
The queried name.
qtype
rdatatype
The queried record type.
server.changed
Indicates that the server has been modified.
server.configuration-error
Indicates that an error occurred when applying a configuration change.
Returns
errors
string
A list of errors encountered in the course of applying the configuration.
object
string
The object that produced the errors.

300 server.formerr-loop
server.formerr-loop
Indicates that CacheServe has detected a FORMERR loop with another server. FORMERR loops
consist of servers sending packets back and forth, and usually occur as the result of a
misconfiguration or malicious behavior.
CacheServe terminates FORMERR loops after several iterations.
Returns
address
addrport
The address and port of the other end of the FORMERR loop.
server.restart
Indicates that CacheServe is restarting.
server.stop
Indicates that CacheServe is shutting down.
server.tcp-client-limit
Indicates that the number of clients with open TCP connections exceeds the configured value
for max-tcp-clients.
This event will be sent a maximum of once per second.
server.udp-recursion-limit
Indicates that the number of UDP queries requiring recursion has exceeded the configured
value of max-recursive-clients.
This event is sent a maximum of once per second.
view-selector.changed
Indicates that a view-selector has been modified.

view.changed 301
Returns
destination-address
addrport
The destination address required by the view-selector; all requests must match this value.
If the value includes a port number, the query's destination address must match both the port
number and the address.
source-address
addrport
The source address required by the view-selector; the client sending the request must have an
address originating within this network.
view.changed
Indicates that a view has been modified.
Returns
name
string
The name of the view.

302 view.changed

Chapter 15: Command
Channel fields and types
reference
ACLs
Access Control Lists (ACLs) are used to control access by evaluating an IP address or network.
ACLs are evaluated by matching an IP address against each ACL element in turn.
An ACL matches if the IP address being evaluated matches the ACL element.
An ACL does not match if the IP address being evaluated either does not match the ACL element,
or the IP address being evaluated doesn't match any ACL element.
To match all IPv4 addresses, use 0.0.0.0/0. To match all IPv6 addresses, use ::/0.
exclude-fields
A string defining the fields to be excluded from a response.
fields
A string defining the fields to be included in a response.

304 acl-element
acl-element
An Access Control List.
An IPv4 or IPv6 address or network prefix, like
127.0.0.0/8
or
11:22::/16.
acl-elements are used in ACLs.
acl-element4
An Access Control List comprised of IPv4 addresses only, like
127.0.0.0/8
acl-element4s are used in ACLs.
acl-element6
An Access Control List comprised of IPv6 addresses only, like
11:22::/16.
acl-element6s are used in ACLs.
addr
An IP address.
addr-or-name
An IP address or domain name.
addr6
An IPv6 address.

addrpat 305
addrpat
An IP address with an optional netmask length, expressed as address or address/masklength.
Unless otherwise specified, mask length defaults to the full length of the address: 32 bits for
IPv4, and 128 bits for IPv6.
addrpat6
An IPv6 address with an optional netmask length, expressed as <ad dr> or
<addr>/<masklength>. When no mask length is specified, the mask length is assumed to be the
full length of the address (128 bits). The host portion of the address must be 0.
addrport
An IP address with an (optional) port, expressed as address or address/#port
addrport4
An IPv4 address with an (optional) port, expressed as address or address/#port
addrport6
An IPv6 address with an (optional) port, expressed as address or address/#port
addrrange
A range of IP addresses expressed by a start and end address, separated by "-":
192.168.1.1-192.168.2.1
anonymization-key-file-path
The path to a key file used by CacheServe for client IP anonymization. Defaults to /etc/nom_
ipanon.key.
boolean
A true or false value.
Nominum software, when interpreting a boolean value, accepts the following values for TRUE
(all values are case-insensitive):

306 dns-flag
l "true"
l "t"
l "yes"
l positive integers
Accepts the following values for FALSE (all values are case-insensitive):
l "false"
l "f"
l "no"
l 0
dns-flag
A DNS header flag.
'aa': Authoritative answer.
'ad': Set on answers where signatures have been cryptographically verified or

the server is authoritative for the data and is allowed to set the bit by
policy.
'cd': Checking disabled.
'qr': query or answer. If true, the answer is a query.
'ra': Recursion available.
'rd': An alias for "recursive".
'tc': Truncated packet.
dns-rcode
A DNS result code.
FORMERR: Format error.
NOERROR: No error.
NOTAUTH: Not authorized.
NOTIMP: Not implemented.
NOTZONE: Name not contained in zone.
NXDOMAIN: Non-existent domain.
NXRRSET: RRset that should exist does not.
REFUSED: Query refused.
SERVFAIL: Server failure.
YXDOMAIN: Name exists when it should not.
YXRRSET: RRset exists when it should not.

edns-flag 307
edns-flag
A DNS extended header flag.
'do'
event-name
The name of a Nominum Command Channel event. May be any of the following:
'layer.provisioning-connected'
'layer.provisioning-connection-failure'
'layer.provisioning-disconnected'
'layer.provisioning-reimaging'
'layer.provisioning-update-failure'
'layer.provisioning-update-success'
'policy.hit'
'ratelimiter.hit'
'resolver.flush'
'resolver.id-spoofing-suspected'
'server.configuration-error'
'server.formerr-loop'
'server.restart'
'server.stop'
'server.tcp-client-limit'
'server.udp-recursion-limit'
A floating-point number representing a time in seconds since the UNIX epoch (00:00 UTC,
January 1, 1970).
inspect-delegation-servers
Information about the name service at a delegation point in the cache.
Format:
({
addresses => ({
addresses => ({
address => addr
rtt => integer
} ...)
glue => boolean
immortal => boolean
origin => addr

308 integer
status => string

ttl => integer
type => rdatatype
} ...)
server => name
status => {
status => string
ttl => integer
}
} ...)
integer
A 32-bit unsigned integer.
Integers may be signed or unsigned: signed integers may encompass negative numbers,
where unsigned integers may not.
ipv4netlen
A value between 1 and 32, representing the number of bits of for an IPv4 netmask.
ipv6netlen
A value between 1 and 128, representing the number of bits of for an IPv6 netmask.
monitor-log-switch
A Command Channel flag denoting a type of command.
Switch Negation Default Description

Log details about valid Command Channel
commands executed by a monitor. Com-
command/executed !command/executed False
mands are logged after handling, and, if
present, include the value of err.
Log details about Command Channel traffic
sent and received by a monitor. All com-
command/info !command/info False
mands are logged when received, and all
responses are logged when sent.
Log details about unknown Command
command/unknown !command/unknown False
Channel commands received by a monitor.

name 309
name
A domain name. If the textual input is not a fully-qualified domain name, it will be converted into
an FQDN by using the root domain as the origin.
name-empty-ok
A domain name. If the textual input is not absolute, it will be converted into an absolute name
by using the root domain as the origin, with the exception of '@', which represents the empty
name and will not be made absolute.
name-label-count
A value between 0 and 128, representing the number of labels to retain in a DNS name, starting
from the least specific and moving to most specific.
The root label is included in this count. A value of 0 means to use the entire name, unaltered.
For example, if the DNS name is "www.nominum.com.", a count of 3 would use "nominum.com."
policy-action
Specifies an action to be taken on a query. Some actions only have an effect at certain points in
the query process.
Format:
('answer' ((rdatatype, rdata) ...))

('answer-byname' name)
('answer-byresolver' string)
'answer-noerror'
'answer-nxdomain'
('answer-ttl' (((rdatatype, rdata) ...), ttl))
('dns64' string)
('dns64-reverse' string)
'drop'
'no-op'
'refuse'
'send-event'
('sort-addresses' ((string ...), boolean))
'stop'
'truncate'

310 policy-action
('answer' ((rdatatype, rdata) ...))

Stage: Prequery, postquery
Synthesizes an answer for a query. The answer is specified as a tuple of rdatatype and rdata,
where:
l rdatatype is a textual representation of a DNS rdata type, and

l rdata is the textual representation of the rdata to use in the answer.
In rdata, any whitespace must be quoted.
The returned answer will always have a TTL of 0; if you want a non-zero TTL, use answer-ttl
instead.
('answer-byname' name)
Synthesizes an answer for a query. name is a DNS name, and CacheServe uses name instead of
the query name when determining the answer. The answer can come from cache, or it can
come as the result of a DNS resolution (as if the name was queried directly).
TTL should never be less than 300 for best performance.
('answer-byresolver' string)
string must match the name of an existing resolver.
Answers the query using the resolver specified by stringinstead of the resolver normally
associated with the query.
'answer-noerror'
Synthesizes an answer with an rcode of NOERROR and no resource records.
'answer-nxdomain'
Synthesizes an answer with an rcode of NXDOMAIN and no authority section.
('answer-ttl' (((rdatatype, rdata) ...), ttl))

Synthesizes an answer for a query, specified as a tuple of (rdatatype, rdata), with an optional ttl
that affects all records in the answer.

policy-action 311
Synthesizes an answer for a query. The answer is specified as a tuple of rdatatype and rdata,
with an optional ttl that affects all records in the answer:
l rdatatype is a textual representation of a DNS rdata type.

l rdata is the textual representation of the rdata to use in the answer.
l ttl is a time value, and may use mixed units (like 1d2h).
In rdata, any whitespace must be quoted.
('dns64' string)
Stage: Postquery
Applies DNS64 transformation, if the query is for the AAAA type, and the result is either:
l The name occurs and no AAAA records exist
l All of the AAAA records match the DNS64 exclusions
This is a terminal action.
('dns64-reverse' string)
string must match the name of an existing dns64 object.
If the query is for type PTR and the qname matches the specified dns64 object, applies DNS64
reverse transformation.
'drop'
Stage: All
Drops the request immediately.
'no-op'
Stage: All
Do nothing. This is a non-terminal action, and has no effect; this action is useful when you want
to match a policy without taking any action.
'refuse'
Stage: All
Refuses the request immediately.
'send-event'
Stage: All
Sends an event. This is a non-terminal action.

312 policy-calendar-selector
('sort-addresses' ((string ...), boolean))

Stage: Postquery
All string entries must match the name of existing address-lists.
Sorts answers according to a defined set of priorities. Priorities are defined as an ordered list of
address-lists, with the first address-list in the list having the highest priority.
The priority of each address in the answer is based on the position of the address-list that
contains it. CacheServe determines which address-list contains an address by either exactly
matching the address, or using the closest matching network.
The boolean denotes 'remove-unmatched', and controls CacheServe's behavior when some
addresses in the answer don't match any address-list:
l If remove-unmatched is true, CacheServe removes these addresses from the response.

l If remove-unmatched is false, CacheServe includes these addresses in the response.
'stop'
Stage: All
Stops executing the current set of bindings (defined as all bindings in the current stage in the
query process).
If stop is executed pre-query, normal DNS processing will occur.
'truncate'
Stage: All
If the query was received over UDP, returns a "truncated" response. If the query was received
over TCP, has no effect.
policy-calendar-selector
A local-time-zone-based policy selector configuration.
Format:
{
end-time => string
not-after => string
not-before => string
start-time => string
time-zone => string
week-days => (string ...)
}
This selector matches only under the following conditions:

policy-result-type 313
l After not-before
l Prior to not-after
Both not-before and not-after are specified as yyyymmddThhmmss, where yyyy indicates the year,
mm indicates the numeric month, dd indicates the numeric day, T is a literal 'T' acting as a
delimiter, hh indicates the hour (on a 24-hour clock), mm indicates minutes, and ss indicates
seconds.
start-time and end-time take the form hhmmss.
time-zone is specified as a string that matches an entry in the 'TZ' column of the IANA tzdb.
week-days takes the form of a list of strings denoting the day of the week. Valid week-days are su,
mo, tu, we, th, fr, and sa.
policy-result-type
The result of a policy.
Format:
'cname' | 'dname' | 'failure' | 'noerror' | 'nxdomain' | 'nxrrset'
Result Description
cname The lookup resulted in a CNAME, which will be followed.
dname The lookup resulted in a DNAME, which will be followed.
failure The lookup failed, which results in a SERVFAIL response.
The lookup succeeded: the queried name exists and records of the queried type
noerror
exist at the queried name.
nxdomain The lookup resulted in an NXDOMAIN response: the queried name does not exist.
The lookup resulted in an NOERROR/NODATA response: the queried name exists
nxrrset
but there are no records of the queried type.
policy-selector
Criteria for selecting a policy to apply to a query. It's important to note that some selectors have
an effect only at certain points in the query process.
Format:
('and' (policy-selector ...))

('answer-address' string)
('calendar' (policy-calendar-selector ...))
('client-address' string)

314 policy-selector
('client-address-is' (acl-element ...))

'initial-qname'
('not' (policy-selector))
('or' (policy-selector ...))
('qflag' 'AD' | 'CD' | 'DO' | 'EDNS' | 'RD')
('qname' (string, 'exact' | 'exact-or-www' | 'subdomain'))
('qname-is' (name, 'exact' | 'exact-or-www' | 'subdomain'))
('qtype' (rdatatype ...))
('ratelimiter' string)
('response-size' uint16)
('result' (policy-result-type ...))
('server-address' string)
('type-exists-at-qname' rdatatype)
('and' (policy-selector ...))

Stage: All
Compound selector; matches only if all selectors in the set of selectors match.
('answer-address' string)
Stage: Postquery
stringmust be the name of an already-configured address-list.
Matches if the response contains A or AAAA records, and any address in the set of responses
matches an IP address or a network on the list.
('calendar' (policy-calendar-selector ...))

Stage: All
Matches at certain times or days as defined in the policy-calendar-selector.
('client-address' string)
Stage: All
Matches if the client address matches an IP address or network on the list.
('client-address-is' (acl-element ...))

Stage: All
Matches if the client address matches an IP address or network in the specified acl-element.

policy-selector 315
'initial-qname'
Stage: All
Matches if the current query name matches the query name in the received packet (no CNAME
or DNAME has been followed).
('not' (policy-selector))
Stage: All
Compound selector; matches only if the associated selector DOES NOT match.
('or' (policy-selector ...))

Stage: All
Compound selector; matches if any of the selectors match.
('qflag' 'AD' | 'CD' | 'DO' | 'EDNS' | 'RD')

Stage: All
Matches if the query has the corresponding flag set. RD, AD and CD correspond to flags in the
DNS header. DO corresponds to the extended flag in the EDNS OPT record. EDNS corresponds
to the presence of an EDNS OPT record.
('qname' (string, 'exact' | 'exact-or-www' | 'subdomain'))

Stage: All
stringmust be the name of an already-configured name-list.
Matches if the query name matches an entry on the name-list. exact specifies an exact match,
exact-or-www specifies an exact match where the www prefix, if present, is ignored, and
subdomain specifies a subdomain match.
This selector refers to different elements of the query in different contexts:
l prequery or postquery, the selector refers to the current query name, which may be the
result of a followed CNAME or DNAME.
l presend, the selector refers to the query name from the DNS packet.
('qname-is' (name, 'exact' | 'exact-or-www' | 'subdomain'))
Stage: All
Matches if the query name matches name. exact specifies an exact match, exact-or-www specifies
an exact match where the www prefix, if present, is ignored, and subdomain specifies a
subdomain match.

316 policy-selector
('qname-prefix' string)
Stage: All
Matches if the query name's prefix exactly matches string.
('qtype' (rdatatype ...))
Stage: All
Matches if rdatatype matches the query's type.
('ratelimiter' string)
Stage: All
stringmust be the name of an already-configured ratelimiter.
Matches UDP queries when the TCP and UDP query rate from matched clients exceeds the
thresholds of the specified ratelimiter.
('response-size' uint16)
Stage: Presend
Matches if the size of the response packet is greater than or equal to the specified value.
('result' (policy-result-type ...))

Stage: Postquery
Matches if the type of the response matches policy-result-type.
('server-address' string)
Stage: Postquery
Matches if the address of the authoritative server that originally provided the response
matches an entry in the address-list.

positive-integer 317
('type-exists-at-qname' rdatatype)
Stage: All
Matches if there are any records of the specified rdatatype at the current query name.
DNS queries may be issued as a result of evaluating this selector.
positive-integer
A 32-bit unsigned integer greater than 0.
provisioning-status
Identifies the status of the current provisioning session. The status value indicates the current
status.
Format:
{
current-time => seconds-since-epoch
database-id => string
error => string
last-update => seconds-since-epoch
status => string
versions => {
<name> => string-empty-ok
...
}
}
Status values
Status Description
initial Initializing
connecting Connecting to the provisioning server.
handshake Exchanging handshake with the provisioning server.
wait Waiting for update events.
update Processing an update.
faulted An unrecoverable error has occurred. No provisioning will be attempted.
How provisioning usually goes

Under normal circumstances, provisioning status flows from initial to wait, and from wait to
update as updates come in.

318 ratelimiter-statistics
When a recoverable error occurs (like a connection being dropped), the provisioning client will
close the current connection and start over with the initial state and a fresh session.
Non-recoverable errors create a faulted state, and you'll have to manually intervene to fix them,
either by issuing a layer.clear-fault command or breaking the connection to the provisioning
server.
ratelimiter-statistics
{
all-indications => uint64
current-entry-count => uint64
current-limited-count => uint64
expiring-entry-age => uint64
indications-by-bps => uint64
indications-by-qps => uint64
uses => uint64
}
all-indications
The number of times a ratelimiter has limited a query for any reason.
current-entry-count
The number of ratelimit entry slots in use. This number will increase to the maximum
configured value, and will not typically decrease unless the rate limiter is configured.
If all slots are in use, older ones will be evicted. If the older slots are evicted too quickly,
especially if they are limited when they are evicted, this indicates rate limiting may not be
effective. See expiring-entry-age and current-limited-count for more information.
current-limited-count
The number of ratelimit entry slots which are currently limited.
expiring-entry-age
The time, in microseconds, that a rate limiting tracking entry was last used before it was
destroyed. If this is cycling quickly, it indicates there may not be sufficient rate limiting entries
confgured to effectively enforce rate limiting.
indications-by-bps
The number of times a ratelimiter has limited a query based on the BPS threshold.
indications-by-qps
The number of times a ratelimiter has limited a query based on the QPS threshold.

rdata 319
uses
The number of times the ratelimiter has been asked to make a decision to limit a query or allow
it to proceed.
rdata
DNS RDATA (RFC1035), represented as a text string.
rdataclass
A DNS rdata class. This is typically IN for the Internet class, but other classes such as CH and HS
are also supported.
rdatatype
A DNS rdata type.
report-max-memory-arg
The maximum amount of memory statmon will use to maintain all report intervals for a single
source, in bytes. By default, there is no limit. The minimum permissible value is 1M.
resolver-statistics
{
cache-misses => uint64
dnssec-validations-failure => uint64
dnssec-validations-insecure => uint64
dnssec-validations-success => uint64
id-spoofing-defense-queries => uint64
ignored-referral-lookups => uint64
lookups => uint64
proactive-lookups => uint64
queries => uint64
recursive-lookups => uint64
responses-by-rcode =>
{
<rcode> => uint64
...
}
}

320 resolver-statistics
cache-misses
The number of cache misses that have occurred as part of resolutions. The number of cache
misses is not strictly related to the number of queries received, as one query may result in zero,
one, or multiple cache misses.
dnssec-validations-failure
The number of failed DNSSEC validations.
dnssec-validations-insecure
The number of DNSSEC validations which determined that the data being validated is provably
insecure.
dnssec-validations-success
The number of successful DNSSEC validations.
id-spoofing-defense-queries
The number of times a query has been sent to an authoritative server using TCP instead of
UDP in order to defend against suspected ID spoofing attacks.
ignored-referral-lookups
The number of referrals ignored as part of subdelegation attack defenses. Ignoring some
referrals is a normal part of the server-s defense strategy and does not indicate that the server
is under attack.
lookups
The number of DNS lookups performed by this resolver. This is different from queries because
resolving a single client DNS query can involve multiple lookups due to following CNAME or
DNAME chains, looking up name server addresses and DNSSEC keys, root server priming, etc.
proactive-lookups
The number of proactive DNS queries (that is, queries done as part of prefetching) issued.
queries
The number of queries processed by this resolver.
rate-limited-requests
The number of DNS requests not sent to other DNS servers from this resolver due to server-
based rate-limiting.
recursive-lookups
The number of DNS lookups (as reported in lookups) that could not be satisfied from the cache.

requests-sent
The number of DNS requests sent to other DNS servers from this resolver.
responses-by-rcode
The number of responses sent with each DNS result code (dns-rcode). The most common
rcode values are NOERROR (the name queried for exists), NXDOMAIN (the name queried for
does not exist), and SERVFAIL (a failure occurred processing the request).
tcp-requests-sent
The number of DNS request messages sent to other DNS servers using TCP from this resolver.
This includes TCP requests made due to UDP message truncation as well as those made due to
suspected ID spoofing attacks.
seconds-since-epoch
A 64-bit unsigned integer representing a time in seconds since the epoch (00:00 UCT, January 1,
1970).
server-statistics
{
recursion-contexts-in-use => uint64
requests-no-view => uint64
requests-received => uint64
responses-received => uint64
responses-sent => uint64
tcp-clients => uint64
}
rate-limited-requests
The number of DNS requests not sent to other DNS servers due to server-based rate-limiting.
recursion-contexts-in-use
The number of clients currently executing recursive DNS lookups. This cannot exceed the limit
configured in the server's max-recursive-clients field.
requests-no-view
The number of DNS requests refused because they did not match any of the configured view-
selectors.

322 sizeval
requests-received
The number of DNS requests received from clients.
requests-sent
The number of DNS requests sent to other DNS servers.
responses-received
The number of DNS responses received from other DNS servers.
responses-sent
The number of DNS responses sent to clients.
tcp-clients
The current number of open TCP connections from clients. This cannot exceed the limit
configured in the server's max-tcp-clients field.
tcp-requests-sent
The number of DNS request messages sent to other DNS servers using TCP. This includes TCP
requests made due to UDP message truncation as well as those made due to suspected query
ID spoofing attacks.
sizeval
An integer optionally followed by a scaling factor: K or k for kilobytes, M or m for megabytes, and
G or g for gigabytes, which scale by 1024, 1024*1024, and 1024*1024*1024, respectively.
A layered configuration edit operation. Takes the form
('defaults' (string ...)) | ('hide' (string ...))
Parameter Description
The "defaults" edit takes a list of of field names and
sets them back to their default values.
('defaults' (string ...))
If the list is empty, then all fields are reset to their
default values.
('hide' (string ...)) The "hide" edit hides the object.

string 323
string
A simple text string.
string-empty-ok
A string which may be empty.
threshold-abate
A 32 bit unsigned integer representing the QPS at which a threshold will become inactive.
threshold-duration
A 32 bit unsigned integer representing the time in seconds over which to track data for a
threshold.
threshold-onset
A 32 bit unsigned integer representing the QPS at which a threshold will become active.
A floating-point number representing a number of seconds with microsecond precision.
time-in-seconds
A 64-bit unsigned integer representing an amount of time in seconds. The integer may be
followed by a scaling factor:
Scaling Factor Representation

s or S Seconds
m or M Minutes
h or H Hours
d or D Days
w or W Weeks

324 ttl
ttl
A DNS TTL. This is similar to a scaled time value, except that it can contain mixed units (1d1h, for
example).
uint16
uint64
unparsed
Data with no defined structure.
uuid
A universially unique identifier (UUID).
versioncheck-days
An integer between 1 and 30.

action 90, 183, 188, 191
policy field 90
Index ad header 306
adding new elements
address-lists 115
-
additional 256
--channel 56
address 75, 125, 127, 130-131
--configuration 56
address-node field 75
--directory 56
cacheserve-deleteconf option 68
--dns-port 56
cacheserve-dumpconf option 67
--fd-limit 56
cacheserve-editconf option 64
--foreground 57
address-list
--foreground-with-syslog 57
events 75
--help 57
supported fields 74
--license 57
address-list object 73
--no-statmon 57
address-list.add 115
--root 57
--user and 57-58
address-list.delete 116
address-list.dump 117
--syslog-facility 58
address-list.dump file 117
--usage 58
address-list.get 117
--user 58
address-list.list 118
--root and 57-58
address-list.load 120
--version 59
merging or replacing entries 120
/
source file format 120
/etc/channel.conf 33, 70
A
aa header 306

326 Index
address-list.update 124 aliases 256
address-lists all 201, 235, 264
adding 115 cacheserve-dumpconf option 67
deleting 116 cacheserve-loadconf option 65
merging or replacing entries 120 all-events
retrieving individual 117 connection field 80
address-node all-indications ratelimiter statistic 318
events 77 amplification attacks 45
supported fields 75 characteristics of 45
address-node fields how they work 45
address 75 purpose-built domains and 46
count 75 ratelimiting clients and 50
errors 76 size-limiting traffic and 51
list 76 and policy-selector 314
post-edits 76 answer 256
pre-edits 76 answer-address policy-selector 314
tag 76 answer-byname policy action 310
address-node object 75 answer-byresolver policy action 310
address-node.add 125 answer-noerror policy action 310
address-node.changed 289 answer-nxdomain policy action 310
address-node.delete 126 answer-ttl policy action 310
address-node.get 126 answer policy action 310
address-node.list 127 auth drop/s 71
address-node.replace 130 auth req/s 71
address lists auth resp/s 71
loading from a file 120 authority 256
retrieving multiple 121

Index 327
B C
binding cache
events 79 retrieving names from 217, 220
priority 78, 133, 141, 143 cache-misses 320
server 78, 134-136, 138, 140, 142, 144 resolver statistic 320
supported fields 77 cacheserve-deleteconf 68
binding fields --configuration 69
errors 77 --destination-address 69
policy 77 --layer 69
post-edits 78 --list 69
pre-edits 78 --name 69
priority 78 --policy 69
server 78 --server 69
view 79 --source-address 69
when 79 --version 69
binding object 77 --view 69
binding.add 132 address 68
binding.changed 290 cacheserve-dumpconf
binding.delete 135 --address 67
binding.get 136 --all 67
binding.list 137 --channel 67
bps 92, 194, 200, 203 --configuration 67
ratelimiter field 92 --destination-address 67
ratelimiter.abate 294 --layer 67
ratelimiter.onset 296 --list 67
broken configuration, finding 22, 252 --list-all 67
--name 67

328 Index
--object-type 67 --check 66
--output 68 --configuration 66
--policy 68 --layer 66
--server 68 --object-type 66
--source-address 68 --version 66
--version 68 limitations of configuration checking 65
--view 68 cacheserve-stats 69
cacheserve-editconf CacheServe file locations
--address 64 address-list.dump 117
--channel 64, 69 cacheserve objects 61
--configuration 64 cacheserve process
--destination-address 64 --channel 56
--layer 64 --configuration 56
--list 64 --directory 56
--name 64 --dns-port 56
--object-type 64, 69 --fd-limit 56
--policy 64 --foreground 57
--server 64 --foreground-with-syslog 57
--source-address 64 --help 57
--version 64 --license 57
--view 65 --no-statmon 57
-c See cacheserve-editconf, --con- --root 57

figuration
-t See cacheserve-editconf, --object-
--syslog-facility 58
type
--usage 58
cacheserve-loadconf 65
--user 58
--all 65
--version 59
--channel 65

Index 329
cacheserve utilities ratelimiter.onset 297
cacheserve-stats 69 client‐network 93
calendar policy-selector 314 clients
cd header 306 rate-limit based on qps 50
channel 84, 157, 163-164 clnt req/s 71
cacheserve-deleteconf option 69 clnt resp/s 71
cacheserve-dumpconf option 67 Command Channel
cacheserve-editconf option 64 new features in CacheServe 22
cacheserve-loadconf option 65 commands
cacheserve process argument 56 address-list.mget 121
layer field 84 resolver.inspect 217
check-address resolver.inspect-delegation 220
cacheserve-loadconf option 66 resolver.mget 223
children 90, 183, 188, 191 server.all-errors 252
policy field 90 commands-not-logged 106, 248, 260, 266
chroot() 13 server field 106
client-address 254 configuration
client-address-is policy-selector 314 best practices 65
client-address policy-selector 314 cacheserve-deleteconf option 69
client-network cacheserve-dumpconf option 67
ratelimiter.abate 294 cacheserve-editconf option 64
ratelimiter.onset 296 cacheserve-loadconf option 66
client-network-family cacheserve process argument 56
ratelimiter.abate 294 deleting 68
ratelimiter.onset 296 dumping 66
client-network-mask-length example 62
ratelimiter.abate 294 loading 65

330 Index
configuration checking, cacheserve versus ratelimiter.onset 297

cacheserve-loadconf 65
current-entry-count ratelimiter
configuration file statistic 318
examples of each element 62 current-limited-count 318
formatting 62 current-limited-count ratelimiter

statistic 318
lists 62
current-time 201, 236, 264
tables 62
D
tuples 62
data dumping
Configuration file format 62
address-list 117
configuration utilities 61
database
connection
retrieving address-lists from 117
supported fields 80
default locations
connection fields
all-events 80
definitions
events 80
list 62
idle-timeout 80
tables 62
connection object 79
tuples 62
connection.get 145
deleting data 68
connection.replace 145
deleting elements
connection.subscribe-all 146
address-lists 116
connection.update 146
descending 118, 121, 128-129, 137, 139,
count 74-75, 87
150-151, 160-161, 168, 170, 177-178,
address-node field 75 185-186, 196, 198, 221, 223, 274-275,
name-list field 87 282, 284
cpu-time 70 destination-address 112, 271-273, 276,

278-279
creation-time

Index 331
cacheserve-editconf option 64 YXRRSET 306
view-selector field 112 dns64
directory events 83
cacheserve process argument 56 supported fields 81
dns-port dns64-reverse policy action 311
cacheserve process argument 56 dns64 fields
DNS amplification attacks See amp- errors 81

lification attacks
mapped 81
DNS headers
name 82
aa 306
post-edits 82
ad 306
pre-edits 82
cd 306
prefix 82
qr 306
suffix 82
ra 306
dns64 object 80
rd 306
dns64 policy action 311
DNS queries
dns64.add 147
modeling 253
dns64.changed 290
DNS rcodes
dns64.delete 148
FORMERR 306
dns64.get 149
NOERROR 306
dns64.list 150
NOTIMP 306
dns64.mget 151
NOTZONE 306
dns64.update 154
NXDOMAIN 306
dnssec-aware 95, 204, 216, 225, 237
NXRRSET 306
resolver field 95
REFUSED 306
dnssec-validations-failure 320
SERVFAIL 306
dnssec-validations-failure resolver
YXDOMAIN 306 statistic 320

332 Index
dnssec-validations-insecure 320 ratelimiter.onset 297
dnssec-validations-insecure resolver stat- error

istic 320
event return 291-292
dnssec-validations-success 320
errors 74, 76-77, 81, 84, 87-88, 91-92, 95,
dnssec-validations-success resolver stat- 106, 111-112, 205, 225, 238, 249, 266
istics 320
domain 218, 220
binding field 77
domain names
dns64 field 81
adding lists of 115
layer field 84
deleting lists of 116
name-list field 87
retrieving individual lists of 117
name-node field 88
dropped 257
policy field 91
dump files
ratelimiter field 92
resolver field 95
dumped data locations
server field 106
address-lists 117
view-selector field 112
dumping configuration data 66
view field 110
dumping data
errors field
address-list 117
server.all-errors and 74, 76-77, 81, 85,
E 87, 89, 91, 93, 95, 106, 111, 113,
205, 225, 238, 249, 266
edns-buffer-size 254
event returns
edns-flags 254
error 291-292
efficiency 70
name 291-292
encrypt 174-176, 180-181
events 80, 145-146
encrypted 88, 174, 180-181
address-list 75
name-node field 88
entry-creation-time
address-node 77

Index 333
address-node.changed 289 resolver.changed 298
binding 79 resolver.flush 298
binding.changed 290 resolver.id-spoofing-suspected 299
connection field 80 server 110
dns64 83 server.changed 299
dns64.changed 290 server.configuration-error 299
layer 86 server.formerr-loop 300
layer.changed 290 server.restart 300
layer.provisioning-connected 291 server.stop 300
layer.provisioning-connection- server.tcp-client-limit 300

failure 291
layer.provisioning-disconnected 291
view 111
layer.provisioning-reimaging 292
view-selector 113
layer.provisioning-update-success 292
view.changed 301
name-list 88
examples
name-list.changed 292
configuration file 62
name-node 89
exclude 147, 153-154
exclude-fields 118, 121, 127, 136, 145, 149,
policy 91 151, 159, 161, 167, 171, 176, 185, 196-
198, 217, 223, 253, 273, 282, 284, 303
policy.changed 293
exists 218
policy.hit 293
expiration 270
ratelimiter 94
expiring-entry-age 318
expiring-entry-age ratelimiter statistic 318
ratelimiter.changed 296
F
faulted state
resolver 105
recovering from 318

334 Index
fd-limit hints 96, 206, 226, 238
cacheserve process argument 56 resolver field 96
fields 118, 122, 127, 145, 149, 151, 159, 161, how to
167, 171, 176, 185, 194, 196-199, 203,
add an address-list 115
217, 223, 253, 273, 282, 284, 303
control file descriptor use 17
control recursion contexts 17
ratelimiter object 93
delete an address-list 116
dump the configuration database 66
find monitoring help 22
file descriptors 56
load data into cacheserve 65
if you're running out 17
manage amplification attacks 45
fixing a faulted provisioning session 318
retrieve an address-list 117
flags 254, 257
run cacheserve as a specific user 58
force-resolution 254
run cacheserve under a specific dir-
foreground
ectory 57
cacheserve process argument 57
I
foreground-with-syslog
id-spoofing-defense-queries 320
id-spoofing-defense-queries resolver stat-
formatting files for address-list.load 120 istic 320
formatting files for name-list.load 169 ID spoofing 53
FORMERR 306 idle-timeout 80, 146
forward 95, 205, 225, 238 connection field 80
resolver field 95 ignore-first-referral 96, 206, 226, 239
H resolver field 96
help ignored-referral-lookups 320
cacheserve process argument 57 ignored-referral-lookups resolver

statistic 320
hidden 85, 157, 163-164
immortal 218, 220
layer field 85

Index 335
important files cacheserve-dumpconf option 67
address-list.dump 117 cacheserve-editconf option 64
indications-by-bps 318 cacheserve-loadconf option 66
indications-by-bps ratelimiter statistic 318 events 86
indications-by-qps 318 priority 85, 157, 163-164
indications-by-qps ratelimiter statistic 318 server 85, 158, 163, 165
initial-qname policy-selector 315 supported fields 84
instance-information 156 layer fields
ipv4netlen 308 channel 84
ipv6netlen 308 errors 84
K hidden 85
key 119, 122, 128-129, 137, 139, 150, 152, name 85

160-161, 168, 171, 177, 179, 185, 187,
priority 85
197-198, 222-223, 274-275, 283-284
provisioning 85
L
server 85
lame delegations 207
layer object 83
last-limited-time
layer.add 157
layer.changed 290
layer.clear-fault 158
last-use-time
layer.delete 158
layer.get 159
layer.list 159
layer 115-116, 118-119, 122-129, 131-133,
135-137, 139, 141, 143, 148-150, 152- layer.provisioning-connected 291
153, 155, 161, 166-168, 171-177, 179- layer.provisioning-connection-failure 291
180, 182-188, 191, 194-197, 199-200,
203, 206, 216, 222-223, 226, 239, 248, layer.provisioning-disconnected 291
253, 260, 266, 271-274, 276, 278-284, layer.provisioning-reimaging 292
286

336 Index
layer.provisioning-update-success 292 definition of 62
layer.reimage 162 deleting a list of domain names 116
layer.replace 162 deleting address-lists 116
layer.update 164 retrieving an individual list of domain

names 117
layers
retrieving individual address-lists 117
events
loading addresses from a file 120
layer.changed 290
loading configuration data 65
log-command-channel 107, 250, 261, 267
layer.provisioning-connection-fail-
ure 291 server field 107
layer.provisioning-disconnected 291 log-dnssec 96, 206, 226, 239
layer.provisioning-reimaging 292 resolver field 96
license log-id-spoofing 97, 206, 227, 239
cacheserve process argument 57 resolver field 96
list 76, 89, 125, 127, 129-131, 174, 176-177, log-lame 97, 207, 227, 240
179-181, 187
resolver field 97
lookups 320
lookups resolver statistic 320
M
managed-key field 98, 208, 228, 240
name-node field 89
managed-keys 97, 207, 227, 240
list-all
resolver field 97
managed-keys-state 98, 208, 228, 241
listen-on-matching 106, 249, 261, 266
resolver field 98
server field 106
managed keys 98, 208, 228, 240
lists 62
mapped 82, 148, 153, 155
adding a list of domain names 115
dns64 field 81
adding address-lists 115

Index 337
max-cache-size 98, 209, 228, 241 111, 113, 205, 225, 238, 249, 252, 266
resolver field 98 monitoring
max-cache-ttl 98, 209, 229, 241 changes in CacheServe 22
resolver field 98 N
max-client-ttl 99, 209, 229, 241 name 74, 82, 85, 87, 89, 91, 93, 100, 111,
115-117, 120, 122-124, 126, 133, 140,
resolver field 99
143, 147, 149, 152, 154, 157-159, 162-
max-edns-udp-size 99, 209, 229, 242 167, 170, 172-176, 180-181, 184, 194-
resolver field 99 195, 199, 203, 216-218, 220-221, 224,
271, 277, 279-282, 285-286, 290-291
max-ncache-ttl 99, 209, 229, 242
resolver field 99
max-recursive-clients 17, 108, 250, 262,
267 cacheserve-editconf option 64
RAM required per context 108, 250, dns64 field 82

262, 268 event return 291-292
server field 107 layer field 85
max-results 119, 122, 128, 130, 138-139, name-list field 87
150, 152, 160, 162, 168, 171, 178-179,
name-node field 89
186-187, 197, 199, 222, 224, 252, 274,
276, 283, 285 policy field 91
max-tcp-clients 108, 250, 262, 268 ratelimiter field 93
server field 108 ratelimiter.abate 295
max-tcp-recursions 17, 99, 210, 230, 242 ratelimiter.onset 297
resolver field 99 resolver field 99
maximum-entries 93, 194, 200, 203 view field 111
ratelimiter field 93 name-empty-ok 309
memory-in-use 201, 236, 264 name-list
memory in-use 71 events 88
misconfigured elements, how to find 74, supported fields 87
76-77, 81, 85, 87, 89, 91, 93, 95, 106,

338 Index
name-list fields errors 88
count 87 list 89
errors 87 name 89
name 87 post-edits 89
post-edits 87 pre-edits 89
pre-edits 87 tag 89
name-list object 86 name-node object 88
name-list.add 165 name-node.add 174
name-list.changed 292 name-node.changed 293
name-list.delete 166 name-node.delete 175
name-list.dump 167 name-node.get 176
name-list.get 167 name-node.list 177
name-list.list 168 name-node.mget 178
name-list.load 169 name-node.replace 179
merging or replacing entries 169 name-node.update 181
source file format 169 negative-trust-anchors
name-list.mget 170 resolver field 100
name-list.replace 172 new features
name-list.update 173 Command Channel connections 22
name-lists no-statmon
merging or replacing entries 169 cacheserve process argument 57
source file format 169 no view/s 71
name-node NOERROR 306
events 89 nonexistence-proof 218
supported fields 88 not policy-selector 315
name-node fields NOTAUTH 306
encrypted 88 NOTIMP 306

Index 339
NOTZONE 306 preferred hardware and OS 18
NXDOMAIN 306 recommended network settings 18
NXRRSET 306 recursion contexts 17
O platform 270
object-type plugins 270
cacheserve-deleteconf option 69 policies 257
cacheserve-dumpconf option 67 policy 78, 133, 135-137, 139, 141, 144
cacheserve-editconf option 64 binding field 77
cacheserve-loadconf option 66 cacheserve-deleteconf option 69
objects cacheserve-dumpconf option 68
address-list 73 cacheserve-editconf option 64
address-node 75 events 91
binding 77 server field 78
connection 79 supported fields 90
dns64 80 policy-selectors
layer 83 and 314
name-list 86 answer-address 314
name-node 88 calendar 314
policy 90 client-address 314
view-selector 112 client-address-is 314
or policy-selector 315 initial-qname 315
output not 315
cacheserve-dumpconf option 68 or 315
P qflag 315
performance tuning qname 315
limiting the number of TCP qname-is 315

connections 17 qname-prefix 316

340 Index
qtype 316 policy.changed 293
response-size 316 policy.delete 184
result 316 policy.get 184
server-address 316 policy.hit 293
type-exists-at-qname 317 policy.list 185
policy actions policy.mget 186
answer 310 policy.replace 188
answer-byname 310 policy.simulate 189
answer-byresolver 310 post-edits 74, 76, 78, 82, 87, 89, 91, 93, 100,
109, 111, 113, 115, 123-125, 131-133,
answer-noerror 310
141, 143, 148, 154-155, 166, 172-174,
answer-nxdomain 310 180, 182-183, 188, 191, 194, 200, 203,
210, 230, 242, 251, 262, 268, 272, 278-
answer-ttl 310
279, 281, 286-287
dns64 311
dns64-reverse 311
binding field 78
send-event 311
dns64 field 82
sort-addresses 312
name-list field 87
stop 312
name-node field 89
truncate 312
policy field 91
policy fields
action 90
resolver field 100
children 90
server field 108
errors 91
name 91
view field 111
post-edits 91
pre-edits 74, 76, 78, 82, 87, 89, 91, 93, 100,
pre-edits 91 109, 111, 113, 116, 123-125, 131-132,
134, 141, 143, 148, 154-155, 166, 172-
policy object 90
173, 175, 180, 182-183, 188, 192, 195,
policy.add 182 200, 204, 210, 230, 243, 251, 262, 268,

Index 341
272, 278-279, 281, 286-287 proactive-lookups 320
address-node field 76 proactive-lookups resolver statistic 320
binding field 78 product 270
dns64 field 82 provisioning
name-list field 87 faulted recovery 318
name-node field 89 layer field 85
policy field 91 provisioning-status 317
ratelimiter field 93 provisioning session 317
resolver field 100 provisioning statuses 317
server field 109 PRSD attacks See pseudo-random sub-

domain attacks
pseudo-random subdomain attacks 17
view field 111
PTR records
prefetch-ratio 100, 210, 230, 243
returning for RFC1918 addresses 105,
resolver field 100
215, 235, 247
prefix 82, 147, 153, 155
purpose-built amplification domains 46
dns64 field 82
Q
preload 100, 108, 211, 231, 243
q/cpusec 71
resolver field 100
qclass 255, 257
preload-nxdomain 101, 211, 231, 244
qflag policy-selector 315
resolver field 101
qname 255, 257
preload-nxrrset 101, 212, 231, 244
qname-case-randomization 101, 212, 232,
resolver field 101 244
priority resolver field 101
binding 78, 133, 141, 143 qname-case-randomization-
binding field 78 exclusions 102, 212, 232, 244
layer 85, 157, 163-164 resolver field 102
layer field 85 qname-is policy-selector 315

342 Index
qname-prefix policy-selector 316 R
qname policy-selector 315 ra header 306
qps 94, 195, 200, 204 rate-limited-requests 320-321
rate-limiting clients using 50 resolver statistic 320
ratelimiter field 94 server statistic 321
ratelimiter.abate 295 rate-limiting 21
ratelimiter.onset 297 ratelimiter
qr header 306 events 94
qtype 255, 257 fields 93
qtype policy-selector 316 ratelimiter fields
queries 320 bps 92
modeling 253 errors 92
queries resolver statistic 320 fields 93
query-name maximum-entries 93
ratelimiter.abate 295 name 93
ratelimiter.onset 297 post-edits 93
query-name-labels pre-edits 93
ratelimiter.abate 295 qps 94
ratelimiter.onset 298 unenforced 94
query-source-pool 102, 212, 232, 245 ratelimiter statistics
resolver field 102 all-indications 318
query-source-pool-v6 102, 213, 233, 245 current-entry-count 318
resolver field 102 current-limited-count 318
query-type expiring-entry-age 318
ratelimiter.abate 296 indications-by-bps 318
ratelimiter.onset 298 indications-by-qps 318
query‐name 93 uses 319

Index 343
ratelimiter.abate 294 creation-time 297
bps 294 entry-creation-time 297
client-network 294 fields 297
client-network-family 294 last-limited-time 297
client-network-mask-length 294 last-use-time 297
creation-time 295 name 297
entry-creation-time 295 qps 297
fields 295 query-name 297
last-limited-time 295 query-name-labels 298
last-use-time 295 query-type 298
name 295 unenforced 298
qps 295 ratelimiter.statistics 201
query-name 295 ratelimiter.update 202
query-name-labels 295 ratelimiters;ratelimiter 92
query-type 296 ratelimiting
unenforced 296 limit clients based on qps 50
ratelimiter.add 193 limit traffic based on size 51
ratelimiter.changed 296 managing amplification attacks 45
ratelimiter.delete 195 simple 43
ratelimiter.get 196 rcode 258
ratelimiter.list 196 rd header 306
ratelimiter.mget 198 rdataclass 319
ratelimiter.onset 296 recovering from faulted state 318
bps 296 recur cntxs 71
client-network 296 recursion-contexts-in-use 70, 321
client-network-family 296 recursion-contexts-in-use server

statistic 321
client-network-mask-length 297

344 Index
recursion contexts 17 forward 95
increasing 17 hints 96
recursive-lookups 320 ignore-first-referral 96
recursive-lookups resolver statistic 320 log-dnssec 96
REFUSED 306 log-id-spoofing 96
requests-no-view 321 log-lame 97
requests-no-view server statistic 321 managed-keys 97
requests-received 70, 322 managed-keys-state 98
requests-received server statistics 322 max-cache-size 98
requests-sent 70, 321-322 max-cache-ttl 98
resolver statistic 321 max-client-ttl 99
server statistic 322 max-edns-udp-size 99
reset 201, 236, 264 max-ncache-ttl 99
reset-time 202, 236, 264 max-tcp-recursions 99
resolutions 224 name 99
resolver 255, 258, 280, 285 negative-trust-anchors 100
events 105 post-edits 100
supported fields 95 pre-edits 100
updating managed-keys on 98, 208, prefetch-ratio 100

228, 240
preload 100
view-selector.query return 277
preload-nxdomain 101
resolver-statistics 319
preload-nxrrset 101
resolver commands
qname-case-randomization 101
resolver.mget 223
qname-case-randomization-
resolver fields exclusions 102
dnssec-aware 95 query-source-pool 102
errors 95 query-source-pool-v6 102

Index 345
rrset-order 103 resolver.inspect-delegation 220
server-address-lookup-order 103 resolver.mget 223
stub 104 resolver.recursing 224
synthesize-nxdomain 104 resolver.replace 225
trusted-keys 105 resolver.statistics 235
resolver statistics statistics 236, 265
cache-misses 320 resolver.update 237
dnssec-validations-failure 320 resolvers
dnssec-validations-insecure 320 retrieving delegation points from the

cache 220
retrieving names from the cache 217
response-size 258
ignored-referral-lookups 320
response-size policy-selector 316
lookups 320
response-time 258
proactive-lookups 320
response size
queries 320
rate-limit using 51
rate-limited-requests 320
responses-by-rcode 321
recursive-lookups 320
responses-by-rcode resolver statistic 321
requests-sent 321
responses-received 70, 322
responses-received server statistic 322
tcp-requests-sent 321
responses-sent 70, 322
resolver.add 204
responses-sent server statistic 322
resolver.changed 298
restart 248
resolver.delete 215
result 258
resolver.flush 216, 298
result policy-selector 316
resolver.get 217
retrieving data
address-list 117

346 Index
retrieving elements server-id 109, 251, 263, 268
address-lists 117 server field 109
retrieving multiple address-lists 121 server-start-time 202, 236, 264
RFC1918 addresses server-version 109, 251, 263, 269
returning PTR records for 105, 215, server field 109

235, 247
server commands
root
server fields
rrset-order 103, 213, 233, 246
commands-not-logged 106
resolver field 103
errors 106
S
listen-on-matching 106
log-command-channel 107
selector 183, 189, 192
max-recursive-clients 107
send-event policy action 311
max-tcp-clients 108
server
post-edits 108
binding 78, 134-136, 138, 140, 142, 144
pre-edits 109
server-id 109
server-version 109
time-zone 109
events 110
versioncheck-interval 109
layer 85, 158, 163, 165
server statistics
layer field 85
rate-limited-requests 321
server-address 255
recursion-contexts-in-use 321
requests-no-view 321
resolver field 103
requests-received 322
server-address policy-selector 316
requests-sent 322
responses-received 322

Index 347
responses-sent 322 SERVFAIL 306
tcp-clients 322 simple ratelimiting 43
tcp-requests-sent 322 sizeval 322
server.add 248 skip-first 119, 122, 128, 130, 138, 140, 151-
152, 160, 162, 169, 171, 178-179, 186-
187, 197, 199, 222, 224, 275-276, 283,
errors field and 74, 76-77, 81, 85, 87, 89, 285
91, 93, 95, 106, 111, 113, 205, 225,
sort-addresses policy action 312
238, 249, 266
source-address 113, 271-273, 277-279
server.block-checkpoints 252
server.changed 299
server.checkpoint 252
server.configuration-error 299
view-selector fields 113
server.formerr-loop 300
start-time 255
server.get 253
statistics
server.query 253
all-indications 318
client-address 254
cache-misses 320
edns-buffer-size 254
current-entry-count 318
edns-flags 254
current-limited-count 318
flags 254
current-time 201, 236, 264
force-resolution 254
dnssec-validations-failure 320
server.replace 260
dnssec-validations-insecure 320
server.restart 300
expiring-entry-age 318
server.stop 300
server.tcp-client-limit 300
ignored-referral-lookups 320
indications-by-bps 318
indications-by-qps 318
servers 221

348 Index
lookups 320 stop 269
memory-in-use 201, 236, 264 stop policy action 312
proactive-lookups 320 stub 104, 214, 221, 234, 246
queries 320 resolver field 104
rate-limited-requests 320-321 stubs
ratelimiter 201 using to return PTRs for RFC1918

addresses 105, 215, 235, 247
recursion-contexts-in-use 321
suffix 83, 148, 154, 156
recursive-lookups 320
dns64 field 82
requests-no-view 321
Supported 92
requests-received 322
Supported objects 61
requests-sent 321-322
synthesize-nxdomain 104, 215, 234, 247
reset-time 202, 236, 264
resolver field 104
resolver.statistics 236, 265
synthetic 221
sys %cpu 71
responses-received 322
syslog-facility
responses-sent 322
retrieving with cacheserve-stats 69
system-time 70, 202, 237, 265
server-start-time 202, 236, 264
T
system-time 202, 237, 265
tables 62
tcp-clients 322
configuration file example 62
tcp-requests-sent 321-322
definition of 62
user-time 202, 237, 265
tag 76, 89, 126, 131-132, 175, 181-182
uses 319
statmon-directory
name-node field 89
target 216
status
tcp 256
provisioning 317

Index 349
tcp-clients 322 definition of 62
tcp-clients server statistic 322 type-exists-at-qname policy-selector 317
tcp-requests-sent 321-322 types 219
server statistic 322 U
tcp-requests-sent resolver statistic 321 uint64 324

tcp clnts 71 unenforced 94, 195, 201, 204
TCP connections ratelimiter field 94
limiting the number of 17 ratelimiter.abate 296
tcp sent/s 71 ratelimiter.onset 298
testing DNS queries 253 unset 124, 132, 145-146, 156, 165, 173, 182,
192, 204, 248, 269, 280, 287
threshold-abate 323
uptime 71
threshold-duration 323
usage
threshold-onset 323
time-zone 109, 111, 251, 263, 269, 281,
286-287 user
server field 109 cacheserve process argument 58
view field 111 user-time 70, 202, 237, 265
timeout 252 uses 319
total %cpu 71 uses ratelimiter statistic 319
trace-messages 258 uuid 270
tracing 256 V
truncate policy action 312 validated 220
trusted-keys 105, 215, 235, 247 vendor 270
resolver field 105 version 270
ttl 219, 221 cacheserve-deleteconf option 69
tuples 62 cacheserve-dumpconf option 68
configuration file example 62 cacheserve-editconf option 64

350 Index
cacheserve-loadconf option 66 view-selector.delete 272
cacheserve process argument 59 view-selector.get 273
versioncheck-interval view-selector.list 274
server field 109 view-selector.mget 275
view 79, 113, 134-136, 138, 140, 142, 144, view-selector.query 276
256, 258, 271, 277, 280
resolver return 277
binding field 79
view-selector return 277
view return 277
events 111
view fields
errors 110
name 111
view-selector
post-edits 111
events 113
pre-edits 111
supported fields 112
time-zone 111
view.add 280
view-selector fields
view.changed 301
destination-address 112
view.delete 281
errors 112
view.get 282
post-edits 113
view.list 282
pre-edits 113
view.mget 284
source-address 113
view.replace 285
view 113
view.update 286
view-selector object 112
W
what's new
checkpointing 22

Index 351
Command Channel connections 22
error reporting 22
monitoring 22
when 79, 134, 142, 144
binding field 79
where cacheserve saves data
address-list dumps 117
YXDOMAIN 306
YXRRSET 306

Vantio-CacheServe-7 0 2

Caricato da

Informazioni sul documento

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Vantio-CacheServe-7 0 2

Caricato da

Copyright:

Formati disponibili

Vantio CacheServe

Version 7.0.2 October 6th, 2014

Centris, Navitas, and Vantio are trademarks of Nominum, Incorporated.

Caching name servers 13

A note about chroot() 13

What's in the manualhelp system 14

Chapter 2: Migrating from Vantio CacheServe 5 15

Chapter 3: Performance tuning 17

Limit the number of TCP connections 17

Increase the number of recursion contexts 17

Use a preferred system 18

Ramp up your network 18

Chapter 4: Differences between CacheServe and Vantio 21

Vantio CacheServe Administrator's Manual NOMINUM CONFIDENTIAL

Chapter 5: Controlling CacheServe with the Command Channel 29

Common Object Methods 31

The /etc/channel.conf file 33

Chapter 6: Basics of the CacheServe policy engine 35

Malicious domain redirection 39

Chapter 7: Simple rate-limiting 43

Chapter 8: Rate-limiting DNS amplification attacks 45

How DNS amplification attacks work 45

Characteristics of amplification attacks 45

Mitigating amplification attacks 45

Dealing with purpose-built amplification domains 46

Managing ANY queries 48

Managing dual-use domains 49

Vantio CacheServe Administrator's Manual NOMINUM CONFIDENTIAL

Rate-limiting amplification traffic 50

Chapter 9: ID spoofing attacks 53

How ID spoofing attacks work 53

How CacheServe defends against ID spoofing attacks 53

Important ID-spoofing-related CacheServe configuration parameters 54

Chapter 10: The cacheserve process 55

CacheServe service scripts 55

Chapter 11: The CacheServe utilities 61

The CacheServe configuration file format 62

NOMINUM CONFIDENTIAL Vantio CacheServe Administrator's Manual

Editing with cacheserve-editconf 63

Loading data with cacheserve-loadconf 65

Dumping data with cacheserve-dumpconf 66

Chapter 12: The CacheServe objects 73

Chapter 13: Command reference 115

Vantio CacheServe Administrator's Manual NOMINUM CONFIDENTIAL

NOMINUM CONFIDENTIAL Vantio CacheServe Administrator's Manual

Vantio CacheServe Administrator's Manual NOMINUM CONFIDENTIAL

About lame delegations 207

Be careful what you wish for 207

NOMINUM CONFIDENTIAL Vantio CacheServe Administrator's Manual

Vantio CacheServe Administrator's Manual NOMINUM CONFIDENTIAL

Chapter 14: Events reference 289

NOMINUM CONFIDENTIAL Vantio CacheServe Administrator's Manual

Chapter 15: Command Channel fields and types reference 303

Vantio CacheServe Administrator's Manual NOMINUM CONFIDENTIAL

NOMINUM CONFIDENTIAL Vantio CacheServe Administrator's Manual

Vantio CacheServe Administrator's Manual NOMINUM CONFIDENTIAL

Caching name servers

A note about chroot()

Vantio CacheServe Administrator's Manual NOMINUM CONFIDENTIAL

What's in the manualhelp system

l Quick-start configuration guides based on common CacheServe operations.

Vantio CacheServe Administrator's Manual NOMINUM CONFIDENTIAL

1. Disable or remove any automatic startup processes for Vantio.

3. Import the dumped Vantio data into the CacheServe database: