mirror of
https://github.com/NLnetLabs/unbound.git
synced 2025-12-20 23:00:56 -05:00
6662f71732
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.
421 lines
15 KiB
Groff
421 lines
15 KiB
Groff
.\" 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
|
|
.INDENT 0.0
|
|
.TP
|
|
.B ub_ctx_create
|
|
Create a new context, initialised with defaults.
|
|
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.
|
|
.TP
|
|
.B ub_ctx_set_option
|
|
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 \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 \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.
|
|
.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\(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 \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 \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(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 \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
|
|
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,
|
|
\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
|
|
\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.
|
|
.TP
|
|
.B ub_ctx_add_ta_file
|
|
Add trust anchors to the given context.
|
|
Pass name of a file with DS and DNSKEY records in zone file format.
|
|
At this time it is only possible to add trusted keys before the first
|
|
resolve is done.
|
|
.TP
|
|
.B ub_ctx_trustedkeys
|
|
Add trust anchors to the given context.
|
|
Pass the name of a bind\-style config file with \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.
|
|
.TP
|
|
.B ub_ctx_debuglevel
|
|
Set debug verbosity for the context.
|
|
Output is directed to stderr.
|
|
Higher debug level gives more output.
|
|
.TP
|
|
.B ub_ctx_async
|
|
Set a context behaviour for asynchronous action.
|
|
if set to true, enables threading and a call to \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 \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 \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 \fBub_process\fP to do callbacks.
|
|
.TP
|
|
.B ub_wait
|
|
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\fP to continue processing.
|
|
.TP
|
|
.B ub_process
|
|
Call this routine to continue processing results from the validating
|
|
resolver (when the \fBfd\fP becomes readable).
|
|
Will perform necessary callbacks.
|
|
.TP
|
|
.B ub_resolve
|
|
Perform resolution and validation of the target name.
|
|
The name is a domain name in a zero terminated text string.
|
|
The rrtype and rrclass are DNS type and class codes.
|
|
The result structure is newly allocated with the resulting data.
|
|
.TP
|
|
.B ub_resolve_async
|
|
Perform asynchronous resolution and validation of the target name.
|
|
Arguments mean the same as for \fBub_resolve\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.
|
|
.TP
|
|
.B ub_resolve_free
|
|
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.
|
|
.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
|
|
\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
|
|
\fI\%unbound.conf(5)\fP statement.
|
|
.TP
|
|
.B ub_ctx_data_remove
|
|
Delete local authority data from the name given.
|
|
.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
|
|
.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
|
|
.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.
|
|
.
|