This file contains functions to resolve DNS queries and validate the answers. More...

#include "libunbound/unbound.h"
#include "libunbound/unbound-event.h"
#include "config.h"
#include <ctype.h>
#include "libunbound/context.h"
#include "libunbound/libworker.h"
#include "util/locks.h"
#include "util/config_file.h"
#include "util/alloc.h"
#include "util/module.h"
#include "util/regional.h"
#include "util/log.h"
#include "util/random.h"
#include "util/net_help.h"
#include "util/tube.h"
#include "util/ub_event.h"
#include "util/edns.h"
#include "services/modstack.h"
#include "services/localzone.h"
#include "services/cache/infra.h"
#include "services/cache/rrset.h"
#include "services/authzone.h"
#include "services/listen_dnsport.h"
#include "sldns/sbuffer.h"
#include "iterator/iter_fwd.h"
#include "iterator/iter_hints.h"

Functions
static struct ub_ctx *	ub_ctx_create_nopipe (void)
	create context functionality, but no pipes

struct ub_ctx *	ub_ctx_create (void)
	Create a resolving and validation context. More...

struct ub_ctx *	ub_ctx_create_ub_event (struct ub_event_base *ueb)
	Create a resolving and validation context. More...

struct ub_ctx *	ub_ctx_create_event (struct event_base *eb)
	Create a resolving and validation context. More...

static void	delq (rbnode_type n, void ATTR_UNUSED(arg))
	delete q

static void	ub_stop_bg (struct ub_ctx *ctx)
	stop the bg thread

void	ub_ctx_delete (struct ub_ctx *ctx)
	Destroy a validation context and free all its resources. More...

int	ub_ctx_set_option (struct ub_ctx ctx, const char opt, const char *val)
	Set an option for the context. More...

int	ub_ctx_get_option (struct ub_ctx ctx, const char opt, char **str)
	Get an option from the context. More...

int	ub_ctx_config (struct ub_ctx ctx, const char fname)
	setup configuration for the given context. More...

int	ub_ctx_add_ta (struct ub_ctx ctx, const char ta)
	Add a trust anchor to the given context. More...

int	ub_ctx_add_ta_file (struct ub_ctx ctx, const char fname)
	Add trust anchors to the given context. More...

int	ub_ctx_add_ta_autr (struct ub_ctx ctx, const char fname)
	Add trust anchor to the given context that is tracked with RFC5011 automated trust anchor maintenance. More...

int	ub_ctx_trustedkeys (struct ub_ctx ctx, const char fname)
	Add trust anchors to the given context. More...

int	ub_ctx_debuglevel (struct ub_ctx *ctx, int d)
	Set debug verbosity for the context Output is directed to stderr. More...

int	ub_ctx_debugout (struct ub_ctx ctx, void out)
	Set debug output (and error output) to the specified stream. More...

int	ub_ctx_async (struct ub_ctx *ctx, int dothread)
	Set a context behaviour for asynchronous action. More...

int	ub_poll (struct ub_ctx *ctx)
	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. More...

int	ub_fd (struct ub_ctx *ctx)
	Get file descriptor. More...

static int	process_answer_detail (struct ub_ctx ctx, uint8_t msg, uint32_t len, ub_callback_type cb, void cbarg, int err, struct ub_result **res)
	process answer from bg worker

static int	process_answer (struct ub_ctx ctx, uint8_t msg, uint32_t len)
	process answer from bg worker

int	ub_process (struct ub_ctx *ctx)
	Call this routine to continue processing results from the validating resolver (when the fd becomes readable). More...

int	ub_wait (struct ub_ctx *ctx)
	Wait for a context to finish with results. More...

int	ub_resolve (struct ub_ctx ctx, const char name, int rrtype, int rrclass, struct ub_result **result)
	Perform resolution and validation of the target name. More...

int	ub_resolve_event (struct ub_ctx ctx, const char name, int rrtype, int rrclass, void mydata, ub_event_callback_type callback, int async_id)
	Perform resolution and validation of the target name. More...

int	ub_resolve_async (struct ub_ctx ctx, const char name, int rrtype, int rrclass, void mydata, ub_callback_type callback, int async_id)
	Perform resolution and validation of the target name. More...

int	ub_cancel (struct ub_ctx *ctx, int async_id)
	Cancel an async query in progress. More...

void	ub_resolve_free (struct ub_result *result)
	Free storage associated with a result structure. More...

const char *	ub_strerror (int err)
	Convert error value to a human readable string. More...

int	ub_ctx_set_fwd (struct ub_ctx ctx, const char addr)
	Set machine to forward DNS queries to, the caching resolver to use. More...

int	ub_ctx_set_tls (struct ub_ctx *ctx, int tls)
	Use DNS over TLS to send queries to machines set with ub_ctx_set_fwd(). More...

int	ub_ctx_set_stub (struct ub_ctx ctx, const char zone, const char *addr, int isprime)
	Add a stub zone, with given address to send to. More...

int	ub_ctx_resolvconf (struct ub_ctx ctx, const char fname)
	Read list of nameservers to use from the filename given. More...

int	ub_ctx_hosts (struct ub_ctx ctx, const char fname)
	Read list of hosts from the filename given. More...

static int	ub_ctx_finalize (struct ub_ctx *ctx)
	finalize the context, if not already finalized

int	ub_ctx_print_local_zones (struct ub_ctx *ctx)
	Debug routine. More...

int	ub_ctx_zone_add (struct ub_ctx ctx, const char zone_name, const char *zone_type)
	Add a new zone with the zonetype to the local authority info of the library. More...

int	ub_ctx_zone_remove (struct ub_ctx ctx, const char zone_name)
	Remove zone from local authority info of the library. More...

int	ub_ctx_data_add (struct ub_ctx ctx, const char data)
	Add localdata to the library local authority info. More...

int	ub_ctx_data_remove (struct ub_ctx ctx, const char data)
	Remove localdata from the library local authority info. More...

const char *	ub_version (void)
	Get a version string from the libunbound implementation. More...

int	ub_ctx_set_event (struct ub_ctx ctx, struct event_base base)
	Set a new libevent event_base on a context created with ub_ctx_create_event. More...

Variables
int	ctx_logfile_overridden = 0
	store that the logfile has a debug override

Detailed Description

This file contains functions to resolve DNS queries and validate the answers.

Synchronously and asynchronously.

Function Documentation

◆ ub_ctx_create()

struct ub_ctx* ub_ctx_create ( void )

Create a resolving and validation context.

The information from /etc/resolv.conf and /etc/hosts is not utilised by default. Use ub_ctx_resolvconf and ub_ctx_hosts to read them.

Returns: a new context. default initialisation. returns NULL on error.

References module_env::cfg, config_delete(), edns_known_options_delete(), module_env::edns_strings, edns_strings_delete(), ub_ctx::env, listen_desetup_locks(), ub_ctx::mods, modstack_call_deinit(), modstack_call_destartup(), modstack_free(), ub_ctx::qq_pipe, ub_ctx::rr_pipe, ub_ctx::seed_rnd, tube_create(), tube_delete(), ub_ctx_create_nopipe(), and ub_randfree().

Referenced by create_unbound_context(), do_update(), and main().

◆ ub_ctx_create_ub_event()

struct ub_ctx* ub_ctx_create_ub_event ( struct ub_event_base * base )

Create a resolving and validation context.

The information from /etc/resolv.conf and /etc/hosts is not utilised by default. Use ub_ctx_resolvconf and ub_ctx_hosts to read them.

Parameters

base	the pluggable event base that the caller has created. The unbound context uses this event base.

Returns: a new context. default initialisation. returns NULL on error. You must use ub_resolve_event with this context. Do not call ub_ctx_async, ub_poll, ub_wait, ub_process, this is all done with the event_base. Setup the options you like with the other functions.

References ub_ctx::created_bg, ub_ctx::dothread, ub_ctx::event_base, and ub_ctx_create_nopipe().

◆ ub_ctx_create_event()

struct ub_ctx* ub_ctx_create_event ( struct event_base * base )

Create a resolving and validation context.

The information from /etc/resolv.conf and /etc/hosts is not utilised by default. Use ub_ctx_resolvconf and ub_ctx_hosts to read them. You have to use the same libevent that unbound was compiled with, otherwise it wouldn't work, the event and event_base structures would be different.

Parameters

base	the event base that the caller has created. The unbound context uses this event base.

Returns: a new context. default initialisation. returns NULL on error. You must use ub_resolve_event with this context. Do not call ub_ctx_async, ub_poll, ub_wait, ub_process, this is all done with the event_base. Setup the options you like with the other functions.

References ub_ctx::created_bg, ub_ctx::dothread, ub_ctx::event_base, ub_ctx::event_base_malloced, ub_ctx_create_nopipe(), ub_ctx_delete(), and ub_libevent_event_base().

◆ ub_ctx_delete()

void ub_ctx_delete ( struct ub_ctx * ctx )

Destroy a validation context and free all its resources.

Outstanding async queries are killed and callbacks are not called for them.

Parameters

ctx	context to delete.

References ub_ctx::bg_tid, ub_ctx::created_bg, do_stop(), ub_ctx::dothread, comm_point::event_added, tube::listen_com, ub_ctx::pipe_pid, ub_ctx::qq_pipe, tube::res_com, ub_ctx::rr_pipe, ub_ctx::thread_worker, and ub_stop_bg().

Referenced by add_5011_probe_root(), do_update(), ext_test(), lookup(), main(), resolve_host_ip(), resolve_name(), and ub_ctx_create_event().

◆ ub_ctx_set_option()

int ub_ctx_set_option	(	struct ub_ctx *	ctx,
		const char *	opt,
		const char *	val
	)

Set an option for the context.

Parameters

ctx	context.
opt	option name from the unbound.conf config file format. (not all settings applicable). The name includes the trailing ':' for example ub_ctx_set_option(ctx, "logfile:", "mylog.txt"); This is a power-users interface that lets you specify all sorts of options. For some specific options, such as adding trust anchors, special routines exist.
val	value of the option.

Returns: : 0 if OK, else error.

References module_env::cfg, ub_ctx::cfglock, config_set_option(), ub_ctx::env, ub_ctx::finalized, UB_AFTERFINAL, UB_NOERROR, and UB_SYNTAX.

Referenced by add_5011_probe_root(), create_unbound_context(), and main().

◆ ub_ctx_get_option()

int ub_ctx_get_option	(	struct ub_ctx *	ctx,
		const char *	opt,
		char **	str
	)

Get an option from the context.

Parameters

ctx	context.
opt	option name from the unbound.conf config file format. (not all settings applicable). The name excludes the trailing ':' for example ub_ctx_get_option(ctx, "logfile", &result); This is a power-users interface that lets you specify all sorts of options.
str	the string is malloced and returned here. NULL on error. The caller must free() the string. In cases with multiple entries (auto-trust-anchor-file), a newline delimited list is returned in the string.

Returns: 0 if OK else an error code (malloc failure, syntax error).

Referenced by main().

◆ ub_ctx_config()

int ub_ctx_config	(	struct ub_ctx *	ctx,
		const char *	fname
	)

setup configuration for the given context.

Parameters

ctx	context.
fname	unbound config file (not all settings applicable). This is a power-users interface that lets you specify all sorts of options. For some specific options, such as adding trust anchors, special routines exist.

Returns: : 0 if OK, else error.

References module_env::cfg, ub_ctx::cfglock, config_read(), ub_ctx::env, ub_ctx::finalized, UB_AFTERFINAL, UB_NOERROR, and UB_SYNTAX.

Referenced by create_unbound_context(), and main().

◆ ub_ctx_add_ta()

int ub_ctx_add_ta	(	struct ub_ctx *	ctx,
		const char *	ta
	)

Add a trust anchor to the given context.

The trust anchor is a string, on one line, that holds a valid DNSKEY or DS RR.

Parameters

ctx	context. At this time it is only possible to add trusted keys before the first resolve is done.
ta	string, with zone-format RR on one line. [domainname] [TTL optional] [type] [class optional] [rdata contents]

Returns: 0 if OK, else error.

References module_env::cfg, cfg_strlist_insert(), ub_ctx::cfglock, ub_ctx::env, ub_ctx::finalized, config_file::trust_anchor_list, UB_AFTERFINAL, UB_NOERROR, and UB_NOMEM.

Referenced by main().

◆ ub_ctx_add_ta_file()

int ub_ctx_add_ta_file	(	struct ub_ctx *	ctx,
		const char *	fname
	)

Add trust anchors to the given context.

Pass name of a file with DS and DNSKEY records (like from dig or drill).

Parameters

ctx	context. At this time it is only possible to add trusted keys before the first resolve is done.
fname	filename of file with keyfile with trust anchors.

Returns: 0 if OK, else error.

References module_env::cfg, cfg_strlist_insert(), ub_ctx::cfglock, ub_ctx::env, ub_ctx::finalized, config_file::trust_anchor_file_list, UB_AFTERFINAL, UB_NOERROR, and UB_NOMEM.

Referenced by do_update(), and main().

◆ ub_ctx_add_ta_autr()

int ub_ctx_add_ta_autr	(	struct ub_ctx *	ctx,
		const char *	fname
	)

Add trust anchor to the given context that is tracked with RFC5011 automated trust anchor maintenance.

The file is written to when the trust anchor is changed. Pass the name of a file that was output from eg. unbound-anchor, or you can start it by providing a trusted DNSKEY or DS record on one line in the file.

Parameters

ctx	context. At this time it is only possible to add trusted keys before the first resolve is done.
fname	filename of file with trust anchor.

Returns: 0 if OK, else error.

References config_file::auto_trust_anchor_file_list, module_env::cfg, cfg_strlist_insert(), ub_ctx::cfglock, ub_ctx::env, ub_ctx::finalized, UB_AFTERFINAL, UB_NOERROR, and UB_NOMEM.

◆ ub_ctx_trustedkeys()

int ub_ctx_trustedkeys	(	struct ub_ctx *	ctx,
		const char *	fname
	)

Add trust anchors to the given context.

Pass the name of a bind-style config file with trusted-keys{}.

Parameters

ctx	context. At this time it is only possible to add trusted keys before the first resolve is done.
fname	filename of file with bind-style config entries with trust anchors.

Returns: 0 if OK, else error.

References module_env::cfg, cfg_strlist_insert(), ub_ctx::cfglock, ub_ctx::env, ub_ctx::finalized, config_file::trusted_keys_file_list, UB_AFTERFINAL, UB_NOERROR, and UB_NOMEM.

Referenced by main().

◆ ub_ctx_debuglevel()

int ub_ctx_debuglevel	(	struct ub_ctx *	ctx,
		int	d
	)

Set debug verbosity for the context Output is directed to stderr.

Parameters

ctx	context.
d	debug level, 0 is off, 1 is very minimal, 2 is detailed, and 3 is lots.

Returns: 0 if OK, else error.

References module_env::cfg, ub_ctx::cfglock, ub_ctx::env, UB_NOERROR, config_file::verbosity, and verbosity.

Referenced by main().

◆ ub_ctx_debugout()

int ub_ctx_debugout	(	struct ub_ctx *	ctx,
		void *	out
	)

Set debug output (and error output) to the specified stream.

Pass NULL to disable. Default is stderr.

Parameters

ctx	context.
out	FILE* out file stream to log to. Type void* to avoid stdio dependency of this header file.

Returns: 0 if OK, else error.

References ub_ctx::cfglock, ctx_logfile_overridden, log_file(), ub_ctx::log_out, ub_ctx::logfile_override, and UB_NOERROR.

◆ ub_ctx_async()

int ub_ctx_async	(	struct ub_ctx *	ctx,
		int	dothread
	)

Set a context behaviour for asynchronous action.

Parameters

ctx	context.
dothread	if true, enables threading and a call to 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 async() calls have been made have no effect (delete and re-create the context to change).

Returns: 0 if OK, else error.

References ub_ctx::cfglock, ub_ctx::dothread, ub_ctx::finalized, UB_AFTERFINAL, and UB_NOERROR.

Referenced by main().

◆ ub_poll()

int ub_poll ( struct ub_ctx * ctx )

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.

Parameters

ctx context.

Returns: : 0 if nothing to read, or nonzero if a result is available. If nonzero, call ctx_process() to do callbacks.

References ub_ctx::rr_pipe, and tube_poll().

◆ ub_fd()

int ub_fd ( struct ub_ctx * ctx )

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. This routine works immediately after context creation, the fd does not change.

Parameters

ctx context.

Returns: : -1 on error, or file descriptor to use select(2) with.

References ub_ctx::rr_pipe, and tube_read_fd().

◆ ub_process()

int ub_process ( struct ub_ctx * ctx )

Call this routine to continue processing results from the validating resolver (when the fd becomes readable).

Will perform necessary callbacks.

Parameters

ctx context

Returns: : 0 if OK, else error.

References ub_result::len, process_answer(), ub_ctx::rr_pipe, ub_ctx::rrpipe_lock, tube_read_msg(), UB_NOERROR, and UB_PIPE.

Referenced by main().

◆ ub_wait()

int ub_wait ( struct ub_ctx * ctx )

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.

Parameters

ctx context.

Returns: : 0 if OK, else error.

References ub_ctx::cfglock, ub_result::len, ub_ctx::num_async, process_answer_detail(), ub_ctx::rr_pipe, ub_ctx::rrpipe_lock, tube_read_msg(), tube_wait(), UB_NOERROR, and UB_PIPE.

Referenced by ext_thread().

◆ ub_resolve()

int ub_resolve	(	struct ub_ctx *	ctx,
		const char *	name,
		int	rrtype,
		int	rrclass,
		struct ub_result **	result
	)

Perform resolution and validation of the target name.

Parameters

ctx	context. The context is finalized, and can no longer accept config changes.
name	domain name in text format (a zero terminated text string).
rrtype	type of RR in host order, 1 is A (address).
rrclass	class of RR in host order, 1 is IN (for internet).
result	the result data is returned in a newly allocated result structure. May be NULL on return, return value is set to an error in that case (out of memory).

Returns: 0 if OK, else error.

References ub_result::answer_len, ub_result::answer_packet, ub_ctx::cfglock, context_finalize(), context_new(), context_query_delete(), ub_ctx::finalized, rbnode_type::key, libworker_fg(), ctx_query::msg, ctx_query::msg_len, ctx_query::node, ub_ctx::queries, rbtree_delete(), ctx_query::res, UB_NOERROR, and UB_NOMEM.

Referenced by dnslook(), do_lookup(), ext_thread(), main(), prime_root_key(), and resolve_host_ip().

◆ ub_resolve_event()

int ub_resolve_event	(	struct ub_ctx *	ctx,
		const char *	name,
		int	rrtype,
		int	rrclass,
		void *	mydata,
		ub_event_callback_type	callback,
		int *	async_id
	)

Perform resolution and validation of the target name.

Asynchronous, after a while, the callback will be called with your data and the result. Uses the event_base user installed by creating the context with ub_ctx_create_event().

Parameters

ctx	context with event_base in it. The context is finalized, and can no longer accept all config changes.
name	domain name in text format (a string).
rrtype	type of RR in host order, 1 is A.
rrclass	class of RR in host order, 1 is IN (for internet).
mydata	this data is your own data (you can pass NULL), and is passed on to the callback function.
callback	this is called on completion of the resolution. It is called as: void callback(void* mydata, int rcode, void* packet, int packet_len, int sec, char* why_bogus, int was_ratelimited) with mydata: the same as passed here, you may pass NULL, with rcode: 0 on no error, nonzero for mostly SERVFAIL situations, this is a DNS rcode. with packet: a buffer with DNS wireformat packet with the answer. do not inspect if rcode != 0. do not write or free the packet buffer, it is used internally in unbound (for other callbacks that want the same data). with packet_len: length in bytes of the packet buffer. with sec: 0 if insecure, 1 if bogus, 2 if DNSSEC secure. with why_bogus: text string explaining why it is bogus (or NULL). with was_ratelimited: if the query was ratelimited. These point to buffers inside unbound; do not deallocate the packet or error string.

If an error happens during processing, your callback will be called with error set to a nonzero value (and result==NULL). For localdata (etc/hosts) the callback is called immediately, before resolve_event returns, async_id=0 is returned.

Parameters

async_id if you pass a non-NULL value, an identifier number is returned for the query as it is in progress. It can be used to cancel the query.

Returns: 0 if OK, else error.

◆ ub_resolve_async()

int ub_resolve_async	(	struct ub_ctx *	ctx,
		const char *	name,
		int	rrtype,
		int	rrclass,
		void *	mydata,
		ub_callback_type	callback,
		int *	async_id
	)

Perform resolution and validation of the target name.

Asynchronous, after a while, the callback will be called with your data and the result.

Parameters

ctx	context. If no thread or process has been created yet to perform the work in the background, it is created now. The context is finalized, and can no longer accept config changes.
name	domain name in text format (a string).
rrtype	type of RR in host order, 1 is A.
rrclass	class of RR in host order, 1 is IN (for internet).
mydata	this data is your own data (you can pass NULL), and is passed on to the callback function.
callback	this is called on completion of the resolution. It is called as: void callback(void* mydata, int err, struct ub_result* result) with mydata: the same as passed here, you may pass NULL, with err: is 0 when a result has been found. with result: a newly allocated result structure. The result may be NULL, in that case err is set.

If an error happens during processing, your callback will be called with error set to a nonzero value (and result==NULL).

Parameters

async_id if you pass a non-NULL value, an identifier number is returned for the query as it is in progress. It can be used to cancel the query.

Returns: 0 if OK, else error.

References ub_ctx::cfglock, context_finalize(), context_new(), context_query_delete(), context_serialize_new_query(), ub_ctx::created_bg, ub_ctx::finalized, rbnode_type::key, libworker_bg(), ctx_query::msg, ctx_query::node, ub_ctx::num_async, ub_ctx::qq_pipe, ub_ctx::qqpipe_lock, ub_ctx::queries, ctx_query::querynum, rbtree_delete(), tube_write_msg(), UB_NOERROR, UB_NOMEM, and UB_PIPE.

Referenced by ext_thread(), and main().

◆ ub_cancel()

int ub_cancel	(	struct ub_ctx *	ctx,
		int	async_id
	)

Cancel an async query in progress.

Its callback will not be called.

Parameters

ctx	context.
async_id	which query to cancel.

Returns: 0 if OK, else error. This routine can return an error if the async_id passed does not exist or has already been delivered. If another thread is processing results at the same time, the result may be delivered at the same time and the cancel fails with an error. Also the cancel can fail due to a system error, no memory or socket failures.

References ctx_query::async, ctx_query::cancelled, ub_ctx::cfglock, context_query_delete(), context_serialize_cancel(), ub_ctx::dothread, rbnode_type::key, log_assert, ctx_query::msg, ctx_query::node, ub_ctx::num_async, ub_ctx::qq_pipe, ub_ctx::qqpipe_lock, ub_ctx::queries, rbtree_delete(), rbtree_search(), tube_write_msg(), UB_NOERROR, UB_NOID, UB_NOMEM, and UB_PIPE.

Referenced by ext_thread(), and main().

◆ ub_resolve_free()

void ub_resolve_free ( struct ub_result * result )

Free storage associated with a result structure.

Parameters

result to free

References ub_result::answer_packet, ub_result::canonname, ub_result::data, ub_result::len, ub_result::qname, and ub_result::why_bogus.

Referenced by context_query_delete(), dnslook(), do_update(), ext_callback(), ext_thread(), main(), process_answer_detail(), and resolve_host_ip().

◆ ub_strerror()

const char* ub_strerror ( int err )

Convert error value to a human readable string.

Parameters

err	error code from one of the libunbound functions. The error codes are from the type enum ub_ctx_err.

Returns: pointer to constant text string, zero terminated.

References UB_AFTERFINAL, UB_FORKFAIL, UB_INITFAIL, UB_NOERROR, UB_NOID, UB_NOMEM, UB_PIPE, UB_READFILE, UB_SERVFAIL, UB_SOCKET, and UB_SYNTAX.

Referenced by add_5011_probe_root(), check_ub_res(), checkerr(), create_unbound_context(), dnslook(), do_update(), main(), print_result(), and resolve_host_ip().

◆ ub_ctx_set_fwd()

int ub_ctx_set_fwd	(	struct ub_ctx *	ctx,
		const char *	addr
	)

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.

To read the list of nameservers from /etc/resolv.conf (from DHCP or so), use the call ub_ctx_resolvconf.

Parameters

ctx	context. At this time it is only possible to set configuration before the first resolve is done.
addr	address, IP4 or IP6 in string format. If the addr is NULL, forwarding is disabled.

Returns: 0 if OK, else error.

References config_stub::addrs, module_env::cfg, cfg_strlist_insert(), ub_ctx::cfglock, config_delstubs(), ub_ctx::env, extstrtoaddr(), ub_ctx::finalized, config_file::forwards, log_assert, config_stub::name, config_stub::next, UB_AFTERFINAL, UB_NOERROR, UB_NOMEM, and UB_SYNTAX.

Referenced by main(), and ub_ctx_resolvconf().

◆ ub_ctx_set_tls()

int ub_ctx_set_tls	(	struct ub_ctx *	ctx,
		int	tls
	)

Use DNS over TLS to send queries to machines set with ub_ctx_set_fwd().

Parameters

ctx	context. At this time it is only possible to set configuration before the first resolve is done.
tls	enable or disable DNS over TLS

Returns: 0 if OK, else error.

References module_env::cfg, ub_ctx::cfglock, ub_ctx::env, ub_ctx::finalized, config_file::ssl_upstream, UB_AFTERFINAL, and UB_NOERROR.

◆ ub_ctx_set_stub()

int ub_ctx_set_stub	(	struct ub_ctx *	ctx,
		const char *	zone,
		const char *	addr,
		int	isprime
	)

Add a stub zone, with given address to send to.

This is for custom root hints or pointing to a local authoritative dns server. For dns resolvers and the 'DHCP DNS' ip address, use ub_ctx_set_fwd. This is similar to a stub-zone entry in unbound.conf.

Parameters

ctx	context. It is only possible to set configuration before the first resolve is done.
zone	name of the zone, string.
addr	address, IP4 or IP6 in string format. The addr is added to the list of stub-addresses if the entry exists. If the addr is NULL the stub entry is removed.
isprime	set to true to set stub-prime to yes for the stub. For local authoritative servers, people usually set it to false, For root hints it should be set to true.

Returns: 0 if OK, else error.

References config_stub::addrs, module_env::cfg, cfg_strlist_insert(), cfg_stub_find(), ub_ctx::cfglock, config_delstub(), ub_ctx::env, extstrtoaddr(), ub_ctx::finalized, config_stub::isprime, config_stub::name, config_stub::next, parse_dname(), config_file::stubs, UB_AFTERFINAL, UB_NOERROR, UB_NOMEM, and UB_SYNTAX.

◆ ub_ctx_resolvconf()

int ub_ctx_resolvconf	(	struct ub_ctx *	ctx,
		const char *	fname
	)

Read list of nameservers to use from the filename given.

Usually "/etc/resolv.conf". Uses those nameservers as caching proxies. If they do not support DNSSEC, validation may fail.

Only nameservers are picked up, the searchdomain, ndots and other settings from resolv.conf(5) are ignored.

Parameters

ctx	context. At this time it is only possible to set configuration before the first resolve is done.
fname	file name string. If NULL "/etc/resolv.conf" is used.

Returns: 0 if OK, else error.

References ub_ctx_set_fwd(), UB_NOERROR, and UB_READFILE.

Referenced by create_unbound_context(), and main().

◆ ub_ctx_hosts()

int ub_ctx_hosts	(	struct ub_ctx *	ctx,
		const char *	fname
	)

Read list of hosts from the filename given.

Usually "/etc/hosts". These addresses are not flagged as DNSSEC secure when queried for.

Parameters

ctx	context. At this time it is only possible to set configuration before the first resolve is done.
fname	file name string. If NULL "/etc/hosts" is used.

Returns: 0 if OK, else error.

References module_env::cfg, cfg_strlist_insert(), ub_ctx::cfglock, ub_ctx::env, ub_ctx::finalized, config_file::local_data, config_stub::name, str_is_ip6(), UB_AFTERFINAL, UB_NOERROR, UB_NOMEM, UB_READFILE, and UB_SYNTAX.

Referenced by main().

◆ ub_ctx_print_local_zones()

int ub_ctx_print_local_zones ( struct ub_ctx * ctx )

Debug routine.

Print the local zone information to debug output.

Parameters

ctx	context. Is finalized by the routine.

Returns: 0 if OK, else error.

References ub_ctx::local_zones, local_zones_print(), ub_ctx_finalize(), and UB_NOERROR.

◆ ub_ctx_zone_add()

int ub_ctx_zone_add	(	struct ub_ctx *	ctx,
		const char *	zone_name,
		const char *	zone_type
	)

Add a new zone with the zonetype to the local authority info of the library.

Parameters

ctx	context. Is finalized by the routine.
zone_name	name of the zone in text, "example.com" If it already exists, the type is updated.
zone_type	type of the zone (like for unbound.conf) in text.

Returns: 0 if OK, else error.

References LDNS_RR_CLASS_IN, local_zone_str2type(), ub_ctx::local_zones, local_zones_add_zone(), local_zones_find(), local_zones::lock, local_zone::lock, parse_dname(), local_zone::type, ub_ctx_finalize(), UB_NOERROR, UB_NOMEM, and UB_SYNTAX.

◆ ub_ctx_zone_remove()

int ub_ctx_zone_remove	(	struct ub_ctx *	ctx,
		const char *	zone_name
	)

Remove zone from local authority info of the library.

Parameters

ctx	context. Is finalized by the routine.
zone_name	name of the zone in text, "example.com" If it does not exist, nothing happens.

Returns: 0 if OK, else error.

References LDNS_RR_CLASS_IN, ub_ctx::local_zones, local_zones_del_zone(), local_zones_find(), local_zones::lock, parse_dname(), ub_ctx_finalize(), UB_NOERROR, and UB_SYNTAX.

◆ ub_ctx_data_add()

int ub_ctx_data_add	(	struct ub_ctx *	ctx,
		const char *	data
	)

Add localdata to the library local authority info.

Similar to local-data config statement.

Parameters

ctx	context. Is finalized by the routine.
data	the resource record in text format, for example "www.example.com IN A 127.0.0.1"

Returns: 0 if OK, else error.

References local_zone::data, ub_ctx::local_zones, local_zones_add_RR(), ub_ctx_finalize(), UB_NOERROR, and UB_NOMEM.

◆ ub_ctx_data_remove()

int ub_ctx_data_remove	(	struct ub_ctx *	ctx,
		const char *	data
	)

Remove localdata from the library local authority info.

Parameters

ctx	context. Is finalized by the routine.
data	the name to delete all data from, like "www.example.com".

Returns: 0 if OK, else error.

References local_zone::data, LDNS_RR_CLASS_IN, ub_ctx::local_zones, local_zones_del_data(), parse_dname(), ub_ctx_finalize(), UB_NOERROR, and UB_SYNTAX.

◆ ub_version()

const char* ub_version ( void )

Get a version string from the libunbound implementation.

Returns: a static constant string with the version number.

◆ ub_ctx_set_event()

int ub_ctx_set_event	(	struct ub_ctx *	ctx,
		struct event_base *	base
	)

Set a new libevent event_base on a context created with ub_ctx_create_event.

You have to use the same libevent that unbound was compiled with, otherwise it wouldn't work, the event and event_base structures would be different. Any outbound queries will be canceled.

Parameters

ctx	the ub_ctx to update. Must have been created with ub_ctx_create_event
base	the new event_base to attach to the ctx

Returns: 0 if OK, else error

References ub_ctx::cfglock, ub_ctx::created_bg, ub_ctx::dothread, ub_ctx::event_base, ub_ctx::event_worker, libworker_delete_event(), UB_INITFAIL, ub_libevent_event_base(), ub_libevent_get_event_base(), and UB_NOERROR.

Functions

Variables

Detailed Description

Function Documentation

◆ ub_ctx_create()

◆ ub_ctx_create_ub_event()

◆ ub_ctx_create_event()

◆ ub_ctx_delete()

◆ ub_ctx_set_option()

◆ ub_ctx_get_option()

◆ ub_ctx_config()

◆ ub_ctx_add_ta()

◆ ub_ctx_add_ta_file()

◆ ub_ctx_add_ta_autr()

◆ ub_ctx_trustedkeys()

◆ ub_ctx_debuglevel()

◆ ub_ctx_debugout()

◆ ub_ctx_async()

◆ ub_poll()

◆ ub_fd()

◆ ub_process()

◆ ub_wait()

◆ ub_resolve()

◆ ub_resolve_event()

◆ ub_resolve_async()

◆ ub_cancel()

◆ ub_resolve_free()

◆ ub_strerror()

◆ ub_ctx_set_fwd()

◆ ub_ctx_set_tls()

◆ ub_ctx_set_stub()

◆ ub_ctx_resolvconf()

◆ ub_ctx_hosts()

◆ ub_ctx_print_local_zones()

◆ ub_ctx_zone_add()

◆ ub_ctx_zone_remove()

◆ ub_ctx_data_add()

◆ ub_ctx_data_remove()

◆ ub_version()

◆ ub_ctx_set_event()