Vantio CacheServe 7.2.0 Administrators Manual 20161208 PDF

Vantio CacheServe
Administrator's Manual
December 8, 2016 7.2.0
Copyright ©2002-2017 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
800 Bridge Parkway
Suite 100
Redwood City, CA 94065
USA
http://www.nominum.com
Centris, Navitas, and Vantio are trademarks of Nominum, Incorporated.

Table of Contents
Table of Contents 2
Chapter 1: Introduction 44
Caching name servers 44
About N2 Connect 44
High performance 45
What's in the manual 45
Chapter 2: Getting started with CacheServe 46
The elements of CacheServe 46
Removing the default view-selector 47
In more detail 47
Chapter 3: CacheServe configuration object quick reference 50
action 50
address-list 50
address-node 50
auth-monitoring 51
auth-server-list 51
auth-server-node 51
auth-server-node 51
2 NOMINUM CONFIDENTIAL
3 Table of Contents
binding 51
connection 52
device-list 52
device-node 52
dns64 52
layer 53
monitoring 53
Core domain tagging 53
name-group 54
name-list 54
name-node 54
policy 54
ratelimiter 55
resolver 55
selector 55
server 55
telemetry 55
view 56
view-selector 56
Chapter 4: Controlling CacheServe with the Command Channel 58
Engine Interaction 58
Command Channel Basics 58
Basic Command Channel Messages 59
Common Object Methods 60
add 60
delete 60
get 60
Vantio CacheServe Administrator's Manual NOMINUM CONFIDENTIAL

Table of Contents 4
list 60
mget 60
replace 61
Updating objects 61
+/Append 61
-/Remove 61
List and Table Slicing 61
The nom-tell Command Channel Client 61
Interactive Mode 62
From the Command Line 62
Retaining History for nom-tell 63
The /etc/channel.conf file 63
Chapter 5: Connecting CacheServe to other Nominum products 66
Policy Manager 66
Kafka 67
A note about leaders 67
The statmon utility 67
Creating a monitoring querystore 68
Creating an authoritative querystore 68
Chapter 6: General operations 70
Unexpected open resolver 70
Monitoring CPU usage 70
The details 70
In summary 71
What it all means 71
Performance tuning 71
Use a recommended OS 71
NOMINUM CONFIDENTIAL Vantio CacheServe Administrator's Manual

5 Table of Contents
Ramp up your network 72
Process tuning 72
Limit the number of TCP connections 72
Increase the number of recursion contexts 72
Configuring authoritative servers 72
Backing up and restoring 73
Backing up CacheServe and querystores 73
Restoring from a backup 74
Chapter 7: The CacheServe policy engine 76
NXDOMAIN redirection 76
Create the NXDOMAIN policy 77
Add an NXDOMAIN action 77
Make NXDOMAIN redirection lists 78
Make an NXDOMAIN policy selector 79
Bind the NXDOMAIN policy to a view 80
Malicious domain redirection 80
Create the malicious redirection policy 81
Add a malicious redirection action 81
Make malicious redirection lists 82
Make a malicious redirection policy selector 82
Bind the malicious redirection policy to a view 83
Chapter 8: Ratelimiting 84
Simple rate-limiting 84
In CacheServe 5 84
In CacheServe 7 84
Rate-limiting DNS amplification attacks 85
How DNS amplification attacks work 85

Table of Contents 6
Characteristics of amplification attacks 85
Mitigating amplification attacks 85
Dealing with purpose-built amplification domains 86
Managing ANY queries 89
Managing dual-use domains 89
Rate-limiting amplification traffic 90
Chapter 9: Defending against DDoS attacks using prefetch extensions 92
Defending against DDoS attacks on authoritative servers 92
The CacheServe prefetch mechanism 93
Prefetch extension 93
Extension entries 93
Configuring prefetch extension 94
Prefetch extension statistics 94
Extended caching and DNSSEC 95
Prioritized prefetch domains 95
How it works 95
Configuration 95
Statistics 96
Chapter 10: ID spoofing attacks 98
How ID spoofing attacks work 98
Defending against ID spoofing attacks 98
Settings related to ID spoofing 99
Statistics and events 99
Caveats 99
Chapter 11: Aggregation with client-subnet 100
Client equivalency 100
Background 101

7 Table of Contents
Overly specific authoritative answers 101
Unpredictably assigned subnets 101
Configuring client equivalency 102
Manually setting representative addresses 103
Chapter 12: SNMP 104
Supported SNMP versions 104
SNMP Concepts and Architecture 104
Managers 104
Agents 105
MIBs 105
GET Messages 105
Traps (Notifications) 105
General Notes on SNMP for Nominum Products 105
snmpagent 106
Synopsis 106
Options 106
Configuration Files 107
Agent Configuration Information 107
Nominum MIBs 108
Using SNMP with Vantio CacheServe 109
Running as a Subagent 109
Running as a Master Agent 110
The snmpagent Configuration File 111
Driver-Specific Configuration Options 114
Using the Command Channel with snmpagent 115
Using Net-SNMP Command-line Tools with snmpagent 117
Chapter 13: The cacheserve process 122

Table of Contents 8
CacheServe process command-line options 122
--channel 122
-c, --configuration 122
--directory 122
--dns-port 123
--fd-limit 123
-F, --foreground-with-syslog 123
-f, --foreground 123
-h, --help 123
--license 124
--no-statmon 124
-r, --root 124
--statmon-directory 124
-s, --syslog-facility 124
--tcp-acl 125
--udp-acl 125
--usage 125
-u, --user 125
-v, --version 125
Chapter 14: The CacheServe utilities 128
Supported objects 128
The CacheServe configuration file format 131
cacheserve-deleteconf 132
Two ways to edit 132
How it works 132
cacheserve-deleteconf options 132
cacheserve-dumpconf 134

9 Table of Contents
Two ways to retrieve data 134
How it works 134
cacheserve-dumpconf options 134
cacheserve-editconf 136
Two ways to edit 136
How it works 136
cacheserve-editconf options 136
cacheserve-loadconf 138
Two ways to load data 138
How it works 138
Configuration checking limitations 138
cacheserve-stats 140
Options 140
Statistics 142
Chapter 15: CacheServe configuration object expanded reference 144
action 144
Commands 144
Supported Fields 145
Events 146
address-list 146
Commands 146
Events 149
address-node 149
Events 151
auth-server-list 151

Table of Contents 10
Commands 151
Events 153
auth-server-node 153
Commands 153
Events 155
binding 155
Events 158
connection 158
device-list 159
Commands 159
Events 161
device-node 161
Events 163
dns64 163
Events 166
layer 166
Layers and Provisioning 167
Events 169
name-group 170

11 Table of Contents
Events 172
name-list 172
Events 173
name-node 174
Events 175
policy 175
Events 178
ratelimiter 178
Events 180
resolver 180
Events 194
selector 195
Events 196
server 197
Events 202
telemetry 202
Events 204
view 204

Events 206
view-selector 206
Events 209
Chapter 16: Command reference 210
action.add 210
Description and usage 210
Fields 210
Examples 211
action.count 211
Fields 211
Returns 211
action.delete 211
Fields 212
Examples 212
action.get 212
Fields 212
Examples 213
action.list 213
Fields 213
Examples 214
action.mget 215

Fields 215
Examples 216
action.replace 216
Fields 217
action.update 218
Examples 219
address-list.add 219
Fields 219
Examples 221
address-list.delete 221
Fields 221
Examples 221
address-list.dump 221
Fields 222
Examples 222
address-list.get 222
Fields 222
Examples 223
address-list.list 223

Fields 223
Examples 224
address-list.load 225
Fields 225
Examples 226
address-list.mget 226
Fields 226
Examples 227
address-list.replace 228
Fields 228
address-list.update 229
Examples 231
address-node.add 231
Fields 231
address-node.delete 232
Fields 232
address-node.get 233
Fields 233
address-node.list 234

Fields 234
address-node.mget 235
Fields 235
address-node.replace 236
Fields 236
address-node.update 237
Fields 238
auth-server-list.add 239
Fields 239
auth-server-list.delete 240
Fields 240
Examples 241
auth-server-list.get 241
Fields 241
Examples 242
auth-server-list.list 242
Fields 242
Examples 243
auth-server-list.mget 243

Fields 243
Examples 245
auth-server-list.replace 245
Fields 245
auth-server-list.update 246
Examples 247
auth-server-node.add 248
Fields 248
Examples 250
auth-server-node.delete 250
Fields 250
Examples 250
auth-server-node.get 251
Fields 251
auth-server-node.list 252
Fields 252
auth-server-node.mget 253
Fields 253
auth-server-node.replace 255

Fields 255
auth-server-node.update 257
binding.add 259
Fields 259
binding.delete 261
Fields 261
binding.get 262
Fields 262
binding.list 263
Fields 263
binding.mget 265
Fields 265
binding.replace 266
Fields 267
binding.update 269
Fields 269
connection.get 271
Fields 271

connection.replace 272
Fields 272
connection.subscribe-all 272
connection.update 272
Fields 272
device-list.add 273
Fields 273
Examples 274
device-list.count 274
Fields 274
Returns 275
device-list.delete 275
Fields 275
Examples 275
device-list.get 275
Fields 276
Examples 276
device-list.list 276
Fields 277
Examples 278

device-list.mget 278
Fields 278
Examples 279
device-list.replace 280
Fields 280
device-list.update 281
Examples 282
device-node.add 282
Fields 282
device-node.count 283
Fields 283
Returns 284
device-node.delete 284
Fields 284
Examples 285
device-node.get 285
Fields 285
device-node.list 286
Fields 286

Returns 287
device-node.mget 288
Fields 288
device-node.replace 290
Fields 290
device-node.update 291
Fields 291
dns64.add 292
Fields 292
dns64.delete 294
Fields 294
dns64.get 295
Fields 295
dns64.list 295
Fields 296
dns64.mget 297
Fields 297
dns64.replace 299

Fields 299
dns64.update 301
Fields 301
instance-information 303
Returns 303
layer.add 303
Fields 303
Examples 305
layer.clear-fault 305
Fields 305
layer.delete 305
Fields 306
layer.get 306
Fields 306
layer.list 306
Fields 307
layer.mget 308
Fields 308
layer.reimage 309

Fields 309
layer.replace 309
Fields 310
layer.update 311
Fields 311
name-group.add 313
Fields 313
name-group.count 314
Fields 314
Returns 314
name-group.delete 314
Fields 314
Examples 315
name-group.get 315
Fields 315
Examples 316
name-group.list 316
Fields 316
Examples 317

name-group.mget 317
Fields 317
Examples 319
name-group.replace 319
Fields 319
name-group.update 320
Examples 322
name-list.add 322
Fields 322
name-list.delete 323
Fields 323
name-list.dump 323
Fields 324
name-list.get 324
Fields 324
name-list.list 325
Fields 325
name-list.load 326

Fields 327
Examples 327
name-list.mget 327
Fields 327
name-list.replace 329
Fields 329
name-list.update 330
Fields 330
name-node.add 331
Fields 331
name-node.delete 332
Fields 332
name-node.get 333
Fields 333
name-node.list 334
Fields 334
name-node.mget 336
Fields 336
name-node.replace 338

Fields 338
name-node.update 339
Fields 339
policy.add 341
Fields 341
policy.delete 343
Fields 343
policy.get 343
Fields 343
policy.list 344
Fields 344
policy.mget 345
Fields 345
policy.replace 347
Field 347
policy.simulate 349
Fields 349
Returns 350

policy.update 350
Fields 351
Examples 352
process-information 352
Returns 353
ratelimiter.add 354
Fields 354
ratelimiter.delete 356
Fields 356
ratelimiter.get 356
Fields 356
ratelimiter.list 357
Fields 357
ratelimiter.mget 358
Fields 359
ratelimiter.limited 360
Fields 360
ratelimiter.replace 362

Fields 363
ratelimiter.statistics 364
Fields 365
Returns 365
ratelimiter.update 366
Fields 366
resolver.add 368
Fields 369
How we determined the default value 376
resolver.delete 381
Fields 381
resolver.flush 381
Fields 381
resolver.get 382
Fields 382
resolver.inspect 382
Fields 383
Returns 383
resolver.inspect-delegation 386

Fields 386
Returns 387
resolver.inspect-forwarders 388
Fields 388
Returns 388
resolver.list 389
Fields 389
resolver.mget 390
Fields 390
resolver.recursing 392
Fields 392
Returns 392
resolver.replace 392
Fields 392
resolver.statistics 404
Fields 404
Returns 404
resolver.update 406
Fields 406
restart 417
selector.add 418
Fields 418

selector.delete 419
Fields 419
selector.get 420
Fields 420
selector.list 420
Fields 420
Returns 422
selector.mget 422
Fields 422
selector.replace 423
Fields 424
selector.update 425
Fields 425
server.add 426
Fields 426
server.all-errors 431
Fields 431
server.block-checkpoints 431
Fields 431

server.checkpoint 431
server.delete 431
Fields 431
server.get 432
Fields 432
server.query 432
Fields 433
Returns 435
Example 438
Example (N2 environment) 439
server.replace 440
Fields 440
server.statistics 445
Fields 445
Returns 445
Example 446
server.unblock-checkpoints 447
server.usage 447
Returns 447
server.update 448
Fields 448

stop 453
telemetry.get 453
Fields 453
telemetry.replace 453
Fields 453
telemetry.statistics 455
Fields 455
Returns 455
Example 456
telemetry.update 457
Fields 457
uuid 458
version 458
Returns 459
view-selector.add 459
Fields 460
view-selector.delete 461
Fields 461
view-selector.get 461
Fields 461

view-selector.list 462
Fields 462
Returns 463
view-selector.mget 464
Fields 464
view-selector.query 465
Fields 465
Returns 466
view-selector.replace 466
Fields 466
Fields 467
view-selector.update 469
Fields 469
view.add 470
Fields 470
view.delete 471
Fields 471
view.get 472

Fields 472
view.list 473
Fields 473
view.mget 473
Fields 474
view.replace 475
Fields 475
view.update 476
Fields 476
Chapter 17: Events reference 480
action.changed 480
Returns 480
address-list.changed 480
Returns 480
address-node.changed 480
Returns 481
auth-monitoring.changed 481
auth-server-list.changed 481
Returns 481
auth-server-node.changed 481
Returns 481
binding.changed 482

Returns 482
dns64.changed 482
Returns 482
layer.changed 482
Returns 482
layer.provisioning-connected 483
Returns 483
layer.provisioning-connection-failure 483
Returns 483
layer.provisioning-disconnected 483
Returns 483
layer.provisioning-reimaging 484
Returns 484
layer.provisioning-update-failure 484
Returns 484
layer.provisioning-update-success 484
monitoring.changed 484
name-group.changed 485
Returns 485
name-list.changed 485
Returns 485
name-node.changed 485
Returns 485
policy.changed 485
Returns 486
policy.hit 486
Returns 486

ratelimiter.abate 486
Returns 487
ratelimiter.changed 488
Returns 488
ratelimiter.onset 489
Returns 489
resolver.changed 490
Returns 491
resolver.flush 491
Returns 491
resolver.id-spoofing-suspected 491
Returns 491
selector.changed 492
Returns 492
server.changed 492
server.configuration-error 492
Returns 492
server.formerr-loop 492
Returns 492
server.restart 493
server.stop 493
server.tcp-client-limit 493
server.udp-recursion-limit 493
telemetry.changed 493
view-selector.changed 493
Returns 493
view.changed 494

Returns 494
Chapter 18: Command Channel fields and types reference 496
ACLs 496
acl-element 496
acl-element4 497
acl-element6 497
addr 497
addr-or-name 497
addr4 497
addr6 497
addrpat 497
addrpat4 498
addrpat6 498
addrport 498
addrport4 498
addrport6 498
addrport-or-name 498
addrrange 498
anonymization-key-file-path 498
boolean 499
dns-flag 499
dns-rcode 499
edns-flag 500
event-name 500
float-seconds-since-epoch 501
inspect-delegation-servers 501
integer 501

ipv4netlen 501
ipv6netlen 502
kafka-configuration-field 502
brokers 502
global-properties 502
partition 503
topic 503
topic-properties 503
monitor-log-switch 503
monitoring-statistics 504
messages-delivered 504
messages-dropped 504
messages-produced 504
queue-full 504
records-delivered 504
records-dropped 505
records-not-produced 505
records-produced 505
name 505
name-empty-ok 505
name-label-count 505
policy-action 505
('annotate (string, string)) 506
('answer' ((rdatatype, rdata) ...)) 506
('answer-by' ((variable | name) resolver))) 507
('answer-byname' name) 507
('answer-byresolver' string) 507

('answer-cname' string) 507
'answer-noerror' 508
'answer-nxdomain' 508
('answer-ttl' (((rdatatype, rdata) ...), ttl)) 508
('assign' (string name)) 508
('dns64' string) 508
('dns64-reverse' string) 509
'drop' 509
'fail' 509
'no-op' 509
'refuse' 509
'send-event' 509
('sort-addresses' ((string ...), boolean)) 509
'stop' 510
'truncate' 510
policy-calendar-selector 510
policy-result-type 511
policy-selector 511
('and' (policy-selector ...)) 512
('answer-address' string) 512
('calendar' (policy-calendar-selector ...)) 512
('client-address' string) 512
('client-address-is' (acl-element ...)) 513
('destination-address' string) 513
('destination-address-is' (acl-element ...)) 513
('device' (string) 513
('device-group' (string ...)) 513

('device-id' string) 513
'initial-qname' 514
('named-selector' string) 514
('not' (policy-selector)) 514
('or' (policy-selector ...)) 514
('qclass' (rdataclass ...)) 514
('qflag' 'AD' | 'CD' | 'DO' | 'EDNS' | 'RD') 514
('qname' (string, 'exact' | 'exact-or-www' | 'subdomain')) 514
('qname-in-group' string) 515
('qname-is' (name, 'exact' | 'exact-or-www' | 'proper-subdomain' | 'subdomain')) 515
('qname-prefix' string) 515
('qtype' (rdatatype ...)) 516
('ratelimiter' string) 516
('response-size' uint16) 516
('result' (policy-result-type ...)) 516
('server-address' string) 516
('synthesized') 516
('type-exists-at-qname' rdatatype) 516
port-mask 517
positive-integer 517
provisioning-status 517
Status values 517
How provisioning usually goes 518
ratelimiter-statistics 518
all-indications 518
current-entry-count 518
current-limited-count 518

expiring-entry-age 518
indications-by-bps 518
indications-by-qps 519
uses 519
rdata 519
rdataclass 519
rdatatype 519
report-max-memory-arg 519
resolver-statistics 519
active-recursions 520
cache-misses 520
dnssec-validations-failure 520
dnssec-validations-insecure 520
dnssec-validations-success 520
dropped-recursions 520
id-spoofing-defense-queries 520
ignored-referral-lookups 520
interrupted-before-recursion 521
interrupted-recursion-waits 521
interrupted-recursions 521
lookups 521
proactive-lookups 521
queries 521
queued-prefetches 521
rate-limited-requests 521
recursive-lookups 521
requests-sent 522

responses-by-rcode 522
tcp-requests-sent 522
seconds-since-epoch 522
server-statistics 522
formerr-loop-dropped 522
lookups 523
malformed-requests-dropped 523
recursion-contexts-in-use 523
requests-no-view 523
requests-received 523
requests-sent 523
responses-received 523
responses-sent 523
suppressed-duplicate-queries 524
tcp-clients 524
tcp-connections-accepted 524
tcp-connections-rejected 524
sizeval 524
std-layered-edit-operation 524
string 525
string-empty-ok 525
telemetry-statistics 525

queue-full 525
records-dropped 526
threshold-abate 526
threshold-duration 526
threshold-onset 526
time-in-microseconds 526
time-in-seconds 526
ttl 527
uint16 527
uint64 527
unparsed 527
uuid 527
versioncheck-days 527
Appendix A: Migrating from Vantio CacheServe 5 528
Migration guidelines 528
Migration procedure 528
A note about chroot() 529
Appendix B: Differences between CacheServe 5 and CacheServe 7 530
General changes 530
Server object 531
Resolver and view objects 531
DNS64 objects 533
Statistics 533
Command channel 533

Policies and bindings (including LVP) 533
Database 534
Monitoring 534
Ratelimiting 534
Index 536

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
AuthServe (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).
About N2 Connect
The N2 Connect version of CacheServe is a restricted-function CacheServe implementation
that eliminates recursion, causing CacheServe to operate only as a forwarding server.
The following CacheServe settings are available but have no effect in N2 Connect:
l auth-server-list
l hints
l ignore-first-referral
l log-lame
l stub
If you are interested in these features, upgrade to a full CacheServe license by contacting
your Nominum salesperson.
45 High performance
High performance
Vantio CacheServe has been engineered to make the most efficient use of modern, multi-
core servers. In testing environments, CacheServe has performed at 2,000,000 queries per
second.
We have put together some performance tuning guidelines to help you take advantage of
CacheServe's capabilities.
What's in the manual

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: Getting started
with CacheServe
Upon installation, Vantio CacheServe creates a very basic initial configuration.
The initial configuration configures CacheServe such that:
l Any client may send queries to CacheServe.

l CacheServe will resolve those queries and return an answer to the client.
The elements of CacheServe

The initial configuration contains the following elements:
l The auth-monitoring object: Objects represent configuration elements in CacheServe.

The auth-monitoring object represents the monitoring system for any authoritative
servers that CacheServe knows about.
l The operator layer: Layers represent sets of CacheServe configuration information
that can be "overlaid" on the basic CacheServe configuration. The "operator" layer is
reserved for critical CacheServe functions, and is the foundational layer upon which
every other layer is overlaid.
l The monitoring object: Like the auth-monitoring object, the monitoring object rep-
resents the monitoring system.
l The world resolver: Resolvers represent a DNS cache and a set of properties related to
DNS resolution. There can be more than one resolver, which allows you to create cus-
tomized DNS environments.
l The server object: A server represents a subset of CacheServe configuration that
applies to the server as a whole. If you change a server object, you affect all other con-
figuration elements within the scope of that server's influence.
l The world view: A view represents a customizable DNS namespace.
47 Removing the default view-selector
l The world view-selector: view-selectors map DNS requests to views based on teh
source and destination addresses of the request.
Removing the default view-selector

CacheServe's initial configuration includes a Resolver called "world" along with a view
called "world" and a view-selector directing all clients to the "world" view. If you are
operating CacheServe in a configuration where there's no load balancer or firewall, this
default configuration can create an open resolver.
To remove the default view-selector and view:
1. Remove the default view-selector:

shell# nom-tell cacheserve
cacheserve> view-selector.delete
2. Remove the "world" view:

cacheserve> view.delete name=world
In more detail
The initial configuration consists of the following elements (shown as the annotated output
of cacheserve-dumpconf):
{
object => "auth-monitoring"
}
This indicates that an auth-monitoring object has been created to represent the
"authoritative monitoring" functions in CacheServe. These functions are managed entirely
by the Nominum statmon utility, but there are minor configuration steps you need to take.
See "creating an authoritative querystore".
{
object => "layer"
priority => "0"
name => "operator"
}
This section indicates that an initial layer called operator has been created, with a priority of
0.

In more detail 48
In general, the operator layer is where CacheServe performs all operations on

configuration objects, and stores all configuration data that goes along with those
operations.
In most cases, you will use additional layers for things like provisioned data (if you are
using CacheServe with a Policy Manager server: see Connecting CacheServe to other
Nominum products), or user-configurable data.
For more information about layers, see the layer object overview.
{
object => "monitoring"
}
As with the auth-monitoring object, this indicates that a monitoring object has been created
to represent the "monitoring" functions in CacheServe. These functions are managed
entirely by the Nominum statmon utility, but there are minor configuration steps you need
to take. See "creating a monitoring querystore".
{
object => "resolver"
name => "world"
}
This indicates that CacheServe has created an initial resolver object, called world.
You will notice that this resolver object has almost no configuration except its name; if you
are unfamiliar with resolver capabilities, the resolver object section is a good starting place.
Resolvers do the heavy lifting in CacheServe, with almost all of the DNS operations
occurring within the context of a resolver.
Furthermore, more than one resolver may be configured, which gives you the ability to
create multiple fully customized DNS environments.
{
object => "server"
}
This indicates that a server object has been created; this is CacheServe's internal
representation of itself, and is important for managing the server's behavior. For more
detail, see the server object.
{
object => "view"

49 In more detail
resolver => "world"

name => "world"
}
This section defines a view named world; you will notice that it refers to the world resolver.
Views represent a customizable DNS namespace, which is particularly helpful when you
start to get into things like policies. Each view has an associated resolver, which makes it
possible to customize the entire resolution chain.
For example, using views (and view-selectors), you can configure CacheServe such that
certain clients "see" different DNS results depending on criteria you define.
For more information on views, see the view object overview.
{
object => "view-selector"
view => "world"
}
View-selectors map DNS requests to specific views depending on the source and
destination of the request. As previously mentioned, view-selectors are particularly
important when working with things like policies, and when you are interested in directing
certain subsets of your customers towards a tailored result.

Chapter 3: CacheServe con-
figuration object quick ref-
erence
CacheServe uses configuration objects to contain its configuration.
This quick reference provides very basic summaries of each object.
The expanded reference section includes the commands, supported fields, and supported
events for each object.
action
actions specify actions that may be referenced by name from other actions.
Full reference material, including commands, supported fields and events, is found in the
action expanded reference.
address-list
address-lists contain nodes that represent addresses and networks. The contents of
address-lists are made up of address-nodes.
address-list expanded reference.
address-node
address-nodes represent all data associated with a single network in an address-list.
51 auth-monitoring
Full reference material, including commands, supported fields, and supported events, is
located in the address-node expanded reference.
auth-monitoring
The auth-monitoring object represents the authoritative monitoring system in CacheServe.
To use this object, you need to configure a query store as described in Connecting
CacheServe to other Nominum products; additional details beyond that are covered in the
Nominum monitoring manuals: Monitoring Query and Request Data on Nominum Engines and
Nominum statmon Utility and Query Store Command Reference.
Note: Changes to monitoring cause CacheServe to restart.
auth-server-list
Note: Has no effect in N2 Connect.
auth-server-lists contain nodes that represent authoritative servers. The contents of auth-
server-lists are made up of auth-server-nodes.
auth-server-list expanded reference.
auth-server-node
auth-server-nodes represent authoritative name servers. auth-server-nodes are used in
auth-server-lists.
auth-server-node expanded reference.
auth-server-node
auth-server-nodes represent authoritative name servers. auth-server-nodes are used in
auth-server-lists.
auth-server-node expanded reference.
binding
bindings represent bindings between policies and the server or views.

connection 52
located in the binding expanded reference.
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.
located in the connection expanded reference.
device-list
device-lists contain nodes that represent device identifiers, and are used in the "device"
policy-selector. The contents of device-lists are made up of device-nodes.
device-list expanded reference.
device-node
device-nodes represent device identifiers. Each device-node contains a device identifier and
an associated view. device-nodes are aggregated into device-lists, which are used in policy
selectors.
located in the device-node expanded reference.
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.
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.

53 layer
located in the dns64 expanded reference.
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.
located in the layer expanded reference.
monitoring
The monitoring object supports statistical processing, and interacts with the Nominum
statmon utility.
To use this object, you need to configure a query store as described in Connecting
CacheServe to other Nominum products; additional details beyond that are covered in the
Core domain tagging

For analytics operations, it's important to know the core domain of a query: this makes it
easier to aggregate information.
The core domain is the name one label deeper than the public suffix of the name: for
example, the core domain for www.nominum.com, the core domain is nominum.com, and
the public suffix is com.
CacheServe computes the core domain depth for a query and writes it to the base
monitoring stream. In most cases, CacheServe will compute the depth when it processes a
cache miss, and will store the depth in the cache entry. For synthesized answers,
CacheServe will compute the depth on an as-needed basis.

name-group 54
name-group
A name-group is a collection of name-lists and other name-groups. name-groups are used
in the "qname-in-group" policy-selector.
located in the name-group expanded reference.
name-list
name-lists contain nodes that represent DNS names. The contents of name-lists are made
up of name-nodes.
located in the name-list expanded reference.
name-node
name-nodes represent all data associated with a single name in an name-list.
located in the name-node expanded reference.
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 policy-selector, which determines whether or not the policy should be applied to a

query.
l A policy-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.
located in the policy expanded reference.

55 ratelimiter
ratelimiter
ratelimiters constrain traffic; they use query or response fields to group queries into
buckets, and apply limits to those buckets.
located in the ratelimiter expanded reference.
resolver
resolvers represent a DNS cache and a set of properties related to DNS resolution.
More than one resolver may be configured, which permits you to create customized DNS
environments.
located in the resolver expanded reference.
selector
selectors map DNS requests to views based on the source and destination addresses of the
request.
located in the selector expanded reference.
server
servers represent a subset of CacheServe configuration that applies to the server as a
whole. Changes made to a server will affect all other configuration elements within the
scope of that server's influence.
located in the server expanded reference.
telemetry
The telemetry object periodically writes engine samples and events into Kafka.
located in the telemetry expanded reference.

view 56
view
views represent a customizable DNS namespace.
located in the view expanded reference.
view-selector
view-selectors map DNS requests to views based on the source and destination addresses
of the request.
located in the view-selector expanded reference.

57 view-selector

Chapter 4: Controlling
CacheServe with the Com-
mand Channel
Engine Interaction
The primary means of interacting with Vantio CacheServe is through the Nominum
Command Channel protocol.
Command Channel Basics

The Nominum Command Channel (CC) is a protocol used to send specially-formatted
messages (most often commands or configuration settings) to a Nominum product, either
from a command-line interface or using a script.
All Nominum-products that use the Command Channel ship with a 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.
59 Basic Command Channel Messages
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.
Command Usage
stop Shuts down the server
version Retrieves version information for the server

Common Object Methods 60
Command Usage
instance-information Retrieves instance id
process-information Retrieves process information for the server, includ-

ing licensing, working directory, process id, and sys-
tem time
Common Object Methods

Nominum products use an object-based architecture, where configuration elements are
represented by software objects within the server.
For example, the Nominum CacheServe nameserver represents parts of the server's
configuration with a server object.
The following methods can be used with most, but not necessarily all, top-level server
configuration 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.

61 replace
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.
Updating objects
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.
-/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)
The nom-tell Command Channel Client

All Nominum products that use the Nominum Command Channel protocol ship with the
nom-tell Command Channel client. nom-tell provides a command-line interface for the
Command Channel connection.
nom-tell is located in /usr/local/nom/sbin, and you may find it convenient to add that
location to your PATH.

Interactive Mode 62
All of the examples in this manual use nom-tell in its interactive mode, which is the
preferred way to send Command Channel messages to a Nominum engine.
Interactive Mode
nom-tell's interactive mode creates a persistent Command Channel session, and is by far
the best option for communicating with a Nominum product.
Using nom-tell in interactive mode has several advantages over using nom-tell from the
command line:
l In interactive mode, nom-tell returns to the interactive prompt (rather than exiting to
the OS shell) after Command Channel responses are received.
l Interactive nom-tell features tab completion of commands, which is particularly use-
ful with complex operations.
l Interactive nom-tell features much simpler list formatting.
To enter nom-tell interactive mode, send a nom-tell command from the OS's command line
with only an engine or service name specified:
# nom-tell <product>
product>
Note: If you leave your nom-tell interactive mode window idle for a few minutes, you may
receive a message that the connection has been closed.
This is normal behavior: the next nom-tell command you send will automatically reopen
the connection.
From the Command Line

Although you'll mostly use nom-tell in interactive mode, there may be times when you want
to quickly send a nom-tell command from the OS's command line. To do so, use the
format:
# nom-tell service_name command [ parameters ]
For example, to send a version command:

# nom-tell <product> version
When you're using nom-tell from the command-line, and you need to send list parameters,
you'll need to enclose each entry in the list in quotation marks. This allows the target to
correctly parse the command.

63 Retaining History for nom-tell
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.
If you find this feature useful, you may want to 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 or processes that use the
Nominum Command Channel protocol.
This is very useful for cases where a Nominum product needs to establish multiple
separate Command Channel connections.
The channel.conf file translates a service name into a location (a host and a port), and
identifies a 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. A secret
of * is interpreted as no secret.
l Optional properties—Each optional property is a key-value pair of the form key=value.

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

The /etc/channel.conf file 64
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 pbZmkTJ-
prEOCLNd9DfIlChUs2EBT5ShcuirylKpD2VSsaPiF

65 The /etc/channel.conf file

Chapter 5: Connecting
CacheServe to other
Nominum products
If you are running Vantio CacheServe in conjunction with other Nominum products, you
may need some extra configuration.
Note: A full explanation of the capacities of the Nominum products listed is beyond the
scope of this manual; please consult the references for the listed products for anything
beyond the basic steps needed to connect them to CacheServe.
Policy Manager
To configure Vantio CacheServe for use with the policy and provisioning servers of
Nominum Policy Manager:
1. On the Policy Manager server, ensure that the provisioning server is listening on all
interfaces.
If you have not already done so, edit the /etc/channel.conf file to contain the following
line:
nom-ccpserver-data 0.0.0.0#16002 secret
2. Ensure that the CacheServe time zone is correct:

cacheserve> server.update time-zone=time-zone-string
67 Kafka
3. Add a provisioning layer to CacheServe. This provisioning layer will cause CacheServe
to retrieve all provisioning information from the Policy Manager's provisioning
server.
For the provisioning-hostname and secret values, use the address of the Policy Man-
ager's provisioning server, and the secret used by the nom-ccpserver-data service on
the Policy Manager server:
cacheserve> layer.add name=pm priority=1 server=(provisioning-
hostname 16002 secret)
Kafka
Nominum products use customized versions of two open-source scaling technologies:
Zookeeper and Kafka. Together, Zookeeper and Kafka provide a durable reporting
architecture for Nominum products.
CacheServe, when being used as part of an N2 solution "stack", connects to Kafka via the
telemetry object.
The telemetry object, including Kafka-related options, is generally documented in this

manual; for specific guidance on connecting CacheServe to N2 products, see the
appropriate N2 product manual.
A note about leaders

Although the mechanics of Kafka leadership and cluster configuration are beyond the
scope of this manual, you may occasionally see a reference to a Kafka "leader".
This refers to the fact that Kafka instances (brokers) are deployed in clusters of 3 or more. In
these clusters, a given Kafka broker may at any time be considered the "leader" for the
brokers in that cluster; in basic terms, the broker currently responsible for organizing the
cluster.
The statmon utility

The Nominum statmon utility may be installed with Vantio CacheServe; if installed, it will
automatically configure a service listener, and Vantio CacheServe creates both auth-
monitoring and monitoring objects to represent it.

Creating a monitoring querystore 68
Note: For detailed information about the use of the auth-monitoring and monitoring
objects, and about monitoring in CacheServe, please consult the Nominum monitoring
manuals: Monitoring Query and Request Data on Nominum Engines and Nominum statmon
Utility and Query Store Command Reference.
Creating a monitoring querystore

Before making use of statmon, you will need to configure a basic query store.
1. Check the /etc/channel.conf file to ensure that there's an entry for statmon. It should
look something like:
statmon 9994 CRaLf7m/rgKHUAd+vZrgQFZM8wCY88tdX3lpRJLDGQSV//
2. Instantiate the query store in CacheServe.
The following command creates a query store in which the query logfile is located in
/var/log, query search results are anonymized, log entries are cached for a maximum
of 2 days, and the maximum size of the query store is capped at 100 MB:
cacheserve> monitoring.update querystore=
{directory=/var/log/querystore anonymize-search-results=true
duration=2d max-size=100M}
Creating an authoritative querystore

1. The process for creating an authoritative querystore is essentially identical, differing
only in the name of the object:
cacheserve> auth-monitoring.update querystore=
{directory=/var/log/querystore anonymize-search-results=true
duration=2d max-size=100M}

69 Creating an authoritative querystore

Chapter 6: General oper-
ations
CacheServe is a high-performance application, and to get the most out of it, you may want
to consider some or all of these suggestions.
Unexpected open resolver

If you find yourself unexpectedly running an open resolver, you may want to reconfigure
CacheServe to remove the default view and view-selector. See “Removing the default view-
selector” on page 47.
Monitoring CPU usage

You can monitor CacheServe's CPU usage with a combination of the cacheserve-stats utility
(using the --cpu argument), and the server.usage Command-Channel command.
The details
cacheserve-stats --cpu reflects the percentage of CPU being used by a given thread group, as
a percentage (for example, 100% usage is represented as 100.0).
The percentage displayed is based on the number of threads being utilized by the thread
group. For example, a thread group using 2 threads could have a maximum displayed CPU
usage of very close to 200.0, or 200% (it's possible for percentage values to very slightly
exceed 100% per thread on a transient basis).
If you are not aware of how many threads are being used by a given thread group,
server.usage will display each thread group and the number of threads in use by that group.
71 In summary
In summary
In a nutshell, the total values returned by cacheserve-stats --cpu should not reflect
maximum thread utilization.
For example:
l server.usage shows a udp thread group with 6 threads.

l cacheserve-stats --cpu shows a value of 200.0 for udp total %cpu.
l The udp thread group is therefore utilizing approximately one-third of its available
CPU resources.
By contrast:
l server.usage shows a udp thread group with 6 threads.

l cacheserve-stats --cpu shows a value of 589.9 for udp total %cpu.
l The udp thread group is using almost all of its available CPU resources.
What it all means
If you're seeing very high CPU utilization, it's an indication of a problem that needs to be
further investigated in a methodical fashion. It's possible for a saturated network or failed
hardware to generate very high CPU utilization.
In some cases, the solution may be to add further capacity, which can be achieved by either
adding more CacheServe instances or greater concurrency to your CacheServe license.
Performance tuning
The following suggestions may improve general CacheServe performance.
Use a recommended OS
The best operating system for CacheServe is a multi-core physical server running RHEL 6.5
or later, 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 recommended OS
If you are not running Linux, or don't have access to a modern Linux kernel, you can
improve CacheServe performance by manually configuring the system to listen on multiple
addresses or ports, and then routing traffic for CacheServe through a load balancer.

Ramp up your network 72
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.
Process tuning
The following suggestions may improve the efficiency of the CacheServe process.
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
50,000 recursion contexts, and up to 100,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 250,000:
cacheserve> server.update max-recursive-clients=50000
Configuring authoritative servers

Note: The auth-server-list object has no effect in N2 Connect.
There may be situations where you will want to configure CacheServer's behavior as it
relates to specific authoritative servers, rather than as it relates to authoritative servers in
general.
The most common use case involves EDNS: some authoritative servers may not answer,
either when a request contains EDNS or there are fragmentation issues with the
transmission path.
As well, there may exist cases where you want to avoid sending any traffic at all to an
authoritative server.

73 Backing up and restoring
CacheServe manages authoritative servers with the auth-server-list and auth-server-node

objects. These objects behave in much the same way as the other list and node objects
in CacheServe:
l auth-server-node objects represent authoritative servers for a given network, and the
nearest authoritative server is used.
l auth-server-list objects are collections of auth-server-node objects that may be used
by a resolver to identify the authoritative servers used by that resolver.
The following example configures an auth-server-list called servers, and adds two
authoritative servers to it. The 1.2.3.4 server supports EDNS, and the 2.3.4.5 server does
not. The world resolver will use the appropriate authoritative server when traffic involves
EDNS.
cacheserve> auth-server-list.add name=server
cacheserve> auth-server-node.add list=servers address=1.2.3.4 \

max-edns-udp-size=1024
cacheserve> auth-server-node.add list=servers address=2.3.4.5 \

ignore=true
cacheserve> resolver.update name=world auth-server-list=servers
Backing up and restoring

To protect against hardware failure, the configuration database should periodically be
backed up.
Backing up CacheServe and querystores
Note: Elsewhere in the manual, we give command examples using the nom-tell
command channel interface (cacheserve>). These instructions give commands from the
operating system prompt, because the command context switches back and forth between
sending commands to CacheServe and sending commands to the host system.
To back up CacheServe:
1. Issue a block-checkpoints command to prevent a checkpoint from occurring during

the backup:
# nom-tell cacheserve server.block-checkpoints timeout=7200
2. Use tar to back up the files in the /var/nom/cacheserve and /usr/local/nom/etc/ dir-
ectories:

Restoring from a backup 74
# # tar cf /directory/backup-name.tar /var/nom/cacheserve/* \

/etc/channel.conf /usr/local/nom/etc/*
Where directory is a filesystem or partition with sufficient free space for the backup.
3. To back up CacheServe querystores that are in the default location:

# tar cf /dir/querystore-backup-name.tar /var/nom/statmon/*
Note: If you've changed querystore locations using the directory argument,

substitute the appropriate directory locations for /var/nom/statmon/*.
4. Re-enable checkpointing with an unblock-checkpoints command:

# nom-tell server.unblock-checkpoints
Note: To conserve disk space, we recommend compressing backups and deleting old
backup files which are no longer needed.
Restoring from a backup

To restore from backup:
1. Stop CacheServe:
# service cacheserve stop
2. Change directories to the location of your backup:

# cd /directory/
3. Extract the files contained in the backup from which you want to restore:
# tar xf backup-name.tar
4. Start CacheServe:
# service cacheserve start
Note: It is normal to see log messages related to the restore in syslog when you
restore your data.

75 Restoring from a backup

Chapter 7: 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.
77 Create the NXDOMAIN policy
Note: This example shows a network in which both IPv4 and IPv6 traffic are being
redirected.
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 will 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'
'2001:db8:f61:a1ff:0:0:0:80')))
redirect-nxdomain-prefix-only-prefixes => ('www')
}
2. You will need both the IPv4 and IPv6 addresses. 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 78
Make NXDOMAIN redirection lists

In this step, you will first create a list that holds the names you want to exempt from
redirection, and then you will create a list that holds the prefixes you want to exempt from
redirection.
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-replace => ((('.') ('192.168.1.1')))
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-do-not-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-do-not-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'

79 Make an NXDOMAIN policy selector
redirect-nxdomain-replace => ((('.') ('192.168.1.1')))

redirect-nxdomain-prefix-exclusions => ("www" "ldap" "smtp")
}
5. In CacheServe, create another name-list. This name-list will contain the names of pre-
fixes you want to exempt:
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
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 will 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 quer-
ies) 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-do-not-redirect-domains
subdomain )))) (not ((qname-prefix nxdomain-do-not-redirect-

Bind the NXDOMAIN policy to a view 80
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-
do-not-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 will 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:

81 Create the malicious redirection policy
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 will use the name
malicious-redirect-policy.
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 will 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'
'2001:db8:f61:a1ff:0:0:0:80'))
...
}
2. You will need both the IPv4 and IPv6 addresses. 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=malicious-redirect-policy
action=(answer ((A 192.168.1.1)(AAAA
2001:db8:f61:a1ff:0:0:0:80)))
{

Make malicious redirection lists 82

}
Make malicious redirection lists

In this step, you will first create a list that holds the names you want to exempt from
redirection, and then you will 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
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.

83 Bind the malicious redirection policy to a view
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:

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 pre-
query (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 8: Ratelimiting
Ratelimiting is the practice of constraining network traffic based on any of several
characteristics.
In this section, we will cover two scenarios: a simple scenario where you want to truncate
traffic above a certain rate, and a more complex scenario where you will use ratelimiting to
deal with a DNS amplification attack.
Simple rate-limiting
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 => '1'
}
This configuration limits traffic to 10qps, and truncates traffic.
In CacheServe 7
In CacheServe 7, rate-limiting is accomplished using policies.
85 Rate-limiting DNS amplification attacks
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 truncate traffic which exceeds the qps limit, using the new rate-
limiter:
cacheserve> policy.add name=rl10 action=truncate \
selector=(ratelimiter overall-qps10)
3. Bind the policy to the server with an appropriate priority:

cacheserve> binding.add policy=rl10 server=1 priority=10
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:
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 are using the statmon command-line interface:

[testbed etc]# nom-tell statmon
nom-tell 3.0.39.2.d, interactive mode
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):
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:

87 Dealing with purpose-built amplification domains
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 are 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 will assume the list
is /tmp/droppurpose-exact-list.
2. Make sure you are using the cacheserve command-line interface:
[testbed etc]# nom-tell cacheserve
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 will assume
the list is /tmp/droppurpose-sub-list.
2. Make sure you are using the cacheserve command-line interface:

[testbed etc]# nom-tell cacheserve

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 will 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 drop-
purpose-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
{
}

89 Managing ANY queries
Managing ANY queries

When you are dealing with DNS amplification attacks, you may see ANY queries used as
part of the attack.
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 will 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.

Rate-limiting amplification traffic 90
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
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)))

91 Rate-limiting amplification traffic
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-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

Chapter 9: Defending
against DDoS attacks using
prefetch extensions
A DoS attack against all the authoritative servers for a service can cause the service to be
completely unavailable even though the service itself remains mostly operational.
Authoritative DNS service is often outsourced to large hosting or Content Delivery Network
(CDN) services. This means the impact from an attack on authority can affect many services
simultaneously.
The Internet of Things has added a powerful new dimension to Distributed DoS attacks
against authoritative servers.
Defending against DDoS attacks on author-

itative servers
A good defense against these issues is one that preserves the contents of the cache past
the natural DNS time-to-live, because the last-known-good values in the cache may still
work.
There are some issues with preserving the contents of the cache. First, not all content is
equally worth preserving, because of the "long tail" aspect of DNS queries. Second, the
most obvious methods of preserving cache contents (such as "just ignore the TTL", or
imposing a minimum TTL) may impair the correct operation of a CDN.
The best solution to the problem is a solution that:
93 The CacheServe prefetch mechanism
l Preserves popular content, and

l Ensures that when authorities again become available, content is rapidly updated to
the current values.
The CacheServe prefetch mechanism

Prefetching occurs automatically in CacheServe. CacheServe prefetches an answer when it
looks up an RRset in the cache and gets a hit, and finds that there's less than than the
lifetime determined by the prefetch ratio remaining.
Prefetching, by proactively fetching refreshed content before the cache entry expires,
attempts to ensure that popular content is always a cache hit for clients.
The frequency with which prefetching occurs is determined by the Resolver object's
prefetch-ratio field.
For example, consider an RRset with a TTL of 320. If CacheServe is configured with a
prefetch-ratio of 16 (the default), CacheServe will prefetch an answer if it gets a query
within the last 20 seconds of the remaining TTL: 20 seconds is 1/16th of the original 320-
second TTL.
Prefetch extension
CacheServe uses prefetching to identify popular content. Therefore, it makes sense to use
the existing prefetching mechanism to extend the life of popular content.
Extension entries
The mechanism via which CacheServe achieves this is extension entries. Extension entries
are cache entries created for popular content, according to the following rules:
1. An extension entry is made for any prefetch attempt that ends without the cache
entry being successfully refreshed (unless an extension cache entry already exists for
the given attempt).
2. If there are less than 2 seconds of life remaining on a prefetch attempt, CacheServe
immediately inserts an extension entry for the given entry.
3. Extension entries have the same DNS content as the entry being replaced, but with
an expiration time 30 seconds in the future.
4. Extension entries are clearly marked as extension entries.
Extension entries behave normally when they're found in cache lookups, with the
exception that extension entries are rendered with a TTL of 0.
Extension entries are themselves subject to prefetching, so data is extended for as long as
authorities are not responding and there's sufficient demand for the content.

Configuring prefetch extension 94
Configuring prefetch extension

Prefetching is on by default in CacheServe. However, if prefetching has somehow been
disabled in CacheServe, you can re-enable it by setting the prefetch-extension option on
the Resolver object:
shell# nom-tell cacheserve
cacheserve> resolver.update name=world prefetch-extension=true
Prefetch extension statistics

The Resolver object's prefetch-extensions statistic is incremented every time CacheServe
makes an extension entry. If you find this statistic increasing rapidly, it may indicate
problems reaching some authoritative servers.
To retrieve the prefetch-extensions statistic, issue a resolver.statistics command:

cacheserve> resolver.statistics name=world
{
type => 'resolver.statistics'
current-time => '1480732697.352383'
server-start-time => '1480731577.288171'
node-id => '6a3de725-6f62-5ccf-8144-803f228e9650'
user-time => '0.163975'
system-time => '0.107983'
memory-in-use => '56425024'
name => 'world'
reset-time => '1480731577.404616'
cache-memory-in-use => '7136'
statistics => {
lookups => '59'
recursive-lookups => '24'
proactive-lookups => '5'
ignored-referral-lookups => '3'
cache-misses => '28'
requests-sent => '178'
queries => '57'
prefetch-extensions => '52'
responses-by-rcode => {
noerror => '32'
servfail => '25'
}
}
}

95 Extended caching and DNSSEC
Extended caching and DNSSEC

Extended caching not only extends the life of content beyond its configured TTL, but may
also extend the life of secure content beyond its validity time. This feature helps in the
most common DNSSEC failure scenarios, where an authority makes a mistake and their
content fails to validate.
Prioritized prefetch domains

An additional means of dealing with prefetching involves the use of "prioritized domains".
Note: CacheServe provides this mechanism as an adjunct to prefetch extensions.
Legitimate and common names may expire from cache because prefetching isn't
completed. This situation generally only occurs when the server is under extremely heavy
load, and prefetch queries are as a result unable to get slots in the set defined by max-
recursive-clients.
Prefetch queries, under normal circumstances, have no advantage over other queries when
looking for a slot. Prioritized prefetch domains provide a weighting for "more
important" prefetches.
How it works
If CacheServe attempts to find a slot for a prefetch and fails, it compares the domain in the
prefetch query to a list of "good" domains. If the domain appears in that list, CacheServe
queues the prefetch. The prefetch queue is not subject to the max-recursive-clients limit.
Queued prefetches are preferentially executed over regular recursions when recursion
slots become available.
Configuration
1. Add a prioritized-domains list:
cacheserve> name-list.add name=good-domains
2. Populate the list with a few names:

cacheserve> name-node.add list=good-domains name=google.com
cacheserve> name-node.add list=good-domains name=nominum.com
3. Associate the list with a resolver, using the name of the list as the argument to the pri-
oritized-domains field:
cacheserve> resolver.update name=world prioritized-
domains=good-domains

Statistics 96
Statistics
The Resolver object's queued-prefetches statistic indicates the number of prefetch queries
that were added to a queue rather than being sent immediately. A prefetch is queued when
there are no available recursion slots and the name of the query is associated with an entry
in the prioritized-domains list.

97 Statistics

Chapter 10: 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.
Defending 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.
99 Settings related to ID spoofing
Settings related to ID spoofing

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

randomizes 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

randomization.
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.
Statistics and events

The following statistics and events are related to ID spoofing:
l id-spoofing-defense-queries: A statistic that records the number of times CacheServe

has sent a query to an authoritative server using TCP instead of UDP, which maps to
the number of times the ID spoofing defense system has been activated.
l resolver.id-spoofing-suspected: An event that appears when CacheServe suspects

that an ID spoofing attack is underway.
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 11: Aggregation
with client-subnet
The client-subnet protocol permits content delivery networks (CDN's) like Akamai and
Google to tailor their answers based on the address of the querying client.
The main benefits of the client-subnet protocol are:
l Quality-of-service improvements.
l Reductions in long-haul network traffic.
l Localization.
However, the client-subnet protocol has some limitations that affect scalability.
These limitations can provoke rapid increases in the amount of data cached,
CPU utilization, and network bandwidth.
Client equivalency
CacheServe, when communicating with CDNs using client-subnet, uses client equivalency
to designate a given address as a representative for a subnet, or a list of subnets.
When CacheServe receives a query from a client in one of those subnets, it treats the query
as if it originated from the representative address.
In this way, CacheServe can identify thousands of clients to the CDN as a single client,
versus individually resolving each client's query.

101 Background
Background
Client equivalency is designed to address two specific situations where the limitations of
client-subnet come into play.
Overly specific authoritative answers

The first type of situation is a network topology where authoritative server answers are
overly specific. This type of situation arises in network topologies where subnets are
assigned to demographic or geographic clusters.
For instance, in this type of network, a /20 may apply to a major metropolitan area, but the
authoritative server may be returning answers specific to /24 subnets within that /20.
In this situation:
1. A client from the metropolitan area sends a query.

2. CacheServe, on behalf of the client, requests information from the authoritative
server.
3. The response from the authoritative server is "for this client, the answer is
192.168.0.1, and this answer applies to all clients in the same /24 as the requestor."
4. Another client from the same metropolitan area, in the same /20 but a different /24,
sends a query.
5. CacheServe, on behalf of the client, requests information from the authoritative
server.
6. The authoritative server responds with the same answer as above, and again indic-
ates that the answer applies to all clients in the same /24 as the requestor.
7. This situation repeats indefinitely for each /24 in the metropolitan area, rapidly
exhausting all available computing resources.
The problem
Even though the CDN's answer for each of the /24 networks in the /20 is the same, each
client is being handled individually.
The solution
A more efficient way of dealing with this situation is to use a single representative address
to stand for all /24's in the /20: for example, "all clients in this city share the 192.168.16/20
subnet, and are functionally equivalent to the client 192.168.1.1".
Unpredictably assigned subnets

The second type of situation is one in which network-adjacent subnets don't correspond to
physically-adjacent geographic areas, which makes it impossible to aggregate subnets into

Configuring client equivalency 102
larger CIDR blocks. This results in a large number of client-subnet queries.
For example, in this kind of topology, if an authoritative server were to provide an answer
based on a /20 subnet, the /20 could be composed of multiple /25 subnets which are
geographically widely distributed.
The problem
The inconsistency between physical location and network location causes the CDN to try to
provide responses for each individual subnet. This creates scalability problems, both for
the CDN and for the caching server that's trying to keep track of many identical responses
for different subnets.
The CDN may be forced to deliver resources across thousands of miles and multiple
network segments for clients that are physically "next door".
The solution
Using client equivalence, it's possible to group physically related subnets even if they're
widely separated in network terms.
All subnets related to City A can be designated as a group, and a single address designated
to stand for that group.
When a query comes in from a "City A" subnet, regardless of network location, the client
can be handled by a physically proximate CDN node versus being routed through distant
network segments on the basis of network topology.
Configuring client equivalency

To configure client equivalency:
1. Configure an address-list, with some nodes. In this example, each node is a subnet
related to the fictional city of Gotham:
cacheserve> address-list.add name=gotham
cacheserve> address-node.add list=gotham address=24.1.2/24
cacheserve> address-node.add list=gotham address=24.2/16
cacheserve> address-node.add list=gotham address=1:2:3::/48
2. Configure another address-list. In this example, each node is a subnet related to the
fictional city of Metropolis:
cacheserve> address-list.add name=metropolis

103 Manually setting representative addresses
cacheserve> address-node.add list=metropolis

address=1.2.0.0/25

address=1.7.128.128/25

address=3.1.2.0/25
3. Configure the resolver, which uses client-subnet to apply the gotham and metropolis
equivalence classes to the Akamai and Google CDN's:
cacheserve> resolver.update name=world client-subnet=
{equivalence-classes=(gotham,metropolis) whitelist=(akadns.com
google.com)}
Manually setting representative addresses

As previously mentioned, CacheServe picks the lowest address available to act as a
representative address. However, it's possible to manually set both IPv4 and IPv6
representative addresses.
To manually apply an IPv4 representative address for clients that originate in the 24.2.0/24
gotham subnet:
cacheserve> address-list.update name=gotham representative-
address-v4=24.2.0/24
To manually apply an IPv6 representative address for clients that originate in the 1:2:3::/48
gotham subnet:
cacheserve> address-list.update name=metropolis representative-
address-v6=1:2:3::/48

Chapter 12: SNMP
Simple Network Monitoring Protocol (SNMP) is the primary protocol used by network
management software to monitor and control networked systems and devices.
SNMP-aware software can be used to monitor and manage Nominum products such as
CacheServe engines.
Nominum assumes that this chapter will be used in conjunction with the documentation
for Net-SNMP, available at http://www.net-snmp.org/.
Supported SNMP versions

Nominum Vantio CacheServe supports SNMP versions v2c and v3. SNMP version v1 is not
supported.
SNMP Concepts and Architecture

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

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

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

snmpagent 106
l In a straightforward installation, snmpagentworks as a subagent to Net-SNMP's mas-

ter agent, snmpd. This is the default case. In the simplest instance, with snmpd run-
ning, no additional configuration is necessary.
l snmpagent can work as a subagent to master agents other than snmpd as long as they
use the AgentX protocol for communication with subagents.
l snmpagent can be set up to function as a master agent. If you're setting up an SNMP-
aware manager exclusively for Nominum products, you can use snmpagent in the
master agent and subagent roles. snmpagent can also work with other subagents that
support the AgentX protocol. In either case, as a master agent, snmpagent requires a
configuration file, typically /var/nom/snmpagent/snmpagent_master.conf.
If necessary, snmpagent can coexist as a master agent with a third-party master agent
running on the same host computer. To do this, you'll have to configure one of the two
master agents to use a non-standard port, and also configure your management
application accordingly to send SNMP traffic to the correct port.
The snmpagent package installs MIBs specific to Nominum products, along with associated
documentation. For details, see Nominum MIBs.
snmpagent
The Nominum SNMP Agent (snmpagent) provides SNMP notifications that correspond to
events sent by Nominum engines, and SNMP GET access to engine statistics.
Synopsis
snmpagent [-c file] [-f] [-F] [-h|--help]
[-m|--masteragent] [ -r|--root directory ]
[-s|--syslog-facility facility ] [-u|--user username]
[--usage ] [ -v|--version]
Options
Option Description
-c | --configurationfile Reads configuration information from the specified file

instead of the default configuration file
(/etc/snmpagent.conf).
If a file is specified using -c and that file cannot be

found, snmpagent exits with an error message.
-f | --foreground Prevents the agent from daemonizing, and sends

output to stderr.

107 Configuration Files
Option Description
-F | --foreground-with-syslog Prevents the agent from daemonizing, and sends

output to both stderr and syslog.
-h | --help Displays a help message and exits.
-m | --masteragent Starts the agent as an SNMP master agent.
-r | --root directory chroot()s to the specified directory when the agents

runs. To fully provide the necessary protection, a non-
root user must also be specified with the --user option.
-s | --syslog-facility When logging to syslog, use the specified syslog facility

instead of the default facility, daemon.
-u | --user username Executes a setuid() to the specified username. If using

this option, make sure that whatever user is indicated
is able to write to the directory from which snmpagent
is run.
--usage Displays usage information and exits.
-v | --version Displays the agent version and exits.
Table 12-1:snmpagent options
Configuration Files
snmpagent can run as either an SNMP master agent or as an SNMP subagent. By default it
runs as a subagent.
In a simple, fresh installation with Net-SNMP's snmpd functioning as a master agent,

snmpagent can run as a subagent without further configuration. If your environment is
more complex—for instance, if you are running snmpagent as a master agent or adding it
to an existing Net-SNMP installation that has already been customized—more
configuration will be involved.
Agent Configuration Information

snmpagent configuration information is specified in two locations:

Nominum MIBs 108
l The /etc/snmpagent.conf file contains configuration options specifying how

snmpagent behaves as a daemon. This behavior can also be specified using the
Command Channel.
These options are described in this manual, in The snmpagent Configuration File
and Using the Command Channel with snmpagent.
l The following files contain options pertaining to snmpagent's SNMP configuration:
l /var/nom/snmpagent/snmpagent_master.conf
l /var/nom/snmpagent/snmpagent_subagent.conf
A minimal, insecure sample snmpagent_master.conf file is displayed in Running as

a Master Agent. Options and further details are beyond the scope of this chapter. See
the Net-SNMP documentation (available from http://www.net-snmp.org).
Note: If you're configuring traps, be sure to configure snmpagent to send notifications in

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

monitoring of any network service application.
l NOMINUM-AGENT-CAPS-MIB—Defines a set of agent capabilities that convey an invent-
ory of management objects exposed by SNMP agents for Nominum products.
l NOMINUM-MDR-MIB—Describes managed objects related to Malicious Domain Redir-
ection in Nominum products.
l NOMINUM-NSM-MIB—Describes managed objects that expose operational status and
statistics for the Nominum Server, Nominum View and Nominum Zone entities that
comprise Nominum Name Server products.
l NOMINUM-NSN-MIB—Describes managed objects and notifications for the asyn-
chronous reporting of events observed on Nominum Name Server products.
l NOMINUM-PCS-MIB—Describes managed objects exposing per-client operational
status and statistics.

109 Using SNMP with Vantio CacheServe
l NOMINUM-POLICY-BASED-RATE-LIMITER-MIB—Describes managed objects exposing con-

figuration information, tracker profiles, statistics and events for policy-based rate-lim-
iting.
l NOMINUM-POLICY-MANAGER-MIB—Describes managed objects exposing configuration

information and statistics for policy management.
l NOMINUM-PROVISIONING-SERVICE-MIB—Describes managed objects exposing con-

figuration information and statistics for provisioning services.
l NOMINUM-PROXY-MIB—Describes managed objects exposing configuration inform-

ation and statistics for provisioning services.
l NOMINUM-QRS-MIB—Describes managed objects exposing query rate statistics and

notifications.
l NOMINUM-RATE-LIMITER-MIB—Describes managed objects exposing tracker profiles

and statistics for rate limiters.
l NOMINUM-RESOLVER-MIB—Describes managed objects exposing tracker profiles and

statistics for resolvers.
l NOMINUM-RTA-MIB—Describes managed objects exposing query rate statistics and

exposing statistics and event notifications for Nominum Real-Time Visibility and Real-
Time Alerts monitors.
l NOMINUM-SMI-MIB—Defines the top level structure of management information and
administrative registrations within the Nominum private enterprise namespace.
l NOMINUM-TC-MIB—Defines a set of textual conventions that concisely convey the syn-
tax and semantics of MIB objects as defined in Nominum enterprise MIB modules.
Using SNMP with Vantio CacheServe

This section describes how to use SNMP to monitor events, statistics and configuration
variables defined for CacheServe.
Running as a Subagent
By default, snmpagent runs as a subagent, typically in conjunction with Net-SNMP's master
agent, snmpd. In the simplest instance, this may not require any configuration at all.
If your environment is more complex — for instance, if you are running a master agent
other than Net-SNMP's snmpd, or if you are extending an existing Net-SNMP installation
that has already been customized — more configuration may be involved. Nominum
assumes that you are familiar with Net-SNMP and that you have access to its
documentation at http://www.net-snmp.org/.

Running as a Master Agent 110
For SNMP configuration file options, see The snmpagent Configuration File.
Details specific to atypical installations are beyond the scope of this chapter, but the
following broadly outlines the necessary steps:
1. Install the snmpagent package that is provided as part of the distribution.
2. Ensure that the installation supports the AgentX protocol. See Configuration
Files.
3. Ensure that an SNMP daemon is running.
4. Configure Nominum-specific options for snmpagent by creating the

/etc/snmpagent.conf file and adding the following lines:
driver cacheserve cacheserve
driver statmon statmon
5. Ensure that a master SNMP agent is configured and running on the same
machine, and that the SNMP agent supports the AgentX protocol.
6. Perform any Net-SNMP configuration necessary for your specific environment.

For details on configuring Net-SNMP, see the Net-SNMP documentation
(available from http://www.net-snmp.org).
7. To make use of the (optional) configuration file, create a

/var/nom/snmpagent/snmpagent_subagent.conf file and populate it with the rel-
evant Net-SNMP configuration data.
8. Start the SNMP agent:

# service snmpagent start
9. f your installation requires it, configure your SNMP management application to

interact with the provided MIBs and the events they define.
Running as a Master Agent

An SNMP configuration file is mandatory when the SNMP agent is operating in master
mode.
Nominum assumes that you are familiar with Net-SNMP and that you have access to its
documentation at http://www.net-snmp.org/.
For complete SNMP configuration file options, see The snmpagent Configuration File.
Details are beyond the scope of this chapter, but the following broadly outlines the
necessary steps:

111 The snmpagent Configuration File
1. Install the snmpagent package that is provided as part of the distribution.
2. Configure Nominum-specific options for snmpagent by creating the

/etc/snmpagent.conf file and adding the following lines:
masteragent
driver cacheserve cacheserve
3. Perform any Net-SNMP configuration necessary for your specific environment,

adding relevant Net-SNMP configuration data to:
/var/nom/snmpagent/snmpagent_master.conf.
You can do this either by hand-editing the file or by using the Net-SNMP
snmpconf utility (part of the Net-SNMP package) to do so.
A minimal, insecure sample /var/nom/snmpagent/snmpagent_master.conf is

displayed below. (This is for illustration only; the user is fflintstone, passwords are
test, and traps and notifications are sent to the local host.):
syslocation "This building"
sysservices 12
rwuser fflintstone
rwcommunity test
trap2sink localhost
master agentx
Note: Further details on configuring Net-SNMP are beyond the scope of this
chapter.
4. Start the SNMP agent:

# service snmpagent start
5. If your installation requires it, configure your SNMP management application to

interact with the provided MIBs and the events they define.
The snmpagent Configuration File

Upon startup, snmpagent tries to read either /etc/snmpagent.conf or the file specified using
the -c command-line option.
If there are no driver directives present in the configuration file, snmpagent tries to read
/etc/channel.conf and monitor any currently running Nominum engines. If driver

The snmpagent Configuration File 112
directives are present in the configuration file, snmpagent does not search
/etc/channel.conf.
If you want snmpagent to scan /etc/channel.conf to discover engines, then all the engines
to be monitored must be running before snmpagent starts. First start the engines, make
sure they're running, and then start snmpagent. This process should also work when
running multiple instances of CacheServe on the same host.
If the snmpagent fails to discover the engine or engines that you want it to monitor, you
may need to add a driver line to the /etc/snmpagent.conf file identifying each engine that
you want it to recognize. Information on how to complete this configuration can be found
below.
A snmpagent configuration file is a sequence of lines. Blank lines and lines starting with the
# comment character are ignored. Each configuration line contains an option name,
optionally followed by whitespace and a value. If a value is present, it is set to the
remaining text on the line, including any non-leading whitespace.
command-channel
command-channel who [secret]
Specifies the address and port to use for Command Channel messages. If no secret is
specified, then who specifies the name of a service in /etc/channel.conf. If a secret is
specified, then who specifies an addrport (restricted to IPv4 addresses), and a port must be
specified.
If secret is anything other than "*", only Command Channel requests signed with secret are
allowed to execute, and Command Channel responses are signed with the secret. If secret is
specified as "*", then Command Channel messages are neither validated nor signed.
Specifying command-channel none disables use of the CC.
Note: This address and port setting has nothing to do with how snmpagent communicates
with the engines it monitors. It is only relevant to interaction with the Command Channel.
directory
directory directory
Instructs the agent to use the specified directory as the working directory of the server. This
command takes effect immediately. Only one directory statement may appear in a
configuration.
The default directory is /var/nom/snmpagent.

113 The snmpagent Configuration File
driver
driver engine engine-type [args...]
Instructs the agent to load an SNMP agent driver for a given Nominum engine. The engine-
type is the type of Nominum engine: cacheserve or statmon.
It connects to the engine corresponding to the appropriate /etc/channel.conf entry, sends

SNMP notifications when the monitored engine sends events, and presents the engine's
statistics via SNMP.
Any remaining arguments are passed to the driver's setup function, and multiple driver
statements may be specified. If you are running multiple instances of CacheServe on the
same host, each instance will require its own driver statement.
At this time, the only valid args is a comma-separated list of events to request from the
engine and convert into SNMP notifications. If unspecified, all events are requested.
log
log switch_name yes_or_no
Instructs the agent to set a logging control switch. snmpagent allows fine-grained control
over what is logged.
switch_name is the name of the switch, Can be:
l command/executed—Logs details about the valid CC commands executed by the

agent. The default value of this switch is false.
l command/unknown—Logs details about unknown CC commands received by the
agent. The default value of this switch is false.
l snmp/get—Logs SNMP GET requests. The default value of this switch is false.
l snmp/set—Logs SNMP SET requests. The default value of this switch is false.
l snmp/trap—Logs SNMP traps and notifications. The default value of this switch is
false.
l snmp/status—Logs SNMP status changes. The default value of this switch is false.
l cacheserve/event and statmon/event—Logs details of events received from

CacheServe. The default value of this switch is false.
yes_or_no is either:
l yes—Enables logging.
l no—Disables logging.

Driver-Specific Configuration Options 114
masteragent
masteragent
Starts the agent as an SNMP master agent.
minseverity
minseverity severity
Sets the minimum severity assigned to a Nominum notification. A notification will not be
sent if it has a severity less than the specified severity. Replace the severity argument with a
number from 0 (zero) to 6, as defined in the NominumPerceivedSeverity textual convention
in NOMINUM-TC-MIB.
This has no effect on clearing notifications (for example, those with a severity of cleared(1)).
observer-address
observer-address addrport
Instructs the agent to include the specified address and (optional) port in SNMP
notifications. If not specified, no address or port is included in SNMP notifications.
setseverity
setseverity notification severity
Sets the severity assigned to a Nominum notification. notification must be the name of one
of the notifications defined in NOMINUM-NSN-MIB, such as nnsnServerEventStop, severity is
specified as a number in the range from 0 (zero) through 6, as defined in the
NominumPerceivedSeverity textual convention in NOMINUM-TC-MIB.
This has no effect on clearing notifications (for example, those with a severity of cleared(1)).
syslog-facility
syslog-facility facility
Instructs the agent to use the specified syslog facility instead of the default facility (daemon).
Driver-Specific Configuration Options

The CacheServe SNMP driver accepts additional configuration elements.
These configuration elements are useful when:
l The agent has no trap sinks configured and hence does not need to receive most
events from the engines it is monitoring.
l The engines are generating large numbers of events, causing the SNMP agent to use
CPU cycles needlessly.

115 Using the Command Channel with snmpagent
Note: Do not enable request-minimal-events if you want the SNMP agent to send SNMP
traps or notifications.
events
A comma-separated list of events to be requested from the engine and converted into
SNMP notifications. If this value is not specified, all events are requested.
For example:
driver cacheserve cacheserve events=all,!cache-flush
request-minimal-events
The request-minimal-events option permits you to control the number of events you
receive from the CacheServe SNMP driver. If you set this option to yes, the driver requests
only the minimal set of events needed to keep applTable up to date. This option supersedes
the events configuration element.
The following example shows how to set the request-minimal-events option :
driver cacheserve cacheserve request-minimal-events=yes
Using the Command Channel with snmpagent

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

/etc/channel.conf, sends SNMP notifications when the monitored server sends events,
and presents the engine's statistics via SNMP.
If the engine name is anything other than the default for the given engine, engine-type must
also be specified, and any additional arguments are passed on to the driver.
It is also possible to use the events argument to restrict the list of events to be requested
from the engine and converted into SNMP notifications. If this value is not specified, all
events are requested.
snmpagent> load-driver name=EngineName [engine-type=cacheserve]

[events=events]
{
type => 'load-driver'

Using the Command Channel with snmpagent 116
pid
Returns the process identification for the agent process.
snmpagent> pid
{
type => 'pid'
pid => '4847'
}
process-information
Retrieves process information for the server.
snmpagent> process-information
{
type => 'process-information'
arguments => ('/usr/local/nom/sbin/snmpagent' '-F')
pid => '4847'
current-time => '1475693394.685179'
start-time => '1475693165.108551'
host-name => 'rt56584-4.a.nominum.com'
working-directory => '/var/nom/snmpagent'
node-id => 'f7860845-d470-5bcb-b59b-2a71daa1dafd'
}
stop
Stops the agent.
snmpagent> stop
show-drivers
Shows the currently loaded drivers. The CC result contains a list of drivers, and each driver-
list item contains a list of currently instantiated drivers for that driver type.
snmpagent> show-drivers
{
type => 'show-drivers'
drivers => {
cacheserve => ('cacheserve')
}
}
uuid
Returns the UUID (Universal Unique IDentifier) of the agent.

117 Using Net-SNMP Command-line Tools with snmpagent
snmpagent> uuid
{
type => 'uuid'
uuid => '864223ee-c791-4e1c-9194-505537860254'
}
unload-driver
Unloads an SNMP agent driver.
snmpagent> unload-driver name

Response:
name => engine_name
version
Returns version information about the agent.
snmpagent> version
{
type => 'version'
vendor => 'Nominum'
product => 'SNMPAgent'
platform => 'rhel-6-x86_64'
version => '16.1.0.0'
}
Using Net-SNMP Command-line Tools with

snmpagent
Net-SNMP, the basic structure on which snmpagent relies, includes a set of command-line
tools for examining and testing your SNMP setup. Many of these tools are bundled with the
snmpagent package: snmpget, snmpwalk, snmptrap, snmptranslate, snmpbulkget,
snmpgetnext, snmpinform, snmpset, snmptable, snmpusm, snmpvacm, and
snmptrapd.
If you have installed the snmpagent package, all the MIBs and driver libraries will be where
both snmpagent and the Net-SNMP tools expect them to be. However, you will still have to
configure the command-line tools to use all the MIBs. You can do that by calling the tools
with the -m ALL option each time, or more neatly by adding the following line to
/etc/snmp/snmp.conf:
mibs +ALL

If you built the tools yourself rather than by installing snmpagent, you will also have to set
the mibdirs environment variable by including the following line:
mibdirs +/usr/local/nom/share/snmp/mibs
It is beyond the scope of this chapter to discuss the Net-SNMP tools in detail. A few
examples are provided for each of the most useful tools: snmptranslate, snmpwalk,
snmpget, and snmptrapd. Please see the Net-SNMP documentation at http://www.net-
snmp.org/.
In all examples below that require a hostname, localhost is used. If snmpagent is not
running on the local host, you can replace this with the hostname or IP address of the
appropriate host computer.
snmptranslate
To verify that the tools can find what they need, use the snmptranslate command as
shown in the following examples:
> snmptranslate -IR applTable

NETWORK-SERVICES-MIB::applTable
> snmptranslate -IR nnsmViewTable

NOMINUM-NSM-MIB::nnsmViewTable
You can also display full object identifiers (OIDs), in numeric or symbolic form:
> snmptranslate -IR -On nnsmViewTable

.1.3.6.1.4.1.5901.4.5.1.2.2
> snmptranslate -IR -Of nnsmViewTable

.iso.org.dod.internet.private.enterprises.nominum.nominumMibs. \
nominumNsmMib.nnsmObjects.nnsmViewObjects.nnsmViewTable
snmpwalk
The applTable shows which Nominum engines snmpagent is monitoring:
> snmpwalk -v 2c -c test localhost -IR applTable

NETWORK-SERVICES-MIB::applName.1 = STRING: dcs
NETWORK-SERVICES-MIB::applDirectoryName.1 = STRING:
NETWORK-SERVICES-MIB::applVersion.1 = STRING: 3.0.0.0
NETWORK-SERVICES-MIB::applUptime.1 = Timeticks: (0) 0:00:00.00
NETWORK-SERVICES-MIB::applOperStatus.1 = INTEGER: up(1)
NETWORK-SERVICES-MIB::applLastChange.1 = Timeticks: (0) 0:00:00.00
NETWORK-SERVICES-MIB::applDescription.1 = STRING: Dynamic Con-
figuration Server
NETWORK-SERVICES-MIB::applURL.1 = STRING:

This example assumes that your "community string" (SNMP password) is test, and that
snmpagent is running on the localhost.
One crucial piece of information the applTable provides is a mapping from the human-
readable server name (dcs in this example) to the application ID (in this case, 1). The
application ID is the number after each column name (applName.1). The application ID
appears in the indexes of all Nominum SMI objects, and provides the only reference to
which Nominum engine a given SMI object refers.
snmpwalk can dump any table in the set of MIBs that snmpagent supports. This includes a
large number of standard MIBs in addition to Nominum's MIBs.
To dump a view table in CacheServe:
> snmpwalk -v 2c -c test localhost -IR nnsmViewTable

NOMINUM-NSM-MIB::nnsmViewName.1.1 = STRING: default
NOMINUM-NSM-MIB::nnsmViewType.1.1 = INTEGER: auth(1)
All Nominum tables (5901 is Nominum's enterprise OID: the examples are edited for
brevity):
>snmpwalk -v 2c -c test localhost .1.3.6.1.4.1.5901

NOMINUM-NSM-MIB::nnsmViewNameToViewID.1."default" = Gauge32: 1
NOMINUM-NSM-MIB::nnsmViewName.1.1 = STRING: default
NOMINUM-NSM-MIB::nnsmViewType.1.1 = INTEGER: auth(1)
NOMINUM-NSM-MIB::nnsmViewAuthLoadTime.1.1 = STRING: 27136-7-
25,17:24:20.0
NOMINUM-NSM-MIB::nnsmViewAuthZonesActive.1.1 = Gauge32: 2 DNS zones
NOMINUM-NSM-MIB::nnsmViewAuthSlavesActive.1.1 = Gauge32: 0 DNS zones
snmpget
You can use snmpget to retrieve single instances.
To get the zone name and zone type indexed by application ID 2, view ID 1, and zone ID 2:
> snmpget -v 2c -c test localhost NOMINUM-NSM-MIB::nns-

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

nnsmZoneNameToZoneID.2.1.8.99.97.116.46.99.111.109.46

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

DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (53405)\
0:08:54.05
SNMPv2-MIB::snmpTrapOID.0 = OID: NOMINUM-NSN-MIB::nnsn\
ServerEventStart
NOMINUM-NSN-MIB::nnsnEventPerceivedSeverity = INTEGER:\
information(0)
NOMINUM-NSN-MIB::nnsnEventDateAndTime = STRING:\
27648-1-9,17:7:51.0
NOMINUM-NSN-MIB::nnsnEventReferenceID = Gauge32: 0
NETWORK-SERVICES-MIB::applName.1 = STRING: <engine>
NETWORK-SERVICES-MIB::applVersion.1 = STRING: <version>
NOMINUM-NSN-MIB::nnsnEventSerialNumber = Counter64: 2


Chapter 13: The
cacheserve process
The cacheserve process is the main CacheServe software process.
By default, the cacheserve executable is located in /usr/local/nom/sbin.
All of the following command-line options are passed to the basic cacheserve command,
as in:
shell #/usr/local/nom/sbin/cacheserve --<COMMAND>
CacheServe process command-line options

--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

123 --dns-port
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. The default
value is 53.
This option is mainly intended for server testing; a server using 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.
The default value is 20000.
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
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 124
--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 --no-statmon
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 --root directory
Configures CacheServe to run under the specified directory. All paths, including that of the
configuration database, are interpreted relative to the specified root.
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-directory
directory
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.

125 --tcp-acl
The default is daemon.
--tcp-acl
shell# /usr/local/nom/sbin/cacheserve --tcp-acl acl
Configures CacheServe to send all TCP socket-creation requests to the nanny process.
Privileged ports must be permitted by an access control list (ACL).
If unspecified, the default ACL permits only the configured dns-port.
The form of the ACL is

([(port ([[!]addrpat] ...))] ...)
For example:
((53 (0.0.0.0/0 ::/0)) (54 (!10.0.1.0/24 10.0.0.0/8)))
--udp-acl
shell# /usr/local/nom/sbin/cacheserve --udp-acl acl
Configures CacheServe to send all UDP socket-creation requests to the nanny process.
Privileged ports must be permitted by an access control list (ACL).
If unspecified, the default ACL permits only the configured dns-port.
The form of the ACL is

([(port ([[!]addrpat] ...))] ...)
For example:
((53 (0.0.0.0/0 ::/0)) (54 (!10.0.1.0/24 10.0.0.0/8)))
--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 CacheServe.
-v, --version
shell# /usr/local/nom/sbin/cacheserve --version

-v, --version 126
Displays the CacheServe version.

127 -v, --version

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

loadconf: utilities that can be used when CacheServe isn't running, and allow you to
either create a textual representation of an object or manipulate the full server con-
figuration in textual format.
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
action Identifies an action that may be referenced by

name from other actions.
address-list Provide containers for address-nodes and rep-

resent addresses and networks.
address-node Represent all data associated with a single network

in an address-list.

129 Supported objects
Element Description
auth-monitoring Represents the authoritative monitoring system in

CacheServe.
Instructions for configuring and managing the

auth.monitoring object are contained in the
Nominum monitoring manuals:
l Monitoring Query and Request Data on

Nominum Engines
l Nominum statmon Utility and Query Store Com-
mand Reference
auth-server-list auth-server-lists contain nodes that represent

authoritative servers. The contents of auth-server-
lists are made up of auth-server-nodes.
auth-server-node auth-server-nodes represent authoritative name

servers. auth-server-nodes make up the contents
of auth-server-lists.
binding Represent bindings between policies and the

server or views.
device-list device-lists contain nodes that represent device

identifiers. The contents of device-lists are made
up of device-nodes.
device-node device-nodes represent device identifiers. Each

device-node contains a device identifier and an
associated view. device-nodes are aggregated into
device-lists, which are used in policy selectors.
dns64 Represent DNS64 translation layers.
layer Represent sets of configuration information that

can be selectively enabled or disabled.

Element Description
monitoring Supports statistical processing, and interacts with

the Nominum statmon utility.
Instructions for configuring and managing the

monitoring object are contained in the Nominum
monitoring manuals:
l Monitoring Query and Request Data on

Nominum Engines
l Nominum statmon Utility and Query Store Com-
mand Reference
name-group name-groups are collections of name-lists and

other name-groups.
name-list Provide containers for name-nodes and represent

addresses and networks.
name-node Represent all data associated with a single name in

a name-list.
policy Execute specific actions based on the results from

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

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

related to DNS resolution.
selector Named selectors (identified as selector objects in

CacheServe) specify selectors that may be
referenced by name from other selectors.
server Represent complete CacheServe configurations.

Changes made to a server globally affect all other
configuration elements within the scope of that
server's influence.
telemetry The telemetry object periodically writes engine

samples and events into Kafka.

131 The CacheServe configuration file format
Element Description
view Provide customizable DNS namespaces.
view-selector Map DNS requests to views based on the source

and 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
"The nom-tell Command Channel Client").
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:

{
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:

cacheserve-deleteconf 132
{
}
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:

{
}
cacheserve-deleteconf
cacheserve-deleteconf gives you a way to delete an element's configuration in textual
format.
Two ways to edit

cacheserve-deleteconf can modify data in two ways:
l By updating a running server, or

l By updating a configuration database.
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 address The address value of the element to be

deleted..

133 cacheserve-deleteconf options
Option What it does
--channel channel Instructs cacheserve-deleteconf to

communicate with the running server using a
different /etc/channel.conf value than the
default.
The named channel must already exist in

/etc/channel.conf: see "The /etc/channel.conf
file".
-c database Instructs cacheserve-deleteconf to modify the

or designated configuration database instead of
--configuration database communicating with the running server.
CacheServe must not be using the database

at the same time you use cacheserve-
deleteconf to modify the database.
--destination-address address The destination-address field of the object

being deleted
--layer layer Instructs cacheserve-deleteconf to the use the

configuration from the specified layer instead
of the default (operator) layer.
--list list The list field of the object being deleted.
--name name The name field of the object being deleted.
-t type Required.
or
Instructs cacheserve-deleteconf to remove an
--object-type type
element of this type.
--policy policy The policy field of the object being deleted.
--server server The server field of the object being deleted.
--source-address address The source-address field of the object being

deleted.
--version Displays cacheserve-deleteconf's version and

exits.
--view view The view field of the object being deleted.

cacheserve-dumpconf 134
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.
cacheserve-dumpconf options
Option What it does
--all Retrieves multiple objects. If --object-type is

specified, retrieves all objects of that type.
--address value The address key field of the object being

dumped.
--channel channel Instructs cacheserve-dumpconf to

communicate with the running server using
a different /etc/channel.conf value than the
default.

file".
-c database Instructs cacheserve-dumpconf to use the

CacheServe must not be using the

database at the same time you use
cacheserve-dumpconf to dump the
database.

135 cacheserve-dumpconf options
Option What it does
--destination-address value The destination-address key field for the

object being dumped.
--json Dumps configuration objects as JSON

objects.
--layer layer Instructs cacheserve-dumpconf to use the

configuration from the specified layer
instead of the default (operator) layer.
--list value The list key field for the object being
dumped.
--list-all value Lists all objects or all objects of a specific

type.
If --object-type is specified, all objects of that

type are retrieved. If not, all objects are
retrieved, with each object's configuration
including an object field indicating its type.
--name value Specifies the name of the object being

dumped.
-t type or Required.
--object-type type
Instructs cacheserve-dumpconf to dump an
object of this type.
Required unless --all or --list-all are present.

If --all or --list-all are present, all objects of
this type are dumped.
--policy value The policy key field of the object being

dumped.
--server value The server key field of the object being

dumped.
--source-address value The source-address key field of the object

being dumped.

cacheserve-editconf 136
Option What it does
--version Displays cacheserve-dumpconf's version and

exits.
--view value The view key field of the object being

dumped.
cacheserve-editconf
cacheserve-editconf gives you a way to edit Cacheserve's configuration in textual format.
Two ways to edit

cacheserve-editconf can edit in two ways:

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

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.
cacheserve-editconf options
Option What it does
--address value The address key field of the object being

modified.
--channel channel Instructs cacheserve-editconf to

communicate with the running server using
a different /etc/channel.conf value than the
default.

file"

137 cacheserve-editconf options
Option What it does
-c database Instructs cacheserve-editconf to modify the


cacheserve-editconf to edit the database.
--destination-address value The destination-address key field for the

object being modified.
--json Edits configuration objects as JSON objects.
--layer layer Instructs cacheserve-editconf to use the con-

figuration from the specified layer instead of
the default (operator) layer.
--list value The list key field for the object being mod-
ified.
--name value Specifies the name of the object being mod-

ified.
-t type or Required.
--object-type type
Instructs cacheserve-editconf to modify an
object of this type.
--policy value The policy key field of the object being mod-
ified.
--server value The server key field of the object being mod-
ified.
--source-address value The source-address key field of the object

being modified.
--version Displays cacheserve-editconf's version and

exits.
--view value The view key field of the object being mod-
ified.

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
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 be non-operational in 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.
Option What it does
--all Loads multiple objects. If --object-type

is specified, all objects are of that
type.
--all does not attempt to reconnect if

the connection is dropped, and is
therefore not recommended if you
are updating a running server.

139 Configuration checking limitations
Option What it does
--channel channel Instructs cacheserve-loadconf to

communicate with the running server
using a different /etc/channel.conf
value than the default.
The named channel must already

exist in /etc/channel.conf: see "The
/etc/channel.conf file".
--check Instructs cacheserve-loadconf to

check the configuration without actu-
ally loading it.
-c database Instructs cacheserve-loadconf to

or modify the designated configuration
--configuration database database instead of communicating
with the running server.

cacheserve-loadconf to load the
database.
--json Loads configuration objects as JSON

objects.
--layer layer Instructs cacheserve-loadconf to the

use the configuration from the
specified layer instead of the default
(operator) layer.
-t type Required.
or
Instructs cacheserve-loadconf to load
--object-type type
an element of this type.
Required unless --all is present; if --all

is present, then multiple objects of
this type may be loaded.

Option What it does
-u Updates an existing configuration.

The syntax for updating and deleting
or
individual fields is the same as that
--update for Nominum Command Channel
updates.
--version Displays cacheserve-loadconf's ver-

sion and exits.
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.
Options
Option Description
--channel channel Communicate with the running server using the specified
channel (as configured in /etc/channel.conf), instead of the
default (cacheserve).
-c, --count count Specify that cacheserve-stats should display statistics at

most this many times, rather than running until
interrupted.

141 Options
Option Description
--cpu Generates CPU usage statistics (versus standard statistics).

CPU usage statistics are mutually exclusive with standard
statistics.
When generating CPU statistics, cacheserve-stats prints

percentages of user, system (sys), and total CPU time for
each thread group as well as the totall process (proc).
The thread groups are:
l udp
l rec (recursion)
l cc (Command Channel)
l ccp (Command Channel provisioning)
l prov (Kafka provisioning)
l kafka
l stat (statmon)
l other
l def (default)
Statistic names are of the form <group>-<type>; the current-

time statistic is also reported.
By default, cacheserve-stats displays the statistics:
l proc-user
l proc-sys
l proc-total
l udp-user
l udp-sys
l udp-total
l rec-user
l rec-sys
l rec-total
--csv Generate output in comma separated value form, rather

than a table. In CSV form, a single header line is emitted,
and the full statistics names are used, not the abbreviated
versions.

Statistics 142
Option Description
-o, --statistics statistics-list 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
l responses-sent
l requests-sent
l responses-received
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, --version Display the version of the server and exit.
-w, --wait interval Specify how long to wait between consecutive

measurements, in seconds. The 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.
l cpu-time (total %cpu): The sum of user-time and system-time.
l current-time (current time): The current time, in seconds since the UNIX epoch.
l efficiency (q/cpusec): Indicates how many queries Vantio CacheServe has processed
per second 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 hit-rate (hit-rate %): Indicates the total cache hit rate, computed as the percentage of
DNS lookups that could be satisfied from the cache and/or configuration.

143 Statistics
memory-in-use (memory in-use): These instantaneous measurements are printed

with no postprocessing.
l rate-limited-requests (auth drop/s)
l recursion-contexts-in-use (recur cntxs)
l requests-no-view (no view/s): These running packet counts are converted to packet
rates (packets/second).
l requests-received (clnt req/s)
l requests-sent (auth req/s)
l responses-received (auth resp/s)
l responses-sent (clnt resp/s)
l system-time (sys %cpu): These running time measurements are converted into
percentages of the total available CPU time.
l tcp-clients (tcp clnts)
l tcp-requests-sent (tcp sent/s)
l uptime (uptime): The amount of time that the Vantio CacheServe instance has been
running, in seconds.
l user-time (user %cpu)

Chapter 15: CacheServe
configuration object expan-
ded reference
CacheServe uses configuration objects to contain its configuration.
This expanded reference provides summaries of each object, as well as the commands for
each object, the object's supported fields, and the object's supported events.
The quick reference section provides simple summaries of each object, if you're just
looking for a quick overview of each object.
action
actions represent actions that may be referenced by name by other actions.
Commands
actions accept the following commands:
Command Description
action.add Creates a new action.
action.count Counts actions.
action.delete Deletes an action.
action.get Retrieves an action.

145 Supported Fields
Command Description
action.list Lists all actions.
action.mget Retrieves multiple actions.
action.replace Replaces the values for an action.
action.update Updates an action with new values or resets values

to their defaults.
Supported Fields
actions support the following fields:
action
Optional
policy-action
The action associated with this named action. If this value is not set, the action has no
effect.
comment
Optional
string
A comment describing this object. Contains user-specific data relating to or identifying the
containing object.
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:

Events 146
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'}
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
Edits to be applied before the layer is composited.
Events
actions report the following events:
l action.changed
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.

Command Description
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.
address-list.update Updates an address-list with new values or resets

values to their defaults.
Supported Fields
address-lists support the following fields:
comment
Optional
string
containing object.
count
integer
errors
Optional
(string ...)


lowest-address-v4
Read-only
addr4
The lowest IPv4 address in this list.
lowest-address-v6
Read-only
addr6
The lowest IPv6 address in this list.
name
Required
string
post-edits
Optional
pre-edits
Optional
representative-address-v4
Optional
addrpat4

149 Events
Defaults to the lowest IPv4 address in the list.
An IPv4 address that represents this list. The address normally matches the list, but is not
required to match. Currently used as part of edns-client-subnet equivalence classes.
Optional
addrpat6
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.
address-node.update Updates an address-node with new values or

resets values to their defaults.
Supported Fields
address-nodes support the following fields:

address
Required
addrpat
The address or network represented by this node.
comment
Optional
string
containing object.
errors
Optional
(string ...)

list
Required
string
The list with which this object is associated.
post-edits
Optional

151 Events
pre-edits
Optional
tag
Optional
string
An opaque tag associated with this object.
Events
address-nodes report the following events:
l address-node.changed
auth-server-list
auth-server-lists contain nodes that represent authoritative server configuration. The

contents of auth-server-lists are made up of auth-server-nodes.
Commands
auth-server-lists accept the following commands:
Command Description
auth-server-list.add Creates a new auth-server-list.
auth-server-list.delete Deletes an auth-server-list.
auth-server-list.get Retrieves an auth-server-list.
auth-server-list.list Lists all auth-server-lists.
auth-server-list.mget Retrieves multiple auth-server-lists.
auth-server-list.replace Replaces the values for an auth-server-list.
auth-server-list.update Updates an auth-server-list with new values or


Supported Fields
auth-server-lists support the following fields:
comment
Optional
string
containing object.
count
integer
errors
Optional
(string ...)

name
Required
string
post-edits
Optional

153 Events
pre-edits
Optional
Events
auth-server-lists report the following events:
l auth-server-list.changed
auth-server-node
auth-server-nodes represent authoritative name servers. auth-server-nodes make up the
contents of auth-server-lists.
Commands
auth-server-nodes accept the following commands:
Command Description
auth-server-node.add Creates a new auth-server-node.
auth-server-node.delete Deletes an auth-server-node.
auth-server-node.get Retrieves an auth-server-node.
auth-server-node.list Lists all auth-server-nodes.
auth-server-node.mget Retrieves multiple auth-server-nodes.
auth-server-node.replace Replaces the values for an auth-server-node.
auth-server-node.update Updates an auth-server-node with new values or

Supported Fields
auth-server-nodes support the following fields:
address
Required
addrpat

comment
Optional
string
containing object.
dnssec-aware
Optional
boolean
Indicates whether or not DNSSEC information should be requested from matching

authoritative servers and cached, overriding any resolver configuration.
edns
Optional
boolean
If set to false, disables the use of EDNS in queries to matching authoritative servers.
errors
Optional
(string ...)

ignore
Optional
boolean

155 Events
If set to true, indicates that no queries should be sent to the authoritative server
represented by this node.
list
Required
string
max-edns-udp-size
Optional
integer
Configures the advertised EDNS packet size, overriding any resolver configuration. The
default is 4096.
When this field is configured, CacheServe, when sending EDNS queries to matching
authoritative servers, advertises that packets of up to this length (in bytes) can be
reassembled.
post-edits
Optional
pre-edits
Optional
Events
auth-server-nodes report the following events:
l auth-server-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 a binding.
binding.update Updates a binding with new values or resets values to their defaults.
Supported Fields
Bindings take the following fields:
comment
Optional
string
containing object.
errors
Optional
(string ...)

policy
Required

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. Indicates that the binding
target is the server object. This binding matches all queries.

Events 158
view
Optional
string
Indicates that the binding target is a view, and that this binding matches all queries
handled by the view. Mutually exclusive with the server field.
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:

Command Description
connection.get Retrieves a connection.
connection.subscribe-all Subscribes a connection to all events, over-

riding any existing list of events.
connection.replace Replaces the values of a connection.
connection.update Updates a connection with new values or

Supported Fields
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.
device-list
device-lists contain nodes that represent device identifiers, and are used in the "device"
policy-selector. The contents of device-lists are made up of device-nodes.
Commands
device-lists accept the following commands:

Command Description
device-list.add Creates a new device-list.
device-list.count Counts device-lists.
device-list.delete Deletes an device-list.
device-list.get Retrieves a device-list.
device-list.list Lists all device-lists.
device-list.mget Retrieves multiple device-lists.
device-list.replace Replaces the values for a device-list.
device-list.update Updates a device-list with new values or resets val-

ues to their defaults.
Supported Fields
device-lists support the following fields:
comment
Optional
string
containing object.
count
integer
errors
Optional
(string ...)

161 Events

name
Required
string
post-edits
Optional
pre-edits
Optional
Events
device-lists report the following events:
l device-list.changed
device-node
device-nodes represent device identifiers. Each device-node contains a device identifier and
an associated view. device-nodes are aggregated into device-lists, which are used in policy
selectors.
Device-nodes are indexed by their views and identifiers: a device-node does not possess a
separate unique name.
When retrieving multiple nodes with the device-node.list or device-node.mget

commands, the list argument is optional. If the list argument is present, only nodes
associated with that list are retrieved. If no list argument is specified, all nodes in all lists
are returned.

device-nodes accept the following commands:
Command Description
device-node.add Creates a new device-node.
device-node.delete Deletes an device-node.
device-node.get Retrieves an device-node.
device-node.list Lists all device-nodes.
device-node.mget Retrieves multiple device-nodes.
device-node.replace Replaces the values for an device-node.
device-node.update Updates an device-node with new values or resets

Supported Fields
device-nodes support the following fields:
comment
Optional
string
containing object.
errors
Optional
(string ...)

identifier
Required

163 Events
string
The device identifier.
list
Required
string
post-edits
Optional
pre-edits
Optional
view
Required
string
The view to which this object applies.
Events
device-nodes report the following events:
l device-node.changed
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.

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 of a connection.
dns64.update Updates a connection with new values or

Supported Fields
dns64 objects take the following fields:
comment
Optional
string
containing object.
errors
Optional
(string ...)


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.
mapped
Optional
(acl-element4 ...)
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
An arbitrary string that uniquely identifies the DNS64 instance.
post-edits
Optional
pre-edits
Optional

Events 166
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
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
Note: The layer and provisioning features require an N2 or ThreatAvert license in addition
to the CacheServe base license.
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.

167 Layers and Provisioning
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).
The preconfigured operator layer always exists, cannot be deleted, and has a priority value
of 0, which means it takes precedence over all other layers.
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.
All provisioning events are contained in the layer namespace (for example, the provisioning
connection event is layer.provisioning-connected).
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 provisioning 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.
layers accept the following commands:
Command Description
layer.add Creates a new layer.
layer.clear-fault Clears faults from a layer's provisioning session and

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.
layer.reimage Erases all data from the layer, and reloads layer data
from the provisioning server.
layer.replace Replaces the values for a layer.
layer.update Updates a layer with new values or resets values to

their defaults.

Supported Fields
Layers support the following fields:
channel
Optional
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.
comment
Optional
string
containing object.
errors
Optional
(string ...)

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.

169 Events
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
(addr-or-nameuint16, string)
A composite of (addr-or-name, uint16, string) 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) 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:

name-group 170
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-group
A name-group is a collection of name-lists and other name-groups. name-groups are used
in the "qname-in-group" policy-selector.
name-groups accept the following commands:
Command Description
name-group.add Creates a new name-group.
name-group.count Counts name-groups.
name-group.delete Deletes a name-group.
name-group.list Retrieves a name-group.
name-group.mget Lists all name-groups.
name-group.mget Retrieves multiple name-groups.
name-group.replace Replaces the values for a name-group.
name-group.update Updates a name-group with new values or resets values

to their defaults.
Supported Fields
name-groups support the following fields:
comment
Optional
string
containing object.

errors
Optional
(string ...)

groups
Optional
(string ...)
Lists the other name-groups that are part of this group.
lists
string
The name-lists that are part of this group.
name
Required
string
post-edits
Optional
pre-edits
Optional

Events 172
Events
name-groups report the following events:
l name-group.changed
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.
name-list.update Updates a name-list with new values or resets values to

their defaults.
Supported Fields
name-lists support the following fields:
comment
Optional
string
containing object.

173 Events
count
integer
errors
Optional
(string ...)

name
Required
string
The name of the list.
post-edits
Optional
pre-edits
Optional
Events
name-lists report the following events:
l name-list.changed

name-node 174
name-node
name-nodes represent all data associated with a single name in a 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.
name-node.update Updates a name-node with new values or resets values

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

175 Events
name
Required
string
post-edits
Optional
pre-edits
Optional
tag
Optional
string
Events
name-nodes report the following events:
l name-node.changed
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 policy-selector, which determines whether or not the policy should be applied to a

query.
l A policy-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
A list of strings identifying child policies attached to the current policy. All children are
executed immediately after the parent policy.
comment
Optional
string
containing object.

errors
Optional
(string ...)

name
Required
string
post-edits
Optional
pre-edits
Optional
selector
Required
policy-selector
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.
The boolean AND and OR selectors support lists of selectors, and the NOT selector inverts
the result of another selector.

Events 178
Policies with no selector specified match all queries.
Events
policies report the following events:
l policy.changed
l policy.hit
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.
comment
Optional
string

containing object.
errors
Optional
(string ...)

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

Events 180
The name of the ratelimiter.
post-edits
Optional
pre-edits
Optional

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.
More than one resolver may be configured, which permits you to create customized DNS
environments.
resolvers accept the following commands:

Command Description
resolver.add Creates a new resolver.
resolver.delete Deletes a resolver.
resolver.flush Flushes a resolver's cache.
resolver.get Retrieves a resolver.
resolver.inspect Retrieves information about a name in the resolver's cache.
resolver.inspect-del- Retrieves information about a delegation point in the

egation resolver's cache.
resolver.inspect-for- Retrieves information about forwarders in the resolver's

warders cache.
resolver.list Lists all resolvers.
resolver.mget Retrieves multiple resolvers.
resolver.replace Replaces the values for a resolver.
resolver.statistics Returns statistics for a resolver.
resolver.update Updates a resolver with new values or resets values to their

defaults.
Supported Fields
Resolvers support the following fields:
auth-server-list
Optional
string
Then name of the auth-server-list containing configuration for specific authoritative

servers.
client-subnet
Optional

{
blacklist => (name ...)
equivalence-classes => (string ...)
max-source-prefix-v4 (ipv4netlen ...)
valid-addresses => (acl-element ...)
whitelist => (name ...)
}
Configures domains that should return responses specific to the source address of the
query.
The whitelist configures domains for which source-specific queries should be enabled, and
the blacklist disables domains.
The max-source-prefix fields for v4 and v6 control how client addresses are truncated for
sending edns-client-subnet options and caching. The specification recommends truncating
IPv4 address to no more than 24 bits; this is the default. No recommendation is provided
for IPv6; the default is 48 bits. Higher values may cause considerable growth in cache
memory. In both cases, the minimum value is 1, and the maximum value is the full length
of an address (32 or 128).
equivalence-classes categorizes client addresses into groups, each of which is represented

by an address-list. When a client matches one of those groups, the representative-address
for that group is used in outgoing edns-client-subnet options instead of a truncated client
address.
The valid addresses acl specifies which addresses present in edns-client-subnet options
provided by clients are valid. A network is considered valid if it either contains the actual
client address or matches this acl.
comment
Optional
string
containing object.
dnssec-aware
Optional
boolean

Indicates whether or not DNSSEC information should be requested and cached. The default
is false, and DNSSEC signatures are not verified unless dnssec-aware is configured.
Configuring either trusted-keys or managed-keys automatically enables dnssec-aware.
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.
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 uses 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
The default is false.
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.
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.
Theresolver.id-spoofing-suspected event is generated when the defense mechanism is

triggered, and 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).
Note: Configuring managed-keys automatically enables dnssec-aware.
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 cannot 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.
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 1G (1 gigabyte).
Values larger than 16G are treated as 16G, and values smaller than 64M are treated as 64M.

max-cache-ttl
Optional
time-in-seconds
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.
If you find that CacheServe is rapidly exhausting its supply of file descriptors as a result of
truncated responses (for example, due to ratelimiting), modifying this setting may help.
The default value should be sufficient for most use cases.
min-cache-ttl
Optional
time-in-seconds
Sets the minimum amount of time for which the server will cache ordinary (positive)
answers.
Values in excess of 15 minutes or the value of max-cache-ttl are clamped to the minimum
of those values.
Note: The minimum may not be applied in all cases, such as when limiting the amount of
time DNSSEC-validated records are cached based on signature expiration, or when caching
negative responses without an SOA record.
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,
and values greater than 32 or less than 4 are clamped to 32 or 4 respectively. Setting the
value to 0 completely disables prefetching.
Note: Changing this value is not recommended, and you should only change it under the
direction of Nominum support.
Prefetching is normally performed when a query requests data that's already cached but
will expire soon from the cache. This prevents commonly-accessed data from ever
expiring, and results in a higher cache hit rate and better average latency.
The prefetch-ratio value defines the relationship between the time at which data expires
and the initial TTL (time-to-live) of the data. Specifically, a value of X means that CacheServe
issues a prefetch query if the currently cached data expires in less than 1/X of the initial
TTL.
preload
Optional
((name, rdatatype, rdata) ...)
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 are 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 are 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
prioritized-domains
Optional
string
The name of a list of domains to be prioritized when prefetching. "Prioritization", in this

case, means that for cached data within the listed domains, CacheServe appends
prefetches to a queue. CacheServe will then more aggressively start prefetch queries for
soon-expiring cached data within the listed domains.

Note: The list should contain only known good domains, to better protect those names
from attacks. The list should never contain the root domain or TLDs.
qname-case-randomization
Optional
'enforced' | 'off' | 'silent-enforced' | 'unenforced'
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 are 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)
Sets the address CacheServe uses to send outgoing IPv6 UDP queries, configuring

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.
connections.
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.
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
((name, ((name, (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 cannot
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 have not actually been delegated authority.
For example, if you are 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.

Events 194
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.
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

195 selector
selector
Named selectors (identified as selector objects in CacheServe) specify selectors that may be
referenced by name from other selectors.
Named selectors are useful for using the same selector in multiple conditions, and provide
a way to save memory and change multiple selectors in a single operation.
selectors accept the following commands:
Command Description
selector.add Creates a new named selector.
selector.delete Deletes a named selector.
selector.get Retrieves a named selector.
selector.list Lists all named selectors.
selector.mget Retrieves multiple named selectors.
selector.replace Replaces the values for a named selector.
selector.update Updates a named selector with new values or

Supported Fields
Selectors take the following fields:
name
Required
string
comment
Optional
string
containing object.

Events 196
errors
Optional
(string ...)

post-edits
Optional
pre-edits
Optional
selector
policy-selector
A policy-selector that identifies selection criteria for this named selector.
The boolean AND and OR selectors permit multiple selectors to be evaluated, and the NOT
selector inverts the result of another selector.
If selector is not set, the selector matches all queries.
Events
view-selectors report the following events:
l selector.changed

197 server
server
servers represent a subset of CacheServe configuration that applies to the server as a
whole. Changes made to a server will 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.
server.unblock-checkpoints Deactivates checkpoint blocking for a

server.
server.replace Replaces the values for a server.
server.update Updates a server with new values or resets

Supported Fields
Servers support the following fields:
commands-not-logged
Optional
(string ...)
Specifies a list of Command Channel message types that should not be logged when log-
command-channel is enabled.
Defaults to ().
For example, specifying server.statistics can reduce log clutter.
errors
Optional
(string ...)


listen-on-matching
Optional
({
instances => integer
interface => string
patterns => (acl-element ...)
port => uint16
} ...)
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).
listen-on-matching can be bound to a single interface, such as eth0, by specifying the

interface: see the second example entry below.
Note: instances takes advantage of certain relatively new Linux features, which permit
multiple sockets listening on a single address and port (SO_REUSEPORT). If you have this
capability, set instances to the number of desired UDP sockets.
listen-on-matching can contain multiple elements, which allows different listener ports to be
specified.
l 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.
l If interface is specified, an address is selected only if it is both bound to the specified

interface and matches the patterns ACL.
l 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).

l 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.
Examples
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'
}
)
}
And here's how you specify listen-on-matching with the same values, this time limiting the
interface to eth0:
cacheserve> server.update listen-on-matching=({interface=eth0
patterns=(192.168.1.1) instances=16}{interface=eth0 patterns=
(127.0.0.1) port=5354})
{
}
{
{
interface => 'eth0'
patterns => ('192.168.1.1/32')
instances => '16'
}
{
interface => 'eth0'
patterns => ('127.0.0.1/32')

port => '5354'

}
)
}
log-command-channel
Optional
boolean
Controls whether or not Command Channel messages are logged.
Defaults to false.
When set to true, commands are logged at the LOG_INFO priority, and large commands
are truncated.
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 25,000, and values over 500,000 are capped at 500,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 100,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
100.
Note: UDP clients are controlled by max-recursive-clients.

post-edits
Optional
pre-edits
Optional
server-description
Optional
string
A user-specified text description for this server instance. server-description is visible only in
telemetry, and only when present.
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.

Events 202
time-zone
Optional
string
Identifies the timezone CacheServe will use. Values must match an entry in the 'TZ' column
of the IANA tzdb.
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
telemetry
The telemetry object periodically writes engine samples and events into Kafka.
The telemetry object accepts the following commands:
Command Description
telemetry.get Creates a new telemetry object.
telemetry.replace Replaces the values for the telemetry object.
telemetry.statistics Returns statistics for the telemetry object.
telemetry.update Updates the values for the telemetry object.
Supported Fields
The telemetry object supports the following fields:

comment
Optional
string
containing object.
enable
boolean
Defaults to false. Enables or disables the telemetry object.
interval
integer
Defaults to 5. The sampling interval for telemetry, in seconds.
kafka
Optional
kafka-configuration-field
Configures the Kafka connection and parameters.
post-edits
Optional
pre-edits
Optional
record-events
Optional
(event-name ...)

Events 204
Specifies a list of events to be recorded by the telemetry stream in addition to the standard
periodic sampling. Defaults to no additional events (an empty value).
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
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:
errors
Optional
(string ...)


name
Required
string
post-edits
Optional
pre-edits
Optional
resolver
Required
string
The name of the resolver associated with this view. All DNS operations are performed in
the context of the resolver.
time-zone
Optional
string
of the IANA tzdb.

Events 206
Events
views report the following events:
l view.changed
view-selector
view-selectors map DNS requests to views based on the source and destination addresses
of the request.
view-selectors are specifically tied to views; CacheServe also features named selectors,
which may be used in multiple conditions.
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.
view-selector.query Simulates a query, and returns the view that

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

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 ...)

post-edits
Optional
pre-edits
Optional
source-address
Optional
addrpat
Requires a view-selector's source address to originate within this network.
source-port-mask
Optional
port-mask
If no port masking is desired, set this value to 0.

When defined, masks the specified bits out of the port when this view-selector is the best
match for the source address. The remaining port number is then used to search for a
view-selector that includes the specified port.
CacheServe only uses view selectors with port information when source-port-mask is
defined on the closest match by address.
The source port mask has no effect if source-address is present and contains an IPv6
network or address or if the source-ports field is present.
source-ports-prefix
Optional
ipv4netlen
If this view-selector is the closest match for the source address, and this field is defined,
the source address is truncated to length when searching for a view-selector, including the
port.
View selectors including port information are only used if source-port-mask and/or source-
port-prefix are defined on the closest match by address. If course port processing is
desired, but no masking or truncation is needed, set the source-port-mask field to 0.
The source port prefix has no effect if the source-address field is present and contains an
IPv6 network or address, or if the source-ports field is present.
source-ports
Optional
(uint16, uint16)
This view-selector requires that the source port of the client, after any modification by the
source-port-mask of the view-selector matching the address, is in this range, specified as a
start and length. The range must be aligned: that is, the length must be a power of 2, and
the start must be a multiple of the length.
View selectors that include port information are used only if source-port-mask is defined
on the closest match by address. If no port masking is desired, set source-port-mask to 0.
view
Required
string

209 Events
The name of the view that handles requests matching this view-selector (if no other, more
specific view-selector matches).
Events
view-selectors report the following events:
l view-selector.changed

Chapter 16: Command ref-
erence
action.add
Description and usage
Creates a new action.
Fields
action
Optional
policy-action
effect.
comment
Optional
string
containing object.
post-edits
Optional

211 Examples
pre-edits
Optional
Examples
cacheserve> action.add name=my-action
{
type => 'action.add'
action.count
Counts actions.
Fields
layer
Optional
string
The layer for this object.
Returns
count
integer
The number of matching objects.
action.delete
Deletes an action.

Fields 212
Fields
name
Required
string
layer
Optional
string
Examples
cacheserve> action.delete name=my-action
{
type => 'action.delete'
}
action.get
Retrieves an action, returning details of the action.
Fields
name
Required
string
exclude-fields
Optional
(string ...)
Defines the fields to exclude from a response.

213 Examples
fields
Optional
(string ...)
Defines the fields to include in a response.
layer
Optional
string
Examples
cacheserve> action.get name=my-action
{
type => 'action.get'
name => 'my-action'
count => '0'
}
action.list
Lists actions, optionally sorted by various criteria.
Fields
descending
Optional
boolean
Sorts returned values in descending order.
end
Optional
{
name => string
}
Defines the last value to be returned. The value is the name of an action.

Examples 214
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
Optional
boolean
If present, skip-first causes the object where the key matches start to be skipped.
start
Optional
{
name => string
}
Defines the first value to be returned. The value is the name of a list.
Examples
cacheserve> action.list
{
type => 'action.list'
name => 'my-action'
}

215 action.mget
action.mget
Retrieves multiple actions.
Fields
descending
Optional
boolean
end
Optional
{
name => string
}
Defines the last value to be returned. The value is the name of an action.
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)
key
Optional
string

Examples 216
layer
Optional
string
max-results
Optional
integer
skip-first
Optional
boolean
start
Optional
{
name => string
}
Examples
cacheserve> action.mget
{
type => 'action.mget'
name => 'my-action'
count => '1'
}
{
name => 'your-action'
count => '0'
}
action.replace
Replaces all fields of an action.

217 Fields
Note: Values that are not explicitly specified are cleared.
Fields
name
Required
string
action
Optional
policy-action
effect.
comment
Optional
string
containing object.
layer
Optional
string
post-edits
Optional
pre-edits
Optional

action.update 218
action.update
Updates one or more fields of an action.
Fields
name
Required
string
action
Optional
policy-action
effect.
comment
Optional
string
containing object.
layer
Optional
string
post-edits
Optional

219 Examples
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 treats the
field as if no value were specified (for instance, populating the field with a default value if
necessary).
Examples
cacheserve> action.update name=my-action comment="A comment" lay-
er=operator
{
type => 'action.update'
}
address-list.add
Creates a new address-list.
Fields
name
Required
string
comment
Optional
string

Fields 220
containing object.
layer
Optional
string
post-edits
Optional
pre-edits
Optional
Optional
addrpat4
Optional
addrpat6

221 Examples
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 222
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
exclude-fields
Optional
(string ...)

223 Examples
fields
Optional
(string ...)
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
boolean
end
Optional
{
name => string
}
Defines the last value to be returned. The value is the name of a list.

Examples 224
key
Optional
string
layer
Optional
string
max-results
Optional
integer
skip-first
Optional
boolean
start
Optional
{
name => string
}
Examples
cacheserve> address-list.list
{
type => 'address-list.list'
name => 'my-list'
}

225 address-list.load
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.

Examples 226
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
boolean
end
Optional
{
name => string
}
exclude-fields
Optional
(string ...)

227 Examples
fields
Optional
(string ...)
key
Optional
string
layer
Optional
string
max-results
Optional
integer
skip-first
Optional
boolean
start
Optional
{
name => string
}
Examples
cacheserve> address-list.mget
{

address-list.replace 228
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
comment
Optional
string
containing object.
layer
Optional
string
post-edits
Optional

229 address-list.update
pre-edits
Optional
Optional
addrpat4
Optional
addrpat6
address-list.update
Updates one or more fields of an address-list.
Fields
name
Required
string
comment
Optional
string

containing object.
layer
Optional
string
post-edits
Optional
pre-edits
Optional
Optional
addrpat4
Optional
addrpat6
unset
Optional

231 Examples
(string ...)
necessary).
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
list
Required
string
comment
Optional
string
containing object.
layer
Optional

address-node.delete 232
string
post-edits
Optional
pre-edits
Optional
tag
Optional
string
address-node.delete
Deletes an address-node.
Fields
address
Required
addrpat
layer
Optional
string

233 address-node.get
list
Required
string
The address-list to which this address-node belongs.
address-node.get
Retrieves an address-node.
Fields
address
Required
addrpat
list
Required
string
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)
layer
Optional
string

address-node.list 234
address-node.list
Lists address-nodes, optionally sorted by various criteria.
Fields
end
Optional
{
address => addrpat
list => string
}
Defines the last value to be returned. The value is an IP address with the name of the
node's associated address-list.
list
Optional
string
layer
Optional
string
max-results
Optional
integer
start
Optional
{
address => addrpat

235 address-node.mget
list => string

}
Defines the first value to be returned. The value is an IP address with the name of the
address-node.mget
Retrieves multiple address-nodes.
Fields
end
Optional
{
address => addrpat
list => string
}
Defines the last value to be returned. The value is an IP address with the name of the
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)
layer
Optional
string

address-node.replace 236
list
Optional
string
max-results
Optional
integer
start
Optional
{
address => addrpat
list => string
}
Defines the first value to be returned. The value is an IP address with the name of the
address-node.replace
Replaces all fields of an address-node.
Fields
address
Required
addrpat
list
Required
string

237 address-node.update
comment
Optional
string
containing object.
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 238
Fields
address
Required
addrpat
list
Required
string
comment
Optional
string
containing object.
layer
Optional
string
post-edits
Optional
pre-edits
Optional

239 auth-server-list.add
tag
Optional
string
unset
Optional
(string ...)
necessary).
auth-server-list.add

Creates a new auth-server-list.
Fields
name
Required
string
comment
Optional
string
containing object.
layer
Optional

auth-server-list.delete 240
string
post-edits
Optional
pre-edits
Optional
auth-server-list.delete

Deletes an auth-server-list.
Fields
name
Required
string
layer
Optional
string

241 Examples
Examples
cacheserve> auth-server-list.delete name=my-auth-list
{
type => 'auth-server-list.delete'
}
auth-server-list.get

Retrieves an auth-server-list, returning details of the list.
Fields
name
Required
string
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)
layer
Optional
string

Examples 242
Examples
cacheserve> auth-server-list.get name=my-auth-list
{
type => 'auth-server-list.get'
name => 'my-auth-list'
count => '0'
}
auth-server-list.list

Lists auth-server-lists.
Fields
descending
Optional
boolean
end
Optional
{
string
}
Defines the last value to be returned.
key
Optional
string
layer
Optional
string

243 Examples
max-results
Optional
integer
skip-first
Optional
boolean
start
Optional
{
name => string
}
Examples
cacheserve> auth-server-list.list
{
type => 'auth-server-list.list'
}
auth-server-list.mget

Retrieves multiple auth-server-lists.
Fields
descending
Optional
boolean

Fields 244
end
Optional
{
name => string
}
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)
key
Optional
string
layer
Optional
string
max-results
Optional
integer

245 Examples
skip-first
Optional
boolean
start
Optional
{
name => string
}
Examples
cacheserve> auth-server-list.mget
{
type => 'auth-server-list.mget'
name => 'loadlist'
count => '1'
}
{
count => '0'
}
auth-server-list.replace

Replaces all fields of an auth-server-list.
Fields
name
Required
string

auth-server-list.update 246
comment
Optional
string
containing object.
layer
Optional
string
post-edits
Optional
pre-edits
Optional
auth-server-list.update

Updates one or more fields of an auth-server-list.
Fields
name
Required
string

247 Examples
comment
Optional
string
containing object.
layer
Optional
string
post-edits
Optional
pre-edits
Optional
unset
Optional
(string ...)
necessary).
Examples
cacheserve> auth-server-list.update name=my-auth-list layer=operator
{
type => 'auth-server-list.update'
}

auth-server-node.add 248
auth-server-node.add
Creates a new auth-server-node.
Fields
address
Required
addrpat
list
Required
string
comment
Optional
string
containing object.
dnssec-aware
Optional
boolean

edns
Optional
boolean

249 Fields
ignore
Optional
boolean
layer
Optional
string
max-edns-udp-size
Optional
integer
default is 4096.
reassembled.
post-edits
Optional
pre-edits
Optional

Examples 250
Examples
cacheserve> auth-server-node.add name=my-node
{
type => 'auth-server-node.add'
auth-server-node.delete
Deletes an auth-server-node.
Fields
address
Required
addrpat
list
Optional
string
layer
Optional
string
Examples
cacheserve> auth-server-node.delete name=my-node
{
type => 'auth-server-node.delete'

251 auth-server-node.get
auth-server-node.get
Retrieves an auth-server-node, returning details of the node.
Fields
address
Required
addrpat
list
Optional
string
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)
layer
Optional
string

auth-server-node.list 252
auth-server-node.list
Lists auth-server-nodes.
Note: When retrieving multiple nodes with the auth-server-node.list command, the list
argument is optional. If list is absent, all nodes in all lists are retrieved.
Fields
list
Optional
string
descending
Optional
boolean
end
Optional
{
address => addrpat
list => string
}
key
Optional
string
layer
Optional
string

253 auth-server-node.mget
max-results
Optional
integer
skip-first
Optional
boolean
start
Optional
{
address => addrpat
list => string
}
Defines the first value to be returned.
auth-server-node.mget
Retrieves multiple auth-server-nodes.
Note: When retrieving multiple nodes with the auth-server-node.mget command, the list
argument is optional. If list is absent, all nodes in all lists are retrieved.
Fields
descending
Optional
boolean
end
Optional

Fields 254
{
address => addrpat
list => string
}
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)
key
Optional
string
layer
Optional
string
max-results
Optional
integer
skip-first
Optional
boolean

255 auth-server-node.replace
start
Optional
{
address => addrpat
list => string
}
auth-server-node.replace
Replaces all fields of an auth-server-node.
Fields
address
Required
addrpat
list
Required
string
comment
Optional
string
containing object.
dnssec-aware
Optional

Fields 256
boolean

edns
Optional
boolean
ignore
Optional
boolean
max-edns-udp-size
Optional
integer
default is 4096.
reassembled.
layer
Optional
string
post-edits
Optional

257 auth-server-node.update
pre-edits
Optional
auth-server-node.update
Updates one or more fields of an auth-server-node.
Fields
address
Required
addrpat
list
Required
string
comment
Optional
string
containing object.
dnssec-aware
Optional
boolean


edns
Optional
boolean
ignore
Optional
boolean
max-edns-udp-size
Optional
integer
default is 4096.
reassembled.
layer
Optional
string
post-edits
Optional
pre-edits
Optional

259 binding.add
unset
Optional
(string ...)
necessary).
binding.add
Creates a new binding.
Fields
policy
Required
string
priority
Required
integer

Fields 260
comment
Optional
string
containing object.
layer
Optional
string
post-edits
Optional
pre-edits
Optional
server
Optional
boolean
view
Optional
string

261 binding.delete
when
Optional
execute.
prequery
postquery
query.
presend
binding.delete
Deletes a binding.
Fields
policy
Required
string
layer
Optional
string

binding.get 262
server
Optional
boolean
view
Optional
string
binding.get
Retrieves a policy binding.
Fields
policy
Required
string
exclude-fields
Optional
(string ...)
fields
string
layer
Optional

263 binding.list
string
server
Optional
boolean
view
Optional
string
binding.list
Lists policy bindings, optionally sorted by various criteria.
Fields
end
Optional
{
policy => string
server => '1'
view => string
Defines the last value to be returned. The value is a policy name, and either or both of the
value '1' for the server or the name of a view.
policy
Required
string

Fields 264
layer
Optional
string
max-results
Optional
integer
server
Optional
boolean
start
Optional
{
policy => string
server => '1'
view => string
Defines the first value to be returned. The value is a policy name, and either or both of the
view
Optional
string

265 binding.mget
binding.mget
Retrieves multiple bindings.
Fields
policy
Required
string
end
Optional
{
policy => string
server => '1'
view => string
Defines the last value to be returned. The value is an policy name, and either or both of the
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)
layer
Optional
string

binding.replace 266
max-results
Optional
integer
server
Optional
boolean
start
Optional
{
policy => string
server => '1'
view => string
Defines the first value to be returned. The value is an policy name, and either or both of
the value '1' for the server or the name of a view.
view
Optional
string
binding.replace
Replaces all fields of a policy binding.

267 Fields
Fields
priority
Required
integer
comment
Optional
string
containing object.
layer
Optional
string
policy
Required
string
post-edits
Optional

Fields 268
pre-edits
Optional
server
Optional
boolean
view
Optional
string
when
Optional
execute.
prequery
postquery
query.
presend

269 binding.update
binding.update
Updates the fields of a policy binding.
Fields
policy
Required
string
comment
Optional
string
containing object.
layer
Optional
string
post-edits
Optional
pre-edits
Optional

Fields 270
priority
Optional
integer
server
Optional
boolean
when
Optional
execute.
prequery
postquery

271 connection.get
query.
presend
view
Optional
string
unset
Optional
(string ...)
necessary).
connection.get
Retrieves a connection configuration.
Fields
exclude-fields
Optional
(string ...)
fields
Optional

connection.replace 272
(string ...)
connection.replace
Replaces field values for a Command Channel connection configuration.
Fields
events
Optional
(event-name ...)
idle-timeout
Optional
time-in-seconds
no timeout.
connection.subscribe-all
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

273 device-list.add
(event-name ...)
idle-timeout
Optional
time-in-seconds
no timeout.
unset
Optional
(string ...)
necessary).
device-list.add
Creates a new device-list.
Fields
name
Required
string
comment
Optional
string

Examples 274
containing object.
layer
Optional
string
post-edits
Optional
pre-edits
Optional
Examples
cacheserve> device-list.add name=my-device-list
{
type => 'device-list.add'
device-list.count
Counts device-lists.
Fields
layer
Optional
string

275 Returns
Returns
count
integer
device-list.delete
Deletes a device-list.
Fields
name
Required
string
layer
Optional
string
Examples
cacheserve> device-list.delete name=my-device-list
{
type => 'device-list.delete'
}
device-list.get
Retrieves a device-list, returning details of the device-list.

Fields 276
Fields
name
Required
string
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)
layer
Optional
string
Examples
cacheserve> device-list.get name=my-device-list
{
type => 'device-list.get'
name => 'my-device-list'
count => '0'
}
device-list.list
Lists device-lists, optionally sorted by various criteria.

277 Fields
Fields
descending
Optional
boolean
end
Optional
{
name => string
}
Defines the last value to be returned. The value is the name of a device-list.
key
Optional
string
layer
Optional
string
max-results
Optional
integer
skip-first
Optional
boolean

Examples 278
start
Optional
{
name => string
}
Examples
cacheserve> device-list.list
{
type => 'device-list.list'
}
device-list.mget
Retrieves multiple device-lists.
Fields
descending
Optional
boolean
end
Optional
{
name => string
}
Defines the last value to be returned. The value is the name of an device-list.
exclude-fields
Optional
(string ...)

279 Examples
fields
Optional
(string ...)
key
Optional
string
layer
Optional
string
max-results
Optional
integer
skip-first
Optional
boolean
start
Optional
{
name => string
}
Examples
cacheserve> device-list.mget
{

type => 'device-list.mget'

count => '1'
}
{
name => 'your-device-list'
count => '0'
}
device-list.replace
Replaces all fields of a device-list.
Fields
name
Required
string
comment
Optional
string
containing object.
layer
Optional
string
post-edits
Optional

281 device-list.update
pre-edits
Optional
device-list.update
Updates one or more fields of a device-list.
Fields
name
Required
string
comment
Optional
string
containing object.
layer
Optional
string
post-edits
Optional
pre-edits
Optional

Examples 282
unset
Optional
(string ...)
necessary).
Examples
cacheserve> device-list.update name=my-device-list comment="A com-
ment" layer=operator
{
type => 'device-list.update'
}
device-node.add
Creates a new device-node.
Fields
identifier
Required
string
list
Required
string
view
Required

283 device-node.count
string
comment
Optional
string
containing object.
layer
Optional
string
post-edits
Optional
pre-edits
Optional
device-node.count
Counts device-nodes.
Fields
list
Optional
string

Returns 284
layer
Optional
string
Returns
count
integer
device-node.delete
Deletes a device-node.
Fields
identifier
Required
string
view
Required
string
list
Optional
string
layer
Optional
string

285 Examples
Examples
cacheserve> device-node.delete name=my-device-node
{
type => 'device-node.delete'
}
device-node.get
Retrieves a device-node.
Fields
identifier
Required
string
view
Required
string
list
Optional
string
exclude-fields
Optional
(string ...)

device-node.list 286
fields
Optional
(string ...)
layer
Optional
string
device-node.list
Lists device-nodes, optionally sorted by various criteria.
Fields
end
Optional
{
identifier => string
list => string
view => string
Defines the last value to be returned. The value is the device-node's name, along with the
node's associated device-list.
descending
Optional
boolean
layer
Optional
string

287 Returns
list
Optional
string
max-results
Optional
integer
start
Optional
{
list => string
name => name
Defines the first value to be returned. The value is the device-node's name, along with the
node's associated name-list.
Returns
identifier
Required
string
list
Optional
string
view
Required

device-node.mget 288
string
device-node.mget
Retrieves multiple device-nodes.
Fields
list
Optional
string
descending
Optional
boolean
end
Optional
{
identifier => string
list => string
view => name
Defines the last value to be returned. The value is the device-node's name, along with the
exclude-fields
Optional
(string ...)

289 Fields
fields
Optional
(string ...)
key
Optional
string
layer
Optional
string
max-results
Optional
integer
skip-first
Optional
boolean
start
Optional
{
list => string
name => name
Defines the first value to be returned. The value is the device-node's name, along with the

device-node.replace 290
device-node.replace
Replaces all values on a device-node with new values.
Fields
identifier
Required
string
list
Required
string
view
Required
string
comment
Optional
string
containing object.
layer
Optional
string
post-edits
Optional

291 device-node.update
pre-edits
Optional
device-node.update
Updates one or more values on a device-node with new values.
Fields
identifier
Required
string
list
Required
string
view
Required
string
comment
Optional
string
containing object.

dns64.add 292
layer
Optional
string
post-edits
Optional
pre-edits
Optional
unset
Optional
(string ...)
necessary).
dns64.add
Creates a new DNS64 layer.
Fields
name
Required
string

293 Fields
prefix
Required
addrpat6
l 32
l 40
l 48
l 56
l 64
l 96
comment
Optional
string
containing object.
exclude
Optional
(acl-element6 ...)
that contain them.
layer
Optional
string
mapped
Optional
(acl-element4 ...)

dns64.delete 294
records.
post-edits
Optional
pre-edits
Optional
suffix
Optional
addr6
dns64.delete
Deletes a dns64 configuration.
Fields
name
Required
string
layer
Optional

295 dns64.get
string
dns64.get
Retrieves a dns64 configuration.
Fields
name
Required
string
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)
layer
Optional
string
dns64.list
Lists dns64 configurations, optionally sorted by various criteria.

Fields 296
Fields
descending
Optional
boolean
end
Optional
{
name => string
Defines the last value to be returned. The value is the name of a DNS64 key.
key
Optional
string
layer
Optional
string
max-results
Optional
integer
skip-first
Optional
boolean

297 dns64.mget
start
Optional
{
name => string
Defines the first value to be returned. The value is the name of a DNS64 key.
dns64.mget
Retrieves multiple DNS64 configurations.
Fields
descending
Optional
boolean
end
Optional
string
end
Optional
{
name => string
Defines the last value to be returned. The value is the name of a DNS64 key.
exclude-fields
Optional
(string ...)

Fields 298
fields
Optional
(string ...)
key
Optional
string
layer
Optional
string
max-results
Optional
integer
skip-first
Optional
boolean
start
Optional
{
name => string
Defines the first value to be returned. The value is the name of a DNS64 key.

299 dns64.replace
dns64.replace
Replaces values for a dns64 layer.
Fields
name
Required
string
prefix
Required
addrpat6
l 32
l 40
l 48
l 56
l 64
l 96
comment
Optional
string
containing object.
exclude
Optional
(acl-element6 ...)

Fields 300
that contain them.
layer
Optional
string
mapped
Optional
(acl-element4 ...)
records.
post-edits
Optional
pre-edits
Optional
suffix
Optional
addr6

301 dns64.update
dns64.update
Updates fields for a dns64 layer.
Fields
name
Required
string
comment
Optional
string
containing object.
exclude
Optional
(acl-element6 ...)
that contain them.
layer
Optional
string
mapped
Optional
(acl-element4 ...)

Fields 302
records.
post-edits
Optional
pre-edits
Optional
prefix
Required
addrpat6
l 32
l 40
l 48
l 56
l 64
l 96
suffix
Optional
addr6
unset
Optional

303 instance-information
(string ...)
necessary).
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.
l The second string is the role of the partner process.
layer.add
Creates a new layer.
Fields
name
Required
string

Fields 304
priority
Required
integer
comment
Optional
string
containing object.
channel
Optional
string
field.
hidden
Optional
boolean

305 Examples
configuration.
server
Optional

Examples
cacheserve> layer.add name=second-layer priority=1
{
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.

Fields 306
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.

307 Fields
Fields
descending
Optional
boolean
end
Optional
{
name => string
Defines the last value to be returned. The value is the name of a layer.
key
Optional
string
max-results
Optional
integer
skip-first
Optional
boolean
start
Optional
{
name => string

layer.mget 308
Defines the first value to be returned. The value is the name of a layer.
layer.mget
Retrieves multiple layers.
Fields
descending
Optional
boolean
end
Optional
{
name => string
Defines the last value to be returned. The value is the name of a layer.
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)
key
Optional
string

309 layer.reimage
max-results
Optional
integer
skip-first
Optional
boolean
start
Optional
{
name => string
Defines the first value to be returned. The value is the name of a layer.
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.

Fields 310
Fields
name
Required
string
priority
Required
integer
channel
Optional
string
field.
hidden
Optional
boolean

311 layer.update
configuration.
server
Optional

layer.update
Updates values for a layer.
Fields
name
Required
string
channel
Optional
string
field.
hidden
Optional
boolean

Fields 312
configuration.
priority
Optional
integer
server
Optional

unset
Optional
(string ...)
necessary).

313 name-group.add
name-group.add
Creates a new name-group.
Fields
name
Required
string
comment
Optional
string
containing object.
groups
Optional
(string ...)
lists
string
layer
Optional
string
post-edits
Optional

pre-edits
Optional
name-group.count
Counts name-groups.
Fields
layer
Optional
string
Returns
count
integer
name-group.delete
Deletes an name-group.
Fields
name
Required
string

315 Examples
layer
Optional
string
Examples
cacheserve> name-group.delete name=my-name-group
{
type => 'name-group.delete'
}
name-group.get
Retrieves a name-group, returning details of the name-group.
Fields
name
Required
string
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)
layer
Optional
string

Examples 316
Examples
cacheserve> name-group.get name=my-name-group
{
type => 'name-group.get'
name => 'my-name-group'
count => '0'
}
name-group.list
Lists name-groups, optionally sorted by various criteria.
Fields
descending
Optional
boolean
end
Optional
{
name => string
}
Defines the last value to be returned. The value is the name of a name-group.
key
Optional
string
layer
Optional
string

317 Examples
max-results
Optional
integer
skip-first
Optional
boolean
start
Optional
{
name => string
}
Examples
cacheserve> name-group.list
{
type => 'name-group.list'
}
name-group.mget
Retrieves multiple name-groups.
Fields
descending
Optional
boolean

Fields 318
end
Optional
{
name => string
}
Defines the last value to be returned. The value is the name of an name-group.
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)
key
Optional
string
layer
Optional
string
max-results
Optional
integer
skip-first
Optional

319 Examples
boolean
start
Optional
{
name => string
}
Examples
cacheserve> name-group.mget
{
type => 'name-group.mget'
count => '1'
}
{
name => 'your-name-group'
count => '0'
}
name-group.replace
Replaces all fields of a name-group.
Fields
name
Required
string
comment
Optional
string

name-group.update 320
containing object.
groups
Optional
(string ...)
lists
string
layer
Optional
string
post-edits
Optional
pre-edits
Optional
name-group.update
Updates one or more fields of a name-group.

321 Description and usage
Fields
name
Required
string
comment
Optional
string
containing object.
groups
Optional
(string ...)

(missing or bad snippet)
layer
Optional
string
post-edits
Optional
pre-edits
Optional

Examples 322
unset
Optional
(string ...)
necessary).
Examples
cacheserve> name-group.update name=my-name-group comment="A comment"
layer=operator
{
type => 'name-group.update'
}
name-list.add
Creates a new name-list.
Fields
name
Required
string
comment
Optional
string
containing object.
layer
Optional
string

323 name-list.delete
post-edits
Optional
pre-edits
Optional
name-list.delete
Deletes a name-list.
Fields
name
Required
string
layer
Optional
string
name-list.dump
Dumps the content of a list to the file name-list.dump in the server's current working
directory.

Fields 324
Fields
name
Required
string
name-list.get
Retrieves a name-list.
Fields
name
Required
string
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)
layer
Optional
string

325 name-list.list
name-list.list
Lists name-list configurations, optionally sorted by various criteria.
Fields
descending
Optional
boolean
end
Optional
{
name => string
Defines the last value to be returned. The value is the name of a name-list.
key
Optional
string
layer
Optional
string
max-results
Optional
integer

name-list.load 326
skip-first
Optional
boolean
start
Optional
{
name => string
Defines the first value to be returned. The value is the name of a name-list.
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.

327 Fields
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.
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

Fields 328
boolean
end
Optional
{
name => string
Defines the last value to be returned. The value is the name of a name-list.
layer
Optional
string
max-results
Optional
integer
skip-first
Optional
boolean
start
Optional
{
name => string
Defines the first value to be returned. The value is the name of a name-list.

329 name-list.replace
name-list.replace
Replaces all fields of an name-list.
Fields
name
Required
string
comment
Optional
string
containing object.
layer
Optional
string
post-edits
Optional
pre-edits
Optional

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

331 name-node.add
(string ...)
necessary).
name-node.add
Creates a new name-node.
Fields
list
Required
string
name
Required
string
comment
Optional
string
containing object.
encrypt
Optional
boolean
If true, instructs CacheServe to encrypt the node's name before trying to find or define it.

name-node.delete 332
encrypted
Optional
boolean
layer
Optional
string
post-edits
Optional
pre-edits
Optional
tag
Optional
string
name-node.delete
Deletes a name-node.
Fields
encrypt
Optional
boolean

333 name-node.get
layer
Optional
string
list
Optional
string
name
Required
string
name-node.get
Retrieves a name-node.
Fields
list
Required
string
name
Required
string

name-node.list 334
encrypt
Optional
boolean
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)
layer
Optional
string
name-node.list
Lists name-nodes, optionally sorted by various criteria.
Fields
descending
Optional
boolean
end
Optional

335 Fields
{
list => string
name => name
Defines the last value to be returned. The value is the name-node's name, along with the
key
Optional
string
layer
Optional
string
list
Optional
string
max-results
Optional
integer
skip-first
Optional
boolean
start
Optional

name-node.mget 336
{
list => string
name => name
Defines the first value to be returned. The value is the name-node's name, along with the
name-node.mget
Retrieves multiple name-nodes.
Fields
list
Optional
string
descending
Optional
boolean
end
Optional
{
list => string
name => name
Defines the last value to be returned. The value is the name-node's name, along with the
exclude-fields
Optional
(string ...)

337 Fields
fields
Optional
(string ...)
key
Optional
string
layer
Optional
string
max-results
Optional
integer
skip-first
Optional
boolean
start
Optional
{
list => string
name => name

name-node.replace 338
Defines the first value to be returned. The value is the name-node's name, along with the
name-node.replace
Replaces all fields of a name-node.
Fields
list
Required
string
name
Required
string
comment
Optional
string
containing object.
encrypt
Optional
boolean
encrypted
Optional
boolean

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

Fields 340
name
Required
string
comment
Optional
string
containing object.
encrypt
Optional
boolean
encrypted
Optional
boolean
layer
Optional
string
post-edits
Optional
pre-edits
Optional

341 policy.add
tag
Optional
string
unset
Optional
(string ...)
necessary).
policy.add
Creates a new policy.
Fields
name
Required
string
action
Optional
policy-action
action is taken.

Fields 342
comment
Optional
string
containing object.
children
Optional
string
layer
Optional
string
post-edits
Optional
pre-edits
Optional
selector
Required
policy-selector

343 policy.delete
policy.delete
Deletes a policy.
Fields
name
Required
string
layer
Optional
string
policy.get
Retrieves a policy.
Fields
name
Required
string
exclude-fields
Optional
(string ...)

policy.list 344
fields
Optional
(string ...)
layer
Optional
string
policy.list
Lists policy configurations, optionally sorted by various criteria.
Fields
descending
Optional
boolean
end
Optional
{
name => string
Defines the last value to be returned. The value is the policy name.
key
Optional
string

345 policy.mget
layer
Optional
string
max-results
Optional
integer
skip-first
Optional
boolean
start
Optional
{
name => string
Defines the first value to be returned. The value is the policy name.
policy.mget
Retrieves multiple policies.
Fields
descending
Optional
boolean

Fields 346
end
Optional
{
name => string
Defines the last value to be returned. The value is the policy name.
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)
key
Optional
string
layer
Optional
string
max-results
Optional
integer

347 policy.replace
skip-first
Optional
boolean
start
Optional
{
name => string
Defines the first value to be returned. The value is the policy name.
policy.replace
Replaces all fields of a policy.
Field
name
Required
string
action
Optional
policy-action
action is taken.
children
Optional
string

Field 348
comment
Optional
string
containing object.
layer
Optional
string
post-edits
Optional
pre-edits
Optional
selector
Required
policy-selector

349 policy.simulate
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 are attempting to
simulate the subsequent part of a query that has followed a CNAME.
qname
Optional
name
The query name of the simulated query.
qtype
Optional
rdatatype
The query type of the simulated query.
start-time
Optional

Returns 350
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:
({
match => boolean
parent => string
policy => string
priority => integer
server => string
view => string
when => 'postquery' | 'prequery' | 'presend'
} ...)
policy.update
Updates all fields of a policy.

351 Fields
Fields
name
Required
string
action
Optional
policy-action
action is taken.
children
Optional
string
comment
Optional
string
containing object.
layer
Optional
string
post-edits
Optional

Examples 352
pre-edits
Optional
selector
Required
policy-selector
unset
Optional
(string ...)
necessary).
Examples
cacheserve> policy.update name=malicious-redirect-policy action=
(answer ((A 192.168.1.1)(AAAA 2001:db8:f61:a1ff:0:0:0:80))
{
}
process-information
Retrieves process information for the server.

353 Returns
Returns
arguments
string
The arguments with which the server was started.
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 354
ratelimiter.add
Adds a ratelimiter.
Fields
name
Required
string
fields
Required
string
bps
Optional
integer
comment
Optional
string
containing object.

355 Fields
layer
Optional
string
maximum-entries
Optional
positive-integer
post-edits
Optional
pre-edits
Optional
qps
Optional
integer
unenforced
Optional
boolean

ratelimiter.delete 356
ratelimiter.delete
Deletes a rate limiter.
Fields
name
Required
string
layer
Optional
string
ratelimiter.get
Retrieves a ratelimiter.
Fields
name
Required
string
exclude-fields
Optional
(string ...)
fields
Optional

357 ratelimiter.list
(string ...)
layer
Optional
string
ratelimiter.list
Lists ratelimiters, optionally sorted by various criteria.
Fields
descending
Optional
boolean
end
Optional
{
name => string
Defines the last value to be returned. The value is the ratelimiter name.
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)

ratelimiter.mget 358
key
Optional
string
layer
Optional
string
max-results
Optional
integer
skip-first
Optional
boolean
start
Optional
{
name => string
Defines the first value to be returned. The value is the ratelimiter name.
ratelimiter.mget
Retrieves multiple rate limiters.

359 Fields
Fields
descending
Optional
boolean
end
Optional
{
name => string
Defines the last value to be returned. The value is the ratelimiter name.
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)
key
Optional
string
layer
Optional
string

ratelimiter.limited 360
max-results
Optional
integer
skip-first
Optional
boolean
start
Optional
{
name => string
Defines the first value to be returned. The value is the ratelimiter name.
ratelimiter.limited
Returns a list of ratelimiter entries. The list is returned as a sequence.
Fields
bps
Optional
integer
client-network
Optional
addr
The network address for this entry.

361 Fields
client-network-family
Optional
'ipv4' or 'ipv6'
Indicates the type of the entry.
client-network-mask-length
Optional
ipv6netlen
The network address mask length.
creation-time
The time at which this ratelimiter was created.
entry-creation-time
The time at which this entry was created.
fields
Optional
(’client‐network’ | ’query‐name’ | ’query‐type’ ...)
string
Specifies the fields to use when grouping entries.
last-limited-time
The time at which this entry was last limited.
last-use-time
The time at which this entry was last used.
name
Required

ratelimiter.replace 362
string
The name of the rate-limited object.
qps
Optional
integer
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.
query-type
rdatatype
The query type of this entry.
unenforced
Optional
boolean
ratelimiter.replace
Replaces all values for a ratelimiter.

363 Fields
Fields
name
Required
string
fields
Required
string
bps
Optional
integer
comment
Optional
string
containing object.
layer
Optional
string

ratelimiter.statistics 364
maximum-entries
Optional
positive-integer
post-edits
Optional
pre-edits
Optional
qps
Optional
integer
unenforced
Optional
boolean
ratelimiter.statistics
Returns the current values for ratelimiter statistics along with general process statistics.

365 Fields
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
creation-time
The time at which this ratelimiter was created.
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.
name
string
The ratelimiter's name.
reset-time

ratelimiter.update 366
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.
Fields
name
Required
string

367 Fields
bps
Optional
integer
comment
Optional
string
containing object.
fields
Optional
string
layer
Optional
string
maximum-entries
Optional
positive-integer

resolver.add 368
post-edits
Optional
pre-edits
Optional
qps
Optional
integer
unenforced
Optional
boolean
unset
Optional
(string ...)
necessary).
resolver.add
Creates a new resolver.

369 Fields
Fields
name
Required
string
auth-server-list
Optional
string

servers.
comment
Optional
string
containing object.
client-subnet
Optional
{
}
query.

Fields 370

address.
dnssec-aware
Optional
boolean
network traffic.
forward
Optional
name servers.
the query.

371 Fields
addrport empty.
hints
Optional
(name, ((name, (addr ...)) ...))
Optional
boolean

layer
Optional
string
log-dnssec
Optional
boolean

Fields 372
log-id-spoofing
Optional
boolean
taking place.

See ID spoofing attacks for more detail.
log-lame
Optional
(name ...)
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

373 Fields
doesn't actually have authoritative data for the zone.
Use caution with lame delegations
It's technically possible to log errors occurring in any domain by specifying the root
domain, but is extremely inadvisable. There are thousands upon thousands of lame
servers, and you'll get deluged by thousands of messages to no good purpose, unless
you're planning to contact the administrators of every one of these "free-range" servers to
ask them to correct the error.
managed-keys
Optional
((name, (rdata...)) ...)

1ihz0=")))

Fields 374
max-cache-size
Optional
sizeval
max-cache-ttl
Optional
time-in-seconds
max-client-ttl
Optional
time-in-seconds
max-edns-udp-size
Optional
integer

max-ncache-ttl
Optional

375 Fields
time-in-seconds
Optional
(name ...)
post-edits
Optional
pre-edits
Optional
prefetch-ratio
Optional
integer

TTL.
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/n of 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



preload-nxdomain
Optional
(name ...)


377 How we determined the default value
preload-nxrrset
Optional
exists.
Optional

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


connections.
Optional
(uint16, addrport6)

connections.
rrset-order
Optional

379 How we determined the default value
Optional
('A' | 'AAAA' ...)
stub
Optional

synthesize-nxdomain
Optional
(name ...)
specified domains.


entire domain.

trusted-keys
Optional
((name, (rdata ...)) ...)
of a security root.

381 resolver.delete
resolver.delete
Deletes a resolver.
Fields
name
Required
string
layer
Optional
string
resolver.flush
Flushes entries from the resolver's cache.
Fields
name
Required
string
target
Optional
('domain' name | 'name' name )
If absent, all names are removed.
If present, and set to name, removes only that name.
If present, and set to domain, removes all names in that domain.

resolver.get 382
resolver.get
Retrieves a resolver.
Fields
name
Required
string
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)
layer
Optional
string
resolver.inspect
Retrieves information about a name in the resolver’s cache, returning the information in
various forms.

383 Fields
Fields
name
Required
string
domain
Required
name
The domain name you are inspecting.
Returns
client-subnet-specific
{
<subnet> => {
domain => name
exists => boolean
immortal => boolean
nonexistence‐proof => ((name, {
<type> => {
data => (string ...)
sigs => (string ...)
ttl => integer
validated => boolean
}
...
}) ...)
ttl => integer
types => {
<type> => {
exists => boolean
immortal => boolean
nonexistence‐proof =>
((name, {
<type> => {
ttl => integer
}
...
}) ...)

Returns 384
origin => addr

prefetches => integer
ttl => integer
wildcard‐proof =>
((name, {
<type> => {
ttl => integer
}
...
}) ...)
}
...
}
}
...
}
domain
Required
name
The domain name you are 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
string

385 Returns
The name of the resolver.
nonexistence-proof
Optional
((name, {
<name> => {
ttl => integer
}
...
}) ...)
For negative entries, nonexistence-proof displays the information that the server uses to
prove that the entry doesn't exist.
prefetches
integer
If present, and this is a negative entry, the number of times this data has been prefetched
since it was initially cached.
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
{ <name> => {
exists => boolean
immortal => boolean
nonexistence-proof => ((name, {
<name> => {
sigs => (string...)
ttl => integer
}
...

}) ...)
origin => addr
prefetches => integer
ttl => integer
wildcard-proof => ((name, {
<name> => {
ttl => integer
}
...
}) ...)
}
...
}
A table mapping DNS record types to subtables which contain information about those
types.
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

387 Returns
name
The domain name of the delegation point you are inspecting.
Returns
domain
Required
name
The domain name of the delegation point you are inspecting.
immortal
Optional
boolean
If present, indicates whether or not an entry is persistent.
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.inspect-forwarders
Retrieves information about a forwarder in the resolver’s cache, returning the information
in various forms.
Fields
name
Required
string
domain
Required
name
The domain name of the forwarder you are inspecting.
Returns
domain
Required
name
The domain name associated with the forwarders to inspect.
forward-mode
Optional
first | off | only
Indicates the forwarding mode.

389 resolver.list
forwarders
Optional
({
address => addrport
edns => {
status => string
ttl => integer
}
outstanding-queries => integer
rtt => integer
} ...)
Contains information about the forwarders.
name
string
resolver.list
Lists resolvers, optionally sorted by various criteria.
Fields
descending
Optional
boolean
end
Optional
{
name => string
Defines the last value to be returned. The value is the resolver name.
skip-first
Optional

resolver.mget 390
boolean
start
Optional
{
name => string
Defines the first value to be returned. The value is the resolver name.
resolver.mget
Retrieves multiple resolvers.
Fields
descending
Optional
boolean
end
Optional
{
name => string
Defines the last value to be returned. The value is the resolver name.
exclude-fields
Optional
(string ...)

391 Fields
fields
Optional
(string ...)
key
Optional
string
layer
Optional
string
max-results
Optional
integer
skip-first
Optional
boolean
start
Optional
{
name => string
Defines the first value to be returned. The value is the resolver name.

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
auth-server-list
Optional
string

servers.
client-subnet
Optional

393 Fields
{
}
query.

address.
comment
Optional
string
containing object.
dnssec-aware
Optional
boolean

Fields 394
network traffic.
forward
Optional
name servers.
the query.
addrport empty.
hints
Optional
(name, ((name, (addr ...)) ...))
Optional

395 Fields
boolean

layer
Optional
string
log-dnssec
Optional
boolean
log-id-spoofing
Optional
boolean
taking place.


Fields 396
log-lame
Optional
(name ...)
managed-keys
Optional
((name, (rdata...)) ...)


397 Fields
1ihz0=")))
max-cache-size
Optional
sizeval
max-cache-ttl
Optional
time-in-seconds
max-client-ttl
Optional
time-in-seconds
max-edns-udp-size
Optional
integer

Fields 398

max-ncache-ttl
Optional
time-in-seconds
Optional
(name ...)
post-edits
Optional
pre-edits
Optional
prefetch-ratio
Optional
integer

399 Fields
TTL.
preload
Optional



preload-nxdomain
Optional
(name ...)


Fields 400
preload-nxrrset
Optional
exists.
Optional

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

401 Fields

connections.
Optional
(uint16, addrport6)

connections.
rrset-order
Optional

Fields 402
Optional
('A' | 'AAAA' ...)
stub
Optional

403 Fields
synthesize-nxdomain
Optional
(name ...)
specified domains.


entire domain.

trusted-keys
Optional
((name, (rdata ...)) ...)
of a security root.

resolver.statistics 404
resolver.statistics
Returns the current values for resolver statistics along with general process statistics.
Fields
name
Required
string
all
Optional
boolean
with a value of 0.
reset
Optional
boolean
Returns
cache-memory-in-use
uint64
The amount of cache memory used by this resolver.
current-time
The current time.
memory-in-use
uint64

405 Returns
name
string
The resolver's name.
reset-time
server-start-time
statistics
{
active-recursions => uint64
cache-misses => uint64
dnssec-validations-failure => uint64
dnssec-validations-insecure => uint64
dnssec-validations-success => uint64
dropped-recursions => uint64
id-spoofing-defense-queries => uint64
ignored-referral-lookups => uint64
interrupted-before-recursion => uint64
interrupted-recursion-waits => uint64
interrupted-recursions => uint64
lookups => uint64
proactive-lookups => uint64
queries => uint64
queued-prefetches => uint64
rate-limited-requests => uint64
recursive-lookups => uint64
requests-sent => uint64
responses-by-rcode =>
{
<name> => uint64
...
}
tcp-requests-sent => uint64
}

resolver.update 406
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
name
Required
string
auth-server-list
Optional
string

servers.
client-subnet
Optional
{
}

407 Fields
query.

address.
comment
Optional
string
containing object.
dnssec-aware
Optional
boolean
network traffic.
forward
Optional

Fields 408
name servers.
the query.
addrport empty.
hints
Optional
(name, ((name, (addr ...)) ...))
Optional
boolean


409 Fields
layer
Optional
string
log-dnssec
Optional
boolean
log-id-spoofing
Optional
boolean
taking place.

log-lame
Optional

Fields 410
(name ...)
managed-keys
Optional
((name, (rdata...)) ...)

1ihz0=")))
max-cache-size
Optional

411 Fields
sizeval
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

Fields 412
Optional
(name ...)
post-edits
Optional
pre-edits
Optional
prefetch-ratio
Optional
integer
TTL.

413 Fields
preload
Optional



preload-nxdomain
Optional
(name ...)

preload-nxrrset
Optional
exists.

Fields 414
Optional

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

connections.

415 Fields
Optional
(uint16, addrport6)

connections.
rrset-order
Optional
Optional
('A' | 'AAAA' ...)

Fields 416
stub
Optional
synthesize-nxdomain
Optional
(name ...)
specified domains.

417 restart


entire domain.

trusted-keys
Optional
((name, (rdata ...)) ...)
of a security root.
unset
Optional
(string ...)
necessary).
restart
Restarts CacheServe.

selector.add 418
selector.add
Creates a new view-selector.
Fields
name
Required
string
comment
Optional
string
containing object.
errors
Optional
(string ...)

layer
Optional
string
post-edits
Optional

419 selector.delete
pre-edits
Optional
selector
policy-selector
selector.delete
Deletes a selector.
Fields
name
Required
string
layer
Optional
string

selector.get 420
selector.get
Retrieves a named selector.
Fields
name
Required
string
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)
layer
Optional
string
selector.list
Lists named selectors, optionally sorted by various criteria.
Fields
descending
Optional

421 Fields
boolean
end
Optional
{
name => string
}
key
Optional
string
layer
Optional
string
max-results
Optional
integer
skip-first
Optional
boolean
start
Optional
{
name => string
}

Returns 422
Returns
name
Required
string
selector.mget
Retrieves multiple named selectors.
Fields
descending
Optional
boolean
end
Optional
{
name => string
}
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)

423 selector.replace
key
Optional
string
layer
Optional
string
max-results
Optional
integer
skip-first
Optional
boolean
start
Optional
{
name => string
}
selector.replace
Replaces values on a named selector.

Fields 424
Fields
name
Required
string
comment
Optional
string
containing object.
layer
Optional
string
post-edits
Optional
pre-edits
Optional
selector
policy-selector

425 selector.update
selector.update
Updates values for a named selector.
Fields
name
Required
string
comment
Optional
string
containing object.
layer
Optional
string
post-edits
Optional
pre-edits
Optional
selector
policy-selector

server.add 426
unset
Optional
(string ...)
necessary).
server.add
Creates a new server.
Fields
layer
Optional
string
commands-not-logged
Optional
(string ...)
Defaults to ().

427 Fields
listen-on-matching
Optional
({
interface => string
port => uint16
} ...)

specified.


Examples
{
}

Fields 428
{
{
patterns => ('192.168.1.1/32')
instances => '16'
}
{
patterns => ('127.0.0.1/32')
port => '5354'
}
)
}
interface to eth0:
cacheserve> server.update listen-on-matching=({interface=eth0 pat-
terns=(192.168.1.1) instances=16}{interface=eth0 patterns=(127.0.0.1)
port=5354})
{
}
{
{
interface => 'eth0'
patterns => ('192.168.1.1/32')
instances => '16'
}
{
interface => 'eth0'
patterns => ('127.0.0.1/32')
port => '5354'
}
)
}
log-command-channel
Optional
boolean
Defaults to false.

429 Fields
are truncated.
Optional
integer

RAM.
max-tcp-clients
Optional
integer
100.
post-edits
Optional
pre-edits
Optional

Fields 430
server-description
Optional
string
server-id
Optional
string-empty-ok
server-version
Optional
string-empty-ok
version.
time-zone
Optional
string
of the IANA tzdb.
Optional
versioncheck-days

431 server.all-errors
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.delete
Deletes a server object.
Fields
layer
Required
string

server.get 432
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.

433 Fields
Simulated queries sent to the Nominum monitoring utilities are marked with the
SIMULATED flag.
Queries where the client-address and server-address are in different families will not be
posted.
Fields
client-address
Optional
addrport
The client address from which the query originated.
client-subnet
Optional
addrpat
The value of the edns-client-subnet option. If present, this option enables EDNS processing
for the request.
destination-address
Optional
addrport
(formerly server-address) Specifies the server address to match against view-selectors or

policies. Defaults to the target address of the command.
device-id
Optional
string
The value of the nom-device-id EDNS option. If present, this option enables EDNS
processing for the request.
edns-buffer-size
Optional
uint16
Indicates the advertised EDNS buffer size, limiting the size of the response.

Fields 434
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.
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

435 Returns
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.
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.
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) ...)

Returns 436
The records in the additional section of the response.
aliases
(name...)
Aliases for the query name encountered during query processing.
answer
Note: Only displayed if you have an NXR, N2 or ThreatAvert license in addition to the
CacheServe base license.
The records in the answer section of the response.
authority
The records in the authority section of the response.
client-subnet
(addrpat, integer)
The value of the edns-client-subnet option in the response, if present. The address is
copied from the request, and the integer is the scope of network addresses for which the
tailored answer is intended.
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

437 Returns
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.
rcode
dns-rcode
The DNS result code.
resolution
boolean
If true, indicates that a resolution was performed as part of processing the query.
resolver
string
The resolver which processed this query.

Example 438
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'
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'
}

439 Example (N2 environment)
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-

e=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'
}
{
policy => 'strict-067e90f9-6c93-37ef-8859-e8cbba15b799'
when => 'prequery'
priority => '10000'
match => 'true'

server.replace 440
}
{
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
(string ...)
Defaults to ().

441 Fields
listen-on-matching
Optional
({
interface => string
port => uint16
} ...)

specified.


Examples
{

Fields 442
}
{
{
patterns => ('192.168.1.1/32')
instances => '16'
}
{
patterns => ('127.0.0.1/32')
port => '5354'
}
)
}
interface to eth0:
port=5354})
{
}
{
{
interface => 'eth0'
patterns => ('192.168.1.1/32')
instances => '16'
}
{
interface => 'eth0'
patterns => ('127.0.0.1/32')
port => '5354'
}
)
}
log-command-channel
Optional
boolean
Defaults to false.

443 Fields
are truncated.
Optional
integer

RAM.
max-tcp-clients
Optional
integer
100.
post-edits
Optional
pre-edits
Optional

Fields 444
server-description
Optional
string
server-id
Optional
string-empty-ok
server-version
Optional
string-empty-ok
version.
time-zone
Optional
string
of the IANA tzdb.
Optional
versioncheck-days

445 server.statistics
server.statistics
Returns the current values for server statistics along with general process statistics.
Fields
all
Optional
boolean
with a value of 0.
reset
Optional
boolean
Returns
current-time
The current time.
memory-in-use
uint64
name
string
The resolver's name.
reset-time

Example 446
server-start-time
statistics
{
formerr-loop-dropped => uint64
lookups => uint64
malformed-requests-dropped => uint64
recursion-contexts-in-use => uint64
requests-no-view => uint64
requests-received => uint64
responses-received => uint64
responses-sent => uint64
suppressed-duplicate-queries => uint64
tcp-clients => uint64
tcp-connections-accepted => uint64
tcp-connections-rejected => 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'
user-time => '1.239811'

447 server.unblock-checkpoints

statistics => {
}
}
server.unblock-checkpoints
Unblocks any blocked database checkpoints.
server.usage
Returns the server's current utilization.
Returns
current-time
The current time.
memory-in-use
uint64
system-time
thread ‐groups
Optional
{
<thread‐group> => {
system‐time => time-in-microseconds
threads => uint64
user‐time => time-in-microseconds
}

server.update 448
...
}
The amount of CPU time used by each group of threads.
user-time
server.update
Updates server fields.
Fields
layer
Optional
string
commands-not-logged
Optional
(string ...)
Defaults to ().
listen-on-matching
Optional
({
interface => string
port => uint16
} ...)

449 Fields

specified.


Examples
{
}
{
{
patterns => ('192.168.1.1/32')
instances => '16'
}
{
patterns => ('127.0.0.1/32')
port => '5354'
}

Fields 450
)
}
interface to eth0:
port=5354})
{
}
{
{
interface => 'eth0'
patterns => ('192.168.1.1/32')
instances => '16'
}
{
interface => 'eth0'
patterns => ('127.0.0.1/32')
port => '5354'
}
)
}
log-command-channel
Optional
boolean
Defaults to false.
are truncated.
Optional
integer

451 Fields

RAM.
max-tcp-clients
Optional
integer
100.
post-edits
Optional
pre-edits
Optional
server-description
Optional
string
server-id
Optional

Fields 452
string-empty-ok
server-version
Optional
string-empty-ok
version.
time-zone
Optional
string
of the IANA tzdb.
Optional
versioncheck-days
unset
Optional
(string ...)
necessary).

453 stop
stop
Stops CacheServe.
telemetry.get
Retrieves the telemetry object.
Fields
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)
layer
Optional
string
telemetry.replace
Replaces all values for the telemetry object.
Fields
layer
Optional

Fields 454
string
comment
Optional
string
containing object.
enable
boolean
interval
integer
kafka
Optional
post-edits
Optional
pre-edits
Optional
record-events
Optional

455 telemetry.statistics
(event-name ...)
telemetry.statistics
Returns the current values for server statistics along with general process statistics.
Fields
all
Optional
boolean
with a value of 0.
reset
Optional
boolean
Returns
current-time
The current time.
memory-in-use
uint64
node-id
uuid

Example 456
The node identifier for the system on which the server is running.
reset-time
server-start-time
statistics
{
messages-delivered => uint64
messages-dropped => uint64
messages-produced => uint64
queue-full => uint64
records-delivered => uint64
records-dropped => uint64
records-produced => uint64
A set of counters. For a detailed explanation of each statistic, see telemetry-statistics.
system-time
user-time
Example
cacheserve> telemetry.statistics
{
type => 'telemetry.statistics'
current-time => '1449531574.235686'
node-id => 'ca875e7c-2d16-5e79-8f43-95ed3d388cee'
user-time => '0.164974'
reset-time => '1449531495.914294'

457 telemetry.update
statistics => {
messages-produced => '42'
}
}
telemetry.update
Updates telemetry fields.
Fields
layer
Optional
string
comment
Optional
string
containing object.
enable
boolean
interval
integer
kafka
Optional

uuid 458
post-edits
Optional
pre-edits
Optional
record-events
Optional
(event-name ...)
unset
Optional
(string ...)
necessary).
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.

459 Returns
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 460
Fields
view
Required
string
destination-address
Optional
addrport

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

461 view-selector.delete
view-selector.delete
Deletes a view-selector.
Fields
destination-address
Optional
addrport

layer
Optional
string
source-address
Optional
addrpat
view-selector.get
Retrieves a view-selector.
Fields
destination-address
Optional
addrport

view-selector.list 462

exclude-fields
Optional
(string ...)
fields
Optional
(string ...)
layer
Optional
string
source-address
Optional
addrpat
view-selector.list
Lists view-selectors, optionally sorted by various criteria.
Fields
end
Optional
{
destination-address => addrport
source-address => addrpat
}

463 Returns
Defines the last value to be returned. The value is the acceptable addresses for the source
and destination of the view-selector.
descending
Optional
boolean
layer
Optional
string
max-results
Optional
integer
start
Optional
{
}
Defines the first value to be returned. The value is the acceptable addresses for the source
view
Optional
string
Restricts view-selector returns to only those matching the specified view.
Returns
destination-address
Optional

addrport

source-address
Optional
addrpat
view-selector.mget
Retrieves multiple view-selectors.
Fields
end
Optional
{
}
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)

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

Returns 466
source-address
Optional
addrpat
The source address of the simulated query.
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
view
Required
string
destination-address
Optional

467 view-selector.mget
addrport

layer
Optional
string
post-edits
Optional
pre-edits
Optional
source-address
Optional
addrpat
view-selector.mget
Retrieves multiple view-selectors.
Fields
end
Optional

Fields 468
{
}
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)
layer
Optional
string
max-results
Optional
integer
start
Optional
{
}

469 view-selector.update
view
Optional
string
view-selector.update
Updates values for a view-selector.
Fields
destination-address
Optional
addrport

layer
Optional
string
post-edits
Optional
pre-edits
Optional

view.add 470
source-address
Optional
addrpat
unset
Optional
(string ...)
necessary).
view
Optional
string
view.add
Creates a new view.
Fields
name
Required
string
resolver
Required
string

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

view.get 472
layer
Optional
string
view.get
Retrieves a view.
Fields
name
Required
string
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)
layer
Optional
string

473 view.list
view.list
Lists views, optionally sorted by various criteria.
Fields
descending
Optional
boolean
end
Optional
{
name => string
Defines the last value to be returned. The value is the view name.
skip-first
Optional
boolean
start
Optional
{
name => string
Defines the first value to be returned. The value is the view name.
view.mget
Retrieves multiple views.

Fields 474
Fields
descending
Optional
boolean
end
Optional
{
name => string
Defines the last value to be returned. The value is the view name.
exclude-fields
Optional
(string ...)
fields
Optional
(string ...)
key
Optional
string
layer
Optional
string

475 view.replace
max-results
Optional
integer
skip-first
Optional
boolean
start
Optional
{
name => string
}
view.replace
Replace values on a view.
Fields
name
Required
string
resolver
Required
string

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

477 Fields
layer
Optional
string
post-edits
Optional
pre-edits
Optional
resolver
Optional
string
The resolver associated with this view. All DNS resolution and caching is performed within
the context of a resolver, which may be shared between multiple views.
time-zone
Optional
string
of the IANA tzdb.
unset
Optional
(string ...)

Fields 478
necessary).

479 Fields

Chapter 17: Events ref-
erence
action.changed
Indicates that an action has been modified.
Returns
name
string
The name of the action.
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.

481 Returns
Returns
address
addrpat
The address or network that the address-node represents.
list
string
The list to which the node belongs.
auth-monitoring.changed
Indicates that the auth-monitoring object has been modified.
For detailed information about monitoring in CacheServe, including the commands

available for both the auth-monitoring and monitoring elements, please consult the
auth-server-list.changed
Indicates that an auth-server-list has been modified.
Returns
name
string
The name of the auth-server-list.
auth-server-node.changed
Indicates that an auth-server-node has been modified.
Returns
name
string
The name of the auth-server-node.

binding.changed 482
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
handled by that view.
dns64.changed
Indicates that a dns64 layer has been modified.
Returns
name
string
layer.changed
Signals that a layer has changed.
Returns
name
Required
string

483 layer.provisioning-connected
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

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
monitoring.changed
Indicates that the monitoring object has been modified.


485 name-group.changed
name-group.changed
Indicates that a name-group has been modified.
Returns
name
string
The name of the name-group.
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 486
Returns
name
string
The policy's name.
policy.hit
Indicates that a policy matched a query.
Returns
client
addrport
The client making the query.
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.

487 Returns
Returns
bps
integer
The maximum bytes-per-second for this ratelimiter.
client-network
addr
ipv4 | ipv6
Indicates whether the entry is for IPv4 or IPv6 networks.
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

ratelimiter.changed 488
name
string
qps
integer
The maximum queries per second for this ratelimiter.
query-name
name
query-name-labels
name-label-count
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

489 ratelimiter.onset
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
ipv4 | ipv6
Indicates whether the entry is for IPv4 or IPv6 networks.
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

resolver.changed 490
The time at which this entry was most recently limited.
last-use-time
name
string
qps
integer
The maximum queries per second for this ratelimiter.
query-name
name
query-name-labels
name-label-count
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.

491 Returns
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.

selector.changed
Indicates that a named selector has been modified.
Returns
name
string
The selector's name.
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.
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

493 server.restart
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.
telemetry.changed
Indicates that the telemetry object has been modified.
view-selector.changed
Indicates that a view-selector has been modified.
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.

view.changed 494
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.

495 Returns

Chapter 18: 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.
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.

497 acl-element4
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.
addr4
An IPv4 address.
addr6
An IPv6 address.
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.

addrpat4 498
addrpat4
An IPv4 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 (32 bits). The host portion of the address must be 0.
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
addrport-or-name
Either an IP address with an optional port, expressed as addr or addr#port, or a domain
name with an optional port, expressed as name or name#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.

499 boolean
boolean
A true or false value.
Nominum software, when interpreting a boolean value, accepts the following values for
TRUE (all values are case-insensitive):
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.

edns-flag 500
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
A DNS extended header flag.
'do'
event-name
The name of a Nominum Command Channel event. May be any of the following:
'address-list.changed'
'address-node.changed'
'auth-monitoring.changed'
'binding.changed'
'dns64.changed'
'layer.changed'
'layer.provisioning-connected'
'layer.provisioning-connection-failure'
'layer.provisioning-disconnected'
'layer.provisioning-reimaging'
'layer.provisioning-update-failure'
'layer.provisioning-update-success'
'monitoring.changed'
'name-list.changed'
'name-node.changed'
'policy.changed'
'policy.hit'
'ratelimiter.abate'
'ratelimiter.changed'
'ratelimiter.onset'
'resolver.changed'
'resolver.flush'
'resolver.id-spoofing-suspected'
'server.changed'
'server.configuration-error'
'server.formerr-loop'
'server.restart'
'server.stop'
'server.tcp-client-limit'

501 float-seconds-since-epoch
'server.udp-recursion-limit'
'view-selector.changed'
'view.changed'
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
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 502
ipv6netlen
A value between 1 and 128, representing the number of bits of for an IPv6 netmask.
Configures Kafka messaging for a partition of a topic. The brokers for the topic are
specified with the brokers option.
{
brokers => (addrport-or-name ...)
global-properties => {
<property> => string-empty-ok
...
}
partition => integer
topic => string
topic-properties => {
...
}
}
If not specified, the value of the environment variable "NOM_KAFKA_BROKERS" is used if

defined, otherwise a single broker named "nom-kafka." is used.
It is not necessary to list all brokers in the Kafka cluster, but for redundancy it is wise to list
more than one. The topic is specified with an appropriate value based on context.
The partition is specified with the partition option, and defaults to the unspecified partition
(-1) in producer contexts, and 0 in consumer contexts.
In keyed producer contexts where hashing is used to determine the partition, specifying
this option is meaningless.
The global−properties and topic−properties options can be used to specify additional

properties; see the librdkafka documentation for details on what options may be set.
brokers
Optional. Specifies the list of Kafka brokers.
Format: (addrport-or-name ...)
global-properties
Optional. Specifies Kafka global properties.

503 partition
Format:
{
...
}
partition
Optional. Specifies the Kafka partition. Defaults to -1.
Format: integer
If partition isn't specified, Kafka producers will use the unspecified partition (-1) and Kafka
consumers will use partition 0.
topic
Optional. Specifies the Kafka topic.
Format: string
If topic is not specified, a default appropriate to the given object is used: nom-dns-base for
the monitoring object, nom-dns-res for the auth-monitoring object, and nom-telemetry for
the telemetry object.
topic-properties
Format:
{
...
}
monitor-log-switch
A Command Channel flag denoting a type of command.
Switch Negation Default Description
command/executed !command/executed False Log details about valid Command

Channel commands executed by
a monitor. Commands are logged
after handling, and, if present,
include the value of err.

monitoring-statistics 504
Switch Negation Default Description
command/info !command/info False Log details about Command Chan-

nel traffic sent and received by a
monitor. All commands are
logged when received, and all
responses are logged when sent.
command/unknown !command/unknown False Log details about unknown Com-

mand Channel commands
received by a monitor.
monitoring-statistics
{
records-not-produced => uint64
messages-delivered
The number of messages successfully delivered.
messages-dropped
The number of messages dropped.
messages-produced
The number of monitoring messages produced.
queue-full
The number of times the output queue was full. This statistic applies only to Kafka
connections.
records-delivered
The number of records successfully delivered. This statistic applies only to Kafka
connections.

505 records-dropped
records-dropped
The number of records dropped when producing. This statistic applies only to Kafka
connections.
records-not-produced
The number of request records that are intentionally not sent into the monitoring system.
This includes invalid records that the monitoring system could not usefully process.
This statistic is primarily useful for identifying differences between the Server object's
requests-recieved statistic and statistics produced by the statmon utility.
records-produced
The number of records produced.
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:

('annotate (string, string)) 506
('annotate (string, string))

('answer' ((rdatatype, rdata) ...))
('answer-by' ((variable | name) resolver)))
('answer-cname' string)
'answer-noerror'
'answer-nxdomain'
('answer-ttl' (((rdatatype, rdata) ...), ttl)) ('answer'
((rdatatype, rdata) ...)) ('assign' (string name))
('dns64' string)
('dns64-reverse' string)
'drop'
'fail'
'no-op'
'refuse'
'send-event'
('sort-addresses' ((string ...), boolean))
'stop'
'truncate'
('annotate (string, string))

Stage: All
Adds annotations, which will be recorded by statmon. The annotation is specified as a key
and a value, and is a non-terminal action.
('answer' ((rdatatype, rdata) ...))

Stage: Prequery, postquery
Note: Requires an NXR, N2 or ThreatAvert license in addition to the CacheServe base

license.
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.

507 ('answer-by' ((variable | name) resolver)))
('answer-by' ((variable | name) resolver)))

Note: Requires an N2 or ThreatAvert license in addition to the CacheServe base license.
Synthesizes an answer for a query, optionally using a different query name or resolver. The
name may be specified as a variable or a literal domain name. If both are specified, and
the variable has been assigned to a valid domain name, the variable takes precedence. If a
resolver is specified, it is used instead of the resolver normally associated with the query.
TTL should never be less than 300 for best performance.
('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-byresolver uses the specified resolver to retrieve the answer to the query. The
appropriate response (e.g. an RRset if found, is returned from the alternate resolver to the
policy running the query as if it had been found by the original resolver. Resolver options
that affect packet generation (rrset-order, max-client-ttl) and statistics use the original
resolver.
('answer-cname' string)

'answer-noerror' 508
Synthesizes an answer containing a CNAME. The CNAME is specified as a DNS name, and
that DNS name is used as the target of the CNAME. The CNAME is added to the DNS
response and then followed.
The CNAME's TTL is always 0.
'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.
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.
('assign' (string name))

Assigns a variable, which can later be used by actions or selectors that expand variables.
This assignment specifies a name and a typed value. This is a non-terminal action.
('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.

509 ('dns64-reverse' string)
('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.
'fail'
Stage: All
Treats the request as an immediate failure, sending a SERVFAIL response.
'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.
('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.

'stop' 510
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:
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.

511 policy-result-type
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.
noerror The lookup succeeded: the queried name exists and records of the queried
type exist at the queried name.
nxdomain The lookup resulted in an NXDOMAIN response: the queried name does not
exist.
nxrrset The lookup resulted in an NOERROR/NODATA response: the queried name

exists 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)
('client-address-is' (acl-element ...))
('destination-address' string)
('destination-address-is' (acl-element ...))
('device' (string)
('device-group' (string ...))

('and' (policy-selector ...)) 512
('device-id' string)
'initial-qname'
('named-selector' string)
('not' (policy-selector))
('or' (policy-selector ...))
('qflag' 'AD' | 'CD' | 'DO' | 'EDNS' | 'RD')
('qname' (string, 'exact' | 'exact-or-www' | 'subdomain'))
('qname-in-group' string)
('qname-is' (name, 'exact' | 'exact-or-www' | 'proper-
subdomain' | 'subdomain'))
('qname-prefix' string)
('qtype' (rdatatype ...))
('ratelimiter' string)
('response-size' uint16)
('result' (policy-result-type ...))
('server-address' string)
('synthesized')
('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

513 ('client-address-is' (acl-element ...))
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.
('destination-address' string)
Stage: All
Matches if the destination address of the client's query matches an IP address or network
on the list.
('destination-address-is' (acl-element ...))

Stage: All
Matches if the destination address of the client's query matches an IP address or network
in the specified acl-element.
('device' (string)
Stage: All
Matches if the query contains a nom-device-id EDNS option, and both the content of the
option and the current view match a device-node on the list.
('device-group' (string ...))

Stage: All
Matches if the query contains a nom-device-id EDNS option, and the content of the option
matches one of the strings in this list.
('device-id' string)
Stage: All
Matches if the query contains a nom-device-id EDNS option, and the content of the option
matches this value.

'initial-qname' 514
'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).
('named-selector' string)
Stage: All
Executes the specified named selector and matches if the specified named selector
matches.
('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.
('qclass' (rdataclass ...))

Stage: Presend
Matches if the query class matches one of the query classes associated with the selector.
('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: Varies: see below
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,
proper-subdomain specifies a proper subdomain match, and subdomain specifies a
subdomain match.
This selector refers to different elements of the query in different contexts:

515 ('qname-in-group' string)
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-in-group' string)
Matches if the query name matches any of the lists associated with the specified name-
group, using the matching criteria associated with each name-list in the group.
('qname-is' (name, 'exact' | 'exact-or-www' | 'proper-subdomain' | 'sub-
domain'))
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, proper-subdomain
specifies a proper subdomain match, and subdomain specifies a subdomain match.
('qname-prefix' string)
Note: Requires an NXR, N2 or ThreatAvert license in addition to the CacheServe base

license.
Matches if a name consisting of the query name's prefix (first label) exactly matches a
query name on a name-list. Never match the root name.

('qtype' (rdatatype ...)) 516
('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.
('synthesized')
Stage: Postquery, presend
Matches only if the response was synthesized by an earlier policy action.
('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.

517 port-mask
port-mask
A 16-bit unsigned integer representing a port mask. May be specified as hexadecimal,
octal, or decimal values. Hex values begin with 0x and octal values begin with 0.
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 518
How provisioning usually goes

Under normal circumstances, provisioning status flows from initial to wait, and from wait
to update as updates come in.
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 will 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.

519 indications-by-qps
indications-by-qps
The number of times a ratelimiter has limited a query based on the QPS threshold.
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
{
active-recursions => uint64
cache-misses => uint64
dnssec-validations-failure => uint64
dnssec-validations-insecure => uint64
dnssec-validations-success => uint64
dropped-recursions => uint64
id-spoofing-defense-queries => uint64
ignored-referral-lookups => uint64
interrupted-before-recursion => uint64
interrupted-recursion-waits => uint64
interrupted-recursions => uint64
lookups => uint64
proactive-lookups => uint64
queries => uint64
queued-prefetches => uint64


responses-by-rcode =>
{
<name> => uint64
...
}
}
active-recursions
The number of recursions currently in progress.
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.
The number of cache hits may be calculated as the difference between lookups and 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.
dropped-recursions
The number of recursions preemptively dropped due to excessive load. A dropped
recursion typically leads to a query not receiving a response.
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

521 interrupted-before-recursion
server is under attack.
interrupted-before-recursion
The number of times that query processing was interrupted because of excessive load,
before either starting a recursion or joining an existing recursion. An interrupted recursion
typically leads to a SERVFAIL response.
interrupted-recursion-waits
The number of times that query processing was interrupted due to an interrupting while
CacheServe was waiting for an existing resolution to complete. An interrupted recursion
interrupted-recursions
The number of recursions interrupted due to excessive load. An interrupted recursion
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 (queries performed as part of prefetching) issued.
queries
The number of queries processed by this resolver.
queued-prefetches
The number of prefetches queued due to excessive load. A prefetch is queued when there
are no available recursion slots and the name matches an entry on the resolver's
prioritized-domains list.
rate-limited-requests
The number of DNS requests not sent by this resolver to other DNS servers as a result of
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 522
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
{
formerr-loop-dropped => uint64
lookups => uint64
malformed-requests-dropped => uint64
recursion-contexts-in-use => uint64
requests-no-view => uint64
requests-received => uint64
responses-received => uint64
responses-sent => uint64
suppressed-duplicate-queries => uint64
tcp-clients => uint64
tcp-connections-accepted => uint64
tcp-connections-rejected => uint64
}
formerr-loop-dropped
The number of DNS requests for which a FORMERR loop was detected (see the
server.formerr-loop event) and for which no response was sent.

523 lookups
lookups
The total number of DNS lookups performed. Note that this does not match the number of
incoming queries, because resolving a single client DNS query can result in multiple
lookups due to CNAME or DNAME chains, looking up nameserver addresses and DNSSEC
keys, root server priming, and so forth.
malformed-requests-dropped
The number of DNS requests received which were so malformed that CacheServe dropped
them immediately, without further processing. This includes packets which didn't include a
full DNS header, or packets for which the DNS header indicated a DNS response, not a
request.
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.
recursive-lookups
The total number of DNS lookups (as reported in lookups) that CacheServe could not
satisfy from the cache.
requests-no-view
The number of DNS requests refused because they did not match any of the configured
view-selectors.
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.

suppressed-duplicate-queries
The number of queries dropped because the source address, source port, and query ID
exactly matched a query already being processed. Typically, this kind of match indicates a
malicious or misbehaving client.
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-connections-accepted
The number of TCP connections accepted from clients. This may not match the number of
TCP requests received, because there may be multiple connections sent over a connection,
or there may be none in some cases.
tcp-connections-rejected
The number of TCP connections rejected due to the limit configured in max-tcp-clients.
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.
std-layered-edit-operation
A layered configuration edit operation. Takes the form
('defaults' (string ...)) | ('hide' (string ...))
Parameter Description
('defaults' (string ...)) The "defaults" edit takes a list of of field names
and sets them back to their default values.
If the list is empty, then all fields are reset to

their default values.
('hide' (string ...)) The "hide" edit hides the object.

525 string
string
A simple text string.
string-empty-ok
A string which may be empty.
telemetry-statistics
{
messages-delivered
The number of messages successfully delivered to Kafka.
messages-dropped
The number of messages dropped when producing into Kafka. In general, this occurs when
the server is unable to send to the leader for a partition, and small drops may occur when
Kafka leadership changes.
messages-produced
The number of messages produced (queued) into Kafka.
queue-full
queue-full refers to Kafka's internal queue for sent messages, and indicates time spent by
CacheServe waiting for Kafka to accept produced messages. The value of the statistic is the
number of times that the Kafka cluster informed CacheServe that the queue was full when
CacheServe tried to produce messages.
records-delivered
The number of records successfully delivered to Kafka.

records-dropped 526
records-dropped
The number of records dropped when producing into Kafka. In general, this occurs when
CacheServe can't contact the current leader for a given partition. During leadership
changes, you may see small drops: this is normal.
records-produced
The number of records produced (queued) into Kafka.
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

527 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.

Appendix A: Migrating
from Vantio CacheServe 5
If you are using Vantio CacheServe 5, you will need to migrate your configuration to the
Vantio CacheServe 7 format. we have 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
somewhere other than /var/nom/cacheserve, like /tmp. Only move the converted data-
base once you are sure the conversion is complete and the results are to your liking.
2. Not all parts of a Vantio CacheServe 5 configuration can be automatically con-
verted; more complicated Vantio configurations may require additional help.
Migration procedure
To migrate from Vantio CacheServe 5 to Vantio CacheServe 7:
1. Disable or remove any automatic startup processes for Vantio CacheServe 5.

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

529 A note about chroot()
where <file> represents the name of the file containing the dumped Vantio
CacheServe 5 data.
4. If you are satisfied with the results of the import, stop Vantio CacheServe 5, and start
Vantio CacheServe 7:
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
CacheServe 5 installation by restoring any changes that you made to startup scripts in
step 1, and starting Vantio.
A note about chroot()

Although it's not required, you can operate Vantio CacheServe in a chroot()ed environment
for enhanced security. In order to do so, you'll need to configure a user and follow these
steps:
1. Create the directory in which you are going to run CacheServe. You can use
/var/nom/cacheserve if that's convenient.
2. Choose the user as which you are going to run CacheServe (create the user, if neces-
sary).
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.

Appendix B: Differences
between CacheServe 5 and
CacheServe 7
There are substantial changes between CacheServe 5 and CacheServe 7. This section of the
manual enumerates those changes.
General changes
The following CacheServe 5 features are no longer supported:
l DNSAUTH.
l DNS classes other than IN (with the exception of magic CHAOS TXT queries).
l Old-style vantio.conf text-format configuration files.
l Lock files.
l MDR: malicious domain redirection is handled through the policy engine.
l NXR: NXDOMAIN redirection is handled through the policy engine.
l UAR: use view-selectors instead.
The following general CacheServe features have changed:
l The default DNS port can only be specified on the command line (see --dns-port).
l The same single address/port combination cannot be configured to accept both

531 Server object
queries and responses.
Server object
The following server object features are no longer supported:
l listen-on: use listen-on-matching.
l blackhole-clients: this functionality is provided by the policy engine.
l The server-reload event.
l The request-no-view event (use the Statmon utility instead).
l server.layer-order. Layer ordering is now controlled by the layer object's priority field.
l server.hidden-layers: to identify hidden layers, use layer.mget and look for

"hidden=true".
The following server object features have changed:
l The syntax of listen-on-matching has changed. See listen-on-matching for details.
l max-cache-size is now per-resolver, not per-server.
l cache-memory-in-use is now a per-resolver statistic, only returned by

resolver.statistics.
l The server-stop event is now called server.stop.
l A server.restart event is generated when the server restarts.
l The tcp-client-limit event is now server.tcp-client-limit.
l The udp-recursion-limit event is now server.udp-recursion-limit.
Resolver and view objects

The following resolver and view features are no longer supported:
l check-responses.
l delegation-only.
l The dnssec-validation-failed event.
l filter-aaaa-on-v4: use the type-exists-at-qname policy selector instead.
l Query logging: use the Statmon utility instead.

Resolver and view objects 532
l query-source and query-source-v6.
l The recursing command.
The following resolver and view features have changed:
l Views in CacheServe 7 are what lwviews are in CacheServe 5. In particular, view

ordering is determined by view-selectors, every view must have a resolver, and there
are no view statistics.
l Most view-level statistics have their equivalent in resolver-statistics, with the following
exceptions:
l mdr-matches and rejected-responses no longer exist.
l lvp-matches and dns64-sythesized-responses are obtained through the

Statmon utility.
l The cache cannot be dumped. Use resolver.inspect to view the cache contents.
l EDNS0 defaults to "on".
l id-spoofing-defense is always on and no longer configurable.
l The id-spoofing-suspected event is now resolver.id-spoofing-suspected, with the

fields name, qname, and qtype.
l Inspection is now resolver-specific:
l inspect and inspect-delegation are now resolver.inspect and resolver.inspect-

delegation.
l Immortal's value is now a boolean value.
l "Unknown name" has changed to "Domain not found".
l Domains are specified with the domain argument.
l log-id-spoofing is now a resolver feature.
l log-lame is now a resolver feature.
l All managed-keys commands have been replaced with the managed-keys field, and
the managed-keys-state field returned by resolver.get or resolver.mget.
l QNAME case randomization has been simplified: see qname-case-randomization for

details.
l record-data-origin is always on and no longer configurable.
l Any RR type may be preloaded.

533 DNS64 objects
l The trusted-keys format has changed to ((name, (rdata ...)) ...)
l View names are no longer limited to 255 characters.
DNS64 objects
l DNS64 has been simplified and integrated into the policy engine.
l DNS64 processing is enabled using the dns64 and dns64-reverse policy actions.
Statistics
l For anything other than simple counters, use the Statmon utility instead.
l The server object keep-statistics-by-client and keep-statistics-by-domain statistics

have been removed.
l The view object keep-statistics-by-type statistic has been removed.
Command channel
l Interactions with the actual Command Channel connection, like enabling events, are
managed by the connection object.
l The deprecated server-time command has been removed.
Policies and bindings (including LVP)

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.
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.
l Policy bindings now have a when field, which defines the point in the query process

Database 534
(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.
l "lvp_query" has been replaced by policy.simulate.
Database
Checkpoints are now automatically carried out at 3 hours and 5 minutes past midnight at
local server time. To explicitly trigger a checkpoint, use server.checkpoint.
Monitoring
Monitoring functions are now provided entirely by the Nominum statmon utility,
supported by CacheServe 7 with the auth-monitoring and monitoring configuration
elements.
Both the auth-monitoring and monitoring elements are pre-configured in CacheServe.

Ratelimiting
Ratelimiting is discussed in detail in Ratelimiting.
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.
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-

535 Ratelimiting
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.

policy 176
post-edits 146
Index pre-edits 146
retrieving individual 212
retrieving multiple 215

-
supported fields 145
--tcp-acl 125
action.add 210
--udp-acl 125
action.changed 480
A
action.count 211
aa header 499
action.delete 211
action 50, 144
action.get 212
action 145
action.list 213
action.add 210
action.mget 215
action.count 211
action.replace 216
action.delete 211
action.update 218
action.get 212
action.list 213
resolver statistic 520
action.mget 215
ad header 499
action.replace 216
adding actions 210
action.update 218
additional
adding 210
server.query return 435
comment 145
address
count 145
address-node 149
counting 211
cacheserve-deleteconf option 132
deleting 211
cacheserve-dumpconf option 134
errors 145
cacheserve-editconf option 136
events 146
name 146

537 Index
address-list 50, 146 address-list.add 219, 239
adding 219, 239 address-list.changed 480
address-list.add 219, 239 address-list.delete 221
address-list.delete 221 address-list.dump 221
address-list.get 222, 250 file location 221
address-list.list 223 address-list.dump file 221
address-list.load 225 address-list.get 222, 250
address-list.mget 226 address-list.list 223
address-list.replace 228, 255 address-list.load 225
address-list.update 229, 257 merging or replacing entries 225
comment 147 source file format 225
count 147, 152, 154 address-list.mget 226
deleting 221 address-list.replace 228, 255
errors 147, 152, 154 address-list.update 229, 257
events 149, 153, 155 address-node 50, 149
loading from a file 225 adding 231
lowest-address-v4 148 address 149
lowest-address-v6 148 address-node.add 231
merging or replacing entries 225 address-node.delete 232
name 148, 152, 154 address-node.get 233
post-edits 148, 152, 155 address-node.list 234
pre-edits 148, 153, 155 address-node.replace 236
representative-address-v4 148 deleting 232
representative-address-v6 149 events 151
retrieving individual 222, 250 list 150
retrieving multiple 226 listing 234
supported fields 147 post-edits 150

Index 538
pre-edits 150 purpose-built domains and 86
replacing values 236 ratelimiting clients and 90
supported fields 149 size-limiting traffic and 91
tag 151 and policy-selector 512
address-node.add 231 annotate policy action 506
address-node.changed 480 answer
address-node.delete 232 server.query return 436
address-node.get 233 answer-address policy-selector 512
address-node.list 234 answer-by policy action 507
address-node.replace 236 answer-byname policy action 507
agents, configuring 105, 107 answer-byresolver policy action 507
aliases answer-cname policy action 507
server.query return 436 answer-noerror policy action 508
all 404, 445 answer-nxdomain policy action 508
ratelimiter.statistics 365 answer-ttl policy action 508
resolver.statistics 404 answer policy action 506
server.statistics 445 assign policy action 508
telemetry.statistics 455 auth-monitoring.changed 481
--all auth-server-list 51, 151
cacheserve-dumpconf option 134 auth-server-list.delete 240
cacheserve-loadconf option 138 auth-server-list.get 241
all-events auth-server-list.list 242
connection 159 auth-server-list.mget 243
all-indications ratelimiter statistic 518 auth-server-list.replace 245
amplification attacks 85 auth-server-list.update 246
characteristics of 85 deleting 240
how they work 85 listing 242

539 Index
resolver 181 authoritative name servers
retrieving individual 241 adding 248
retrieving multiple 243 adding lists of 242
supported fields 152 listing authoritative name servers 252
auth-server-list.add 242 authoritative servers 72
auth-server-list.changed 481 adding 250
auth-server-list.delete 240 deleting lists of 240
auth-server-list.get 241 listing 252
auth-server-list.mget 243 authority
auth-server-list.replace 245 server.query return 436
auth-server-list.update 246 B
auth-server-node 51, 153 backing up 73

adding 248, 250 backups
auth-server-node.add 248, 250 creating 73
auth-server-node.list 252 restoring 74
auth-server-node.mget 253 binding
listing 252 binding.add 259
retrieving multiple 253 binding.delete 261
supported fields 153 binding.get 262
auth-server-node.add 248, 250 binding.list 263
auth-server-node.changed 481 events 158
auth-server-node.list 252 policy 156
auth-server-node.mget 253 post-edits 157
auth drop/s 143 pre-edits 157
auth req/s 143 priority 157
auth resp/s 143 server 157

Index 540
view 157 cacheserve-deleteconf 132
when 158 --configuration 133
binding object 51, 155 --destination-address 133
binding.add 259 --layer 133
binding.changed 482 --list 133
binding.delete 261 --name 133
binding.get 262 --policy 133
binding.list 263 --server 133
bps --source-address 133
ratelimiter 178 --version 133
ratelimiter.abate 487 --view 133
ratelimiter.onset 489 address 132
broken configuration, finding 431 cacheserve-dumpconf
C --address 134
cache --all 134
retrieving forwarders from 388 --channel 134
retrieving names from 382, 386 --configuration 134
cache-memory-in-use 404 --destination-address 135
cache-misses 520 --json 135
resolver statistic 520 --layer 135
cacheserve --list 135
database location 122 --list-all 135
license location 124 --name 135
performance tuning 70 --object-type 135
run in foreground 123 cacheserve-editconf
supported log facilities 124 --address 136
--channel 133, 136

541 Index
--configuration 137 cacheserve-stats 140
--destination-address 137 channel argument 140
--json 137 count argument 140
--layer 137 cpu argument 141
--list 137 csv argument 141
--name 137 statistics argument 142
--object-type 133, 137 version argument 142
--policy 135, 137 wait argument 142
--server 135, 137 CacheServe file locations
--source-address 135, 137 address-list.dump 221
--version 136-137 cacheserve objects 128
--view 136-137 cacheserve process
-c See cacheserve-editconf, --con- --channel 122

figuration
--configuration 122
-t See cacheserve-editconf, --object-
--directory 122
type
--dns-port 123
--fd-limit 123
--all 138
--foreground 123
--channel 139
--foreground-with-syslog 123
--check 139
--help 123
--configuration 139
--license 124
--json 139
--no-statmon 124
--layer 139
--root 124
--object-type 139
--statmon-directory 124
--version 140
--syslog-facility 124
limitations of configuration
checking 138 --tcp-acl 125
--udp-acl 125

Index 542
--usage 125 client-network 179, 354, 363, 367
--user 125 (client-network (32 128)) 179, 354,

363, 367
--version 125
cacheserve utilities
calendar policy-selector 512
cd header 499
channel
client-subnet 181, 369, 392, 406
cacheserve-loadconf option 139
resolver 181
cacheserve process argument 122
layer 168, 203
client-subnet-specific 383
--channel 122
clients
channell
rate-limit based on qps 90
cacheserve-stats argument 140
clnt req/s 143
check-address
clnt resp/s 143
cacheserve-loadconf option 139
command-channel SNMP option 112
children
Command Channel
policy 176
add method 60
chroot() 529
adding list or table values in specific
--directory and 123
positions 61
client-address 433
appending values 61
client-address-is policy-selector 513
basic commands 59
client-address policy-selector 512
common methods 60
delete method 60

543 Index
escaping characters 59 resolver.inspect-delegation 386
events 58 resolver.inspect-forwarders 388
get method 60 resolver.mget 390
list method 60 server.all-errors 431
list slicing 61 commands-not-logged
lists 59 server 197
mget method 60 comment
nom-tell client 61 action 145
protocol basics 58 address-list 147
protocol message formats 59 device-list 160
protocol message types 58 resolver 182
removing values 61 selector 195
replace method 61 configuration
requests 58 best practices 138
responses 58 cacheserve-deleteconf option 133
table slicing 61 cacheserve-dumpconf option 134
tables 59 cacheserve-editconf option 137
updating object values 61 cacheserve-loadconf option 139
using with snmpagent 115 cacheserve process argument 122
commands deleting 132
action.mget 215 dumping 134
address-list.mget 226 example 131
auth-server-list.mget 243 loading 138
auth-server-node.mget 253 --configuration 122
device-list.mget 278 configuration checking, cacheserve

versus cacheserve-loadconf 138
name-group.mget 317

Index 544
configuration examples connection
adding an action to a policy 77 all-events 159
binding.add 80 events 159
name-list.add 78-79 idle-timeout 159
name-node.add 78-79 supported fields 159
policy-selector 79 connection object 52, 158
policy.add 77, 81 connection.get 271
policy.get 80 connection.replace 272
policy.update 77, 79, 81, 352 connection.subscribe-all 272
server.get 199, 427-428, 442, 449-450 connection.update 272
server.query 438 count
server.query in an N2 action 145

environment 439
address-list 147, 152, 154
updating managed-keys 186, 373,
396, 410
device-list 160
updating max-recursive-clients 72
name-list 172
configuration file
counting actions 211
examples of each element 131
counting device-lists 274
formatting 131
counting device-nodes 283
lists 131
counting name-groups 314
tables 131
cpu
tuples 131
Configuration file format 131
cpu-time 142
configuration files
CPU usage, monitoring 70
SNMP 107
creation-time
snmpagent 111
configuration utilities 128

545 Index
csv destination-address 433, 465
cacheserve-stats argument 141 cacheserve-deleteconf option 133
current-entry-count ratelimiter cacheserve-dumpconf option 135

statistic 518
view-selector 206
current-limited-count ratelimiter
destination-address-is policy-
statistic 518
selector 513
D
destination-address policy-selector 513
data dumping
device-group policy-selector 513
address-list 221
device-id policy-selector 513
database
device-list 52, 159
default location 122
adding 273
retrieving address-lists from 221
comment 160
default locations
count 160
counting 274
default view-selector, removing 47
deleting 275
definitions
device-list.add 273
list 131
device-list.count 274
tables 131
device-list.delete 275
tuples 131
device-list.get 275
deleting data 132
device-list.list 276
deleting elements
device-list.mget 278
actions 211
address-lists 221
device-list.update 281
auth-server-lists 240
errors 160
device-lists 275
events 161
device-nodes 284
name 161
name-groups 314

Index 546
post-edits 161 pre-edits 163
pre-edits 161 replacing values for 290
representative-address-v4 161 supported fields 162
retrieving individual 275 tag 163
retrieving multiple 278 updating values for 291
supported fields 160 device-node.add 282
device-list.add 273 device-node.count 283
device-list.count 274 device-node.delete 284
device-list.delete 275 device-node.get 285
device-list.get 275 device-node.list 286
device-list.list 276 device-node.mget 288
device-list.mget 278 device-node.replace 290
device-list.replace 280 device-node.update 291
device-list.update 281 device policy-selector 513
device-node 52, 161 devices
adding 282 adding lists of 273
counting 283 directory
deleting 284 cacheserve process argument 122
device-node.add 282 --directory 122
device-node.count 283 chroot() and 123
device-node.delete 284 directory, SNMP option 112
device-node.replace 290 disable communications with a pro-

visioning server 167
device-node.update 291
dns-port
events 163
identifier 162
--dns-port 123
list 163
DNS amplification attacks See amp-
post-edits 163
lification attacks

547 Index
DNS headers pre-edits 165
aa 499 prefix 166
ad 499 suffix 166
cd 499 supported fields 164
qr 499 dns64-reverse policy action 509
ra 499 dns64 object 52, 163
rd 499 dns64 policy action 508
DNS queries dns64.add 292
modeling 432 dns64.changed 482
DNS rcodes dns64.delete 294
FORMERR 499 dns64.get 295
NOERROR 499 dns64.list 295
NOTIMP 499 dns64.mget 297
NOTZONE 499 dns64.update 301
NXDOMAIN 500 DNSSEC
NXRRSET 500 managed-keys 186, 373, 396, 410
REFUSED 500 dnssec-aware
SERVFAIL 500 resolver 182
YXDOMAIN 500 dnssec-validations-failure 520
YXRRSET 500 dnssec-validations-failure resolver stat-

istic 520
dns64
errors 164
dnssec-validations-insecure resolver stat-
events 166
istic 520
exclude 165
mapped 165
dnssec-validations-success resolver stat-
name 165 istics 520
post-edits 165 domain 383-384, 386-388

Index 548
domain names error
adding lists of 219, 239 event return 483-484
retrieving individual lists of 222, 241, errors

250
action 145
driver-specific options, SNMP 114
driver, SNMP option 113
device-list 160
dropped
dns64 164
layer 168, 203
name-group 170
dropped-recursions resolver
name-list 173
statistics 520
policy 176
dump files
ratelimiter 179
resolver 183
dumped data locations
selector 195
address-lists 221
server 197
dumping configuration data 134
view 204
dumping data
view-selector 207
address-list 221
/etc/channel.conf 63, 140
E
event returns
EDNS 181
error 483-484
edns-buffer-size 433
name 483-484
edns-flags 434
events
efficiency 142
action 146
encrypted
action.changed 480
name-node 174
entry-creation-time
address-list.changed 480
address-node 151

549 Index
address-node.changed 480 policy 178
auth-monitoring.changed 481 policy.changed 485
auth-server-list.changed 481 policy.hit 486
auth-server-node.changed 481 ratelimiter 180
binding 158 ratelimiter.abate 486
binding.changed 482 ratelimiter.changed 488
connection 159 ratelimiter.onset 489
device-list 161 resolver 194
device-node 163 resolver.changed 490
dns64 166 resolver.flush 491
dns64.changed 482 resolver.id-spoofing-suspected 491
layer 169, 204 selector.changed 492
layer.changed 482 server 202
layer.provisioning-connected 483 server.changed 492
layer.provisioning-connection- server.configuration-error 492

failure 483
server.formerr-loop 492
server.restart 493
server.stop 493
server.tcp-client-limit 493
layer.provisioning-update-
server.udp-recursion-limit 493
success 484
SNMP 115
telemetry.changed 493
name-group 172
view 206
name-group.changed 485
view-selector 196, 209
name-list 173
view-selector.changed 493
name-list.changed 485
view.changed 494
name-node 175
name-node.changed 485

Index 550
examples flags 434
configuration file 131 server.query return 436
SNMP agent configuration 105, 107 force-resolution 434
exclude foreground
dns64 165 cacheserve process argument 123
exists 384 --foreground 123
expiration 459 foreground-with-syslog
expiring-entry-age 518 cacheserve process argument 123
expiring-entry-age ratelimiter --foreground-with-syslog 123

statistic 518
foreground, running cacheserve in 123
F
formatting files for address-list.load 225
faulted state
formatting files for name-list.load 326
recovering from 518
FORMERR 499
fd-limit
server statistic 522
--fd-limit 123
forward
fields
resolver 183
ratelimiter 179
forward-mode 388
inspect-forwarders return 388
forwarders 389
file descriptor exhaustion 188
inspect-forwarders return 389
file descriptors 72, 123, 192, 378, 401,
G
414-415
GET messages 105
if you're running out 72
groups
files
name-group 171
fixing a faulted provisioning session 518

551 Index
H dump the configuration database 134
help list authoritative name servers 252
cacheserve process argument 123 load data into cacheserve 138
--help 123 manage amplification attacks 85
hidden manage authoritative servers 72
layer 168, 203 performance-tune CacheServe 70
hints retrieve a device-list 275
resolver 183 retrieve a name-group 315
hit-rate percentage 142 retrieve an action 212
how-to retrieve an address-list 222, 250
fix an open resolver 70 retrieve an auth-server-list 241
how to run cacheserve as a specific user 125
add a device-list 273 run cacheserve under a specific dir-

ectory 124
add an action 210
I
add an address-list 219, 239
add an auth-server-list 242
id-spoofing-defense-queries resolver
add an auth-server-node 248, 250
statistic 520
control file descriptor use 72
ID spoofing 98
control recursion contexts 72
identifier
count a device-list 274
device-node 162
count a device-node 283
idle-timeout
count a name-group 314
connection 159
count an action 211
delete a list of authoritative
resolver 184
servers 240
delete a list of devices 275
ignored-referral-lookups resolver stat-
delete a list of domain names 221
istic 520

Index 552
immortal 384, 387 cacheserve-loadconf option 139
important files K
address-list.dump 221 Kafka 55, 67

indications-by-bps 518 kafka-configuration-field 502
indications-by-bps ratelimiter L
statistic 518
lame delegations 372
last-limited-time
indications-by-qps ratelimiter
statistic 519 ratelimiter.abate 487
initial-qname policy-selector 514 ratelimiter.onset 489
inspect-forwarders last-use-time
forward-mode return 388 ratelimiter.abate 487
forwarders return 389 ratelimiter.onset 490
instance-information 303 layer
interrupted-before-recursion 521 cacheserve-deleteconf option 133
interrupted-before-recursion resolver cacheserve-dumpconf option 135

statistic 521 cacheserve-editconf option 137
interrupted-recursion-waits 521 cacheserve-loadconf option 139
interrupted-recursion-waits resolver stat- channel 168, 203
istic 521
errors 168, 203
events 169, 204
interrupted-recursions resolver
hidden 168, 203
statistic 521
layer.mget 308
ipv4netlen 501
name 169, 203
ipv6netlen 502
operator 167
J
priority 169
json
provisioning 169
provisioning and 167

553 Index
server 169 layer.provisioning-reimaging 484
supported fields 168 license
layer object 53, 166 cacheserve process argument 124
layer.add 303 default location 124
layer.changed 482 --license 124
layer.clear-fault 305 list
layer.delete 305 address-node 150
layer.get 306 cacheserve-deleteconf option 133
layer.list 306 cacheserve-dumpconf option 135
layer.mget 308 cacheserve-editconf option 137
layer.provisioning-connected 483 device-node 163
layer.provisioning-connection- name-node 174

failure 483
list-all
listen-on-matching
server 198
layer.provisioning-update-success 484
lists 131
layer.reimage 309
adding a list of authoritative name
layer.replace 309 servers 242
layer.update 311 adding a list of devices 273
layers adding a list of domain names 219,

239
events
adding address-lists 219, 239, 252
layer.changed 482
adding auth-server-lists 242
layer.provisioning-connected 483
adding device-lists 273
layer.provisioning-connection-fail-
ure 483 adding values in specific positions 61
layer.provisioning- definition of 131

disconnected 483

Index 554
deleting a list of authoritative log-id-spoofing

servers 240
resolver 184
deleting a list of devices 275
log-lame
deleting a list of domain names 221
resolver 185
deleting address-lists 221
logging
deleting auth-server-lists 240
supported facilities 124
deleting device-lists 275
lookups 521, 523
retrieving an individual list of domain
names 222, 241, 250
lookups resolver statistic 521
retrieving individual address-
lists 222, 250 lowest-address-v4
retrieving individual auth-server- address-list 148

lists 241
lowest-address-v6
slicing syntax 61
address-list 148
lists of devices
M
deleting 275
lists of domain names
deleting 221
malicious domain redirection 76, 80
load-driver
managed-keys
SNMP command 115
configuration example 186, 373, 396,
loading addresses from a file 225 410
loading configuration data 138 resolver 185
log managed-keys-state
SNMP field 113 resolver 186
log-command-channel managed-keys field 186, 373, 396, 410
server 200 managers, SNMP 104
log-dnssec mapped
resolver 184 dns64 165

555 Index
master agent, running SNMP as 110 messages-delivered 504, 525
masteragent, SNMP option 114 monitoring statistic 504
max-cache-size telemetry statistic 525
resolver 186 messages-dropped 504, 525
max-cache-ttl monitoring statistic 504
resolver 186 telemetry statistic 525
max-client-ttl messages-produced 504, 525
resolver 187 monitoring statistic 504
max-edns-udp-size telemetry statistic 525
resolver 187 MIBs 105
max-ncache-ttl NETWORK-SERVICES-MIB.TXT 108
resolver 187 NOMINUM-AGENT-CAPS-MIB 108
max-recursive-clients 72 NOMINUM-MDR-MIB 108
configuration example 72 NOMINUM-NSM-MIB 108
RAM required per context 200, 429, NOMINUM-NSN-MIB 108

443, 451
NOMINUM-PCS-MIB 108
server 200
NOMINUM-POLICY-BASED-RATE-
max-tcp-clients LIMITING-MIB 109
server 200 NOMINUM-POLICY-MANAGER-

MIB 109
max-tcp-recursions 72
NOMINUM-PROVISIONING-SERVICE-
resolver 187
MIB 109
maximum-entries
NOMINUM-PROXY-MIB 109
ratelimiter 179
NOMINUM-QRS-MIB 109
MDR
NOMINUM-RATE-LIMITER-MIB 109
CacheServe equivalent 76
NOMINUM-RESOLVER-MIB 109
memory in-use 143
NOMINUM-RTA-MIB 109
NOMINUM-SMI-MIB 109

Index 556
Nominum-specific 108 cacheserve-editconf option 137
NOMINUM-TC-MIB 109 device-list 161
min-cache-ttl dns64 165
resolver 188 event return 483-484
minseverity layer 169, 203
SNMP option 114 name-list 171, 173
misconfigured elements, how to name-node 175

find 431
policy 177
monitoring 534
ratelimiter 179
Monitoring CPU usage 70
monitoring statistics
resolver 188
selector 195
view 205
queue-full 504
name-empty-ok 505
name-group
records-dropped 505
counting 314
records-not-produced 505
deleting 314
errors 170
events 172
N
groups 171
N2 environment, server.query example
in 439
name-group.delete 314
name 384, 387, 389
name-group.get 315
action 146
name-group.list 316
name-group.mget 317
name-group.replace 319

557 Index
name-group.update 320 name-list.dump 323
retrieving individual 315 name-list.get 324
retrieving multiple 317 name-list.list 325
supported fields 170 name-list.load 326
name-group object 54, 170 merging or replacing entries 326
name-group.add 313 source file format 326
name-group.changed 485 name-list.mget 327
name-group.count 314 name-list.replace 329
name-group.delete 314 name-list.update 330
name-group.get 315 name-lists
name-group.list 316 merging or replacing entries 326
name-group.mget 317 source file format 326
name-group.replace 319 name-node
name-group.update 320 configuration examples 79
name-list encrypted 174
count 172 events 175
errors 173 list 174
events 173 name 175
name 171, 173 post-edits 175
post-edits 171, 173 pre-edits 175
pre-edits 171, 173 supported fields 174
supported fields 172 tag 175
name-list object 54, 172 name-node object 54, 174
name-list.add 322 name-node.add 331
configuration examples 78-79 configuration examples 78
name-list.changed 485 name-node.changed 485
name-list.delete 323 name-node.delete 332

Index 558
name-node.get 333 retaining history for 63
name-node.list 334 Nominum 104
name-node.mget 336 NOMINUM-AGENT-CAPS-MIB 108
name-node.replace 338 NOMINUM-NSM-MIB 108
name-node.update 339 NOMINUM-NSN-MIB 108
named-selector policy-selector 514 NOMINUM-PCS-MIB 108
named selector See selector NOMINUM-POLICY-BASED-RATE-

LIMITING-MIB 109
NOMINUM-POLICY-MANAGER-MIB 109
resolver 188
NOMINUM-PROVISIONING-SERVICE-
net-SNMP
MIB 109
command-line
NOMINUM-PROXY-MIB 109
general information 117
NOMINUM-QRS-MIB 109
snmpget 119
NOMINUM-RATE-LIMITER-MIB 109
snmptranslate 118
NOMINUM-RESOLVER-MIB 109
snmptrapd 120
NOMINUM-SMI-MIB 109
snmpwalk 118
Nominum-specific MIBs 108
using with snmpagent 117
NOMINUM-TC-MIB 109
NETWORK-SERVICES-MIB.TXT 108
nonexistence-proof 385
no-statmon
not policy-selector 514
NOTAUTH 499
--no-statmon 124
NOTIMP 499
no view/s 143
NOTZONE 499
NOERROR 499
NXDOMAIN 500
nom-tell 61
NXDOMAIN redirection 76
command-line mode 62
creating a policy for 77
executable location 61
NXR
interactive mode 62
CacheServe equivalent 76

559 Index
NXRRSET 500 view-selector 56, 206
O observer-address 114
object-type open resolver, fixing 70
cacheserve-deleteconf option 133 operator layer 48, 167
cacheserve-dumpconf option 135 or policy-selector 514
cacheserve-editconf option 137 P
cacheserve-loadconf option 139 performance tuning 70
objects limiting the number of TCP con-

nections 72
action 50, 144
preferred hardware and OS 71
address-list 50, 146
recommended network settings 72
address-node 50, 149
recursion contexts 72
address-server-list 51
pid, SNMP option 116
platform 459
auth-server-node 51, 153
plugins 459
binding 51, 155
policies
connection 52, 158
device-list 52, 159
policy
device-node 52, 161
action 176
dns64 52, 163
binding 156
layer 53, 166
name-group 54, 170
cacheserve-editconf option 135, 137
name-list 54, 172
children 176
name-node 54, 174
creating an NXDOMAIN redirection 77
policy 54, 175
errors 176
ratelimiter 55, 178
events 178
selector 55, 195
name 177
telemetry 55, 202

Index 560
post-edits 177 qname-is 515
pre-edits 177 qname-prefix 515
selector 177 qtype 516
server 157 response-size 516
supported fields 176 result 516
policy-action server-address 516
configuration examples 77 synthesized 516
policy-selector type-exists-at-qname 516
configuration examples 79 policy actions
policy-selectors annotate 506
and 512 answer 506
answer-address 512 answer-by 507-508
calendar 512 answer-byname 507
client-address 512 answer-byresolver 507
client-address-is 513 answer-noerror 508
destination-address 513 answer-nxdomain 508
destination-address-is 513 answer-ttl 508
device 513 dns64 508
device-group 513 dns64-reverse 509
device-id 513 send-event 509
initial-qname 514 sort-addresses 509
named-selector 514 stop 510
not 514 truncate 510
or 514 policy object 54, 175
qclass 514 policy selectors
qflag 514 qname-in-group 515
qname 514

561 Index
policy.add 341 selector 196
configuration examples 77, 81 server 200
policy.changed 485 view 205
policy.delete 343 view-selector 207
policy.get 343 pre-edits
configuration examples 80 action 146
policy.hit 486 address-list 148, 153, 155
policy.list 344 address-node 150
policy.mget 345 binding 157
policy.replace 347 device-list 161
policy.simulate 349 device-node 163
policy.update 350 dns64 165
configuration examples 77, 79, 81, name-list 171, 173

352
name-node 175
post-edits
policy 177
action 146
ratelimiter 180
resolver 189
address-node 150
selector 196
binding 157
server 201
device-list 161
view 205
device-node 163
view-selector 207
dns64 165
prefetch-ratio
name-list 171, 173
resolver 189
name-node 175
prefetches 385
policy 177
prefix
ratelimiter 180
dns64 166
resolver 188

Index 562
preload domain attacks
resolver 189 pseudo-random subdomain attacks 72
preload-nxdomain PTR records
resolver 190 returning for RFC1918 addresses 194,

380, 403, 417
preload-nxrrset
purpose-built amplification domains 86
resolver 190
Q
prioritized-domains
q/cpusec 142
resolver 190
qclass 434
priority
binding 157
qclass policy-selector 514
layer 169
qflag policy-selector 514
qname 434
proactive-lookups resolver statistic 521
process-information 116
product 459
resolver 191
provisioning
faulted recovery 518
resolver 191
layer 169
qname-in-group policy selector 515
layers and 167
qname-is policy-selector 515
where events are reported 167
qname-prefix policy-selector 515
provisioning-status 517
qname policy-selector 514
provisioning events 167
qps
provisioning server
rate-limiting clients using 90
disabling communications with 167
ratelimiter 180
provisioning session 517
provisioning statuses 517
PRSD attacks See pseudo-random sub-

563 Index
qr header 499 R
qtype 434 ra header 499
server.query return 437 rate-limited-requests 521, 523
qtype policy-selector 516 server statistic 523
queries 521 rate-limited-requests resolver

statistic 521
modeling 432
rate-limiting 84
queries resolver statistic 521
ratelimiter 55, 178
query-name
bps 178
client-network 179, 354, 363, 367
errors 179
query-name-labels
events 180
fields 179
maximum-entries 179
query-source-pool
name 179
resolver 191
post-edits 180
pre-edits 180
resolver 192
qps 180
query-type
query-name 179, 354, 363, 367
unenforced 180
ratelimiter statistics
query‐name 179, 354, 363, 367
all-indications 518
queue-full 504, 525
current-entry-count 518
monitoring statistic 504
telemetry statistic 525
expiring-entry-age 518
indications-by-bps 518
queued-prefetches resolver statistic 521

Index 564
uses 519 client-network-family 489
ratelimiter.abate 486 client-network-mask-length 489
bps 487 creation-time 489
client-network 487 entry-creation-time 489
client-network-family 487 fields 489
client-network-mask-length 487 last-limited-time 489
creation-time 487 last-use-time 490
entry-creation-time 487 name 490
fields 487 qps 490
last-limited-time 487 query-name 490
last-use-time 487 query-name-labels 490
name 488 query-type 490
qps 488 unenforced 490
query-name 488 ratelimiter.statistics 364
query-name-labels 488 all 365
query-type 488 ratelimiter.update 366
unenforced 488 ratelimiting
ratelimiter.add 354 limit clients based on qps 90
ratelimiter.changed 488 limit traffic based on size 91
ratelimiter.delete 356 managing amplification attacks 85
ratelimiter.get 356 simple 84
ratelimiter.limited 360 rcode
ratelimiter.list 357 server.query return 437
ratelimiter.mget 358 rd header 499
ratelimiter.onset 489 rdataclass 519
bps 489 records-delivered 504, 525
client-network 489 monitoring statistic 504

565 Index
telemetry statistic 525 representative-address-v6
records-dropped 505, 526 address-list 149
monitoring statistic 505 request-minimal-events 115
telemetry statistic 526 requests-no-view 523
records-not-produced 505 requests-no-view server statistic 523
monitoring statistic 505 requests-received 142, 523
records-produced 505, 526 requests-received server statistics 523
monitoring statistic 505 requests-sent 142, 522-523
telemetry statistic 526 resolver statistic 522
recovering from faulted state 518 server statistic 523
recur cntxs 143 reset 365, 404, 445
recursion-contexts-in-use 142, 523 telemetry.statistics 455
recursion-contexts-in-use server resolution

statistic 523
recursion contexts 72
resolutions 392
increasing 72
resolver 435
recursive-lookups 521, 523
client-subnet 181
recursive-lookups resolver statistic 521
comment 182
redirection
dnssec-aware 182
malicious domain 80
errors 183
NXDOMAIN 76
events 194
REFUSED 500
forward 183
hints 183
address-list 148
ignore-first-referral 184
device-list 161
log-dnssec 184
log-id-spoofing 184

Index 566
log-lame 185 server.query return 437
managed-keys 185 stub 193
managed-keys-state 186 supported fields 181
managed-keys example 186, 373, synthesize-nxdomain 193

396, 410
trusted-keys 194
max-cache-size 186
view-selector.query return 466
max-cache-ttl 186
resolver-statistics 519
max-client-ttl 187
resolver commands
max-edns-udp-size 187
resolver.mget 390
max-ncache-ttl 187
resolver statistics
max-tcp-recursions 187
min-cache-ttl 188
cache-misses 520
name 188
dnssec-validations-failure 520
negative-trust-anchors 188
post-edits 188
pre-edits 189
prefetch-ratio 189
preload 189
preload-nxdomain 190
interrupted-before-recursion 521
preload-nxrrset 190
interrupted-recursion-waits 521
prioritized-domains 190
qname-case-randomization 191
lookups 521
qname-case-randomization-exclu-
sions 191
queries 521
query-source-pool 191
query-source-pool-v6 192
rrset-order 192
server-address-lookup-order 193

567 Index
requests-sent 522 response-time
responses-by-rcode 522 server.query return 438
tcp-requests-sent 522 response size
resolver.add 368 rate-limit using 91
resolver.changed 490 responses-by-rcode 522
resolver.delete 381 responses-by-rcode resolver

statistic 522
resolver.flush 381, 491
responses-received 142, 523
resolver.get 382
responses-received server statistic 523
resolver.id-spoofing-suspected 491
responses-sent 142, 523
responses-sent server statistic 523
restart 417
restoring from backup 73
resolver.mget 390
result
resolver.replace 392
result policy-selector 516
resolver.statistics
retrieving data
all 404
address-list 221
statistics 405, 446
retrieving elements
resolver.update 406
actions 212
resolvers
address-lists 222, 250
retrieving delegation points from the
cache 386 auth-server-lists 241
retrieving forwarders from the device-lists 275

cache 388
name-groups 315
retrieving names from the cache 382
retrieving multiple actions 215
response-size
retrieving multiple address-lists 226
retrieving multiple auth-server-lists 243
response-size policy-selector 516

Index 568
retrieving multiple auth-server- selector.delete 419

nodes 253
selector.get 420
retrieving multiple device-lists 278
selector.list 420
retrieving multiple name-groups 317
selector.mget 422
RFC1918 addresses
selector.replace 423
returning PTR records for 194, 380,
selector.update 425
403, 417
send-event policy action 509
root
server
--root 124
cacheserve-editconf option 135, 137
--user and 124-125
commands-not-logged 197
rrset-order
errors 197
resolver 192
events 202
S
layer 169
seconds-since-epoch 522
listen-on-matching 198
selector
log-command-channel 200
comment 195
max-recursive-clients 200
errors 195
max-tcp-clients 200
name 195
post-edits 200
policy 177
pre-edits 201
post-edits 196
server-id 201
pre-edits 196
server-version 201
selector 196
time-zone 201
selector fields 196
versioncheck-interval 202
selector object 55, 195
resolver 193
selector.add 418
server-address policy-selector 516

569 Index
server-id server.checkpoint 431
server 201 server.configuration-error 492
server-version server.delete 431
server 201 server.formerr-loop 492
server commands server.get 432
server.all-errors 431 configuration examples 199, 427-428,

442, 449-450
server statistics
server.query 432
client-address 433
lookups 523
client-subnet;client-subnet
server.query 433
configuration example 438-439
recursion-contexts-in-use 523
edns-buffer-size 433
edns-flags 434
requests-no-view 523
flags 434
requests-received 523
force-resolution 434
requests-sent 523
server.query returns
responses-received 523
additional 435
responses-sent 523
aliases 436
answer 436
tcp-clients 524
authority 436
tcp-connections-accepted 524
client-subnet 436
tcp-connections-rejected 524
dropped 436
flags 436
server.add 426
policies 436
server.all-errors 431
qclass 437
server.block-checkpoints 431
qname 437
server.changed 492

Index 570
qtype 437 sizeval 524
rcode 437 SNMP
resolution 437 agent configuration information 107
resolver 437 agents 105
response-size 438 command-channel option 112
response-time 438 concepts and architecture 104
result 438 configuration file 107
trace-messages 438 configuration files 107
view 438 configuring agents 107
server.replace 440 directory option 112
server.restart 493 driver-specific options 114
server.statistics driver option 113
all 445 events 115
server.stop 493 GET messages 105
server.tcp-client-limit 493 log field 113
server.udp-recursion-limit 493 managers 104
server.unblock-checkpoints 447 master agents and 110
server.update masteragent 114
configuration examples 199, 427-428, MIBs 105

441-442, 449-450
minseverity option 114
server.usage 447
network management
servers 387 applications 104
SERVFAIL 500 Nominum MIBs 108
setseverity 114 options 106
show-drivers 116 pid 116
simple ratelimiting 84 running as a master agent 110
SIMULATED 433 running as a subagent 109

571 Index
stop command 116 location of mibs 108
syslog-facility 114 manipulating via the Command Chan-

nel 115
traps 105
MIB documentation 106, 108
traps defined 105
options
with Nominum products, general
notes 105 command-channel 112
SNMP agents, configuring 105, 107 specifying configuration

information 107
snmpagent 105-106
using with Net-SNMP 117
--configuration flag 106
using with Net-SNMP command-line
--foreground-with-syslog flag 107
tools 117
--foreground flag 106
using with the Command
--help flag 107 Channel 115
--masteragent flag 107 snmpagent.conf 108
--root flag 107 snmpagent_master.conf 106, 108
--usage flag 107 snmpagent_master.conf sample file 111
--user flag 107 snmpagent_subagent.conf 108
--version flag 107 snmpget 119
command-channel 112 snmptranslate 118
command synopsis 106 snmptrapd 120
configuration file 111 snmpwalk 118
command-channel 112 SO_REUSEPORT 71, 198, 427, 441, 449
directory 112 sort-addresses policy action 509
driver 113 source-address 466
log 113 cacheserve-deleteconf option 133
masteragent 114 cacheserve-editconf option 135, 137
syslog-facility 114 view-selector fields 207
configuring 107

Index 572
source-port-mask interrupted-recursions 521
view-selector fields 207 lookups 521, 523
source-ports malformed-requests-dropped 523
view-selector fields 208 messages-delivered 504, 525
source-ports-prefix messages-dropped 504, 525
view-selector fields 208 messages-produced 504, 525
start-time 435 proactive-lookups 521
statistics queries 521
active-recursions 520 queue-full 504, 525
all-indications 518 queued-prefetches 521
cache-memory-in-use 404 rate-limited-requests 521, 523
cache-misses 520 ratelimiter 364
cacheserve-stats argument 142 records-delivered 504, 525
current-entry-count 518 records-dropped 505, 526
current-limited-count 518 records-not-produced 505
dnssec-validations-failure 520 records-produced 505, 526
dnssec-validations-insecure 520 recursion-contexts-in-use 523
dnssec-validations-success 520 recursive-lookups 521, 523
dropped-recursions 520 requests-no-view 523
expiring-entry-age 518 requests-received 523
formerr-loop-dropped 522 requests-sent 522-523
id-spoofing-defense-queries 520 resolver.statistics 405, 446
ignored-referral-lookups 520 responses-by-rcode 522
indications-by-bps 518 responses-received 523
indications-by-qps 519 responses-sent 523
interrupted-before-recursion 521 retrieving with cacheserve-stats 140
interrupted-recursion-waits 521 suppressed-duplicate-queries 524

573 Index
tcp-clients 524 synthesize-nxdomain
tcp-connections-accepted 524 resolver 193
tcp-connections-rejected 524 synthesized policy-selector 516
tcp-requests-sent 522, 524 synthetic 387
telemetry.statistics 456 sys %cpu 143
uses 519 syslog
statmon-directory supported facilities 124
cacheserve process argument 124 syslog-facility
--statmon-directory 124 cacheserve process argument 124
status --syslog-facility 124
provisioning 517 syslog-facility, SNMP 114
stop 453 system-time 142
stop policy action 510 T
stop, SNMP command 116 tables 131

stub 387 adding values in specific positions 61
resolver 193 configuration file example 131
stubs definition of 131
using to return PTRs for RFC1918 slicing syntax 61
addresses 194, 380, 403, 417
tag
subagent, running SNMP as 109
address-node 151
suffix
device-node 163
dns64 166
name-node 175
Supported 178
target 381
tcp 435
tcp-acl
tcp-clients 524

Index 574
tcp-clients server statistic 524 telemetry.statistics 455
tcp-connections-accepted 524 all 455
server statistic 524 reset 455
tcp-connections-rejected 524 statistics 456
server statistic 524 testing DNS queries 432
tcp-requests-sent 522, 524 thread-groups 447
server statistic 524 threshold-abate 526
tcp-requests-sent resolver statistic 522 threshold-duration 526
tcp clnts 143 threshold-onset 526
TCP connections time-zone
limiting the number of 72 server 201
tcp sent/s 143 view 205
telemetry timeout 431
statistics 456 total %cpu 142
supported fields 202 trace-messages
telemetry object 55, 202 server.query return 438
telemetry statistics tracing 435
messages-delivered 525 traps, SNMP 105
messages-dropped 525 truncate policy action 510
messages-produced 525 trusted-keys
queue-full 525 resolver 194
records-delivered 525 ttl 385, 388
records-dropped 526 tuples 131
records-produced 526 configuration file example 131
telemetry.changed 493 definition of 131
telemetry.get 453 type-exists-at-qname policy-selector 516
telemetry.replace 453 types 385

575 Index
U cacheserve-loadconf option 140
udp-acl cacheserve-stats argument 142
cacheserve process argument 125 cacheserve process argument 125
uint64 527 --version 125
unenforced versioncheck-interval
ratelimiter 180 server 202
ratelimiter.abate 488 view 435
ratelimiter.onset 490 binding 157
unload-driver 117 cacheserve-deleteconf option 133
uptime 143 cacheserve-editconf option 136-137
usage errors 204
cacheserve process argument 125 events 206
--usage 125 name 205
user post-edits 205
cacheserve process argument 125 pre-edits 205
--user 125 server.query return 438
--root and 124-125 time-zone 205
user-time 142 view-selector 208
uses 519 view-selector.query return 466
uses ratelimiter statistic 519 view-selector
uuid 115-116, 458 destination-address 206
V errors 207
validated 386 events 196, 209
vendor 459 post-edits 207
version 117, 458 pre-edits 207
cacheserve-deleteconf option 133 source-address 207
cacheserve-editconf option 136-137 source-port-mask 207

Index 576
source-port-prefix 208 W
source-ports 208 wait argument
supported fields 206 cacheserve-stats 142
view 208 when
view-selector.query return 466 binding 158
view-selector object 56, 206 where cacheserve saves data
view-selector.add 459 address-list dumps 221
view-selector.changed 493 Y
view-selector.delete 461 YXDOMAIN 500
view-selector.get 461 YXRRSET 500
view-selector.list 462 Z
view-selector.mget 464, 467 Zookeeper 67
view-selector.query 465
resolver return 466
view-selector return 466
view return 466
view-selector.replace 466
view-selector.update 469
view.add 470
view.changed 494
view.delete 471
view.get 472
view.list 473
view.mget 473
view.replace 475
view.update 476

Vantio CacheServe 7.2.0 Administrators Manual 20161208 PDF

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Vantio CacheServe 7.2.0 Administrators Manual 20161208 PDF

Uploaded by

Copyright:

Available Formats

Vantio CacheServe

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

Caching name servers 44

What's in the manual 45

Chapter 2: Getting started with CacheServe 46

The elements of CacheServe 46

Removing the default view-selector 47

Chapter 3: CacheServe configuration object quick reference 50

Core domain tagging 53

Chapter 4: Controlling CacheServe with the Command Channel 58

Command Channel Basics 58

Basic Command Channel Messages 59

Common Object Methods 60

Vantio CacheServe Administrator's Manual NOMINUM CONFIDENTIAL

List and Table Slicing 61

The nom-tell Command Channel Client 61

From the Command Line 62

Retaining History for nom-tell 63

The /etc/channel.conf file 63

Chapter 5: Connecting CacheServe to other Nominum products 66

A note about leaders 67

The statmon utility 67

Creating a monitoring querystore 68

Creating an authoritative querystore 68

Chapter 6: General operations 70

Unexpected open resolver 70

Monitoring CPU usage 70

What it all means 71

NOMINUM CONFIDENTIAL Vantio CacheServe Administrator's Manual

Ramp up your network 72

Limit the number of TCP connections 72

Increase the number of recursion contexts 72

Configuring authoritative servers 72

Backing up and restoring 73

Backing up CacheServe and querystores 73

Restoring from a backup 74

Chapter 7: The CacheServe policy engine 76

Create the NXDOMAIN policy 77

Add an NXDOMAIN action 77

Make NXDOMAIN redirection lists 78

Make an NXDOMAIN policy selector 79

Bind the NXDOMAIN policy to a view 80

Malicious domain redirection 80

Create the malicious redirection policy 81

Add a malicious redirection action 81

Make malicious redirection lists 82

Make a malicious redirection policy selector 82

Bind the malicious redirection policy to a view 83

Rate-limiting DNS amplification attacks 85

How DNS amplification attacks work 85

Vantio CacheServe Administrator's Manual NOMINUM CONFIDENTIAL

Characteristics of amplification attacks 85

Mitigating amplification attacks 85

Dealing with purpose-built amplification domains 86

Managing ANY queries 89

Managing dual-use domains 89

Rate-limiting amplification traffic 90

Chapter 9: Defending against DDoS attacks using prefetch extensions 92

Defending against DDoS attacks on authoritative servers 92

The CacheServe prefetch mechanism 93

Configuring prefetch extension 94

Prefetch extension statistics 94

Extended caching and DNSSEC 95