upstream/unbound
1
0
Fork 0
mirror of https://github.com/NLnetLabs/unbound.git synced 2026-02-02 19:59:28 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

RST man pages (#1285)

Browse source 
Introduce restructuredText man pages to sync the online and source code man page documentation.
The templated man pages (*.in) are still part of the repo but generated with docutils from their .rst counterpart.
Documentation on how to generate those (mainly for core developers) are in README.man.
This commit is contained in:
Yorgos Thessalonikefs 2025-05-20 12:20:20 +02:00 committed by GitHub
parent 32644937b0
commit 6662f71732
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
15 changed files with 14625 additions and 3852 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
doc/README.man Normal file
View file

@ -0,0 +1,16 @@
After Unbound 1.23.0, the source of the man pages is in reStructuredText format.
This helps with the online documentation at https://unbound.docs.nlnetlabs.nl
and makes it easier to maintain and contribute to the documentation.
The templated man pages (*.in) are still part of the code repository as to not
alter current procedures that could be in place by users/packagers.
The templated man pages (*.in) are generated by Sphinx (used for the online
documentation).
The online documentation has its own repository at
https://github.com/NLnetLabs/unbound-manual.
In the README.md there (branch test-auto for now), there are further simple
instructions on how to generate the templated man pages there and update them
in this repository.

673
doc/libunbound.3.in
View file

@ -1,335 +1,306 @@
.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_type,
.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_set_stub,
.B ub_ctx_set_tls,
.B ub_ctx_resolvconf,
.B ub_ctx_hosts,
.B ub_ctx_add_ta,
.B ub_ctx_add_ta_autr,
.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_set_stub\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone,
\fIchar*\fR addr,
.br
\fIint\fR isprime);
.LP
\fIint\fR
\fBub_ctx_set_tls\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR tls);
.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_autr\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
.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_type\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 works independent from a running unbound server, and
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 can 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
.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "LIBUNBOUND" "3" "@date@" "@version@" "Unbound"
.SH NAME
libunbound \- Unbound DNS validating resolver @version@ functions.
.SH SYNOPSIS
.sp
\fB#include <unbound.h>\fP
.sp
struct ub_ctx * \fBub_ctx_create\fP(void);
.sp
void \fBub_ctx_delete\fP(struct ub_ctx* ctx);
.sp
int \fBub_ctx_set_option\fP(struct ub_ctx* ctx, char* opt, char* val);
.sp
int \fBub_ctx_get_option\fP(struct ub_ctx* ctx, char* opt, char** val);
.sp
int \fBub_ctx_config\fP(struct ub_ctx* ctx, char* fname);
.sp
int \fBub_ctx_set_fwd\fP(struct ub_ctx* ctx, char* addr);
.INDENT 0.0
.TP
int \fBub_ctx_set_stub\fP(struct ub_ctx* ctx, char* zone, char* addr,
int isprime);
.UNINDENT
.sp
int \fBub_ctx_set_tls\fP(struct ub_ctx* ctx, int tls);
.sp
int \fBub_ctx_resolvconf\fP(struct ub_ctx* ctx, char* fname);
.sp
int \fBub_ctx_hosts\fP(struct ub_ctx* ctx, char* fname);
.sp
int \fBub_ctx_add_ta\fP(struct ub_ctx* ctx, char* ta);
.sp
int \fBub_ctx_add_ta_autr\fP(struct ub_ctx* ctx, char* fname);
.sp
int \fBub_ctx_add_ta_file\fP(struct ub_ctx* ctx, char* fname);
.sp
int \fBub_ctx_trustedkeys\fP(struct ub_ctx* ctx, char* fname);
.sp
int \fBub_ctx_debugout\fP(struct ub_ctx* ctx, FILE* out);
.sp
int \fBub_ctx_debuglevel\fP(struct ub_ctx* ctx, int d);
.sp
int \fBub_ctx_async\fP(struct ub_ctx* ctx, int dothread);
.sp
int \fBub_poll\fP(struct ub_ctx* ctx);
.sp
int \fBub_wait\fP(struct ub_ctx* ctx);
.sp
int \fBub_fd\fP(struct ub_ctx* ctx);
.sp
int \fBub_process\fP(struct ub_ctx* ctx);
.INDENT 0.0
.TP
int \fBub_resolve\fP(struct ub_ctx* ctx, char* name,
int rrtype, int rrclass, struct ub_result** result);
.TP
int \fBub_resolve_async\fP(struct ub_ctx* ctx, char* name,
int rrtype, int rrclass, void* mydata,
ub_callback_type* callback, int* async_id);
.UNINDENT
.sp
int \fBub_cancel\fP(struct ub_ctx* ctx, int async_id);
.sp
void \fBub_resolve_free\fP(struct ub_result* result);
.sp
const char * \fBub_strerror\fP(int err);
.sp
int \fBub_ctx_print_local_zones\fP(struct ub_ctx* ctx);
.sp
int \fBub_ctx_zone_add\fP(struct ub_ctx* ctx, char* zone_name, char* zone_type);
.sp
int \fBub_ctx_zone_remove\fP(struct ub_ctx* ctx, char* zone_name);
.sp
int \fBub_ctx_data_add\fP(struct ub_ctx* ctx, char* data);
.sp
int \fBub_ctx_data_remove\fP(struct ub_ctx* ctx, char* data);
.SH DESCRIPTION
.sp
Unbound is an implementation of a DNS resolver, that does caching and DNSSEC
validation.
This is the library API, for using the \fB\-lunbound\fP library.
The server daemon is described in \fI\%unbound(8)\fP\&.
The library works independent from a running unbound server, and 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.
.sp
The library uses a variable of type \fIstruct ub_ctx\fP to keep context between
calls.
The user must maintain it, creating it with \fBub_ctx_create\fP and deleting it
with \fBub_ctx_delete\fP\&.
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.
.sp
The functions are thread\-safe, and a context can 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.
.sp
The functions are discussed in turn below.
.SH "FUNCTIONS"
.TP
.SH FUNCTIONS
.INDENT 0.0
.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 asynchronous operation if you use
lib openssl (the application calls these functions once for initialisation).
Openssl 1.0.0 or later uses the CRYPTO_THREADID_set_callback function.
The information from \fB/etc/resolv.conf\fP and \fB/etc/hosts\fP is
not utilised by default.
Use \fBub_ctx_resolvconf\fP and \fBub_ctx_hosts\fP to read them.
Before you call this, use the openssl functions
\fBCRYPTO_set_id_callback\fP and \fBCRYPTO_set_locking_callback\fP to set
up asynchronous operation if you use lib openssl (the application calls
these functions once for initialisation).
Openssl 1.0.0 or later uses the \fBCRYPTO_THREADID_set_callback\fP
function.
.TP
.B ub_ctx_delete
Delete validation context and free associated resources.
Outstanding async queries are killed and callbacks are not called for them.
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 ':'.
A power\-user interface that lets you specify one of the options from
the config file format, see \fI\%unbound.conf(5)\fP\&.
Not all options are relevant.
For some specific options, such as adding trust anchors, special
routines exist.
Pass the option name with the trailing \fB\(aq:\(aq\fP\&.
.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.
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 \fB\(aq:\(aq\fP\&.
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. This function is thread\-safe only if a single instance of
ub_ctx* exists in the application. If several instances exist the
application has to ensure that ub_ctx_config is not called in parallel by
the different instances.
A power\-user interface that lets you specify an unbound config file,
see \fI\%unbound.conf(5)\fP, which is read for
configuration.
Not all options are relevant.
For some specific options, such as adding trust anchors, special
routines exist.
This function is thread\-safe only if a single instance of \fBub_ctx\fP*
exists in the application.
If several instances exist the application has to ensure that
\fBub_ctx_config\fP is not called in parallel by the different instances.
.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.
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_set_stub
Set a stub zone, authoritative dns servers to use for a particular zone.
IP4 or IP6 address. If the address is NULL the stub entry is removed.
Set isprime true if you configure root hints with it. Otherwise similar to
the stub zone item from unbound's config file. Can be called several times,
for different zones, or to add multiple addresses for a particular zone.
At this time it is only possible to set configuration before the
first resolve is done.
Set a stub zone, authoritative dns servers to use for a particular
zone.
IP4 or IP6 address.
If the address is NULL the stub entry is removed.
Set isprime true if you configure root hints with it.
Otherwise similar to the stub zone item from unbound\(aqs config file.
Can be called several times, for different zones, or to add multiple
addresses for a particular zone.
At this time it is only possible to set configuration before the first
resolve is done.
.TP
.B ub_ctx_set_tls
Enable DNS over TLS (DoT) for machines set with
.B ub_ctx_set_fwd.
At this time it is only possible to set configuration before the
first resolve is done.
Enable DNS over TLS (DoT) for machines set with \fBub_ctx_set_fwd\fP\&.
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.
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 \fB\(dq/etc/resolv.conf\(dq\fP\&.
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.
settings from \fIresolv.conf(5)\fP are ignored.
If fname NULL is passed, \fB\(dq/etc/resolv.conf\(dq\fP 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.
Usually \fB\(dq/etc/hosts\(dq\fP\&.
When queried for, these addresses are not marked DNSSEC secure.
If fname NULL is passed, \fB\(dq/etc/hosts\(dq\fP is used (if on Windows,
\fBetc/hosts\fP 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
.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.
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.
\fB[domainname]\fP \fB[type]\fP \fB[rdata contents]\fP\&.
Both DS and DNSKEY records are accepted.
.TP
.B ub_ctx_add_ta_autr
Add filename with automatically tracked trust anchor to the given context.
Pass name of a file with the managed trust anchor. You can create this
file with \fIunbound\-anchor\fR(8) for the root anchor. You can also
create it with an initial file with one line with a DNSKEY or DS record.
Add filename with automatically tracked trust anchor to the given
context.
Pass name of a file with the managed trust anchor.
You can create this file with
\fI\%unbound\-anchor(8)\fP for the root anchor.
You can also create it with an initial file with one line with a DNSKEY
or DS record.
If the file is writable, it is updated when the trust anchor changes.
At this time it is only possible to add trusted keys before the
first resolve is done.
At this time it is only possible to add trusted keys before the first
resolve is done.
.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.
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.
Pass the name of a bind\-style config file with \fBtrusted\-keys{}\fP\&.
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.
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.
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
if set to true, enables threading and a call to \fBub_resolve_async\fP
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).
Changes to this setting after \fBub_resolve_async\fP 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.
Do not poll in a loop, instead extract the \fBfd\fP 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.
If nonzero, call \fBub_process\fP 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.
Wait for a context to finish with results.
Calls \fBub_process\fP 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.
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\fP to continue processing.
.TP
.B ub_process
Call this routine to continue processing results from the validating
resolver (when the fd becomes readable).
resolver (when the \fBfd\fP becomes readable).
Will perform necessary callbacks.
.TP
.B ub_resolve
@ -340,95 +311,111 @@ 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.
Arguments mean the same as for \fBub_resolve\fP 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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
void my_callback_function(void* my_arg, int err,
struct ub_result* result);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBasync_id\fP 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 \fBasync_id\fP 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.
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.
Free struct \fBub_result\fP contents after use.
.TP
.B ub_strerror
Convert error value from one of the unbound library functions
to a human readable string.
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.
Add new zone to local authority info, like local\-zone
\fI\%unbound.conf(5)\fP 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.
\fI\%unbound.conf(5)\fP 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
.UNINDENT
.SH RESULT DATA STRUCTURE
.sp
The result of the DNS resolution and validation is returned as \fIstruct
ub_result\fP\&.
The result structure contains the following entries:
.INDENT 0.0
.INDENT 3.5
.sp
.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 was_ratelimited; /* true if the query was ratelimited (SERVFAIL) by unbound */
int ttl; /* number of seconds the result is valid */
};
.ft C
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 was_ratelimited; /* true if the query was ratelimited (SERVFAIL) by unbound */
int ttl; /* number of seconds the result is valid */
};
.ft P
.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.
.B ub_ctx_config
and
.B ub_ctx_resolvconf
attempt to leave errno informative on a function return with file read failure.
.SH "SEE ALSO"
\fIunbound.conf\fR(5),
\fIunbound\fR(8).
.SH "AUTHORS"
.B Unbound
developers are mentioned in the CREDITS file in the distribution.
.UNINDENT
.UNINDENT
.sp
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
.sp
Many routines return an error code.
The value 0 (zero) denotes no error happened.
Other values can be passed to \fBub_strerror\fP to obtain a readable error
string.
\fBub_strerror\fP returns a zero terminated string.
\fBub_ctx_create\fP returns NULL on an error (a malloc failure).
\fBub_poll\fP returns true if some information may be available, false otherwise.
\fBub_fd\fP returns a file descriptor or \-1 on error.
\fBub_ctx_config\fP and \fBub_ctx_resolvconf\fP attempt to leave errno informative
on a function return with file read failure.
.SH SEE ALSO
.sp
\fI\%unbound.conf(5)\fP, \fI\%unbound(8)\fP\&.
.SH AUTHOR
Unbound developers are mentioned in the CREDITS file in the distribution.
.SH COPYRIGHT
1999-2025, NLnet Labs
.\" Generated by docutils manpage writer.
.

491
doc/libunbound.rst Normal file
View file

@ -0,0 +1,491 @@
..
WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
..
IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
..
IT HELPS PEOPLE DIFFING THE CHANGES
..
WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
..
IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
..
IT HELPS PEOPLE DIFFING THE CHANGES
..
WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
..
IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
..
IT HELPS PEOPLE DIFFING THE CHANGES
..
WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
..
IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
..
IT HELPS PEOPLE DIFFING THE CHANGES
libunbound(3)
=============
Synopsis
--------
.. only:: html
.. code-block:: c
#include <unbound.h>
struct ub_ctx * ub_ctx_create(void);
void ub_ctx_delete(struct ub_ctx* ctx);
int ub_ctx_set_option(struct ub_ctx* ctx, char* opt, char* val);
int ub_ctx_get_option(struct ub_ctx* ctx, char* opt, char** val);
int ub_ctx_config(struct ub_ctx* ctx, char* fname);
int ub_ctx_set_fwd(struct ub_ctx* ctx, char* addr);
int ub_ctx_set_stub(struct ub_ctx* ctx, char* zone, char* addr,
int isprime);
int ub_ctx_set_tls(struct ub_ctx* ctx, int tls);
int ub_ctx_resolvconf(struct ub_ctx* ctx, char* fname);
int ub_ctx_hosts(struct ub_ctx* ctx, char* fname);
int ub_ctx_add_ta(struct ub_ctx* ctx, char* ta);
int ub_ctx_add_ta_autr(struct ub_ctx* ctx, char* fname);
int ub_ctx_add_ta_file(struct ub_ctx* ctx, char* fname);
int ub_ctx_trustedkeys(struct ub_ctx* ctx, char* fname);
int ub_ctx_debugout(struct ub_ctx* ctx, FILE* out);
int ub_ctx_debuglevel(struct ub_ctx* ctx, int d);
int ub_ctx_async(struct ub_ctx* ctx, int dothread);
int ub_poll(struct ub_ctx* ctx);
int ub_wait(struct ub_ctx* ctx);
int ub_fd(struct ub_ctx* ctx);
int ub_process(struct ub_ctx* ctx);
int ub_resolve(struct ub_ctx* ctx, char* name, int rrtype,
int rrclass, struct ub_result** result);
int ub_resolve_async(struct ub_ctx* ctx, char* name, int rrtype,
int rrclass, void* mydata, ub_callback_type callback,
int* async_id);
int ub_cancel(struct ub_ctx* ctx, int async_id);
void ub_resolve_free(struct ub_result* result);
const char * ub_strerror(int err);
int ub_ctx_print_local_zones(struct ub_ctx* ctx);
int ub_ctx_zone_add(struct ub_ctx* ctx, char* zone_name, char* zone_type);
int ub_ctx_zone_remove(struct ub_ctx* ctx, char* zone_name);
int ub_ctx_data_add(struct ub_ctx* ctx, char* data);
int ub_ctx_data_remove(struct ub_ctx* ctx, char* data);
.. only:: man
**#include <unbound.h>**
struct ub_ctx \* **ub_ctx_create**\ (void);
void **ub_ctx_delete**\ (struct ub_ctx\* ctx);
int **ub_ctx_set_option**\ (struct ub_ctx\* ctx, char\* opt, char\* val);
int **ub_ctx_get_option**\ (struct ub_ctx\* ctx, char\* opt, char\*\* val);
int **ub_ctx_config**\ (struct ub_ctx\* ctx, char* fname);
int **ub_ctx_set_fwd**\ (struct ub_ctx\* ctx, char\* addr);
int **ub_ctx_set_stub**\ (struct ub_ctx\* ctx, char\* zone, char\* addr,
int isprime);
int **ub_ctx_set_tls**\ (struct ub_ctx\* ctx, int tls);
int **ub_ctx_resolvconf**\ (struct ub_ctx\* ctx, char\* fname);
int **ub_ctx_hosts**\ (struct ub_ctx\* ctx, char\* fname);
int **ub_ctx_add_ta**\ (struct ub_ctx\* ctx, char\* ta);
int **ub_ctx_add_ta_autr**\ (struct ub_ctx\* ctx, char\* fname);
int **ub_ctx_add_ta_file**\ (struct ub_ctx\* ctx, char\* fname);
int **ub_ctx_trustedkeys**\ (struct ub_ctx\* ctx, char\* fname);
int **ub_ctx_debugout**\ (struct ub_ctx\* ctx, FILE\* out);
int **ub_ctx_debuglevel**\ (struct ub_ctx\* ctx, int d);
int **ub_ctx_async**\ (struct ub_ctx\* ctx, int dothread);
int **ub_poll**\ (struct ub_ctx\* ctx);
int **ub_wait**\ (struct ub_ctx\* ctx);
int **ub_fd**\ (struct ub_ctx\* ctx);
int **ub_process**\ (struct ub_ctx\* ctx);
int **ub_resolve**\ (struct ub_ctx\* ctx, char\* name,
int rrtype, int rrclass, struct ub_result\*\* result);
int **ub_resolve_async**\ (struct ub_ctx\* ctx, char\* name,
int rrtype, int rrclass, void\* mydata,
ub_callback_type\* callback, int\* async_id);
int **ub_cancel**\ (struct ub_ctx\* ctx, int async_id);
void **ub_resolve_free**\ (struct ub_result\* result);
const char \* **ub_strerror**\ (int err);
int **ub_ctx_print_local_zones**\ (struct ub_ctx\* ctx);
int **ub_ctx_zone_add**\ (struct ub_ctx\* ctx, char\* zone_name, char\* zone_type);
int **ub_ctx_zone_remove**\ (struct ub_ctx\* ctx, char\* zone_name);
int **ub_ctx_data_add**\ (struct ub_ctx\* ctx, char\* data);
int **ub_ctx_data_remove**\ (struct ub_ctx\* ctx, char\* data);
Description
-----------
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 :doc:`unbound(8)</manpages/unbound>`.
The library works independent from a running unbound server, and 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.
The library uses a variable of type *struct ub_ctx* to keep context between
calls.
The user must maintain it, creating it with **ub_ctx_create** and deleting it
with **ub_ctx_delete**.
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.
The functions are thread-safe, and a context can 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.
The functions are discussed in turn below.
Functions
---------
.. glossary::
ub_ctx_create
Create a new context, initialised with defaults.
The information from :file:`/etc/resolv.conf` and :file:`/etc/hosts` is
not utilised by default.
Use **ub_ctx_resolvconf** and **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 asynchronous operation if you use lib openssl (the application calls
these functions once for initialisation).
Openssl 1.0.0 or later uses the **CRYPTO_THREADID_set_callback**
function.
ub_ctx_delete
Delete validation context and free associated resources.
Outstanding async queries are killed and callbacks are not called for
them.
ub_ctx_set_option
A power-user interface that lets you specify one of the options from
the config file format, see :doc:`unbound.conf(5)</manpages/unbound.conf>`.
Not all options are relevant.
For some specific options, such as adding trust anchors, special
routines exist.
Pass the option name with the trailing ``':'``.
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.
ub_ctx_config
A power-user interface that lets you specify an unbound config file,
see :doc:`unbound.conf(5)</manpages/unbound.conf>`, which is read for
configuration.
Not all options are relevant.
For some specific options, such as adding trust anchors, special
routines exist.
This function is thread-safe only if a single instance of **ub_ctx**\*
exists in the application.
If several instances exist the application has to ensure that
**ub_ctx_config** is not called in parallel by the different instances.
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.
ub_ctx_set_stub
Set a stub zone, authoritative dns servers to use for a particular
zone.
IP4 or IP6 address.
If the address is NULL the stub entry is removed.
Set isprime true if you configure root hints with it.
Otherwise similar to the stub zone item from unbound's config file.
Can be called several times, for different zones, or to add multiple
addresses for a particular zone.
At this time it is only possible to set configuration before the first
resolve is done.
ub_ctx_set_tls
Enable DNS over TLS (DoT) for machines set with **ub_ctx_set_fwd**.
At this time it is only possible to set configuration before the first
resolve is done.
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 :file:`"/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 *resolv.conf(5)* are ignored.
If fname NULL is passed, :file:`"/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.
ub_ctx_hosts
Read list of hosts from the filename given.
Usually :file:`"/etc/hosts"`.
When queried for, these addresses are not marked DNSSEC secure.
If fname NULL is passed, :file:`"/etc/hosts"` is used (if on Windows,
:file:`etc/hosts` from WINDIR is picked instead).
At this time it is only possible to set configuration before the first
resolve is done.
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.
ub_ctx_add_ta_autr
Add filename with automatically tracked trust anchor to the given
context.
Pass name of a file with the managed trust anchor.
You can create this file with
:doc:`unbound-anchor(8)</manpages/unbound-anchor>` for the root anchor.
You can also create it with an initial file with one line with a DNSKEY
or DS record.
If the file is writable, it is updated when the trust anchor changes.
At this time it is only possible to add trusted keys before the first
resolve is done.
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.
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.
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.
ub_ctx_debuglevel
Set debug verbosity for the context.
Output is directed to stderr.
Higher debug level gives more output.
ub_ctx_async
Set a context behaviour for asynchronous action.
if set to true, enables threading and a call to **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 **ub_resolve_async** calls have been made
have no effect (delete and re-create the context to change).
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 **ub_process** to do callbacks.
ub_wait
Wait for a context to finish with results.
Calls **ub_process** after the wait for you.
After the wait, there are no more outstanding asynchronous queries.
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 **ub_process** to continue processing.
ub_process
Call this routine to continue processing results from the validating
resolver (when the **fd** becomes readable).
Will perform necessary callbacks.
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.
ub_resolve_async
Perform asynchronous resolution and validation of the target name.
Arguments mean the same as for **ub_resolve** 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:
.. code-block:: c
void my_callback_function(void* my_arg, int err,
struct ub_result* result);
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.
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.
ub_resolve_free
Free struct **ub_result** contents after use.
ub_strerror
Convert error value from one of the unbound library functions to a
human readable string.
ub_ctx_print_local_zones
Debug printout the local authority information to debug output.
ub_ctx_zone_add
Add new zone to local authority info, like local-zone
:doc:`unbound.conf(5)</manpages/unbound.conf>` statement.
ub_ctx_zone_remove
Delete zone from local authority info.
ub_ctx_data_add
Add resource record data to local authority info, like local-data
:doc:`unbound.conf(5)</manpages/unbound.conf>` statement.
ub_ctx_data_remove
Delete local authority data from the name given.
Result Data structure
---------------------
The result of the DNS resolution and validation is returned as *struct
ub_result*.
The result structure contains the following entries:
.. code-block:: c
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 was_ratelimited; /* true if the query was ratelimited (SERVFAIL) by unbound */
int ttl; /* number of seconds the result is valid */
};
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.
Return Values
-------------
Many routines return an error code.
The value 0 (zero) denotes no error happened.
Other values can be passed to **ub_strerror** to obtain a readable error
string.
**ub_strerror** returns a zero terminated string.
**ub_ctx_create** returns NULL on an error (a malloc failure).
**ub_poll** returns true if some information may be available, false otherwise.
**ub_fd** returns a file descriptor or -1 on error.
**ub_ctx_config** and **ub_ctx_resolvconf** attempt to leave errno informative
on a function return with file read failure.
See Also
--------
:doc:`unbound.conf(5)</manpages/unbound.conf>`, :doc:`unbound(8)</manpages/unbound>`.

379
doc/unbound-anchor.8.in
View file

@ -1,189 +1,300 @@
.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.
The program fetches the trust anchor with the method from RFC7958 when
regular RFC5011 update fails to bring it up to date.
.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "UNBOUND-ANCHOR" "8" "@date@" "@version@" "Unbound"
.SH NAME
unbound-anchor \- Unbound @version@ anchor utility.
.SH SYNOPSIS
.sp
\fBunbound\-anchor\fP [\fBopts\fP]
.SH DESCRIPTION
.sp
\fBunbound\-anchor\fP performs setup or update of the root trust anchor for DNSSEC
validation.
The program fetches the trust anchor with the method from \fI\%RFC 7958\fP when
regular \fI\%RFC 5011\fP update fails to bring it up to date.
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
scripts.
Before you start the \fI\%unbound(8)\fP DNS server.
.sp
Suggested usage:
.P
.INDENT 0.0
.INDENT 3.5
.sp
.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
.ft C
# in the init scripts.
# provide or update the root anchor (if necessary)
unbound\-anchor \-a \(dq@UNBOUND_ROOTKEY_FILE@\(dq
# 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: \(dq@UNBOUND_ROOTKEY_FILE@\(dq
unbound \-c unbound.conf
.ft P
.fi
.P
This tool provides builtin default contents for the root anchor and root
update certificate files.
.P
.UNINDENT
.UNINDENT
.sp
This tool provides builtin default contents for the root anchor and root update
certificate files.
.sp
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 (RFC7958),
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
It performs a https fetch of
\fI\%root\-anchors.xml\fP
and checks the results (\fI\%RFC 7958\fP); if all checks are successful, it updates
the root anchor file.
Otherwise the root anchor file is unchanged.
It performs \fI\%RFC 5011\fP tracking if the DNSSEC information available via the
DNS makes that possible.
.sp
It does not perform an update if the certificate is expired, if the network is
down or other errors occur.
.sp
The available options are:
.INDENT 0.0
.TP
.B \-a \fIfile
.B \-a <file>
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.
Default is \fB@UNBOUND_ROOTKEY_FILE@\fP\&.
If the file does not exist, or is empty, a builtin root key is written
to it.
.UNINDENT
.INDENT 0.0
.TP
.B \-c \fIfile
.B \-c <file>
The root update certificate file, that is read in.
Default is @UNBOUND_ROOTCERT_FILE@.
Default is \fB@UNBOUND_ROOTCERT_FILE@\fP\&.
If the file does not exist, or is empty, a builtin certificate is used.
.UNINDENT
.INDENT 0.0
.TP
.B \-l
List the builtin root key and builtin root update certificate on stdout.
.UNINDENT
.INDENT 0.0
.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.
.B \-u <name>
The server name, it connects to \fBhttps://name\fP\&.
Specify without \fBhttps://\fP prefix.
The default is \fB\(dqdata.iana.org\(dq\fP\&.
It connects to the port specified with \fI\%\-P\fP\&.
You can pass an IPv4 address or IPv6 address (no brackets) if you want.
.UNINDENT
.INDENT 0.0
.TP
.B \-S
Do not use SNI for the HTTPS connection. Default is to use SNI.
Do not use SNI for the HTTPS connection.
Default is to use SNI.
.UNINDENT
.INDENT 0.0
.TP
.B \-b \fIaddress
The source address to bind to for domain resolution and contacting the server
on https. May be either an IPv4 address or IPv6 address (no brackets).
.B \-b <address>
The source address to bind to for domain resolution and contacting the
server on https.
May be either an IPv4 address or IPv6 address (no brackets).
.UNINDENT
.INDENT 0.0
.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.
.B \-x <path>
The pathname to the root\-anchors.xml file on the server.
(forms URL with \fI\%\-u\fP).
The default is \fB/root\-anchors/root\-anchors.xml\fP\&.
.UNINDENT
.INDENT 0.0
.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.
.B \-s <path>
The pathname to the root\-anchors.p7s file on the server.
(forms URL with \fI\%\-u\fP).
The default is \fB/root\-anchors/root\-anchors.p7s\fP\&.
This file has to be a PKCS7 signature over the xml file, using the pem
file (\fI\%\-c\fP) as trust anchor.
.UNINDENT
.INDENT 0.0
.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.
.B \-n <name>
The emailAddress for the Subject of the signer\(aqs certificate from the
p7s signature file.
Only signatures from this name are allowed.
The default is \fBdnssec@iana.org\fP\&.
If you pass \fB\(dq\(dq\fP then the emailAddress is not checked.
.UNINDENT
.INDENT 0.0
.TP
.B \-4
Use IPv4 for domain resolution and contacting the server on https. Default is
to use IPv4 and IPv6 where appropriate.
Use IPv4 for domain resolution and contacting the server on
https.
Default is to use IPv4 and IPv6 where appropriate.
.UNINDENT
.INDENT 0.0
.TP
.B \-6
Use IPv6 for domain resolution and contacting the server on https. Default is
to use IPv4 and IPv6 where appropriate.
Use IPv6 for domain resolution and contacting the server on https.
Default is to use IPv4 and IPv6 where appropriate.
.UNINDENT
.INDENT 0.0
.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.
.B \-f <resolv.conf>
Use the given resolv.conf file.
Not enabled by default, but you could try to pass
\fB/etc/resolv.conf\fP 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.
.UNINDENT
.INDENT 0.0
.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.
.B \-r <root.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 (\fI\%\-u\fP 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.
resolver, cannot use that recursive resolver itself because it is
bootstrapping that server.
.UNINDENT
.INDENT 0.0
.TP
.B \-R
Allow fallback from \-f resolv.conf file to direct root servers query.
It allows you to prefer local resolvers, but fallback automatically
to direct root query if they do not respond or do not support DNSSEC.
Allow fallback from \fI\%\-f\fP \fB<resolv.conf>\fP file to direct root
servers query.
It allows you to prefer local resolvers, but fallback automatically to
direct root query if they do not respond or do not support DNSSEC.
.UNINDENT
.INDENT 0.0
.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.
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.
.UNINDENT
.INDENT 0.0
.TP
.B \-C \fIunbound.conf
Debug option to read unbound.conf into the resolver process used.
.B \-C <unbound.conf>
Debug option to read \fB<unbound.conf>\fP into the resolver process
used.
.UNINDENT
.INDENT 0.0
.TP
.B \-P \fIport
Set the port number to use for the https connection. The default is 443.
.B \-P <port>
Set the port number to use for the https connection.
The default is 443.
.UNINDENT
.INDENT 0.0
.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.
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.
.UNINDENT
.INDENT 0.0
.TP
.B \-h
Show the version and commandline option help.
.SH "EXIT CODE"
.UNINDENT
.SH EXIT CODE
.sp
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
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 \fI\%RFC 5011\fP tracking, or if an error occurred.
.sp
You can check the exit value in this manner:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
unbound-anchor \-a "root.key" || logger "Please check root.key"
.ft C
unbound\-anchor \-a \(dqroot.key\(dq || logger \(dqPlease check root.key\(dq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
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
https://github.com/NLnetLabs/unbound/blob/master/LICENSE) and might be stale or
not suitable to your purpose.
.P
By running "unbound\-anchor \-l" the keys and certificate that are
.SH TRUST
.sp
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 \fI\%https://github.com/NLnetLabs/unbound/blob/master/LICENSE\fP
and might be stale or not suitable to your purpose.
.sp
By running \fI\%unbound\-anchor \-l\fP 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"
.sp
The built\-in configuration can be overridden by providing a root\-cert file and
a rootkey file.
.SH FILES
.INDENT 0.0
.TP
.I @UNBOUND_ROOTKEY_FILE@
The root anchor file, updated with 5011 tracking, and read and written to.
.B @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).
.B @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
\fI\%https://data.iana.org/root\-anchors/icannbundle.pem\fP (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
.B \fI\%https://data.iana.org/root\-anchors/root\-anchors.xml\fP
Source for the root key information.
.TP
.I https://data.iana.org/root\-anchors/root\-anchors.p7s
.B \fI\%https://data.iana.org/root\-anchors/root\-anchors.p7s\fP
Signature on the root key information.
.SH "SEE ALSO"
\fIunbound.conf\fR(5),
\fIunbound\fR(8).
.UNINDENT
.SH SEE ALSO
.sp
\fI\%unbound.conf(5)\fP,
\fI\%unbound(8)\fP\&.
.SH AUTHOR
Unbound developers are mentioned in the CREDITS file in the distribution.
.SH COPYRIGHT
1999-2025, NLnet Labs
.\" Generated by docutils manpage writer.
.

281
doc/unbound-anchor.rst Normal file
View file

@ -0,0 +1,281 @@
..
WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
..
IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
..
IT HELPS PEOPLE DIFFING THE CHANGES
..
WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
..
IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
..
IT HELPS PEOPLE DIFFING THE CHANGES
..
WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
..
IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
..
IT HELPS PEOPLE DIFFING THE CHANGES
..
WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
..
IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
..
IT HELPS PEOPLE DIFFING THE CHANGES
.. program:: unbound-anchor
unbound-anchor(8)
=================
Synopsis
--------
**unbound-anchor** [``opts``]
Description
-----------
``unbound-anchor`` performs setup or update of the root trust anchor for DNSSEC
validation.
The program fetches the trust anchor with the method from :rfc:`7958` when
regular :rfc:`5011` update fails to bring it up to date.
It can be run (as root) from the commandline, or run as part of startup
scripts.
Before you start the :doc:`unbound(8)</manpages/unbound>` DNS server.
Suggested usage:
.. code-block:: text
# 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
This tool provides builtin default contents for the root anchor and root update
certificate files.
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 <http://data.iana.org/root-anchors/root-anchors.xml>`__
and checks the results (:rfc:`7958`); if all checks are successful, it updates
the root anchor file.
Otherwise the root anchor file is unchanged.
It performs :rfc:`5011` tracking if the DNSSEC information available via the
DNS makes that possible.
It does not perform an update if the certificate is expired, if the network is
down or other errors occur.
The available options are:
.. option:: -a <file>
The root anchor key file, that is read in and written out.
Default is :file:`@UNBOUND_ROOTKEY_FILE@`.
If the file does not exist, or is empty, a builtin root key is written
to it.
.. option:: -c <file>
The root update certificate file, that is read in.
Default is :file:`@UNBOUND_ROOTCERT_FILE@`.
If the file does not exist, or is empty, a builtin certificate is used.
.. option:: -l
List the builtin root key and builtin root update certificate on stdout.
.. option:: -u <name>
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 :option:`-P`.
You can pass an IPv4 address or IPv6 address (no brackets) if you want.
.. option:: -S
Do not use SNI for the HTTPS connection.
Default is to use SNI.
.. option:: -b <address>
The source address to bind to for domain resolution and contacting the
server on https.
May be either an IPv4 address or IPv6 address (no brackets).
.. option:: -x <path>
The pathname to the root-anchors.xml file on the server.
(forms URL with :option:`-u`).
The default is :file:`/root-anchors/root-anchors.xml`.
.. option:: -s <path>
The pathname to the root-anchors.p7s file on the server.
(forms URL with :option:`-u`).
The default is :file:`/root-anchors/root-anchors.p7s`.
This file has to be a PKCS7 signature over the xml file, using the pem
file (:option:`-c`) as trust anchor.
.. option:: -n <name>
The emailAddress for the Subject of the signer's certificate from the
p7s signature file.
Only signatures from this name are allowed.
The default is ``dnssec@iana.org``.
If you pass ``""`` then the emailAddress is not checked.
.. option:: -4
Use IPv4 for domain resolution and contacting the server on
https.
Default is to use IPv4 and IPv6 where appropriate.
.. option:: -6
Use IPv6 for domain resolution and contacting the server on https.
Default is to use IPv4 and IPv6 where appropriate.
.. option:: -f <resolv.conf>
Use the given resolv.conf file.
Not enabled by default, but you could try to pass
:file:`/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.
.. option:: -r <root.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 (:option:`-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.
.. option:: -R
Allow fallback from :option:`-f` ``<resolv.conf>`` file to direct root
servers query.
It allows you to prefer local resolvers, but fallback automatically to
direct root query if they do not respond or do not support DNSSEC.
.. option:: -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.
.. option:: -C <unbound.conf>
Debug option to read :file:`<unbound.conf>` into the resolver process
used.
.. option:: -P <port>
Set the port number to use for the https connection.
The default is 443.
.. option:: -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.
.. option:: -h
Show the version and commandline option help.
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 :rfc:`5011` tracking, or if an error occurred.
You can check the exit value in this manner:
.. code-block:: text
unbound-anchor -a "root.key" || logger "Please check root.key"
Or something more suitable for your operational environment.
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 https://github.com/NLnetLabs/unbound/blob/master/LICENSE
and might be stale or not suitable to your purpose.
By running :option:`unbound-anchor -l` the keys and certificate that are
configured in the code are printed for your convenience.
The built-in configuration can be overridden by providing a root-cert file and
a rootkey file.
Files
-----
@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.
@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.
https://data.iana.org/root-anchors/root-anchors.xml
Source for the root key information.
https://data.iana.org/root-anchors/root-anchors.p7s
Signature on the root key information.
See Also
--------
:doc:`unbound.conf(5)</manpages/unbound.conf>`,
:doc:`unbound(8)</manpages/unbound>`.

121
doc/unbound-checkconf.8.in
View file

@ -1,56 +1,93 @@
.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 [ \-f ]
.RB [ \-q ]
.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.
.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "UNBOUND-CHECKCONF" "8" "@date@" "@version@" "Unbound"
.SH NAME
unbound-checkconf \- Check Unbound @version@ configuration file for errors.
.SH SYNOPSIS
.sp
\fBunbound\-checkconf\fP [\fB\-hf\fP] [\fB\-o option\fP] [cfgfile]
.SH DESCRIPTION
.sp
\fBunbound\-checkconf\fP checks the configuration file for the
\fI\%unbound(8)\fP DNS resolver for syntax and other errors.
The config file syntax is described in
\fIunbound.conf\fR(5).
.P
\fI\%unbound.conf(5)\fP\&.
.sp
The available options are:
.INDENT 0.0
.TP
.B \-h
Show the version and commandline option help.
.UNINDENT
.INDENT 0.0
.TP
.B \-f
Print full pathname, with chroot applied to it. Use with the \-o option.
.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.
Print full pathname, with chroot applied to it.
Use with the \fI\%\-o\fP option.
.UNINDENT
.INDENT 0.0
.TP
.B \-q
Make the operation quiet, suppress output on success.
.UNINDENT
.INDENT 0.0
.TP
.I cfgfile
The config file to read with settings for Unbound. It is checked.
.B \-o <option>
If given, after checking the config file the value of this option is
printed to stdout.
For \fB\(dq\(dq\fP (disabled) options an empty line is printed.
.UNINDENT
.INDENT 0.0
.TP
.B 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"
.UNINDENT
.SH EXIT CODE
.sp
The \fBunbound\-checkconf\fP program exits with status code 1 on error, 0 for a
correct config file.
.SH FILES
.INDENT 0.0
.TP
.I @ub_conf_file@
.B @ub_conf_file@
Unbound configuration file.
.SH "SEE ALSO"
\fIunbound.conf\fR(5),
\fIunbound\fR(8).
.UNINDENT
.SH SEE ALSO
.sp
\fI\%unbound.conf(5)\fP,
\fI\%unbound(8)\fP\&.
.SH AUTHOR
Unbound developers are mentioned in the CREDITS file in the distribution.
.SH COPYRIGHT
1999-2025, NLnet Labs
.\" Generated by docutils manpage writer.
.

98
doc/unbound-checkconf.rst Normal file
View file

@ -0,0 +1,98 @@
..
WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
..
IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
..
IT HELPS PEOPLE DIFFING THE CHANGES
..
WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
..
IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
..
IT HELPS PEOPLE DIFFING THE CHANGES
..
WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
..
IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
..
IT HELPS PEOPLE DIFFING THE CHANGES
..
WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
..
IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
..
IT HELPS PEOPLE DIFFING THE CHANGES
.. program:: unbound-checkconf
unbound-checkconf(8)
====================
Synopsis
--------
**unbound-checkconf** [``-hf``] [``-o option``] [cfgfile]
Description
-----------
``unbound-checkconf`` checks the configuration file for the
:doc:`unbound(8)</manpages/unbound>` DNS resolver for syntax and other errors.
The config file syntax is described in
:doc:`unbound.conf(5)</manpages/unbound.conf>`.
The available options are:
.. option:: -h
Show the version and commandline option help.
.. option:: -f
Print full pathname, with chroot applied to it.
Use with the :option:`-o` option.
.. option:: -q
Make the operation quiet, suppress output on success.
.. option:: -o <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.
.. option:: cfgfile
The config file to read with settings for Unbound.
It is checked.
If omitted, the config file at the default location is checked.
Exit Code
---------
The ``unbound-checkconf`` program exits with status code 1 on error, 0 for a
correct config file.
Files
-----
@ub_conf_file@
Unbound configuration file.
See Also
--------
:doc:`unbound.conf(5)</manpages/unbound.conf>`,
:doc:`unbound(8)</manpages/unbound>`.

1817
doc/unbound-control.8.in
View file

File diff suppressed because it is too large Load diff

1354
doc/unbound-control.rst Normal file
View file

File diff suppressed because it is too large Load diff

242
doc/unbound-host.1.in
View file

@ -1,118 +1,190 @@
.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 [ \-C
.IR configfile ]
.RB [ \-vdhr46D ]
.RB [ \-c
.IR class ]
.RB [ \-t
.IR type ]
.RB [ \-y
.IR key ]
.RB [ \-f
.IR keyfile ]
.RB [ \-F
.IR namedkeyfile ]
.I hostname
.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
.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "UNBOUND-HOST" "1" "@date@" "@version@" "Unbound"
.SH NAME
unbound-host \- Unbound @version@ DNS lookup utility.
.SH SYNOPSIS
.sp
\fBunbound\-host\fP [\fB\-C configfile\fP] [\fB\-vdhr46D\fP] [\fB\-c class\fP]
[\fB\-t type\fP] [\fB\-y key\fP] [\fB\-f keyfile\fP] [\fB\-F namedkeyfile\fP] hostname
.SH DESCRIPTION
.sp
\fBunbound\-host\fP uses the Unbound validating resolver to query for the hostname
and display results.
With the \fI\%\-v\fP option it displays validation status: secure, insecure,
bogus (security failure).
.sp
By default it reads no configuration file whatsoever.
It attempts to reach the internet root servers.
With \fI\%\-C\fP an unbound config file and with \fI\%\-r\fP \fBresolv.conf\fP
can be read.
.sp
The available options are:
.INDENT 0.0
.TP
.I hostname
.B hostname
This name is resolved (looked up in the DNS).
If a IPv4 or IPv6 address is given, a reverse lookup is performed.
.UNINDENT
.INDENT 0.0
.TP
.B \-h
Show the version and commandline option help.
.UNINDENT
.INDENT 0.0
.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.
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.
Bogus (security failure) means that the response failed one or more
checks, it is likely wrong, outdated, tampered with, or broken.
.UNINDENT
.INDENT 0.0
.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.
Enable debug output to stderr.
One \fI\%\-d\fP shows what the resolver and validator are doing and may
tell you what is going on.
More times, \fI\%\-d\fP \fI\%\-d\fP, gives a lot of output, with every
packet sent and received.
.UNINDENT
.INDENT 0.0
.TP
.B \-c \fIclass
Specify the class to lookup for, the default is IN the internet class.
.B \-c <class>
Specify the class to lookup for, the default is IN the internet
class.
.UNINDENT
.INDENT 0.0
.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.
.B \-t <type>
Specify the type of data to lookup.
The default looks for IPv4, IPv6 and mail handler data, or domain name
pointers for reverse queries.
.UNINDENT
.INDENT 0.0
.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".
.B \-y <key>
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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\-y \(dqexample.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD\(dq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.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.
Enables DNSSEC validation.
Reads the root anchor from the default configured root anchor at the
default location, \fB@UNBOUND_ROOTKEY_FILE@\fP\&.
.UNINDENT
.INDENT 0.0
.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.
.B \-f <keyfile>
Reads keys from a file.
Every line has a DS or DNSKEY record, in the format as for \fI\%\-y\fP\&.
The zone file format, the same as \fBdig\fP and \fBdrill\fP produce.
.UNINDENT
.INDENT 0.0
.TP
.B \-F \fInamedkeyfile
Reads keys from a BIND\-style named.conf file. Only the trusted\-key {}; entries
are read.
.B \-F <namedkeyfile>
Reads keys from a BIND\-style \fBnamed.conf\fP file.
Only the \fBtrusted\-key {};\fP entries are read.
.UNINDENT
.INDENT 0.0
.TP
.B \-C \fIconfigfile
Uses the specified unbound.conf to prime
.IR libunbound (3).
.B \-C <configfile>
Uses the specified unbound.conf to prime \fI\%libunbound(3)\fP\&.
Pass it as first argument if you want to override some options from the
config file with further arguments on the commandline.
.UNINDENT
.INDENT 0.0
.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).
Read \fB/etc/resolv.conf\fP, and use the forward DNS servers from
there (those could have been set by DHCP).
More info in \fIresolv.conf(5)\fP\&.
Breaks validation if those servers do not support DNSSEC.
.UNINDENT
.INDENT 0.0
.TP
.B \-4
Use solely the IPv4 network for sending packets.
.UNINDENT
.INDENT 0.0
.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
.UNINDENT
.SH EXAMPLES
.sp
Some examples of use.
The keys shown below are fakes, thus a security failure is encountered.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ 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).
$ unbound\-host \-v \-y \(dqexample.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD\(dq www.example.com
$ unbound\-host \-v \-y \(dqexample.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD\(dq 192.0.2.153
.ft P
.fi
.UNINDENT
.UNINDENT
.SH EXIT CODE
.sp
The \fBunbound\-host\fP 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
.sp
\fI\%unbound.conf(5)\fP,
\fI\%unbound(8)\fP\&.
.SH AUTHOR
Unbound developers are mentioned in the CREDITS file in the distribution.
.SH COPYRIGHT
1999-2025, NLnet Labs
.\" Generated by docutils manpage writer.
.

176
doc/unbound-host.rst Normal file
View file

@ -0,0 +1,176 @@
..
WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
..
IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
..
IT HELPS PEOPLE DIFFING THE CHANGES
..
WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
..
IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
..
IT HELPS PEOPLE DIFFING THE CHANGES
..
WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
..
IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
..
IT HELPS PEOPLE DIFFING THE CHANGES
..
WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
..
IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
..
IT HELPS PEOPLE DIFFING THE CHANGES
.. program:: unbound-host
unbound-host(1)
===============
Synopsis
--------
**unbound-host** [``-C configfile``] [``-vdhr46D``] [``-c class``]
[``-t type``] [``-y key``] [``-f keyfile``] [``-F namedkeyfile``] hostname
Description
-----------
``unbound-host`` uses the Unbound validating resolver to query for the hostname
and display results.
With the :option:`-v` option it displays validation status: secure, insecure,
bogus (security failure).
By default it reads no configuration file whatsoever.
It attempts to reach the internet root servers.
With :option:`-C` an unbound config file and with :option:`-r` ``resolv.conf``
can be read.
The available options are:
.. option:: hostname
This name is resolved (looked up in the DNS).
If a IPv4 or IPv6 address is given, a reverse lookup is performed.
.. option:: -h
Show the version and commandline option help.
.. option:: -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.
.. option:: -d
Enable debug output to stderr.
One :option:`-d` shows what the resolver and validator are doing and may
tell you what is going on.
More times, :option:`-d` :option:`-d`, gives a lot of output, with every
packet sent and received.
.. option:: -c <class>
Specify the class to lookup for, the default is IN the internet
class.
.. option:: -t <type>
Specify the type of data to lookup.
The default looks for IPv4, IPv6 and mail handler data, or domain name
pointers for reverse queries.
.. option:: -y <key>
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:
.. code-block:: text
-y "example.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD"
.. option:: -D
Enables DNSSEC validation.
Reads the root anchor from the default configured root anchor at the
default location, :file:`@UNBOUND_ROOTKEY_FILE@`.
.. option:: -f <keyfile>
Reads keys from a file.
Every line has a DS or DNSKEY record, in the format as for :option:`-y`.
The zone file format, the same as ``dig`` and ``drill`` produce.
.. option:: -F <namedkeyfile>
Reads keys from a BIND-style :file:`named.conf` file.
Only the ``trusted-key {};`` entries are read.
.. option:: -C <configfile>
Uses the specified unbound.conf to prime :doc:`libunbound(3)</manpages/libunbound>`.
Pass it as first argument if you want to override some options from the
config file with further arguments on the commandline.
.. option:: -r
Read :file:`/etc/resolv.conf`, and use the forward DNS servers from
there (those could have been set by DHCP).
More info in *resolv.conf(5)*.
Breaks validation if those servers do not support DNSSEC.
.. option:: -4
Use solely the IPv4 network for sending packets.
.. option:: -6
Use solely the IPv6 network for sending packets.
Examples
--------
Some examples of use.
The keys shown below are fakes, thus a security failure is encountered.
.. code-block:: text
$ unbound-host www.example.com
$ unbound-host -v -y "example.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD" www.example.com
$ unbound-host -v -y "example.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD" 192.0.2.153
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.
See Also
--------
:doc:`unbound.conf(5)</manpages/unbound.conf>`,
:doc:`unbound(8)</manpages/unbound>`.

169
doc/unbound.8.in
View file

@ -1,88 +1,123 @@
.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 [ \-p ]
.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 (.),
.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "UNBOUND" "8" "@date@" "@version@" "Unbound"
.SH NAME
unbound \- Unbound DNS validating resolver @version@.
.SH SYNOPSIS
.sp
\fBunbound\fP [\fB\-hdpv\fP] [\fB\-c <cfgfile>\fP]
.SH DESCRIPTION
.sp
\fBunbound\fP is a caching DNS resolver.
.sp
It uses a built in list of authoritative nameservers for the root zone (\fB\&.\fP),
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.
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).
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\(aqs 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
To use a locally running Unbound for resolving put:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
nameserver 127.0.0.1
.RE
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
into \fIresolv.conf(5)\fP\&.
.sp
If authoritative DNS is needed as well using \fI\%nsd(8)\fP,
careful setup is required because authoritative nameservers and resolvers are
using the same port number (53).
.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:
.INDENT 0.0
.TP
.B \-h
Show the version number and commandline option help, and exit.
.UNINDENT
.INDENT 0.0
.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).
.B \-c <cfgfile>
Set the config file with settings for unbound to read instead of reading the
file at the default location, \fB@ub_conf_file@\fP\&.
The syntax is described in \fI\%unbound.conf(5)\fP\&.
.UNINDENT
.INDENT 0.0
.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.
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.
.UNINDENT
.INDENT 0.0
.TP
.B \-p
Don't use a pidfile. This argument should only be used by supervision
systems which can ensure that only one instance of Unbound will run
concurrently.
Don\(aqt use a pidfile.
This argument should only be used by supervision systems which can ensure
that only one instance of Unbound will run concurrently.
.UNINDENT
.INDENT 0.0
.TP
.B \-v
Increase verbosity. If given multiple times, more information is logged.
This is added to the verbosity (if any) from the config file.
Increase verbosity.
If given multiple times, more information is logged.
This is in addition to the verbosity (if any) from the config file.
.UNINDENT
.INDENT 0.0
.TP
.B \-V
Show the version number and build options, and exit.
.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.
.UNINDENT
.SH SEE ALSO
.sp
\fI\%unbound.conf(5)\fP,
\fI\%unbound\-checkconf(8)\fP,
\fI\%nsd(8)\fP\&.
.SH AUTHOR
Unbound developers are mentioned in the CREDITS file in the distribution.
.SH COPYRIGHT
1999-2025, NLnet Labs
.\" Generated by docutils manpage writer.
.

7545
doc/unbound.conf.5.in
View file

File diff suppressed because it is too large Load diff

4996
doc/unbound.conf.rst Normal file
View file

File diff suppressed because it is too large Load diff

119
doc/unbound.rst Normal file
View file

@ -0,0 +1,119 @@
..
WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
..
IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
..
IT HELPS PEOPLE DIFFING THE CHANGES
..
WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
..
IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
..
IT HELPS PEOPLE DIFFING THE CHANGES
..
WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
..
IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
..
IT HELPS PEOPLE DIFFING THE CHANGES
..
WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
..
IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
..
IT HELPS PEOPLE DIFFING THE CHANGES
.. program:: unbound
unbound(8)
==========
Synopsis
--------
**unbound** [``-hdpv``] [``-c <cfgfile>``]
Description
-----------
``unbound`` is a caching DNS resolver.
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.
To use a locally running Unbound for resolving put:
.. code-block:: text
nameserver 127.0.0.1
into *resolv.conf(5)*.
If authoritative DNS is needed as well using :external+nsd:doc:`manpages/nsd`,
careful setup is required because authoritative nameservers and resolvers are
using the same port number (53).
The available options are:
.. option:: -h
Show the version number and commandline option help, and exit.
.. option:: -c <cfgfile>
Set the config file with settings for unbound to read instead of reading the
file at the default location, :file:`@ub_conf_file@`.
The syntax is described in :doc:`unbound.conf(5)</manpages/unbound.conf>`.
.. option:: -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.
.. option:: -p
Don't use a pidfile.
This argument should only be used by supervision systems which can ensure
that only one instance of Unbound will run concurrently.
.. option:: -v
Increase verbosity.
If given multiple times, more information is logged.
This is in addition to the verbosity (if any) from the config file.
.. option:: -V
Show the version number and build options, and exit.
See Also
--------
:doc:`unbound.conf(5)</manpages/unbound.conf>`,
:doc:`unbound-checkconf(8)</manpages/unbound-checkconf>`,
:external+nsd:doc:`manpages/nsd`.