diff options
Diffstat (limited to 'external/unbound/doc/unbound-control.8.in')
| -rw-r--r-- | external/unbound/doc/unbound-control.8.in | 555 |
1 files changed, 0 insertions, 555 deletions
diff --git a/external/unbound/doc/unbound-control.8.in b/external/unbound/doc/unbound-control.8.in deleted file mode 100644 index 47d2a4861..000000000 --- a/external/unbound/doc/unbound-control.8.in +++ /dev/null @@ -1,555 +0,0 @@ -.TH "unbound-control" "8" "Jun 13, 2017" "NLnet Labs" "unbound 1.6.3" -.\" -.\" unbound-control.8 -- unbound remote control manual -.\" -.\" Copyright (c) 2008, NLnet Labs. All rights reserved. -.\" -.\" See LICENSE for the license. -.\" -.\" -.SH "NAME" -.B unbound\-control, -.B unbound\-control\-setup -\- Unbound remote server control utility. -.SH "SYNOPSIS" -.B unbound\-control -.RB [ \-hq ] -.RB [ \-c -.IR cfgfile ] -.RB [ \-s -.IR server ] -.IR command -.SH "DESCRIPTION" -.B Unbound\-control -performs remote administration on the \fIunbound\fR(8) DNS server. -It reads the configuration file, contacts the unbound server over SSL -sends the command and displays the result. -.P -The available options are: -.TP -.B \-h -Show the version and commandline option help. -.TP -.B \-c \fIcfgfile -The config file to read with settings. If not given the default -config file @ub_conf_file@ is used. -.TP -.B \-s \fIserver[@port] -IPv4 or IPv6 address of the server to contact. If not given, the -address is read from the config file. -.TP -.B \-q -quiet, if the option is given it does not print anything if it works ok. -.SH "COMMANDS" -There are several commands that the server understands. -.TP -.B start -Start the server. Simply execs \fIunbound\fR(8). The unbound executable -is searched for in the \fBPATH\fR set in the environment. It is started -with the config file specified using \fI\-c\fR or the default config file. -.TP -.B stop -Stop the server. The server daemon exits. -.TP -.B reload -Reload the server. This flushes the cache and reads the config file fresh. -.TP -.B verbosity \fInumber -Change verbosity value for logging. Same values as \fBverbosity\fR keyword in -\fIunbound.conf\fR(5). This new setting lasts until the server is issued -a reload (taken from config file again), or the next verbosity control command. -.TP -.B log_reopen -Reopen the logfile, close and open it. Useful for logrotation to make the -daemon release the file it is logging to. If you are using syslog it will -attempt to close and open the syslog (which may not work if chrooted). -.TP -.B stats -Print statistics. Resets the internal counters to zero, this can be -controlled using the \fBstatistics\-cumulative\fR config statement. -Statistics are printed with one [name]: [value] per line. -.TP -.B stats_noreset -Peek at statistics. Prints them like the \fBstats\fR command does, but does not -reset the internal counters to zero. -.TP -.B status -Display server status. Exit code 3 if not running (the connection to the -port is refused), 1 on error, 0 if running. -.TP -.B local_zone \fIname\fR \fItype -Add new local zone with name and type. Like \fBlocal\-zone\fR config statement. -If the zone already exists, the type is changed to the given argument. -.TP -.B local_zone_remove \fIname -Remove the local zone with the given name. Removes all local data inside -it. If the zone does not exist, the command succeeds. -.TP -.B local_data \fIRR data... -Add new local data, the given resource record. Like \fBlocal\-data\fR -config statement, except for when no covering zone exists. In that case -this remote control command creates a transparent zone with the same -name as this record. This command is not good at returning detailed syntax -errors. -.TP -.B local_data_remove \fIname -Remove all RR data from local name. If the name already has no items, -nothing happens. Often results in NXDOMAIN for the name (in a static zone), -but if the name has become an empty nonterminal (there is still data in -domain names below the removed name), NOERROR nodata answers are the -result for that name. -.TP -.B local_zones -Add local zones read from stdin of unbound\-control. Input is read per line, -with name space type on a line. For bulk additions. -.TP -.B local_zones_remove -Remove local zones read from stdin of unbound\-control. Input is one name per -line. For bulk removals. -.TP -.B local_datas -Add local data RRs read from stdin of unbound\-control. Input is one RR per -line. For bulk additions. -.TP -.B local_datas_remove -Remove local data RRs read from stdin of unbound\-control. Input is one name per -line. For bulk removals. -.TP -.B dump_cache -The contents of the cache is printed in a text format to stdout. You can -redirect it to a file to store the cache in a file. -.TP -.B load_cache -The contents of the cache is loaded from stdin. Uses the same format as -dump_cache uses. Loading the cache with old, or wrong data can result -in old or wrong data returned to clients. Loading data into the cache -in this way is supported in order to aid with debugging. -.TP -.B lookup \fIname -Print to stdout the name servers that would be used to look up the -name specified. -.TP -.B flush \fIname -Remove the name from the cache. Removes the types -A, AAAA, NS, SOA, CNAME, DNAME, MX, PTR, SRV and NAPTR. -Because that is fast to do. Other record types can be removed using -.B flush_type -or -.B flush_zone\fR. -.TP -.B flush_type \fIname\fR \fItype -Remove the name, type information from the cache. -.TP -.B flush_zone \fIname -Remove all information at or below the name from the cache. -The rrsets and key entries are removed so that new lookups will be performed. -This needs to walk and inspect the entire cache, and is a slow operation. -.TP -.B flush_bogus -Remove all bogus data from the cache. -.TP -.B flush_negative -Remove all negative data from the cache. This is nxdomain answers, -nodata answers and servfail answers. Also removes bad key entries -(which could be due to failed lookups) from the dnssec key cache, and -iterator last-resort lookup failures from the rrset cache. -.TP -.B flush_stats -Reset statistics to zero. -.TP -.B flush_requestlist -Drop the queries that are worked on. Stops working on the queries that the -server is working on now. The cache is unaffected. No reply is sent for -those queries, probably making those users request again later. -Useful to make the server restart working on queries with new settings, -such as a higher verbosity level. -.TP -.B dump_requestlist -Show what is worked on. Prints all queries that the server is currently -working on. Prints the time that users have been waiting. For internal -requests, no time is printed. And then prints out the module status. -This prints the queries from the first thread, and not queries that are -being serviced from other threads. -.TP -.B flush_infra \fIall|IP -If all then entire infra cache is emptied. If a specific IP address, the -entry for that address is removed from the cache. It contains EDNS, ping -and lameness data. -.TP -.B dump_infra -Show the contents of the infra cache. -.TP -.B set_option \fIopt: val -Set the option to the given value without a reload. The cache is -therefore not flushed. The option must end with a ':' and whitespace -must be between the option and the value. Some values may not have an -effect if set this way, the new values are not written to the config file, -not all options are supported. This is different from the set_option call -in libunbound, where all values work because unbound has not been initialized. -.IP -The values that work are: statistics\-interval, statistics\-cumulative, -do\-not\-query\-localhost, harden\-short\-bufsize, harden\-large\-queries, -harden\-glue, harden\-dnssec\-stripped, harden\-below\-nxdomain, -harden\-referral\-path, prefetch, prefetch\-key, log\-queries, -hide\-identity, hide\-version, identity, version, val\-log\-level, -val\-log\-squelch, ignore\-cd\-flag, add\-holddown, del\-holddown, -keep\-missing, tcp\-upstream, ssl\-upstream, max\-udp\-size, ratelimit, -ip\-ratelimit, cache\-max\-ttl, cache\-min\-ttl, cache\-max\-negative\-ttl. -.TP -.B get_option \fIopt -Get the value of the option. Give the option name without a trailing ':'. -The value is printed. If the value is "", nothing is printed -and the connection closes. On error 'error ...' is printed (it gives -a syntax error on unknown option). For some options a list of values, -one on each line, is printed. The options are shown from the config file -as modified with set_option. For some options an override may have been -taken that does not show up with this command, not results from e.g. the -verbosity and forward control commands. Not all options work, see list_stubs, -list_forwards, list_local_zones and list_local_data for those. -.TP -.B list_stubs -List the stub zones in use. These are printed one by one to the output. -This includes the root hints in use. -.TP -.B list_forwards -List the forward zones in use. These are printed zone by zone to the output. -.TP -.B list_insecure -List the zones with domain\-insecure. -.TP -.B list_local_zones -List the local zones in use. These are printed one per line with zone type. -.TP -.B list_local_data -List the local data RRs in use. The resource records are printed. -.TP -.B insecure_add \fIzone -Add a \fBdomain\-insecure\fR for the given zone, like the statement in unbound.conf. -Adds to the running unbound without affecting the cache contents (which may -still be bogus, use \fBflush_zone\fR to remove it), does not affect the config file. -.TP -.B insecure_remove \fIzone -Removes domain\-insecure for the given zone. -.TP -.B forward_add \fR[\fI+i\fR] \fIzone addr ... -Add a new forward zone to running unbound. With +i option also adds a -\fIdomain\-insecure\fR for the zone (so it can resolve insecurely if you have -a DNSSEC root trust anchor configured for other names). -The addr can be IP4, IP6 or nameserver names, like \fIforward-zone\fR config -in unbound.conf. -.TP -.B forward_remove \fR[\fI+i\fR] \fIzone -Remove a forward zone from running unbound. The +i also removes a -\fIdomain\-insecure\fR for the zone. -.TP -.B stub_add \fR[\fI+ip\fR] \fIzone addr ... -Add a new stub zone to running unbound. With +i option also adds a -\fIdomain\-insecure\fR for the zone. With +p the stub zone is set to prime, -without it it is set to notprime. The addr can be IP4, IP6 or nameserver -names, like the \fIstub-zone\fR config in unbound.conf. -.TP -.B stub_remove \fR[\fI+i\fR] \fIzone -Remove a stub zone from running unbound. The +i also removes a -\fIdomain\-insecure\fR for the zone. -.TP -.B forward \fR[\fIoff\fR | \fIaddr ...\fR ] -Setup forwarding mode. Configures if the server should ask other upstream -nameservers, should go to the internet root nameservers itself, or show -the current config. You could pass the nameservers after a DHCP update. -.IP -Without arguments the current list of addresses used to forward all queries -to is printed. On startup this is from the forward\-zone "." configuration. -Afterwards it shows the status. It prints off when no forwarding is used. -.IP -If \fIoff\fR is passed, forwarding is disabled and the root nameservers -are used. This can be used to avoid to avoid buggy or non\-DNSSEC supporting -nameservers returned from DHCP. But may not work in hotels or hotspots. -.IP -If one or more IPv4 or IPv6 addresses are given, those are then used to forward -queries to. The addresses must be separated with spaces. With '@port' the -port number can be set explicitly (default port is 53 (DNS)). -.IP -By default the forwarder information from the config file for the root "." is -used. The config file is not changed, so after a reload these changes are -gone. Other forward zones from the config file are not affected by this command. -.TP -.B ratelimit_list \fR[\fI+a\fR] -List the domains that are ratelimited. Printed one per line with current -estimated qps and qps limit from config. With +a it prints all domains, not -just the ratelimited domains, with their estimated qps. The ratelimited -domains return an error for uncached (new) queries, but cached queries work -as normal. -.TP -.B ip_ratelimit_list \fR[\fI+a\fR] -List the ip addresses that are ratelimited. Printed one per line with current -estimated qps and qps limit from config. With +a it prints all ips, not -just the ratelimited ips, with their estimated qps. The ratelimited -ips are dropped before checking the cache. -.TP -.B view_list_local_zones \fIview\fR -\fIlist_local_zones\fR for given view. -.TP -.B view_local_zone \fIview\fR \fIname\fR \fItype -\fIlocal_zone\fR for given view. -.TP -.B view_local_zone_remove \fIview\fR \fIname -\fIlocal_zone_remove\fR for given view. -.TP -.B view_list_local_data \fIview\fR -\fIlist_local_data\fR for given view. -.TP -.B view_local_data \fIview\fR \fIRR data... -\fIlocal_data\fR for given view. -.TP -.B view_local_data_remove \fIview\fR \fIname -\fIlocal_data_remove\fR for given view. -.SH "EXIT CODE" -The unbound\-control program exits with status code 1 on error, 0 on success. -.SH "SET UP" -The setup requires a self\-signed certificate and private keys for both -the server and client. The script \fIunbound\-control\-setup\fR generates -these in the default run directory, or with \-d in another directory. -If you change the access control permissions on the key files you can decide -who can use unbound\-control, by default owner and group but not all users. -Run the script under the same username as you have configured in unbound.conf -or as root, so that the daemon is permitted to read the files, for example with: -.nf - sudo \-u unbound unbound\-control\-setup -.fi -If you have not configured -a username in unbound.conf, the keys need read permission for the user -credentials under which the daemon is started. -The script preserves private keys present in the directory. -After running the script as root, turn on \fBcontrol\-enable\fR in -\fIunbound.conf\fR. -.SH "STATISTIC COUNTERS" -The \fIstats\fR command shows a number of statistic counters. -.TP -.I threadX.num.queries -number of queries received by thread -.TP -.I threadX.num.queries_ip_ratelimited -number of queries rate limited by thread -.TP -.I threadX.num.cachehits -number of queries that were successfully answered using a cache lookup -.TP -.I threadX.num.cachemiss -number of queries that needed recursive processing -.TP -.I threadX.num.prefetch -number of cache prefetches performed. This number is included in -cachehits, as the original query had the unprefetched answer from cache, -and resulted in recursive processing, taking a slot in the requestlist. -Not part of the recursivereplies (or the histogram thereof) or cachemiss, -as a cache response was sent. -.TP -.I threadX.num.zero_ttl -number of replies with ttl zero, because they served an expired cache entry. -.TP -.I threadX.num.recursivereplies -The 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. -.TP -.I threadX.requestlist.avg -The average number of requests in the internal recursive processing request list on insert of a new incoming recursive processing query. -.TP -.I threadX.requestlist.max -Maximum size attained by the internal recursive processing request list. -.TP -.I threadX.requestlist.overwritten -Number 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. -.TP -.I threadX.requestlist.exceeded -Queries 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. -.TP -.I threadX.requestlist.current.all -Current size of the request list, includes internally generated queries (such -as priming queries and glue lookups). -.TP -.I threadX.requestlist.current.user -Current size of the request list, only the requests from client queries. -.TP -.I threadX.recursion.time.avg -Average time it took to answer queries that needed recursive processing. Note that queries that were answered from the cache are not in this average. -.TP -.I threadX.recursion.time.median -The median of the time it took to answer queries that needed recursive -processing. The median means that 50% of the user queries were answered in -less than this time. Because of big outliers (usually queries to non -responsive servers), the average can be bigger than the median. This median -has been calculated by interpolation from a histogram. -.TP -.I threadX.tcpusage -The currently held tcp buffers for incoming connections. A spot value on -the time of the request. This helps you spot if the incoming\-num\-tcp -buffers are full. -.TP -.I total.num.queries -summed over threads. -.TP -.I total.num.cachehits -summed over threads. -.TP -.I total.num.cachemiss -summed over threads. -.TP -.I total.num.prefetch -summed over threads. -.TP -.I total.num.zero_ttl -summed over threads. -.TP -.I total.num.recursivereplies -summed over threads. -.TP -.I total.requestlist.avg -averaged over threads. -.TP -.I total.requestlist.max -the maximum of the thread requestlist.max values. -.TP -.I total.requestlist.overwritten -summed over threads. -.TP -.I total.requestlist.exceeded -summed over threads. -.TP -.I total.requestlist.current.all -summed over threads. -.TP -.I total.recursion.time.median -averaged over threads. -.TP -.I total.tcpusage -summed over threads. -.TP -.I time.now -current time in seconds since 1970. -.TP -.I time.up -uptime since server boot in seconds. -.TP -.I time.elapsed -time since last statistics printout, in seconds. -.SH EXTENDED STATISTICS -.TP -.I mem.cache.rrset -Memory in bytes in use by the RRset cache. -.TP -.I mem.cache.message -Memory in bytes in use by the message cache. -.TP -.I mem.mod.iterator -Memory in bytes in use by the iterator module. -.TP -.I mem.mod.validator -Memory in bytes in use by the validator module. Includes the key cache and -negative cache. -.TP -.I histogram.<sec>.<usec>.to.<sec>.<usec> -Shows a histogram, summed over all threads. Every element counts the -recursive queries whose reply time fit between the lower and upper bound. -Times larger or equal to the lowerbound, and smaller than the upper bound. -There are 40 buckets, with bucket sizes doubling. -.TP -.I num.query.type.A -The total number of queries over all threads with query type A. -Printed for the other query types as well, but only for the types for which -queries were received, thus =0 entries are omitted for brevity. -.TP -.I num.query.type.other -Number of queries with query types 256\-65535. -.TP -.I num.query.class.IN -The total number of queries over all threads with query class IN (internet). -Also printed for other classes (such as CH (CHAOS) sometimes used for -debugging), or NONE, ANY, used by dynamic update. -num.query.class.other is printed for classes 256\-65535. -.TP -.I num.query.opcode.QUERY -The total number of queries over all threads with query opcode QUERY. -Also printed for other opcodes, UPDATE, ... -.TP -.I num.query.tcp -Number of queries that were made using TCP towards the unbound server. -.TP -.I num.query.tcpout -Number of queries that the unbound server made using TCP outgoing towards -other servers. -.TP -.I num.query.ipv6 -Number of queries that were made using IPv6 towards the unbound server. -.TP -.I num.query.flags.RD -The number of queries that had the RD flag set in the header. -Also printed for flags QR, AA, TC, RA, Z, AD, CD. -Note that queries with flags QR, AA or TC may have been rejected -because of that. -.TP -.I num.query.edns.present -number of queries that had an EDNS OPT record present. -.TP -.I num.query.edns.DO -number of queries that had an EDNS OPT record with the DO (DNSSEC OK) bit set. -These queries are also included in the num.query.edns.present number. -.TP -.I num.answer.rcode.NXDOMAIN -The number of answers to queries, from cache or from recursion, that had the -return code NXDOMAIN. Also printed for the other return codes. -.TP -.I num.answer.rcode.nodata -The number of answers to queries that had the pseudo return code nodata. -This means the actual return code was NOERROR, but additionally, no data was -carried in the answer (making what is called a NOERROR/NODATA answer). -These queries are also included in the num.answer.rcode.NOERROR number. -Common for AAAA lookups when an A record exists, and no AAAA. -.TP -.I num.answer.secure -Number of answers that were secure. The answer validated correctly. -The AD bit might have been set in some of these answers, where the client -signalled (with DO or AD bit in the query) that they were ready to accept -the AD bit in the answer. -.TP -.I num.answer.bogus -Number of answers that were bogus. These answers resulted in SERVFAIL -to the client because the answer failed validation. -.TP -.I num.rrset.bogus -The number of rrsets marked bogus by the validator. Increased for every -RRset inspection that fails. -.TP -.I unwanted.queries -Number of queries that were refused or dropped because they failed the -access control settings. -.TP -.I unwanted.replies -Replies that were unwanted or unsolicited. Could have been random traffic, -delayed duplicates, very late answers, or could be spoofing attempts. -Some low level of late answers and delayed duplicates are to be expected -with the UDP protocol. Very high values could indicate a threat (spoofing). -.TP -.I msg.cache.count -The number of items (DNS replies) in the message cache. -.TP -.I rrset.cache.count -The number of RRsets in the rrset cache. This includes rrsets used by -the messages in the message cache, but also delegation information. -.TP -.I infra.cache.count -The number of items in the infra cache. These are IP addresses with their -timing and protocol support information. -.TP -.I key.cache.count -The number of items in the key cache. These are DNSSEC keys, one item -per delegation point, and their validation status. -.SH "FILES" -.TP -.I @ub_conf_file@ -unbound configuration file. -.TP -.I @UNBOUND_RUN_DIR@ -directory with private keys (unbound_server.key and unbound_control.key) and -self\-signed certificates (unbound_server.pem and unbound_control.pem). -.SH "SEE ALSO" -\fIunbound.conf\fR(5), -\fIunbound\fR(8). |