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