tiamak/salvium
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

added unbound to external deps

Browse Source
This commit is contained in:
Riccardo Spagni
2014-10-05 23:44:31 +02:00
parent 732493c5cb
commit 9ef094b356
394 changed files with 199264 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
external/unbound/doc/CREDITS vendored Normal file
View File

@@ -0,0 +1,23 @@
Unbound was developed at NLnet Labs by Wouter Wijngaards.
Unbound was architected in January of 2004 by Jakob Schlyter of Kirei
and Roy Arends of Nominet. VeriSign and EP.Net funded development of
the prototype, which was built by David Blacka and Matt Larson of VeriSign.
Late in 2006, NLnet Labs joined the effort, writing an implementation in C
based on the existing prototype and using experience NLnet Labs gained
during the development of NSD, an authoritative DNS server.
At NLnet Labs, Jelte Jansen, Mark Santcroos and Matthijs Mekking
reviewed the unbound C sources.
Jakob Schlyter - for advice on secure settings, random numbers and blacklists.
Ondřej Surý - running coverity analysis tool on 0.9 dev version.
Alexander Gall - multihomed, anycast testing of unbound resolver server.
Zdenek Vasicek and Marek Vavrusa - python module.
cz.nic - sponsoring 'summer of code' development by Zdenek and Marek.
Brett Carr - windows beta testing.
Luca Bruno - patch for windows support in libunbound hosts and resolvconf().
Tom Hendrikx - contributed split-itar.sh a useful script to 5011-track ITAR.
Daisuke HIGASHI - patch for rrset-roundrobin and minimal-responses.
Simon Perrault - DNS64 module.
Robert Edmonds - dnstap code.

5618
external/unbound/doc/Changelog vendored Normal file
View File

File diff suppressed because it is too large Load Diff

103
external/unbound/doc/FEATURES vendored Normal file
View File

@@ -0,0 +1,103 @@
Unbound Features
(C) Copyright 2008, Wouter Wijngaards, NLnet Labs.
This document describes the features and RFCs that unbound
adheres to, and which ones are decided to be out of scope.
Big Features
------------
Recursive service.
Caching service.
Forwarding and stub zones.
Very limited authoritative service.
DNSSEC Validation options.
EDNS0, NSEC3, IPv6, DNAME, Unknown-RR-types.
RSASHA256, GOST, ECDSA, SHA384 DNSSEC algorithms.
Details
-------
Processing support
RFC 1034-1035: as a recursive, caching server. Not authoritative.
including CNAMEs, referrals, wildcards, classes, ...
AAAA type, and IP6 dual stack support.
type ANY queries are supported, class ANY queries are supported.
RFC 1123, 6.1 Requirements for DNS of internet hosts.
RFC 4033-4035: as a validating caching server (unbound daemon).
as a validating stub (libunbound).
RFC 1918.
RFC 1995, 1996, 2136: not authoritative, so no AXFR, IXFR, NOTIFY or
dynamic update services are appropriate.
RFC 2181: completely, including the trust model, keeping rrsets together.
RFC 2308: TTL directive, and the rest of the RFC too.
RFC 2671: EDNS0 support, default advertisement 4Kb size.
RFC 2672: DNAME support.
RFC 3597: Unknown RR type support.
RFC 4343: case insensitive handling of domain names.
RFC 4509: SHA256 DS hash.
RFC 4592: wildcards.
RFC 4697: No DNS Resolution Misbehavior.
RFC 5011: update of trust anchors with timers.
RFC 5155: NSEC3, NSEC3PARAM types
RFC 5358: reflectors-are-evil: access control list for recursive
service. In fact for all DNS service so cache snooping is halted.
RFC 5452: forgery resilience. all recommendations followed.
RFC 5702: RSASHA256 signature algorithm.
RFC 5933: GOST signature algorithm.
RFC 6303: default local zones.
It is possible to block zones or return an address for localhost.
This is a very limited authoritative service. Defaults as in draft.
RFC 6604: xNAME RCODE and status bits.
RFC 6605: ECDSA signature algorithm, SHA384 DS hash.
chroot and drop-root-privileges support, default enabled in config file.
AD bit in query can be used to request AD bit in response (w/o using DO bit).
CD bit in query can be used to request bogus data.
UDP and TCP service is provided downstream.
UDP and TCP are used to request from upstream servers.
SSL wrapped TCP service can be used upstream and provided downstream.
Multiple queries can be made over a TCP stream.
No TSIG support at this time.
No SIG0 support at this time.
No dTLS support at this time.
This is not a DNS statistics package, but some operationally useful
values are provided via unbound-control stats.
TXT RRs from the Chaos class (id.server, hostname.bind, ...) are supported.
draft-0x20: implemented, use caps-for-id option to enable use.
Also implements bitwise echo of the query to support downstream 0x20.
draft-ietf-dnsop-resolver-priming(-00): can prime and can fallback to
a safety belt list.
draft-ietf-dnsop-dnssec-trust-anchor(-01): DS records can be configured
as trust anchors. Also DNSKEYs are allowed, by the way.
draft-ietf-dnsext-dnssec-bis-updates: supported.
Record type syntax support, extensive, from lib ldns.
For these types only syntax and parsing support is needed.
RFC 1034-1035: basic RR types.
RFC 1183: RP, AFSDB, X25, ISDN, RT
RFC 1706: NSAP
RFC 2535: KEY, SIG, NXT: treated as unknown data, syntax is parsed (obsolete).
2163: PX
AAAA type
1876: LOC type
2782: SRV type
2915: NAPTR type.
2230: KX type.
2538: CERT type.
2672: DNAME type.
OPT type
3123: APL
3596: AAAA
SSHFP type
4025: IPSECKEY
4033-4035: DS, RRSIG, NSEC, DNSKEY
4701: DHCID
5155: NSEC3, NSEC3PARAM
4408: SPF
6944: DNSKEY algorithm status

30
external/unbound/doc/LICENSE vendored Normal file
View File

@@ -0,0 +1,30 @@
Copyright (c) 2007, NLnet Labs. All rights reserved.
This software is open source.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
Neither the name of the NLNET LABS nor the names of its contributors may
be used to endorse or promote products derived from this software without
specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

149
external/unbound/doc/README vendored Normal file
View File

@@ -0,0 +1,149 @@
README for Unbound @version@
Copyright 2007 NLnet Labs
http://unbound.net
This software is under BSD license, see LICENSE for details.
The DNS64 module has BSD license in dns64/dns64.c.
The DNSTAP code has BSD license in dnstap/dnstap.c.
* Download the latest release version of this software from
http://unbound.net
or get a beta version from the svn repository at
http://unbound.net/svn/
* Uses the following libraries;
* libevent http://www.monkey.org/~provos/libevent/ (BSD license)
(optional) can use builtin alternative instead.
* libexpat (for the unbound-anchor helper program) (MIT license)
* Make and install: ./configure; make; make install
* --with-libevent=/path/to/libevent
Can be set to either the system install or the build directory.
--with-libevent=no (default) gives a builtin alternative
implementation. libevent is useful when having many (thousands)
of outgoing ports. This improves randomization and spoof
resistance. For the default of 16 ports the builtin alternative
works well and is a little faster.
* --with-libexpat=/path/to/libexpat
Can be set to the install directory of libexpat.
* --without-pthreads
This disables pthreads. Without this option the pthreads library
is detected automatically. Use this option to disable threading
altogether, or, on Solaris, also use --with(out)-solaris-threads.
* --enable-checking
This enables assertions in the code that guard against a variety of
programming errors, among which buffer overflows. The program exits
with an error if an assertion fails (but the buffer did not overflow).
* --enable-static-exe
This enables a debug option to statically link against the
libevent library.
* --enable-lock-checks
This enables a debug option to check lock and unlock calls. It needs
a recent pthreads library to work.
* --enable-alloc-checks
This enables a debug option to check malloc (calloc, realloc, free).
The server periodically checks if the amount of memory used fits with
the amount of memory it thinks it should be using, and reports
memory usage in detail.
* --with-conf-file=filename
Set default location of config file,
the default is /usr/local/etc/unbound/unbound.conf.
* --with-pidfile=filename
Set default location of pidfile,
the default is /usr/local/etc/unbound/unbound.pid.
* --with-run-dir=path
Set default working directory,
the default is /usr/local/etc/unbound.
* --with-chroot-dir=path
Set default chroot directory,
the default is /usr/local/etc/unbound.
* --with-rootkey-file=path
Set the default root.key path. This file is read and written.
the default is /usr/local/etc/unbound/root.key
* --with-rootcert-file=path
Set the default root update certificate path. A builtin certificate
is used if this file is empty or does not exist.
the default is /usr/local/etc/unbound/icannbundle.pem
* --with-username=user
Set default user name to change to,
the default is the "unbound" user.
* --with-pyunbound
Create libunbound wrapper usable from python.
Needs python-devel and swig development tools.
* --with-pythonmodule
Compile the python module that processes responses in the server.
* --disable-sha2
Disable support for RSASHA256 and RSASHA512 crypto.
* --disable-gost
Disable support for GOST crypto, RFC 5933.
* 'make test' runs a series of self checks.
Known issues
------------
o If there are no replies for a forward or stub zone, for a reverse zone,
you may need to add a local-zone: name transparent or nodefault to the
server: section of the config file to unblock the reverse zone.
Only happens for (sub)zones that are blocked by default; e.g. 10.in-addr.arpa
o If libevent is older (before 1.3c), unbound will exit instead of reload
on sighup. On a restart 'did not exit gracefully last time' warning is
printed. Perform ./configure --with-libevent=no or update libevent, rerun
configure and recompile unbound to make sighup work correctly.
It is strongly suggested to use a recent version of libevent.
o If you are not receiving the correct source IP address on replies (e.g.
you are running a multihomed, anycast server), the interface-automatic
option can be enabled to set socket options to achieve the correct
source IP address on UDP replies. Listing all IP addresses explicitly in
the config file is an alternative. The interface-automatic option uses
non portable socket options, Linux and FreeBSD should work fine.
o The warning 'openssl has no entropy, seeding with time', with chroot
enabled, may be solved with a symbolic link to /dev/random from <chrootdir>.
o On Solaris 5.10 some libtool packages from repositories do not work with
gcc, showing errors gcc: unrecognized option `-KPIC'
To solve this do ./configure libtool=./libtool [your options...].
On Solaris you may pass CFLAGS="-xO4 -xtarget=generic" if you use sun-cc.
o If unbound-control (or munin graphs) do not work, this can often be because
the unbound-control-setup script creates the keys with restricted
permissions, and the files need to be made readable or ownered by both the
unbound daemon and unbound-control.
o Crosscompile seems to hang. You tried to install unbound under wine.
wine regedit and remove all the unbound entries from the registry or
delete .wine/drive_c.
Acknowledgements
----------------
o Unbound was written in portable C by Wouter Wijngaards (NLnet Labs).
o Thanks to David Blacka and Matt Larson (Verisign) for the unbound-java
prototype. Design and code from that prototype has been used to create
this program. Such as the iterator state machine and the cache design.
o Other code origins are from the NSD (NLnet Labs) and LDNS (NLnet Labs)
projects. Such as buffer, region-allocator and red-black tree code.
o See Credits file for contributors.
Your Support
------------
NLnet Labs offers all of its software products as open source, most are
published under a BSD license. You can download them, not only from the
NLnet Labs website but also through the various OS distributions for
which NSD, ldns, and Unbound are packaged. We therefore have little idea
who uses our software in production environments and have no direct ties
with 'our customers'.
Therefore, we ask you to contact us at users@NLnetLabs.nl and tell us
whether you use one of our products in your production environment,
what that environment looks like, and maybe even share some praise.
We would like to refer to the fact that your organization is using our
products. We will only do that if you explicitly allow us. In all other
cases we will keep the information you share with us to ourselves.
In addition to the moral support you can also support us
financially. NLnet Labs is a recognized not-for-profit charity foundation
that is chartered to develop open-source software and open-standards
for the Internet. If you use our software to satisfaction please express
that by giving us a donation. For small donations PayPal can be used. For
larger and regular donations please contact us at users@NLnetLabs.nl. Also
see http://www.nlnetlabs.nl/labs/contributors/.
* mailto:unbound-bugs@nlnetlabs.nl

30
external/unbound/doc/README.DNS64 vendored Normal file
View File

@@ -0,0 +1,30 @@
The DNS64 code was written by Viagenie, 2009, by Simon Perrault as part
of the Ecdysis project. The code is copyright by them, and has the BSD
license (see the dns64/dns64.c file).
To enable DNS64 functionality in Unbound, two directives in unbound.conf must
be edited:
1. The "module-config" directive must start with "dns64". For example:
module-config: "dns64 validator iterator"
If you're not using DNSSEC then you may remove "validator".
2. The "dns64-prefix" directive indicates your DNS64 prefix. For example:
dns64-prefix: 64:FF9B::/96
The prefix must be a /96 or shorter.
To test that things are working right, perform a query against Unbound for a
domain name for which no AAAA record exists. You should see a AAAA record in
the answer section. The corresponding IPv6 address will be inside the DNS64
prefix. For example:
$ unbound -c unbound.conf
$ dig @localhost jazz-v4.viagenie.ca aaaa
[...]
;; ANSWER SECTION:
jazz-v4.viagenie.ca. 86400 IN AAAA 64:ff9b::ce7b:1f02

17
external/unbound/doc/README.svn vendored Normal file
View File

@@ -0,0 +1,17 @@
README.svn
For a svn checkout:
* configure script, aclocal.m4, as well as yacc/lex output files are
committed to the repository.
* use --enable-debug flag for configure to enable dependency tracking and
assertions, otherwise, use make clean; make after svn update.
* Note changes in the Changelog.
* Every check-in a postcommit hook is run
(the postcommit hook is in the svn/unbound/hooks directory).
* generates commit email with your changes and comment.
* compiles and runs the tests (with testcode/do-tests.sh).
* If build errors or test errors happen
* Please fix your errors and commit again.
* Use gnu make to compile, make or 'gmake'.

24
external/unbound/doc/README.tests vendored Normal file
View File

@@ -0,0 +1,24 @@
README unbound tests
For a quick test that runs unit tests and state machine tests, use
make test
There is a long test setup for unbound that needs tools installed. Use
make longtest
To make and run the long tests. The results are summarized at the end.
You need to have the following programs installed and in your PATH.
* dig - from the bind-tools package. Used to send DNS queries.
* splint (optional) - for lint test
* doxygen (optional) - for doc completeness test
* ldns-testns - from ldns examples. Used as DNS auth server.
* xxd and nc (optional) - for (malformed) packet transmission.
The optional programs are detected and can be omitted.
testdata/ contains the data for tests.
testcode/ contains scripts and c code for the tests.
do-tests.sh : runs all the tests in the testdata directory.
testbed.sh : compiles on a set of (user specific) hosts and runs do-tests.
Tests are run using testcode/mini_tpkg.sh.

76
external/unbound/doc/TODO vendored Normal file
View File

@@ -0,0 +1,76 @@
TODO items. These are interesting todo items.
o understand synthesized DNAMEs, so those TTL=0 packets are cached properly.
o NSEC/NSEC3 aggressive negative caching, so that updates to NSEC/NSEC3
will result in proper negative responses.
o (option) where port 53 is used for send and receive, no other ports are used.
o (option) to not send replies to clients after a timeout of (say 5 secs) has
passed, but keep task active for later retries by client.
o (option) private TTL feature (always report TTL x in answers).
o (option) pretend-dnssec-unaware, and pretend-edns-unaware modes for workshops.
o delegpt use rbtree for ns-list, to avoid slowdown for very large NS sets.
o (option) reprime and refresh oft used data before timeout.
o (option) retain prime results in a overlaid roothints file.
o (option) store primed key data in a overlaid keyhints file (sort of like drafttimers).
o windows version, auto update feature, a query to check for the version.
o command the server with TSIG inband. get-config, clearcache,
get stats, get memstats, get ..., reload, clear one zone from cache
o NSID rfc 5001 support.
o timers rfc 5011 support.
o Treat YXDOMAIN from a DNAME properly, in iterator (not throwaway), validator.
o make timeout backoffs randomized (a couple percent random) to spread traffic.
o inspect date on executable, then warn user in log if its more than 1 year.
o (option) proactively prime root, stubs and trust anchors, feature.
early failure, faster on first query, but more traffic.
o library add convenience functions for A, AAAA, PTR, getaddrinfo, libresolve.
o library add function to validate input from app that is signed.
o add dynamic-update requests (making a dynupd request) to libunbound api.
o SIG(0) and TSIG.
o support OPT record placement on recv anywhere in the additional section.
o add local-file: config with authority features.
o (option) to make local-data answers be secure for libunbound (default=no)
o (option) to make chroot: copy all needed files into jail (or make jail)
perhaps also print reminder to link /dev/random and sysloghack.
o overhaul outside-network servicedquery to merge with udpwait and tcpwait,
to make timers in servicedquery independent of udpwait queues.
o check into rebinding ports for efficiency, configure time test.
o EVP hardware crypto support.
o option to ignore all inception and expiration dates for rrsigs.
o cleaner code; return and func statements on newline.
o memcached module that sits before validator module; checks for memcached
data (on local lan), stores recursion lookup. Provides one cache for multiple resolver machines, coherent reply content in anycast setup.
o no openssl_add_all_algorithms, but only the ones necessary, less space.
o listen to NOTIFY messages for zones and flush the cache for that zone
if received. Useful when also having a stub to that auth server.
Needs proper protection, TSIG, in place.
o winevent - do not go more than 64 fds (by polling with select one by
one), win95/98 have 100fd limit in the kernel, so this ruins w9x portability.
*** Features features, for later
* dTLS, TLS, look to need special port numbers, cert storage, recent libssl.
* aggressive negative caching for NSEC, NSEC3.
* multiple queries per question, server exploration, server selection.
* support TSIG on queries, for validating resolver deployment.
* retry-mode, where a bogus result triggers a retry-mode query, where a list
of responses over a time interval is collected, and each is validated.
or try in TCP mode. Do not 'try all servers several times', since we must
not create packet storms with operator errors.
o on windows version, implement that OS ancillary data capabilities for
interface-automatic. IPPKTINFO, IP6PKTINFO for WSARecvMsg, WSASendMsg.
o local-zone directive with authority service, full authority server
is a non-goal.
o infra and lame cache: easier size config (in Mb), show usage in graphs.
- store time of dump in cachedumps, so that on a load the ttls can be
compared to the absolute time, and now-expired items can be dealt with.
later
- selective verbosity; ubcontrol trace example.com
- cache fork-dump, pre-load
- for fwds, send queries to N servers in fwd-list, use first reply.
document high scalable, high available unbound setup onepager.
- prefetch DNSKEY when DS in delegation seen (nonCD, underTA).
- use libevent if available on system by default(?), default outgoing 256to1024
[1] BIND-like query logging to see who's looking up what and when
[2] more logging about stuff like SERVFAIL and REFUSED responses
[3] a Makefile that works without gnumake

70
external/unbound/doc/control_proto_spec.txt vendored Normal file
View File

@@ -0,0 +1,70 @@
Specification for the unbound-control protocol.
Server listens on 8953 TCP (localhost by default). Client connects,
SSLv3 or TLSv1 connection setup (server selfsigned certificate,
client has cert signed by server certificate).
Port 8953 is registered with IANA as:
ub-dns-control 8953/tcp unbound dns nameserver control
# Wouter Wijngaards <wouter&nlnetlabs.nl> 10 May 2011
On may 11 2011, ticket [IANA #442315].
Query and Response
------------------
Client sends
UBCT[version] [commandline] \n
fixed string UBCT1 (for version 1), then an ascii text line,
with a command, some whitespace allowed. Line ends with '\n'.
Server executes command. And sends reply in ascii text over channel,
closes the channel when done.
in case of error the first line of the response is:
error <descriptive text possible> \n
or the remainder is data of the response, for many commands the
response is 'ok\n'.
Queries and responses
---------------------
stop
stops the server.
reload
reloads the config file, and flushes the cache.
verbosity <new value>
Change logging verbosity to new value.
stats
output is a list of [name]=[value] lines.
clears the counters.
dump_cache
output is a text representation of the cache contents.
data ends with a line 'EOF' before connection close.
load_cache
client sends cache contents (like from dump_cache), which is stored
in the cache. end of data indicated with a line with 'EOF' on it.
The data is sent after the query line.
flush <name>
flushes some information regarding the name from the cache.
removes the A, AAAA, NS, SOA, CNAME, DNAME, MX, PTR, SRV, NAPTR types.
Does not remove other types.
flush_type <name> <RR type>
removes rrtype entry from the cache.
flush_zone <name>
removes name and everything below that name from the cache.
has to search through the cache item by item, so this is slow.
lookup <name>
see what servers would be queried for a lookup of the given name.
local_zone_remove <name of local-zone entry>
the local-zone entry is removed.
All data from the local zone is also deleted.
If it did not exist, nothing happens.
local_zone <name of local zone> <type>
As the config file entry. Adds new local zone or updates
existing zone type.
local_data_remove <name>
Removes local-data (all types) name.
local_data <resource record string>
Add new local data record (on the rest of the line).
local_data_add www.example.com. IN A 192.0.2.2
if no local_zone exists for it; a transparent zone with the same
name as the data is created.
Other commands in the unbound-control manual page.

603
external/unbound/doc/example.conf.in vendored Normal file
View File

@@ -0,0 +1,603 @@
#
# Example configuration file.
#
# See unbound.conf(5) man page, version @version@.
#
# this is a comment.
#Use this to include other text into the file.
#include: "otherfile.conf"
# The server clause sets the main parameters.
server:
# whitespace is not necessary, but looks cleaner.
# verbosity number, 0 is least verbose. 1 is default.
verbosity: 1
# print statistics to the log (for every thread) every N seconds.
# Set to "" or 0 to disable. Default is disabled.
# statistics-interval: 0
# enable cumulative statistics, without clearing them after printing.
# statistics-cumulative: no
# enable extended statistics (query types, answer codes, status)
# printed from unbound-control. default off, because of speed.
# extended-statistics: no
# number of threads to create. 1 disables threading.
# num-threads: 1
# specify the interfaces to answer queries from by ip-address.
# The default is to listen to localhost (127.0.0.1 and ::1).
# specify 0.0.0.0 and ::0 to bind to all available interfaces.
# specify every interface[@port] on a new 'interface:' labelled line.
# The listen interfaces are not changed on reload, only on restart.
# interface: 192.0.2.153
# interface: 192.0.2.154
# interface: 192.0.2.154@5003
# interface: 2001:DB8::5
# enable this feature to copy the source address of queries to reply.
# Socket options are not supported on all platforms. experimental.
# interface-automatic: no
# port to answer queries from
# port: 53
# specify the interfaces to send outgoing queries to authoritative
# server from by ip-address. If none, the default (all) interface
# is used. Specify every interface on a 'outgoing-interface:' line.
# outgoing-interface: 192.0.2.153
# outgoing-interface: 2001:DB8::5
# outgoing-interface: 2001:DB8::6
# number of ports to allocate per thread, determines the size of the
# port range that can be open simultaneously. About double the
# num-queries-per-thread, or, use as many as the OS will allow you.
# outgoing-range: 4096
# permit unbound to use this port number or port range for
# making outgoing queries, using an outgoing interface.
# outgoing-port-permit: 32768
# deny unbound the use this of port number or port range for
# making outgoing queries, using an outgoing interface.
# Use this to make sure unbound does not grab a UDP port that some
# other server on this computer needs. The default is to avoid
# IANA-assigned port numbers.
# If multiple outgoing-port-permit and outgoing-port-avoid options
# are present, they are processed in order.
# outgoing-port-avoid: "3200-3208"
# number of outgoing simultaneous tcp buffers to hold per thread.
# outgoing-num-tcp: 10
# number of incoming simultaneous tcp buffers to hold per thread.
# incoming-num-tcp: 10
# buffer size for UDP port 53 incoming (SO_RCVBUF socket option).
# 0 is system default. Use 4m to catch query spikes for busy servers.
# so-rcvbuf: 0
# buffer size for UDP port 53 outgoing (SO_SNDBUF socket option).
# 0 is system default. Use 4m to handle spikes on very busy servers.
# so-sndbuf: 0
# use SO_REUSEPORT to distribute queries over threads.
# so-reuseport: no
# EDNS reassembly buffer to advertise to UDP peers (the actual buffer
# is set with msg-buffer-size). 1480 can solve fragmentation (timeouts).
# edns-buffer-size: 4096
# Maximum UDP response size (not applied to TCP response).
# Suggested values are 512 to 4096. Default is 4096. 65536 disables it.
# max-udp-size: 4096
# buffer size for handling DNS data. No messages larger than this
# size can be sent or received, by UDP or TCP. In bytes.
# msg-buffer-size: 65552
# the amount of memory to use for the message cache.
# plain value in bytes or you can append k, m or G. default is "4Mb".
# msg-cache-size: 4m
# the number of slabs to use for the message cache.
# the number of slabs must be a power of 2.
# more slabs reduce lock contention, but fragment memory usage.
# msg-cache-slabs: 4
# the number of queries that a thread gets to service.
# num-queries-per-thread: 1024
# if very busy, 50% queries run to completion, 50% get timeout in msec
# jostle-timeout: 200
# msec to wait before close of port on timeout UDP. 0 disables.
# delay-close: 0
# the amount of memory to use for the RRset cache.
# plain value in bytes or you can append k, m or G. default is "4Mb".
# rrset-cache-size: 4m
# the number of slabs to use for the RRset cache.
# the number of slabs must be a power of 2.
# more slabs reduce lock contention, but fragment memory usage.
# rrset-cache-slabs: 4
# the time to live (TTL) value lower bound, in seconds. Default 0.
# If more than an hour could easily give trouble due to stale data.
# cache-min-ttl: 0
# the time to live (TTL) value cap for RRsets and messages in the
# cache. Items are not cached for longer. In seconds.
# cache-max-ttl: 86400
# the time to live (TTL) value for cached roundtrip times, lameness and
# EDNS version information for hosts. In seconds.
# infra-host-ttl: 900
# the number of slabs to use for the Infrastructure cache.
# the number of slabs must be a power of 2.
# more slabs reduce lock contention, but fragment memory usage.
# infra-cache-slabs: 4
# the maximum number of hosts that are cached (roundtrip, EDNS, lame).
# infra-cache-numhosts: 10000
# Enable IPv4, "yes" or "no".
# do-ip4: yes
# Enable IPv6, "yes" or "no".
# do-ip6: yes
# Enable UDP, "yes" or "no".
# do-udp: yes
# Enable TCP, "yes" or "no".
# do-tcp: yes
# upstream connections use TCP only (and no UDP), "yes" or "no"
# useful for tunneling scenarios, default no.
# tcp-upstream: no
# Detach from the terminal, run in background, "yes" or "no".
# do-daemonize: yes
# control which clients are allowed to make (recursive) queries
# to this server. Specify classless netblocks with /size and action.
# By default everything is refused, except for localhost.
# Choose deny (drop message), refuse (polite error reply),
# allow (recursive ok), allow_snoop (recursive and nonrecursive ok)
# deny_non_local (drop queries unless can be answered from local-data)
# refuse_non_local (like deny_non_local but polite error reply).
# access-control: 0.0.0.0/0 refuse
# access-control: 127.0.0.0/8 allow
# access-control: ::0/0 refuse
# access-control: ::1 allow
# access-control: ::ffff:127.0.0.1 allow
# if given, a chroot(2) is done to the given directory.
# i.e. you can chroot to the working directory, for example,
# for extra security, but make sure all files are in that directory.
#
# If chroot is enabled, you should pass the configfile (from the
# commandline) as a full path from the original root. After the
# chroot has been performed the now defunct portion of the config
# file path is removed to be able to reread the config after a reload.
#
# All other file paths (working dir, logfile, roothints, and
# key files) can be specified in several ways:
# o as an absolute path relative to the new root.
# o as a relative path to the working directory.
# o as an absolute path relative to the original root.
# In the last case the path is adjusted to remove the unused portion.
#
# The pid file can be absolute and outside of the chroot, it is
# written just prior to performing the chroot and dropping permissions.
#
# Additionally, unbound may need to access /dev/random (for entropy).
# How to do this is specific to your OS.
#
# If you give "" no chroot is performed. The path must not end in a /.
# chroot: "@UNBOUND_CHROOT_DIR@"
# if given, user privileges are dropped (after binding port),
# and the given username is assumed. Default is user "unbound".
# If you give "" no privileges are dropped.
# username: "@UNBOUND_USERNAME@"
# the working directory. The relative files in this config are
# relative to this directory. If you give "" the working directory
# is not changed.
# directory: "@UNBOUND_RUN_DIR@"
# the log file, "" means log to stderr.
# Use of this option sets use-syslog to "no".
# logfile: ""
# Log to syslog(3) if yes. The log facility LOG_DAEMON is used to
# log to, with identity "unbound". If yes, it overrides the logfile.
# use-syslog: yes
# print UTC timestamp in ascii to logfile, default is epoch in seconds.
# log-time-ascii: no
# print one line with time, IP, name, type, class for every query.
# log-queries: no
# the pid file. Can be an absolute path outside of chroot/work dir.
# pidfile: "@UNBOUND_PIDFILE@"
# file to read root hints from.
# get one from ftp://FTP.INTERNIC.NET/domain/named.cache
# root-hints: ""
# enable to not answer id.server and hostname.bind queries.
# hide-identity: no
# enable to not answer version.server and version.bind queries.
# hide-version: no
# the identity to report. Leave "" or default to return hostname.
# identity: ""
# the version to report. Leave "" or default to return package version.
# version: ""
# the target fetch policy.
# series of integers describing the policy per dependency depth.
# The number of values in the list determines the maximum dependency
# depth the recursor will pursue before giving up. Each integer means:
# -1 : fetch all targets opportunistically,
# 0: fetch on demand,
# positive value: fetch that many targets opportunistically.
# Enclose the list of numbers between quotes ("").
# target-fetch-policy: "3 2 1 0 0"
# Harden against very small EDNS buffer sizes.
# harden-short-bufsize: no
# Harden against unseemly large queries.
# harden-large-queries: no
# Harden against out of zone rrsets, to avoid spoofing attempts.
# harden-glue: yes
# Harden against receiving dnssec-stripped data. If you turn it
# off, failing to validate dnskey data for a trustanchor will
# trigger insecure mode for that zone (like without a trustanchor).
# Default on, which insists on dnssec data for trust-anchored zones.
# harden-dnssec-stripped: yes
# Harden against queries that fall under dnssec-signed nxdomain names.
# harden-below-nxdomain: no
# Harden the referral path by performing additional queries for
# infrastructure data. Validates the replies (if possible).
# Default off, because the lookups burden the server. Experimental
# implementation of draft-wijngaards-dnsext-resolver-side-mitigation.
# harden-referral-path: no
# Use 0x20-encoded random bits in the query to foil spoof attempts.
# This feature is an experimental implementation of draft dns-0x20.
# use-caps-for-id: no
# Enforce privacy of these addresses. Strips them away from answers.
# It may cause DNSSEC validation to additionally mark it as bogus.
# Protects against 'DNS Rebinding' (uses browser as network proxy).
# Only 'private-domain' and 'local-data' names are allowed to have
# these private addresses. No default.
# private-address: 10.0.0.0/8
# private-address: 172.16.0.0/12
# private-address: 192.168.0.0/16
# private-address: 169.254.0.0/16
# private-address: fd00::/8
# private-address: fe80::/10
# Allow the domain (and its subdomains) to contain private addresses.
# local-data statements are allowed to contain private addresses too.
# private-domain: "example.com"
# If nonzero, unwanted replies are not only reported in statistics,
# but also a running total is kept per thread. If it reaches the
# threshold, a warning is printed and a defensive action is taken,
# the cache is cleared to flush potential poison out of it.
# A suggested value is 10000000, the default is 0 (turned off).
# unwanted-reply-threshold: 0
# Do not query the following addresses. No DNS queries are sent there.
# List one address per entry. List classless netblocks with /size,
# do-not-query-address: 127.0.0.1/8
# do-not-query-address: ::1
# if yes, the above default do-not-query-address entries are present.
# if no, localhost can be queried (for testing and debugging).
# do-not-query-localhost: yes
# if yes, perform prefetching of almost expired message cache entries.
# prefetch: no
# if yes, perform key lookups adjacent to normal lookups.
# prefetch-key: no
# if yes, Unbound rotates RRSet order in response.
# rrset-roundrobin: no
# if yes, Unbound doesn't insert authority/additional sections
# into response messages when those sections are not required.
# minimal-responses: no
# module configuration of the server. A string with identifiers
# separated by spaces. Syntax: "[dns64] [validator] iterator"
# module-config: "validator iterator"
# File with trusted keys, kept uptodate using RFC5011 probes,
# initial file like trust-anchor-file, then it stores metadata.
# Use several entries, one per domain name, to track multiple zones.
#
# If you want to perform DNSSEC validation, run unbound-anchor before
# you start unbound (i.e. in the system boot scripts). And enable:
# Please note usage of unbound-anchor root anchor is at your own risk
# and under the terms of our LICENSE (see that file in the source).
# auto-trust-anchor-file: "@UNBOUND_ROOTKEY_FILE@"
# File with DLV trusted keys. Same format as trust-anchor-file.
# There can be only one DLV configured, it is trusted from root down.
# Download http://ftp.isc.org/www/dlv/dlv.isc.org.key
# dlv-anchor-file: "dlv.isc.org.key"
# File with trusted keys for validation. Specify more than one file
# with several entries, one file per entry.
# Zone file format, with DS and DNSKEY entries.
# Note this gets out of date, use auto-trust-anchor-file please.
# trust-anchor-file: ""
# Trusted key for validation. DS or DNSKEY. specify the RR on a
# single line, surrounded by "". TTL is ignored. class is IN default.
# Note this gets out of date, use auto-trust-anchor-file please.
# (These examples are from August 2007 and may not be valid anymore).
# trust-anchor: "nlnetlabs.nl. DNSKEY 257 3 5 AQPzzTWMz8qSWIQlfRnPckx2BiVmkVN6LPupO3mbz7FhLSnm26n6iG9N Lby97Ji453aWZY3M5/xJBSOS2vWtco2t8C0+xeO1bc/d6ZTy32DHchpW 6rDH1vp86Ll+ha0tmwyy9QP7y2bVw5zSbFCrefk8qCUBgfHm9bHzMG1U BYtEIQ=="
# trust-anchor: "jelte.nlnetlabs.nl. DS 42860 5 1 14D739EB566D2B1A5E216A0BA4D17FA9B038BE4A"
# File with trusted keys for validation. Specify more than one file
# with several entries, one file per entry. Like trust-anchor-file
# but has a different file format. Format is BIND-9 style format,
# the trusted-keys { name flag proto algo "key"; }; clauses are read.
# you need external update procedures to track changes in keys.
# trusted-keys-file: ""
# Ignore chain of trust. Domain is treated as insecure.
# domain-insecure: "example.com"
# Override the date for validation with a specific fixed date.
# Do not set this unless you are debugging signature inception
# and expiration. "" or "0" turns the feature off. -1 ignores date.
# val-override-date: ""
# The time to live for bogus data, rrsets and messages. This avoids
# some of the revalidation, until the time interval expires. in secs.
# val-bogus-ttl: 60
# The signature inception and expiration dates are allowed to be off
# by 10% of the signature lifetime (expir-incep) from our local clock.
# This leeway is capped with a minimum and a maximum. In seconds.
# val-sig-skew-min: 3600
# val-sig-skew-max: 86400
# Should additional section of secure message also be kept clean of
# unsecure data. Useful to shield the users of this validator from
# potential bogus data in the additional section. All unsigned data
# in the additional section is removed from secure messages.
# val-clean-additional: yes
# Turn permissive mode on to permit bogus messages. Thus, messages
# for which security checks failed will be returned to clients,
# instead of SERVFAIL. It still performs the security checks, which
# result in interesting log files and possibly the AD bit in
# replies if the message is found secure. The default is off.
# val-permissive-mode: no
# Ignore the CD flag in incoming queries and refuse them bogus data.
# Enable it if the only clients of unbound are legacy servers (w2008)
# that set CD but cannot validate themselves.
# ignore-cd-flag: no
# Have the validator log failed validations for your diagnosis.
# 0: off. 1: A line per failed user query. 2: With reason and bad IP.
# val-log-level: 0
# It is possible to configure NSEC3 maximum iteration counts per
# keysize. Keep this table very short, as linear search is done.
# A message with an NSEC3 with larger count is marked insecure.
# List in ascending order the keysize and count values.
# val-nsec3-keysize-iterations: "1024 150 2048 500 4096 2500"
# instruct the auto-trust-anchor-file probing to add anchors after ttl.
# add-holddown: 2592000 # 30 days
# instruct the auto-trust-anchor-file probing to del anchors after ttl.
# del-holddown: 2592000 # 30 days
# auto-trust-anchor-file probing removes missing anchors after ttl.
# If the value 0 is given, missing anchors are not removed.
# keep-missing: 31622400 # 366 days
# the amount of memory to use for the key cache.
# plain value in bytes or you can append k, m or G. default is "4Mb".
# key-cache-size: 4m
# the number of slabs to use for the key cache.
# the number of slabs must be a power of 2.
# more slabs reduce lock contention, but fragment memory usage.
# key-cache-slabs: 4
# the amount of memory to use for the negative cache (used for DLV).
# plain value in bytes or you can append k, m or G. default is "1Mb".
# neg-cache-size: 1m
# By default, for a number of zones a small default 'nothing here'
# reply is built-in. Query traffic is thus blocked. If you
# wish to serve such zone you can unblock them by uncommenting one
# of the nodefault statements below.
# You may also have to use domain-insecure: zone to make DNSSEC work,
# unless you have your own trust anchors for this zone.
# local-zone: "localhost." nodefault
# local-zone: "127.in-addr.arpa." nodefault
# local-zone: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa." nodefault
# local-zone: "10.in-addr.arpa." nodefault
# local-zone: "16.172.in-addr.arpa." nodefault
# local-zone: "17.172.in-addr.arpa." nodefault
# local-zone: "18.172.in-addr.arpa." nodefault
# local-zone: "19.172.in-addr.arpa." nodefault
# local-zone: "20.172.in-addr.arpa." nodefault
# local-zone: "21.172.in-addr.arpa." nodefault
# local-zone: "22.172.in-addr.arpa." nodefault
# local-zone: "23.172.in-addr.arpa." nodefault
# local-zone: "24.172.in-addr.arpa." nodefault
# local-zone: "25.172.in-addr.arpa." nodefault
# local-zone: "26.172.in-addr.arpa." nodefault
# local-zone: "27.172.in-addr.arpa." nodefault
# local-zone: "28.172.in-addr.arpa." nodefault
# local-zone: "29.172.in-addr.arpa." nodefault
# local-zone: "30.172.in-addr.arpa." nodefault
# local-zone: "31.172.in-addr.arpa." nodefault
# local-zone: "168.192.in-addr.arpa." nodefault
# local-zone: "0.in-addr.arpa." nodefault
# local-zone: "254.169.in-addr.arpa." nodefault
# local-zone: "2.0.192.in-addr.arpa." nodefault
# local-zone: "100.51.198.in-addr.arpa." nodefault
# local-zone: "113.0.203.in-addr.arpa." nodefault
# local-zone: "255.255.255.255.in-addr.arpa." nodefault
# local-zone: "0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa." nodefault
# local-zone: "d.f.ip6.arpa." nodefault
# local-zone: "8.e.f.ip6.arpa." nodefault
# local-zone: "9.e.f.ip6.arpa." nodefault
# local-zone: "a.e.f.ip6.arpa." nodefault
# local-zone: "b.e.f.ip6.arpa." nodefault
# local-zone: "8.b.d.0.1.0.0.2.ip6.arpa." nodefault
# And for 64.100.in-addr.arpa. to 127.100.in-addr.arpa.
# if unbound is running service for the local host then it is useful
# to perform lan-wide lookups to the upstream, and unblock the
# long list of local-zones above. If this unbound is a dns server
# for a network of computers, disabled is better and stops information
# leakage of local lan information.
# unblock-lan-zones: no
# a number of locally served zones can be configured.
# local-zone: <zone> <type>
# local-data: "<resource record string>"
# o deny serves local data (if any), else, drops queries.
# o refuse serves local data (if any), else, replies with error.
# o static serves local data, else, nxdomain or nodata answer.
# o transparent gives local data, but resolves normally for other names
# o redirect serves the zone data for any subdomain in the zone.
# o nodefault can be used to normally resolve AS112 zones.
# o typetransparent resolves normally for other types and other names
#
# defaults are localhost address, reverse for 127.0.0.1 and ::1
# and nxdomain for AS112 zones. If you configure one of these zones
# the default content is omitted, or you can omit it with 'nodefault'.
#
# If you configure local-data without specifying local-zone, by
# default a transparent local-zone is created for the data.
#
# You can add locally served data with
# local-zone: "local." static
# local-data: "mycomputer.local. IN A 192.0.2.51"
# local-data: 'mytext.local TXT "content of text record"'
#
# You can override certain queries with
# local-data: "adserver.example.com A 127.0.0.1"
#
# You can redirect a domain to a fixed address with
# (this makes example.com, www.example.com, etc, all go to 192.0.2.3)
# local-zone: "example.com" redirect
# local-data: "example.com A 192.0.2.3"
#
# Shorthand to make PTR records, "IPv4 name" or "IPv6 name".
# You can also add PTR records using local-data directly, but then
# you need to do the reverse notation yourself.
# local-data-ptr: "192.0.2.3 www.example.com"
# service clients over SSL (on the TCP sockets), with plain DNS inside
# the SSL stream. Give the certificate to use and private key.
# default is "" (disabled). requires restart to take effect.
# ssl-service-key: "path/to/privatekeyfile.key"
# ssl-service-pem: "path/to/publiccertfile.pem"
# ssl-port: 443
# request upstream over SSL (with plain DNS inside the SSL stream).
# Default is no. Can be turned on and off with unbound-control.
# ssl-upstream: no
# DNS64 prefix. Must be specified when DNS64 is use.
# Enable dns64 in module-config. Used to synthesize IPv6 from IPv4.
# dns64-prefix: 64:ff9b::0/96
# Python config section. To enable:
# o use --with-pythonmodule to configure before compiling.
# o list python in the module-config string (above) to enable.
# o and give a python-script to run.
python:
# Script file to load
# python-script: "@UNBOUND_SHARE_DIR@/ubmodule-tst.py"
# Remote control config section.
remote-control:
# Enable remote control with unbound-control(8) here.
# set up the keys and certificates with unbound-control-setup.
# control-enable: no
# what interfaces are listened to for remote control.
# give 0.0.0.0 and ::0 to listen to all interfaces.
# control-interface: 127.0.0.1
# control-interface: ::1
# port number for remote control operations.
# control-port: 8953
# unbound server key file.
# server-key-file: "@UNBOUND_RUN_DIR@/unbound_server.key"
# unbound server certificate file.
# server-cert-file: "@UNBOUND_RUN_DIR@/unbound_server.pem"
# unbound-control key file.
# control-key-file: "@UNBOUND_RUN_DIR@/unbound_control.key"
# unbound-control certificate file.
# control-cert-file: "@UNBOUND_RUN_DIR@/unbound_control.pem"
# Stub zones.
# Create entries like below, to make all queries for 'example.com' and
# 'example.org' go to the given list of nameservers. list zero or more
# nameservers by hostname or by ipaddress. If you set stub-prime to yes,
# the list is treated as priming hints (default is no).
# With stub-first yes, it attempts without the stub if it fails.
# stub-zone:
# name: "example.com"
# stub-addr: 192.0.2.68
# stub-prime: no
# stub-first: no
# stub-zone:
# name: "example.org"
# stub-host: ns.example.com.
# Forward zones
# Create entries like below, to make all queries for 'example.com' and
# 'example.org' go to the given list of servers. These servers have to handle
# recursion to other nameservers. List zero or more nameservers by hostname
# or by ipaddress. Use an entry with name "." to forward all queries.
# If you enable forward-first, it attempts without the forward if it fails.
# forward-zone:
# name: "example.com"
# forward-addr: 192.0.2.68
# forward-addr: 192.0.2.73@5355 # forward to port 5355.
# forward-first: no
# forward-zone:
# name: "example.org"
# forward-host: fwd.example.com

BIN
external/unbound/doc/ietf67-design-02.odp vendored Normal file
View File

Binary file not shown.

BIN
external/unbound/doc/ietf67-design-02.pdf vendored Normal file
View File

Binary file not shown.

385
external/unbound/doc/libunbound.3.in vendored Normal file
View File

@@ -0,0 +1,385 @@
.TH "libunbound" "3" "@date@" "NLnet Labs" "unbound @version@"
.\"
.\" libunbound.3 -- unbound library functions manual
.\"
.\" Copyright (c) 2007, NLnet Labs. All rights reserved.
.\"
.\" See LICENSE for the license.
.\"
.\"
.SH "NAME"
.B libunbound,
.B unbound.h,
.B ub_ctx,
.B ub_result,
.B ub_callback_t,
.B ub_ctx_create,
.B ub_ctx_delete,
.B ub_ctx_set_option,
.B ub_ctx_get_option,
.B ub_ctx_config,
.B ub_ctx_set_fwd,
.B ub_ctx_resolvconf,
.B ub_ctx_hosts,
.B ub_ctx_add_ta,
.B ub_ctx_add_ta_file,
.B ub_ctx_trustedkeys,
.B ub_ctx_debugout,
.B ub_ctx_debuglevel,
.B ub_ctx_async,
.B ub_poll,
.B ub_wait,
.B ub_fd,
.B ub_process,
.B ub_resolve,
.B ub_resolve_async,
.B ub_cancel,
.B ub_resolve_free,
.B ub_strerror,
.B ub_ctx_print_local_zones,
.B ub_ctx_zone_add,
.B ub_ctx_zone_remove,
.B ub_ctx_data_add,
.B ub_ctx_data_remove
\- Unbound DNS validating resolver @version@ functions.
.SH "SYNOPSIS"
.B #include <unbound.h>
.LP
\fIstruct ub_ctx *\fR
\fBub_ctx_create\fR(\fIvoid\fR);
.LP
\fIvoid\fR
\fBub_ctx_delete\fR(\fIstruct ub_ctx*\fR ctx);
.LP
\fIint\fR
\fBub_ctx_set_option\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR opt, \fIchar*\fR val);
.LP
\fIint\fR
\fBub_ctx_get_option\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR opt, \fIchar**\fR val);
.LP
\fIint\fR
\fBub_ctx_config\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
.LP
\fIint\fR
\fBub_ctx_set_fwd\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR addr);
.LP
\fIint\fR
\fBub_ctx_resolvconf\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
.LP
\fIint\fR
\fBub_ctx_hosts\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
.LP
\fIint\fR
\fBub_ctx_add_ta\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR ta);
.LP
\fIint\fR
\fBub_ctx_add_ta_file\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
.LP
\fIint\fR
\fBub_ctx_trustedkeys\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
.LP
\fIint\fR
\fBub_ctx_debugout\fR(\fIstruct ub_ctx*\fR ctx, \fIFILE*\fR out);
.LP
\fIint\fR
\fBub_ctx_debuglevel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR d);
.LP
\fIint\fR
\fBub_ctx_async\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR dothread);
.LP
\fIint\fR
\fBub_poll\fR(\fIstruct ub_ctx*\fR ctx);
.LP
\fIint\fR
\fBub_wait\fR(\fIstruct ub_ctx*\fR ctx);
.LP
\fIint\fR
\fBub_fd\fR(\fIstruct ub_ctx*\fR ctx);
.LP
\fIint\fR
\fBub_process\fR(\fIstruct ub_ctx*\fR ctx);
.LP
\fIint\fR
\fBub_resolve\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name,
.br
\fIint\fR rrtype, \fIint\fR rrclass, \fIstruct ub_result**\fR result);
.LP
\fIint\fR
\fBub_resolve_async\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name,
.br
\fIint\fR rrtype, \fIint\fR rrclass, \fIvoid*\fR mydata,
.br
\fIub_callback_t\fR callback, \fIint*\fR async_id);
.LP
\fIint\fR
\fBub_cancel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR async_id);
.LP
\fIvoid\fR
\fBub_resolve_free\fR(\fIstruct ub_result*\fR result);
.LP
\fIconst char *\fR
\fBub_strerror\fR(\fIint\fR err);
.LP
\fIint\fR
\fBub_ctx_print_local_zones\fR(\fIstruct ub_ctx*\fR ctx);
.LP
\fIint\fR
\fBub_ctx_zone_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name, \fIchar*\fR zone_type);
.LP
\fIint\fR
\fBub_ctx_zone_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name);
.LP
\fIint\fR
\fBub_ctx_data_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data);
.LP
\fIint\fR
\fBub_ctx_data_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data);
.SH "DESCRIPTION"
.B Unbound
is an implementation of a DNS resolver, that does caching and
DNSSEC validation. This is the library API, for using the \-lunbound library.
The server daemon is described in \fIunbound\fR(8).
The library can be used to convert hostnames to ip addresses, and back,
and obtain other information from the DNS. The library performs public\-key
validation of results with DNSSEC.
.P
The library uses a variable of type \fIstruct ub_ctx\fR to keep context
between calls. The user must maintain it, creating it with
.B ub_ctx_create
and deleting it with
.B ub_ctx_delete\fR.
It can be created and deleted at any time. Creating it anew removes any
previous configuration (such as trusted keys) and clears any cached results.
.P
The functions are thread\-safe, and a context an be used in a threaded (as
well as in a non\-threaded) environment. Also resolution (and validation)
can be performed blocking and non\-blocking (also called asynchronous).
The async method returns from the call immediately, so that processing
can go on, while the results become available later.
.P
The functions are discussed in turn below.
.SH "FUNCTIONS"
.TP
.B ub_ctx_create
Create a new context, initialised with defaults.
The information from /etc/resolv.conf and /etc/hosts is not utilised
by default. Use
.B ub_ctx_resolvconf
and
.B ub_ctx_hosts
to read them.
Before you call this, use the openssl functions CRYPTO_set_id_callback and
CRYPTO_set_locking_callback to set up asyncronous operation if you use
lib openssl (the application calls these functions once for initialisation).
.TP
.B ub_ctx_delete
Delete validation context and free associated resources.
Outstanding async queries are killed and callbacks are not called for them.
.TP
.B ub_ctx_set_option
A power\-user interface that lets you specify one of the options from the
config file format, see \fIunbound.conf\fR(5). Not all options are
relevant. For some specific options, such as adding trust anchors, special
routines exist. Pass the option name with the trailing ':'.
.TP
.B ub_ctx_get_option
A power\-user interface that gets an option value. Some options cannot be
gotten, and others return a newline separated list. Pass the option name
without trailing ':'. The returned value must be free(2)d by the caller.
.TP
.B ub_ctx_config
A power\-user interface that lets you specify an unbound config file, see
\fIunbound.conf\fR(5), which is read for configuration. Not all options are
relevant. For some specific options, such as adding trust anchors, special
routines exist.
.TP
.B ub_ctx_set_fwd
Set machine to forward DNS queries to, the caching resolver to use.
IP4 or IP6 address. Forwards all DNS requests to that machine, which
is expected to run a recursive resolver. If the proxy is not
DNSSEC capable, validation may fail. Can be called several times, in
that case the addresses are used as backup servers.
At this time it is only possible to set configuration before the
first resolve is done.
.TP
.B ub_ctx_resolvconf
By default the root servers are queried and full resolver mode is used, but
you can use this call to read the list of nameservers to use from the
filename given.
Usually "/etc/resolv.conf". Uses those nameservers as caching proxies.
If they do not support DNSSEC, validation may fail.
Only nameservers are picked up, the searchdomain, ndots and other
settings from \fIresolv.conf\fR(5) are ignored.
If fname NULL is passed, "/etc/resolv.conf" is used (if on Windows,
the system\-wide configured nameserver is picked instead).
At this time it is only possible to set configuration before the
first resolve is done.
.TP
.B ub_ctx_hosts
Read list of hosts from the filename given.
Usually "/etc/hosts". When queried for, these addresses are not marked
DNSSEC secure. If fname NULL is passed, "/etc/hosts" is used
(if on Windows, etc/hosts from WINDIR is picked instead).
At this time it is only possible to set configuration before the
first resolve is done.
.TP
.B
ub_ctx_add_ta
Add a trust anchor to the given context.
At this time it is only possible to add trusted keys before the
first resolve is done.
The format is a string, similar to the zone\-file format,
[domainname] [type] [rdata contents]. Both DS and DNSKEY records are accepted.
.TP
.B ub_ctx_add_ta_file
Add trust anchors to the given context.
Pass name of a file with DS and DNSKEY records in zone file format.
At this time it is only possible to add trusted keys before the
first resolve is done.
.TP
.B ub_ctx_trustedkeys
Add trust anchors to the given context.
Pass the name of a bind\-style config file with trusted\-keys{}.
At this time it is only possible to add trusted keys before the
first resolve is done.
.TP
.B ub_ctx_debugout
Set debug and error log output to the given stream. Pass NULL to disable
output. Default is stderr. File\-names or using syslog can be enabled
using config options, this routine is for using your own stream.
.TP
.B ub_ctx_debuglevel
Set debug verbosity for the context. Output is directed to stderr.
Higher debug level gives more output.
.TP
.B ub_ctx_async
Set a context behaviour for asynchronous action.
if set to true, enables threading and a call to
.B ub_resolve_async
creates a thread to handle work in the background.
If false, a process is forked to handle work in the background.
Changes to this setting after
.B ub_resolve_async
calls have been made have no effect (delete and re\-create the context
to change).
.TP
.B ub_poll
Poll a context to see if it has any new results.
Do not poll in a loop, instead extract the fd below to poll for readiness,
and then check, or wait using the wait routine.
Returns 0 if nothing to read, or nonzero if a result is available.
If nonzero, call
.B ub_process
to do callbacks.
.TP
.B ub_wait
Wait for a context to finish with results. Calls
.B ub_process
after the wait for you. After the wait, there are no more outstanding
asynchronous queries.
.TP
.B ub_fd
Get file descriptor. Wait for it to become readable, at this point
answers are returned from the asynchronous validating resolver.
Then call the \fBub_process\fR to continue processing.
.TP
.B ub_process
Call this routine to continue processing results from the validating
resolver (when the fd becomes readable).
Will perform necessary callbacks.
.TP
.B ub_resolve
Perform resolution and validation of the target name.
The name is a domain name in a zero terminated text string.
The rrtype and rrclass are DNS type and class codes.
The result structure is newly allocated with the resulting data.
.TP
.B ub_resolve_async
Perform asynchronous resolution and validation of the target name.
Arguments mean the same as for \fBub_resolve\fR except no
data is returned immediately, instead a callback is called later.
The callback receives a copy of the mydata pointer, that you can use to pass
information to the callback. The callback type is a function pointer to
a function declared as
.IP
void my_callback_function(void* my_arg, int err,
.br
struct ub_result* result);
.IP
The async_id is returned so you can (at your option) decide to track it
and cancel the request if needed. If you pass a NULL pointer the async_id
is not returned.
.TP
.B ub_cancel
Cancel an async query in progress. This may return an error if the query
does not exist, or the query is already being delivered, in that case you
may still get a callback for the query.
.TP
.B ub_resolve_free
Free struct ub_result contents after use.
.TP
.B ub_strerror
Convert error value from one of the unbound library functions
to a human readable string.
.TP
.B ub_ctx_print_local_zones
Debug printout the local authority information to debug output.
.TP
.B ub_ctx_zone_add
Add new zone to local authority info, like local\-zone \fIunbound.conf\fR(5)
statement.
.TP
.B ub_ctx_zone_remove
Delete zone from local authority info.
.TP
.B ub_ctx_data_add
Add resource record data to local authority info, like local\-data
\fIunbound.conf\fR(5) statement.
.TP
.B ub_ctx_data_remove
Delete local authority data from the name given.
.SH "RESULT DATA STRUCTURE"
The result of the DNS resolution and validation is returned as
\fIstruct ub_result\fR. The result structure contains the following entries.
.P
.nf
struct ub_result {
char* qname; /* text string, original question */
int qtype; /* type code asked for */
int qclass; /* class code asked for */
char** data; /* array of rdata items, NULL terminated*/
int* len; /* array with lengths of rdata items */
char* canonname; /* canonical name of result */
int rcode; /* additional error code in case of no data */
void* answer_packet; /* full network format answer packet */
int answer_len; /* length of packet in octets */
int havedata; /* true if there is data */
int nxdomain; /* true if nodata because name does not exist */
int secure; /* true if result is secure */
int bogus; /* true if a security failure happened */
char* why_bogus; /* string with error if bogus */
int ttl; /* number of seconds the result is valid */
};
.fi
.P
If both secure and bogus are false, security was not enabled for the
domain of the query. Else, they are not both true, one of them is true.
.SH "RETURN VALUES"
Many routines return an error code. The value 0 (zero) denotes no error
happened. Other values can be passed to
.B ub_strerror
to obtain a readable error string.
.B ub_strerror
returns a zero terminated string.
.B ub_ctx_create
returns NULL on an error (a malloc failure).
.B ub_poll
returns true if some information may be available, false otherwise.
.B ub_fd
returns a file descriptor or \-1 on error.
.SH "SEE ALSO"
\fIunbound.conf\fR(5),
\fIunbound\fR(8).
.SH "AUTHORS"
.B Unbound
developers are mentioned in the CREDITS file in the distribution.

294
external/unbound/doc/requirements.txt vendored Normal file
View File

@@ -0,0 +1,294 @@
Requirements for Recursive Caching Resolver
(a.k.a. Treeshrew, Unbound-C)
By W.C.A. Wijngaards, NLnet Labs, October 2006.
Contents
1. Introduction
2. History
3. Goals
4. Non-Goals
1. Introduction
---------------
This is the requirements document for a DNS name server and aims to
document the goals and non-goals of the project. The DNS (the Domain
Name System) is a global, replicated database that uses a hierarchical
structure for queries.
Data in the DNS is stored in Resource Record sets (RR sets), and has a
time to live (TTL). During this time the data can be cached. It is
thus useful to cache data to speed up future lookups. A server that
looks up data in the DNS for clients and caches previous answers to
speed up processing is called a caching, recursive nameserver.
This project aims to develop such a nameserver in modular components, so
that also DNSSEC (secure DNS) validation and stub-resolvers (that do not
run as a server, but a linked into an application) are easily possible.
The main components are the Validator that validates the security
fingerprints on data sets, the Iterator that sends queries to the
hierarchical DNS servers that own the data and the Cache that stores
data from previous queries. The networking and query management code
then interface with the modules to perform the necessary processing.
In Section 2 the origins of the Unbound project are documented. Section
3 lists the goals, while Section 4 lists the explicit non-goals of the
project. Section 5 discusses choices made during development.
2. History
----------
The unbound resolver project started by Bill Manning, David Blacka, and
Matt Larson (from the University of California and from Verisign), that
created a Java based prototype resolver called Unbound. The basic
design decisions of clean modules was executed.
The Java prototype worked very well, with contributions from Geoff
Sisson and Roy Arends from Nominet. Around 2006 the idea came to create
a full-fledged C implementation ready for deployed use. NLnet Labs
volunteered to write this implementation.
3. Goals
--------
o A validating recursive DNS resolver.
o Code diversity in the DNS resolver monoculture.
o Drop-in replacement for BIND apart from config.
o DNSSEC support.
o Fully RFC compliant.
o High performance
* even with validation.
o Used as
* stub resolver.
* full caching name server.
* resolver library.
o Elegant design of validator, resolver, cache modules.
* provide the ability to pick and choose modules.
o Robust.
o In C, open source: The BSD license.
o Highly portable, targets include modern Unix systems, such as *BSD,
solaris, linux, and maybe also the windows platform.
o Smallest as possible component that does the job.
o Stub-zones can be configured (local data or AS112 zones).
4. Non-Goals
------------
o An authoritative name server.
o Too many Features.
5. Choices
----------
o rfc2181 decourages duplicates RRs in RRsets. unbound does not create
duplicates, but when presented with duplicates on the wire from the
authoritative servers, does not perform duplicate removal.
It does do some rrsig duplicate removal, in the msgparser, for dnssec qtype
rrsig and any, because of special rrsig processing in the msgparser.
o The harden-glue feature, when yes all out of zone glue is deleted, when
no out of zone glue is used for further resolving, is more complicated
than that, see below.
Main points:
* rfc2182 trust handling is used.
* data is let through only in very specific cases
* spoofability remains possible.
Not all glue is let through (despite the name of the option). Only glue
which is present in a delegation, of type A and AAAA, where the name is
present in the NS record in the authority section is let through.
The glue that is let through is stored in the cache (marked as 'from the
additional section'). And will then be used for sending queries to. It
will not be present in the reply to the client (if RD is off).
A direct query for that name will attempt to get a msg into the message
cache. Since A and AAAA queries are not synthesized by the unbound cache,
this query will be (eventually) sent to the authoritative server and its
answer will be put in the cache, marked as 'from the answer section' and
thus remove the 'from the additional section' data, and this record is
returned to the client.
The message has a TTL smaller or equal to the TTL of the answer RR.
If the cache memory is low; the answer RR may be dropped, and a glue
RR may be inserted, within the message TTL time, and thus return the
spoofed glue to a client. When the message expires, it is refetched and
the cached RR is updated with the correct content.
The server can be spoofed by getting it to visit a especially prepared
domain. This domain then inserts an address for another authoritative
server into the cache, when visiting that other domain, this address may
then be used to send queries to. And fake answers may be returned.
If the other domain is signed by DNSSEC, the fakes will be detected.
In summary, the harden glue feature presents a security risk if
disabled. Disabling the feature leads to possible better performance
as more glue is present for the recursive service to use. The feature
is implemented so as to minimise the security risk, while trying to
keep this performance gain.
o The method by which dnssec-lameness is detected is not secure. DNSSEC lame
is when a server has the zone in question, but lacks dnssec data, such as
signatures. The method to detect dnssec lameness looks at nonvalidated
data from the parent of a zone. This can be used, by spoofing the parent,
to create a false sense of dnssec-lameness in the child, or a false sense
or dnssec-non-lameness in the child. The first results in the server marked
lame, and not used for 900 seconds, and the second will result in a
validator failure (SERVFAIL again), when the query is validated later on.
Concluding, a spoof of the parent delegation can be used for many cases
of denial of service. I.e. a completely different NS set could be returned,
or the information withheld. All of these alterations can be caught by
the validator if the parent is signed, and result in 900 seconds bogus.
The dnssec-lameness detection is used to detect operator failures,
before the validator will properly verify the messages.
Also for zones for which no chain of trust exists, but a DS is given by the
parent, dnssec-lameness detection enables. This delivers dnssec to our
clients when possible (for client validators).
The following issue needs to be resolved:
a server that serves both a parent and child zone, where
parent is signed, but child is not. The server must not be marked
lame for the parent zone, because the child answer is not signed.
Instead of a false positive, we want false negatives; failure to
detect dnssec-lameness is less of a problem than marking honest
servers lame. dnssec-lameness is a config error and deserves the trouble.
So, only messages that identify the zone are used to mark the zone
lame. The zone is identified by SOA or NS RRsets in the answer/auth.
That includes almost all negative responses and also A, AAAA qtypes.
That would be most responses from servers.
For referrals, delegations that add a single label can be checked to be
from their zone, this covers most delegation-centric zones.
So possibly, for complicated setups, with multiple (parent-child) zones
on a server, dnssec-lameness detection does not work - no dnssec-lameness
is detected. Instead the zone that is dnssec-lame becomes bogus.
o authority features.
This is a recursive server, and authority features are out of scope.
However, some authority features are expected in a recursor. Things like
localhost, reverse lookup for 127.0.0.1, or blocking AS112 traffic.
Also redirection of domain names with fixed data is needed by service
providers. Limited support is added specifically to address this.
Adding full authority support, requires much more code, and more complex
maintenance.
The limited support allows adding some static data (for localhost and so),
and to respond with a fixed rcode (NXDOMAIN) for domains (such as AS112).
You can put authority data on a separate server, and set the server in
unbound.conf as stub for those zones, this allows clients to access data
from the server without making unbound authoritative for the zones.
o the access control denies queries before any other processing.
This denies queries that are not authoritative, or version.bind, or any.
And thus prevents cache-snooping (denied hosts cannot make non-recursive
queries and get answers from the cache).
o If a client makes a query without RD bit, in the case of a returned
message from cache which is:
answer section: empty
auth section: NS record present, no SOA record, no DS record,
maybe NSEC or NSEC3 records present.
additional: A records or other relevant records.
A SOA record would indicate that this was a NODATA answer.
A DS records would indicate a referral.
Absence of NS record would indicate a NODATA answer as well.
Then the receiver does not know whether this was a referral
with attempt at no-DS proof) or a nodata answer with attempt
at no-data proof. It could be determined by attempting to prove
either condition; and looking if only one is valid, but both
proofs could be valid, or neither could be valid, which creates
doubt. This case is validated by unbound as a 'referral' which
ascertains that RRSIGs are OK (and not omitted), but does not
check NSEC/NSEC3.
o Case preservation
Unbound preserves the casing received from authority servers as best
as possible. It compresses without case, so case can get lost there.
The casing from the query name is used in preference to the casing
of the authority server. This is the same as BIND. RFC4343 allows either
behaviour.
o Denial of service protection
If many queries are made, and they are made to names for which the
authority servers do not respond, then the requestlist for unbound
fills up fast. This results in denial of service for new queries.
To combat this the first 50% of the requestlist can run to completion.
The last 50% of the requestlist get (200 msec) at least and are replaced
by newer queries when older (LIFO).
When a new query comes in, and a place in the first 50% is available, this
is preferred. Otherwise, it can replace older queries out of the last 50%.
Thus, even long queries get a 50% chance to be resolved. And many 'short'
one or two round-trip resolves can be done in the last 50% of the list.
The timeout can be configured.
o EDNS fallback. Is done according to the EDNS RFC (and update draft-00).
Unbound assumes EDNS 0 support for the first query. Then it can detect
support (if the servers replies) or non-support (on a NOTIMPL or FORMERR).
Some middleboxes drop EDNS 0 queries, mainly when forwarding, not when
routing packets. To detect this, when timeouts keep happening, as the
timeout approached 5-10 seconds, and EDNS status has not been detected yet,
a single probe query is sent. This probe has a sub-second timeout, and
if the server responds (quickly) without EDNS, this is cached for 15 min.
This works very well when detecting an address that you use much - like
a forwarder address - which is where the middleboxes need to be detected.
Otherwise, it results in a 5 second wait time before EDNS timeout is
detected, which is slow but it works at least.
It minimizes the chances of a dropped query making a (DNSSEC) EDNS server
falsely EDNS-nonsupporting, and thus DNSSEC-bogus, works well with
middleboxes, and can detect the occasional authority that drops EDNS.
For some boxes it is necessary to probe for every failing query, a
reassurance that the DNS server does EDNS does not mean that path can
take large DNS answers.
o 0x20 backoff.
The draft describes to back off to the next server, and go through all
servers several times. Unbound goes on get the full list of nameserver
addresses, and then makes 3 * number of addresses queries.
They are sent to a random server, but no one address more than 4 times.
It succeeds if one has 0x20 intact, or else all are equal.
Otherwise, servfail is returned to the client.
o NXDOMAIN and SOA serial numbers.
Unbound keeps TTL values for message formats, and thus rcodes, such
as NXDOMAIN. Also it keeps the latest rrsets in the rrset cache.
So it will faithfully negative cache for the exact TTL as originally
specified for an NXDOMAIN message, but send a newer SOA record if
this has been found in the mean time. In point, this could lead to a
negative cached NXDOMAIN reply with a SOA RR where the serial number
indicates a zone version where this domain is not any longer NXDOMAIN.
These situations become consistent once the original TTL expires.
If the domain is DNSSEC signed, by the way, then NSEC records are
updated more carefully. If one of the NSEC records in an NXDOMAIN is
updated from another query, the NXDOMAIN is dropped from the cache,
and queried for again, so that its proof can be checked again.
o SOA records in negative cached answers for DS queries.
The current unbound code uses a negative cache for queries for type DS.
This speeds up building chains of trust, and uses NSEC and NSEC3
(optout) information to speed up lookups. When used internally,
the bare NSEC(3) information is sufficient, probably picked up from
a referral. When answering to clients, a SOA record is needed for
the correct message format, a SOA record is picked from the cache
(and may not actually match the serial number of the SOA for which the
NSEC and NSEC3 records were obtained) if available otherwise network
queries are performed to get the data.
o Parent and child with different nameserver information.
A misconfiguration that sometimes happens is where the parent and child
have different NS, glue information. The child is authoritative, and
unbound will not trust information from the parent nameservers as the
final answer. To help lookups, unbound will however use the parent-side
version of the glue as a last resort lookup. This resolves lookups for
those misconfigured domains where the servers reported by the parent
are the only ones working, and servers reported by the child do not.
o Failure of validation and probing.
Retries on a validation failure are now 5x to a different nameserver IP
(if possible), and then it gives up, for one name, type, class entry in
the message cache. If a DNSKEY or DS fails in the chain of trust in the
key cache additionally, after the probing, a bad key entry is created that
makes the entire zone bogus for 900 seconds. This is a fixed value at
this time and is conservative in sending probes. It makes the compound
effect of many resolvers less and easier to handle, but penalizes
individual resolvers by having less probes and a longer time before fixes
are picked up.

175
external/unbound/doc/unbound-anchor.8.in vendored Normal file
View File

@@ -0,0 +1,175 @@
.TH "unbound-anchor" "8" "@date@" "NLnet Labs" "unbound @version@"
.\"
.\" unbound-anchor.8 -- unbound anchor maintenance utility manual
.\"
.\" Copyright (c) 2008, NLnet Labs. All rights reserved.
.\"
.\" See LICENSE for the license.
.\"
.\"
.SH "NAME"
.B unbound\-anchor
\- Unbound anchor utility.
.SH "SYNOPSIS"
.B unbound\-anchor
.RB [ opts ]
.SH "DESCRIPTION"
.B Unbound\-anchor
performs setup or update of the root trust anchor for DNSSEC validation.
It can be run (as root) from the commandline, or run as part of startup
scripts. Before you start the \fIunbound\fR(8) DNS server.
.P
Suggested usage:
.P
.nf
# in the init scripts.
# provide or update the root anchor (if necessary)
unbound-anchor -a "@UNBOUND_ROOTKEY_FILE@"
# Please note usage of this root anchor is at your own risk
# and under the terms of our LICENSE (see source).
#
# start validating resolver
# the unbound.conf contains:
# auto-trust-anchor-file: "@UNBOUND_ROOTKEY_FILE@"
unbound -c unbound.conf
.fi
.P
This tool provides builtin default contents for the root anchor and root
update certificate files.
.P
It tests if the root anchor file works, and if not, and an update is possible,
attempts to update the root anchor using the root update certificate.
It performs a https fetch of root-anchors.xml and checks the results, if
all checks are successful, it updates the root anchor file. Otherwise
the root anchor file is unchanged. It performs RFC5011 tracking if the
DNSSEC information available via the DNS makes that possible.
.P
It does not perform an update if the certificate is expired, if the network
is down or other errors occur.
.P
The available options are:
.TP
.B \-a \fIfile
The root anchor key file, that is read in and written out.
Default is @UNBOUND_ROOTKEY_FILE@.
If the file does not exist, or is empty, a builtin root key is written to it.
.TP
.B \-c \fIfile
The root update certificate file, that is read in.
Default is @UNBOUND_ROOTCERT_FILE@.
If the file does not exist, or is empty, a builtin certificate is used.
.TP
.B \-l
List the builtin root key and builtin root update certificate on stdout.
.TP
.B \-u \fIname
The server name, it connects to https://name. Specify without https:// prefix.
The default is "data.iana.org". It connects to the port specified with \-P.
You can pass an IPv4 addres or IPv6 address (no brackets) if you want.
.TP
.B \-x \fIpath
The pathname to the root\-anchors.xml file on the server. (forms URL with \-u).
The default is /root\-anchors/root\-anchors.xml.
.TP
.B \-s \fIpath
The pathname to the root\-anchors.p7s file on the server. (forms URL with \-u).
The default is /root\-anchors/root\-anchors.p7s. This file has to be a PKCS7
signature over the xml file, using the pem file (\-c) as trust anchor.
.TP
.B \-n \fIname
The emailAddress for the Subject of the signer's certificate from the p7s
signature file. Only signatures from this name are allowed. default is
dnssec@iana.org. If you pass "" then the emailAddress is not checked.
.TP
.B \-4
Use IPv4 for domain resolution and contacting the server on https. Default is
to use IPv4 and IPv6 where appropriate.
.TP
.B \-6
Use IPv6 for domain resolution and contacting the server on https. Default is
to use IPv4 and IPv6 where appropriate.
.TP
.B \-f \fIresolv.conf
Use the given resolv.conf file. Not enabled by default, but you could try to
pass /etc/resolv.conf on some systems. It contains the IP addresses of the
recursive nameservers to use. However, since this tool could be used to
bootstrap that very recursive nameserver, it would not be useful (since
that server is not up yet, since we are bootstrapping it). It could be
useful in a situation where you know an upstream cache is deployed (and
running) and in captive portal situations.
.TP
.B \-r \fIroot.hints
Use the given root.hints file (same syntax as the BIND and Unbound root hints
file) to bootstrap domain resolution. By default a list of builtin root
hints is used. Unbound\-anchor goes to the network itself for these roots,
to resolve the server (\-u option) and to check the root DNSKEY records.
It does so, because the tool when used for bootstrapping the recursive
resolver, cannot use that recursive resolver itself because it is bootstrapping
that server.
.TP
.B \-v
More verbose. Once prints informational messages, multiple times may enable
large debug amounts (such as full certificates or byte\-dumps of downloaded
files). By default it prints almost nothing. It also prints nothing on
errors by default; in that case the original root anchor file is simply
left undisturbed, so that a recursive server can start right after it.
.TP
.B \-C \fIunbound.conf
Debug option to read unbound.conf into the resolver process used.
.TP
.B \-P \fIport
Set the port number to use for the https connection. The default is 443.
.TP
.B \-F
Debug option to force update of the root anchor through downloading the xml
file and verifying it with the certificate. By default it first tries to
update by contacting the DNS, which uses much less bandwidth, is much
faster (200 msec not 2 sec), and is nicer to the deployed infrastructure.
With this option, it still attempts to do so (and may verbosely tell you),
but then ignores the result and goes on to use the xml fallback method.
.TP
.B \-h
Show the version and commandline option help.
.SH "EXIT CODE"
This tool exits with value 1 if the root anchor was updated using the
certificate or if the builtin root-anchor was used. It exits with code
0 if no update was necessary, if the update was possible with RFC5011
tracking, or if an error occurred.
.P
You can check the exit value in this manner:
.nf
unbound-anchor -a "root.key" || logger "Please check root.key"
.fi
Or something more suitable for your operational environment.
.SH "TRUST"
The root keys and update certificate included in this tool
are provided for convenience and under the terms of our
license (see the LICENSE file in the source distribution or
http://unbound.nlnetlabs.nl/svn/trunk/LICENSE) and might be stale or
not suitable to your purpose.
.P
By running "unbound\-anchor \-l" the keys and certificate that are
configured in the code are printed for your convenience.
.P
The build\-in configuration can be overridden by providing a root\-cert
file and a rootkey file.
.SH "FILES"
.TP
.I @UNBOUND_ROOTKEY_FILE@
The root anchor file, updated with 5011 tracking, and read and written to.
The file is created if it does not exist.
.TP
.I @UNBOUND_ROOTCERT_FILE@
The trusted self\-signed certificate that is used to verify the downloaded
DNSSEC root trust anchor. You can update it by fetching it from
https://data.iana.org/root\-anchors/icannbundle.pem (and validate it).
If the file does not exist or is empty, a builtin version is used.
.TP
.I https://data.iana.org/root\-anchors/root\-anchors.xml
Source for the root key information.
.TP
.I https://data.iana.org/root\-anchors/root\-anchors.p7s
Signature on the root key information.
.SH "SEE ALSO"
\fIunbound.conf\fR(5),
\fIunbound\fR(8).

48
external/unbound/doc/unbound-checkconf.8.in vendored Normal file
View File

@@ -0,0 +1,48 @@
.TH "unbound-checkconf" "8" "@date@" "NLnet Labs" "unbound @version@"
.\"
.\" unbound-checkconf.8 -- unbound configuration checker manual
.\"
.\" Copyright (c) 2007, NLnet Labs. All rights reserved.
.\"
.\" See LICENSE for the license.
.\"
.\"
.SH "NAME"
unbound\-checkconf
\- Check unbound configuration file for errors.
.SH "SYNOPSIS"
.B unbound\-checkconf
.RB [ \-h ]
.RB [ \-o
.IR option ]
.RI [ cfgfile ]
.SH "DESCRIPTION"
.B Unbound\-checkconf
checks the configuration file for the
\fIunbound\fR(8)
DNS resolver for syntax and other errors.
The config file syntax is described in
\fIunbound.conf\fR(5).
.P
The available options are:
.TP
.B \-h
Show the version and commandline option help.
.TP
.B \-o\fI option
If given, after checking the config file the value of this option is
printed to stdout. For "" (disabled) options an empty line is printed.
.TP
.I cfgfile
The config file to read with settings for unbound. It is checked.
If omitted, the config file at the default location is checked.
.SH "EXIT CODE"
The unbound\-checkconf program exits with status code 1 on error,
0 for a correct config file.
.SH "FILES"
.TP
.I @ub_conf_file@
unbound configuration file.
.SH "SEE ALSO"
\fIunbound.conf\fR(5),
\fIunbound\fR(8).

490
external/unbound/doc/unbound-control.8.in vendored Normal file
View File

@@ -0,0 +1,490 @@
.TH "unbound-control" "8" "@date@" "NLnet Labs" "unbound @version@"
.\"
.\" 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 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 inited.
.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.
.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_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.
.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.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.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 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.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 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.total.sbrk
If 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.
.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).

116
external/unbound/doc/unbound-host.1.in vendored Normal file
View File

@@ -0,0 +1,116 @@
.TH "unbound\-host" "1" "@date@" "NLnet Labs" "unbound @version@"
.\"
.\" unbound-host.1 -- unbound DNS lookup utility
.\"
.\" Copyright (c) 2007, NLnet Labs. All rights reserved.
.\"
.\" See LICENSE for the license.
.\"
.\"
.SH "NAME"
.B unbound\-host
\- unbound DNS lookup utility
.SH "SYNOPSIS"
.B unbound\-host
.RB [ \-vdhr46D ]
.RB [ \-c
.IR class ]
.RB [ \-t
.IR type ]
.I hostname
.RB [ \-y
.IR key ]
.RB [ \-f
.IR keyfile ]
.RB [ \-F
.IR namedkeyfile ]
.RB [ \-C
.IR configfile ]
.SH "DESCRIPTION"
.B Unbound\-host
uses the unbound validating resolver to query for the hostname and display
results. With the \fB\-v\fR option it displays validation
status: secure, insecure, bogus (security failure).
.P
By default it reads no configuration file whatsoever. It attempts to reach
the internet root servers. With \fB\-C\fR an unbound config file and with
\fB\-r\fR resolv.conf can be read.
.P
The available options are:
.TP
.I hostname
This name is resolved (looked up in the DNS).
If a IPv4 or IPv6 address is given, a reverse lookup is performed.
.TP
.B \-h
Show the version and commandline option help.
.TP
.B \-v
Enable verbose output and it shows validation results, on every line.
Secure means that the NXDOMAIN (no such domain name), nodata (no such data)
or positive data response validated correctly with one of the keys.
Insecure means that that domain name has no security set up for it.
Bogus (security failure) means that the response failed one or more checks,
it is likely wrong, outdated, tampered with, or broken.
.TP
.B \-d
Enable debug output to stderr. One \-d shows what the resolver and validator
are doing and may tell you what is going on. More times, \-d \-d, gives a
lot of output, with every packet sent and received.
.TP
.B \-c \fIclass
Specify the class to lookup for, the default is IN the internet class.
.TP
.B \-t \fItype
Specify the type of data to lookup. The default looks for IPv4, IPv6 and
mail handler data, or domain name pointers for reverse queries.
.TP
.B \-y \fIkey
Specify a public key to use as trust anchor. This is the base for a chain
of trust that is built up from the trust anchor to the response, in order
to validate the response message. Can be given as a DS or DNSKEY record.
For example \-y "example.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD".
.TP
.B \-D
Enables DNSSEC validation. Reads the root anchor from the default configured
root anchor at the default location, \fI@UNBOUND_ROOTKEY_FILE@\fR.
.TP
.B \-f \fIkeyfile
Reads keys from a file. Every line has a DS or DNSKEY record, in the format
as for \-y. The zone file format, the same as dig and drill produce.
.TP
.B \-F \fInamedkeyfile
Reads keys from a BIND\-style named.conf file. Only the trusted\-key {}; entries
are read.
.TP
.B \-C \fIconfigfile
Uses the specified unbound.conf to prime
.IR libunbound (3).
.TP
.B \-r
Read /etc/resolv.conf, and use the forward DNS servers from there (those could
have been set by DHCP). More info in
.IR resolv.conf (5).
Breaks validation if those servers do not support DNSSEC.
.TP
.B \-4
Use solely the IPv4 network for sending packets.
.TP
.B \-6
Use solely the IPv6 network for sending packets.
.SH "EXAMPLES"
Some examples of use. The keys shown below are fakes, thus a security failure
is encountered.
.P
$ unbound\-host www.example.com
.P
$ unbound\-host \-v \-y "example.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD" www.example.com
.P
$ unbound\-host \-v \-y "example.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD" 192.0.2.153
.SH "EXIT CODE"
The unbound\-host program exits with status code 1 on error,
0 on no error. The data may not be available on exit code 0, exit code 1
means the lookup encountered a fatal error.
.SH "SEE ALSO"
\fIunbound.conf\fR(5),
\fIunbound\fR(8).

79
external/unbound/doc/unbound.8.in vendored Normal file
View File

@@ -0,0 +1,79 @@
.TH "unbound" "8" "@date@" "NLnet Labs" "unbound @version@"
.\"
.\" unbound.8 -- unbound manual
.\"
.\" Copyright (c) 2007, NLnet Labs. All rights reserved.
.\"
.\" See LICENSE for the license.
.\"
.\"
.SH "NAME"
.B unbound
\- Unbound DNS validating resolver @version@.
.SH "SYNOPSIS"
.B unbound
.RB [ \-h ]
.RB [ \-d ]
.RB [ \-v ]
.RB [ \-c
.IR cfgfile ]
.SH "DESCRIPTION"
.B Unbound
is a caching DNS resolver.
.P
It uses a built in list of authoritative nameservers for the root zone (.),
the so called root hints.
On receiving a DNS query it will ask the root nameservers for
an answer and will in almost all cases receive a delegation to a top level
domain (TLD) authoritative nameserver.
It will then ask that nameserver for an answer.
It will recursively continue until an answer is found or no answer is
available (NXDOMAIN).
For performance and efficiency reasons that answer is cached for a
certain time (the answer's time\-to\-live or TTL).
A second query for the same name will then be answered from the cache.
Unbound can also do DNSSEC validation.
.P
To use a locally running
.B Unbound
for resolving put
.sp
.RS 6n
nameserver 127.0.0.1
.RE
.sp
into
.IR resolv.conf (5).
.P
If authoritative DNS is needed as well using
.IR nsd (8),
careful setup is required because authoritative nameservers and
resolvers are using the same port number (53).
.P
The available options are:
.TP
.B \-h
Show the version and commandline option help.
.TP
.B \-c\fI cfgfile
Set the config file with settings for unbound to read instead of reading the
file at the default location, @ub_conf_file@. The syntax is
described in \fIunbound.conf\fR(5).
.TP
.B \-d
Debug flag: do not fork into the background, but stay attached to
the console. This flag will also delay writing to the log file until
the thread\-spawn time, so that most config and setup errors appear on
stderr. If given twice or more, logging does not switch to the log file
or to syslog, but the log messages are printed to stderr all the time.
.TP
.B \-v
Increase verbosity. If given multiple times, more information is logged.
This is in addition to the verbosity (if any) from the config file.
.SH "SEE ALSO"
\fIunbound.conf\fR(5),
\fIunbound\-checkconf\fR(8),
\fInsd\fR(8).
.SH "AUTHORS"
.B Unbound
developers are mentioned in the CREDITS file in the distribution.

1141
external/unbound/doc/unbound.conf.5.in vendored Normal file
View File

File diff suppressed because it is too large Load Diff

1648
external/unbound/doc/unbound.doxygen vendored Normal file
View File

File diff suppressed because it is too large Load Diff