1unbound-control(8) unbound 1.4.13 unbound-control(8)
2
6 unbound-control, unbound-control-setup - Unbound remote server control
7 utility.
8
10 unbound-control [-h] [-c cfgfile] [-s server] command
11
13 Unbound-control performs remote administration on the unbound(8) DNS
14 server. It reads the configuration file, contacts the unbound server
15 over SSL sends the command and displays the result.
16 The available options are:
18 -h Show the version and commandline option help.
20 -c cfgfile
22 The config file to read with settings. If not given the default
23 config file /etc/unbound/unbound.conf is used.
24 -s server[@port]
26 IPv4 or IPv6 address of the server to contact. If not given,
27 the address is read from the config file.
28
30 There are several commands that the server understands.
31 start Start the server. Simply execs unbound(8). The unbound exe‐
33 cutable is searched for in the PATH set in the environment. It
34 is started with the config file specified using -c or the
35 default config file.
36 stop Stop the server. The server daemon exits.
38 reload Reload the server. This flushes the cache and reads the config
40 file fresh.
41 verbosity number
43 Change verbosity value for logging. Same values as verbosity
44 keyword in unbound.conf(5). This new setting lasts until the
45 server is issued a reload (taken from config file again), or the
46 next verbosity control command.
47 log_reopen
49 Reopen the logfile, close and open it. Useful for logrotation
50 to make the daemon release the file it is logging to. If you
51 are using syslog it will attempt to close and open the syslog
52 (which may not work if chrooted).
53 stats Print statistics. Resets the internal counters to zero, this can
55 be controlled using the statistics-cumulative config statement.
56 Statistics are printed with one [name]: [value] per line.
57 stats_noreset
59 Peek at statistics. Prints them like the stats command does, but
60 does not reset the internal counters to zero.
61 status Display server status. Exit code 3 if not running (the connec‐
63 tion to the port is refused), 1 on error, 0 if running.
64 local_zone name type
66 Add new local zone with name and type. Like local-zone config
67 statement. If the zone already exists, the type is changed to
68 the given argument.
69 local_zone_remove name
71 Remove the local zone with the given name. Removes all local
72 data inside it. If the zone does not exist, the command suc‐
73 ceeds.
74 local_data RR data...
76 Add new local data, the given resource record. Like local-data
77 config statement, except for when no covering zone exists. In
78 that case this remote control command creates a transparent zone
79 with the same name as this record. This command is not good at
80 returning detailed syntax errors.
81 local_data_remove name
83 Remove all RR data from local name. If the name already has no
84 items, nothing happens. Often results in NXDOMAIN for the name
85 (in a static zone), but if the name has become an empty nonter‐
86 minal (there is still data in domain names below the removed
87 name), NOERROR nodata answers are the result for that name.
88 dump_cache
90 The contents of the cache is printed in a text format to stdout.
91 You can redirect it to a file to store the cache in a file.
92 load_cache
94 The contents of the cache is loaded from stdin. Uses the same
95 format as dump_cache uses. Loading the cache with old, or wrong
96 data can result in old or wrong data returned to clients. Load‐
97 ing data into the cache in this way is supported in order to aid
98 with debugging.
99 lookup name
101 Print to stdout the name servers that would be used to look up
102 the name specified.
103 flush name
105 Remove the name from the cache. Removes the types A, AAAA, NS,
106 SOA, CNAME, DNAME, MX, PTR, SRV and NAPTR. Because that is fast
107 to do. Other record types can be removed using flush_type or
108 flush_zone.
109 flush_type name type
111 Remove the name, type information from the cache.
112 flush_zone name
114 Remove all information at or below the name from the cache. The
115 rrsets and key entries are removed so that new lookups will be
116 performed. This needs to walk and inspect the entire cache, and
117 is a slow operation.
118 flush_stats
120 Reset statistics to zero.
121 flush_requestlist
123 Drop the queries that are worked on. Stops working on the
124 queries that the server is working on now. The cache is unaf‐
125 fected. No reply is sent for those queries, probably making
126 those users request again later. Useful to make the server
127 restart working on queries with new settings, such as a higher
128 verbosity level.
129 dump_requestlist
131 Show what is worked on. Prints all queries that the server is
132 currently working on. Prints the time that users have been
133 waiting. For internal requests, no time is printed. And then
134 prints out the module status.
135 flush_infra all|IP
137 If all then entire infra cache is emptied. If a specific IP
138 address, the entry for that address is removed from the cache.
139 It contains EDNS, ping and lameness data.
140 dump_infra
142 Show the contents of the infra cache.
143 set_option opt: val
145 Set the option to the given value without a reload. The cache
146 is therefore not flushed. The option must end with a ':' and
147 whitespace must be between the option and the value. Some val‐
148 ues may not have an effect if set this way, the new values are
149 not written to the config file, not all options are supported.
150 This is different from the set_option call in libunbound, where
151 all values work because unbound has not been inited.
152 The values that work are: statistics-interval, statistics-cumu‐
154 lative, do-not-query-localhost, harden-short-bufsize,
155 harden-large-queries, harden-glue, harden-dnssec-stripped,
156 harden-below-nxdomain, harden-referral-path, prefetch,
157 prefetch-key, log-queries, hide-identity, hide-version, iden‐
158 tity, version, val-log-level, val-log-squelch, ignore-cd-flag,
159 add-holddown, del-holddown, keep-missing, tcp-upstream.
160 get_option opt
162 Get the value of the option. Give the option name without a
163 trailing ':'. The value is printed. If the value is "", noth‐
164 ing is printed and the connection closes. On error 'error ...'
165 is printed (it gives a syntax error on unknown option). For
166 some options a list of values, one on each line, is printed.
167 The options are shown from the config file as modified with
168 set_option. For some options an override may have been taken
169 that does not show up with this command, not results from e.g.
170 the verbosity and forward control commands. Not all options
171 work, see list_stubs, list_forwards, list_local_zones and
172 list_local_data for those.
173 list_stubs
175 List the stub zones in use. These are printed one by one to the
176 output. This includes the root hints in use.
177 list_forwards
179 List the forward zones in use. These are printed zone by zone
180 to the output.
181 list_local_zones
183 List the local zones in use. These are printed one per line
184 with zone type.
185 list_local_data
187 List the local data RRs in use. The resource records are
188 printed.
189 forward [off | addr ... ]
191 Setup forwarding mode. Configures if the server should ask
192 other upstream nameservers, should go to the internet root name‐
193 servers itself, or show the current config. You could pass the
194 nameservers after a DHCP update.
195 Without arguments the current list of addresses used to forward
197 all queries to is printed. On startup this is from the for‐
198 ward-zone "." configuration. Afterwards it shows the status.
199 It prints off when no forwarding is used.
200 If off is passed, forwarding is disabled and the root name‐
202 servers are used. This can be used to avoid to avoid buggy or
203 non-DNSSEC supporting nameservers returned from DHCP. But may
204 not work in hotels or hotspots.
205 If one or more IPv4 or IPv6 addresses are given, those are then
207 used to forward queries to. The addresses must be separated
208 with spaces. With '@port' the port number can be set explicitly
209 (default port is 53 (DNS)).
210 By default the forwarder information from the config file for
212 the root "." is used. The config file is not changed, so after
213 a reload these changes are gone. Other forward zones from the
214 config file are not affected by this command.
215
217 The unbound-control program exits with status code 1 on error, 0 on
218 success.
219
221 The setup requires a self-signed certificate and private keys for both
222 the server and client. The script unbound-control-setup generates
223 these in the default run directory, or with -d in another directory.
224 If you change the access control permissions on the key files you can
225 decide who can use unbound-control, by default owner and group but not
226 all users. Run the script under the same username as you have config‐
227 ured in unbound.conf or as root, so that the daemon is permitted to
228 read the files, for example with:
229 sudo -u unbound unbound-control-setup
230 If you have not configured a username in unbound.conf, the keys need
231 read permission for the user credentials under which the daemon is
232 started. The script preserves private keys present in the directory.
233 After running the script as root, turn on control-enable in
234 unbound.conf.
235
237 The stats command shows a number of statistic counters.
238 threadX.num.queries
240 number of queries received by thread
241 threadX.num.cachehits
243 number of queries that were successfully answered using a cache
244 lookup
245 threadX.num.cachemiss
247 number of queries that needed recursive processing
248 threadX.num.prefetch
250 number of cache prefetches performed. This number is included
251 in cachehits, as the original query had the unprefetched answer
252 from cache, and resulted in recursive processing, taking a slot
253 in the requestlist. Not part of the recursivereplies (or the
254 histogram thereof) or cachemiss, as a cache response was sent.
255 threadX.num.recursivereplies
257 The number of replies sent to queries that needed recursive pro‐
258 cessing. Could be smaller than threadX.num.cachemiss if due to
259 timeouts no replies were sent for some queries.
260 threadX.requestlist.avg
262 The average number of requests in the internal recursive pro‐
263 cessing request list on insert of a new incoming recursive pro‐
264 cessing query.
265 threadX.requestlist.max
267 Maximum size attained by the internal recursive processing
268 request list.
269 threadX.requestlist.overwritten
271 Number of requests in the request list that were overwritten by
272 newer entries. This happens if there is a flood of queries that
273 recursive processing and the server has a hard time.
274 threadX.requestlist.exceeded
276 Queries that were dropped because the request list was full.
277 This happens if a flood of queries need recursive processing,
278 and the server can not keep up.
279 threadX.requestlist.current.all
281 Current size of the request list, includes internally generated
282 queries (such as priming queries and glue lookups).
283 threadX.requestlist.current.user
285 Current size of the request list, only the requests from client
286 queries.
287 threadX.recursion.time.avg
289 Average time it took to answer queries that needed recursive
290 processing. Note that queries that were answered from the cache
291 are not in this average.
292 threadX.recursion.time.median
294 The median of the time it took to answer queries that needed
295 recursive processing. The median means that 50% of the user
296 queries were answered in less than this time. Because of big
297 outliers (usually queries to non responsive servers), the aver‐
298 age can be bigger than the median. This median has been calcu‐
299 lated by interpolation from a histogram.
300 total.num.queries
302 summed over threads.
303 total.num.cachehits
305 summed over threads.
306 total.num.cachemiss
308 summed over threads.
309 total.num.prefetch
311 summed over threads.
312 total.num.recursivereplies
314 summed over threads.
315 total.requestlist.avg
317 averaged over threads.
318 total.requestlist.max
320 the maximum of the thread requestlist.max values.
321 total.requestlist.overwritten
323 summed over threads.
324 total.requestlist.exceeded
326 summed over threads.
327 total.requestlist.current.all
329 summed over threads.
330 total.recursion.time.median
332 averaged over threads.
333 time.now
335 current time in seconds since 1970.
336 time.up
338 uptime since server boot in seconds.
339 time.elapsed
341 time since last statistics printout, in seconds.
342
344 mem.total.sbrk
345 If sbrk(2) is available, an estimate of the heap size of the
346 program in number of bytes. Close to the total memory used by
347 the program, as reported by top and ps. Could be wrong if the
348 OS allocates memory non-contiguously.
349 mem.cache.rrset
351 Memory in bytes in use by the RRset cache.
352 mem.cache.message
354 Memory in bytes in use by the message cache.
355 mem.mod.iterator
357 Memory in bytes in use by the iterator module.
358 mem.mod.validator
360 Memory in bytes in use by the validator module. Includes the key
361 cache and negative cache.
362 histogram.<sec>.<usec>.to.<sec>.<usec>
364 Shows a histogram, summed over all threads. Every element counts
365 the recursive queries whose reply time fit between the lower and
366 upper bound. Times larger or equal to the lowerbound, and
367 smaller than the upper bound. There are 40 buckets, with bucket
368 sizes doubling.
369 num.query.type.A
371 The total number of queries over all threads with query type A.
372 Printed for the other query types as well, but only for the
373 types for which queries were received, thus =0 entries are omit‐
374 ted for brevity.
375 num.query.type.other
377 Number of queries with query types 256-65535.
378 num.query.class.IN
380 The total number of queries over all threads with query class IN
381 (internet). Also printed for other classes (such as CH (CHAOS)
382 sometimes used for debugging), or NONE, ANY, used by dynamic
383 update. num.query.class.other is printed for classes 256-65535.
384 num.query.opcode.QUERY
386 The total number of queries over all threads with query opcode
387 QUERY. Also printed for other opcodes, UPDATE, ...
388 num.query.tcp
390 Number of queries that were made using TCP towards the unbound
391 server.
392 num.query.ipv6
394 Number of queries that were made using IPv6 towards the unbound
395 server.
396 num.query.flags.RD
398 The number of queries that had the RD flag set in the header.
399 Also printed for flags QR, AA, TC, RA, Z, AD, CD. Note that
400 queries with flags QR, AA or TC may have been rejected because
401 of that.
402 num.query.edns.present
404 number of queries that had an EDNS OPT record present.
405 num.query.edns.DO
407 number of queries that had an EDNS OPT record with the DO
408 (DNSSEC OK) bit set. These queries are also included in the
409 num.query.edns.present number.
410 num.answer.rcode.NXDOMAIN
412 The number of answers to queries, from cache or from recursion,
413 that had the return code NXDOMAIN. Also printed for the other
414 return codes.
415 num.answer.rcode.nodata
417 The number of answers to queries that had the pseudo return code
418 nodata. This means the actual return code was NOERROR, but
419 additionally, no data was carried in the answer (making what is
420 called a NOERROR/NODATA answer). These queries are also
421 included in the num.answer.rcode.NOERROR number. Common for
422 AAAA lookups when an A record exists, and no AAAA.
423 num.answer.secure
425 Number of answers that were secure. The answer validated cor‐
426 rectly. The AD bit might have been set in some of these
427 answers, where the client signalled (with DO or AD bit in the
428 query) that they were ready to accept the AD bit in the answer.
429 num.answer.bogus
431 Number of answers that were bogus. These answers resulted in
432 SERVFAIL to the client because the answer failed validation.
433 num.rrset.bogus
435 The number of rrsets marked bogus by the validator. Increased
436 for every RRset inspection that fails.
437 unwanted.queries
439 Number of queries that were refused or dropped because they
440 failed the access control settings.
441 unwanted.replies
443 Replies that were unwanted or unsolicited. Could have been ran‐
444 dom traffic, delayed duplicates, very late answers, or could be
445 spoofing attempts. Some low level of late answers and delayed
446 duplicates are to be expected with the UDP protocol. Very high
447 values could indicate a threat (spoofing).
448
450 /etc/unbound/unbound.conf
451 unbound configuration file.
452 /etc/unbound
454 directory with private keys (unbound_server.key and unbound_con‐
455 trol.key) and self-signed certificates (unbound_server.pem and
456 unbound_control.pem).
457
459 unbound.conf(5), unbound(8).
460NLnet Labs Sep 15, 2011 unbound-control(8)