Date: Fri, 22 May 2026 20:52:52 +0000 From: Dag-Erling=?utf-8?Q? Sm=C3=B8rg?=rav <des@FreeBSD.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org Subject: git: 290190b26c09 - main - unbound: Regenerate for 1.24.1 Message-ID: <6a10c224.190d3.7930a324@gitrepo.freebsd.org>
index | next in thread | raw e-mail
The branch main has been updated by des: URL: https://cgit.FreeBSD.org/src/commit/?id=290190b26c09c307a9cd70703fa20ad2b2b600a6 commit 290190b26c09c307a9cd70703fa20ad2b2b600a6 Author: Dag-Erling Smørgrav <des@FreeBSD.org> AuthorDate: 2026-05-22 20:04:22 +0000 Commit: Dag-Erling Smørgrav <des@FreeBSD.org> CommitDate: 2026-05-22 20:14:47 +0000 unbound: Regenerate for 1.24.1 No functional changes intended. Fixes: 8b29c373e6ab ("unbound: Vendor import 1.24.1") --- contrib/unbound/doc/example.conf | 14 +- contrib/unbound/doc/libunbound.3 | 675 ++- contrib/unbound/doc/unbound-anchor.8 | 383 +- contrib/unbound/doc/unbound-checkconf.8 | 121 +- contrib/unbound/doc/unbound-control.8 | 2038 +++++--- contrib/unbound/doc/unbound-host.1 | 242 +- contrib/unbound/doc/unbound.8 | 169 +- contrib/unbound/doc/unbound.conf.5 | 8152 ++++++++++++++++++++----------- lib/libunbound/config.h | 24 +- 9 files changed, 7568 insertions(+), 4250 deletions(-) diff --git a/contrib/unbound/doc/example.conf b/contrib/unbound/doc/example.conf index 3a5188f00477..56bb3247b20e 100644 --- a/contrib/unbound/doc/example.conf +++ b/contrib/unbound/doc/example.conf @@ -1,7 +1,7 @@ # # Example configuration file. # -# See unbound.conf(5) man page, version 1.23.1. +# See unbound.conf(5) man page, version 1.24.1. # # this is a comment. @@ -116,8 +116,8 @@ server: # so-rcvbuf: 0 # buffer size for UDP port 53 outgoing (SO_SNDBUF socket option). - # 0 is system default. Use 4m to handle spikes on very busy servers. - # so-sndbuf: 0 + # 0 is system default. Set larger to handle spikes on very busy servers. + # so-sndbuf: 4m # use SO_REUSEPORT to distribute queries over threads. # at extreme load it could be better to turn it off to distribute even. @@ -163,7 +163,7 @@ server: # msg-cache-slabs: 4 # the number of queries that a thread gets to service. - # num-queries-per-thread: 1024 + # num-queries-per-thread: 2048 # if very busy, 50% queries run to completion, 50% get timeout in msec # jostle-timeout: 200 @@ -196,6 +196,10 @@ server: # Limit on upstream queries for an incoming query and its recursion. # max-global-quota: 200 + # Should the scrubber remove promiscuous NS from positive answers, + # protects against poison attempts. + # iter-scrub-promiscuous: yes + # msec for waiting for an unknown server to reply. Increase if you # are behind a slow satellite link, to eg. 1128. # unknown-server-time-limit: 376 @@ -279,7 +283,7 @@ server: # do-ip6: yes # If running unbound on an IPv6-only host, domains that only have - # IPv4 servers would become unresolveable. If NAT64 is available in + # IPv4 servers would become unresolvable. If NAT64 is available in # the network, unbound can use NAT64 to reach these servers with # the following option. This is NOT needed for enabling DNS64 on a # system that has IPv4 connectivity. diff --git a/contrib/unbound/doc/libunbound.3 b/contrib/unbound/doc/libunbound.3 index 8ef33b0998a2..681c141fcd76 100644 --- a/contrib/unbound/doc/libunbound.3 +++ b/contrib/unbound/doc/libunbound.3 @@ -1,335 +1,306 @@ -.TH "libunbound" "3" "Jul 16, 2025" "NLnet Labs" "unbound 1.23.1" -.\" -.\" 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 1.23.1 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" "Oct 22, 2025" "1.24.1" "Unbound" +.SH NAME +libunbound \- Unbound DNS validating resolver 1.24.1 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. -.TP -.B -ub_ctx_add_ta +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. +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. +. diff --git a/contrib/unbound/doc/unbound-anchor.8 b/contrib/unbound/doc/unbound-anchor.8 index 23c1dd4b060f..ba8bd843a67c 100644 --- a/contrib/unbound/doc/unbound-anchor.8 +++ b/contrib/unbound/doc/unbound-anchor.8 @@ -1,189 +1,300 @@ -.TH "unbound-anchor" "8" "Jul 16, 2025" "NLnet Labs" "unbound 1.23.1" -.\" -.\" 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" "Oct 22, 2025" "1.24.1" "Unbound" +.SH NAME +unbound-anchor \- Unbound 1.24.1 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 "/var/unbound/root.key" - # 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: "/var/unbound/root.key" - unbound \-c unbound.conf +.ft C +# in the init scripts. +# provide or update the root anchor (if necessary) +unbound\-anchor \-a \(dq/var/unbound/root.key\(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/var/unbound/root.key\(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 /var/unbound/root.key. -If the file does not exist, or is empty, a builtin root key is written to it. *** 11839 LINES SKIPPED ***home | help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?6a10c224.190d3.7930a324>