iterator.h File Reference

This file contains a module that performs recursive iterative DNS query processing. More...

#include "services/outbound_list.h"
#include "util/data/msgreply.h"
#include "util/module.h"

Data Structures
struct	iter_nat64
	Iterator global state for nat64. More...
struct	iter_env
	Global state for the iterator. More...
struct	iter_qstate
	Per query state for the iterator module. More...
struct	iter_prep_list
	List of prepend items. More...

Macros
#define	MAX_TARGET_COUNT   64
	max number of targets spawned for a query and its subqueries
#define	MAX_DP_TARGET_COUNT   16
	max number of target lookups per qstate, per delegation point
#define	MAX_TARGET_NX   5
	max number of nxdomains allowed for target lookups for a query and its subqueries
#define	MAX_TARGET_NX_FALLBACK   (MAX_TARGET_NX*2)
	max number of nxdomains allowed for target lookups for a query and its subqueries when fallback has kicked in
#define	MAX_REFERRAL_COUNT   130
	max number of referrals.
#define	DNSSEC_LAME_DETECT_COUNT   4
	max number of queries for which to perform dnsseclameness detection, (rrsigs missing detection) after that, just pick up that response
#define	MAX_MINIMISE_COUNT   10
	max number of QNAME minimisation iterations.
#define	MAX_MINIMISE_TIMEOUT_COUNT   3
#define	MINIMISE_ONE_LAB   4
	number of labels from QNAME that are always send individually when using QNAME minimisation, even when the number of labels of the QNAME is bigger than MAX_MINIMISE_COUNT
#define	MINIMISE_MULTIPLE_LABS   (MAX_MINIMISE_COUNT - MINIMISE_ONE_LAB)
#define	TARGET_FETCH_STOP   3
	at what query-sent-count to stop target fetch policy
#define	RTT_BAND   400
	RTT band, within this amount from the best, servers are chosen randomly.
#define	EMPTY_NODATA_RETRY_COUNT   2
	Number of retries for empty nodata packets before it is accepted.

Enumerations
enum	minimisation_state { INIT_MINIMISE_STATE = 0 , MINIMISE_STATE , SKIP_MINIMISE_STATE , DONOT_MINIMISE_STATE }
	QNAME minimisation state. More...
enum	iter_state {   INIT_REQUEST_STATE = 0 , INIT_REQUEST_2_STATE , INIT_REQUEST_3_STATE , QUERYTARGETS_STATE ,   QUERY_RESP_STATE , PRIME_RESP_STATE , COLLECT_CLASS_STATE , DSNS_FIND_STATE ,   FINISHED_STATE }
	State of the iterator for a query. More...
enum	target_count_variables {   TARGET_COUNT_REF = 0 , TARGET_COUNT_QUERIES , TARGET_COUNT_NX , TARGET_COUNT_GLOBAL_QUOTA ,   TARGET_COUNT_MAX }
	Shared counters for queries. More...

Functions
struct module_func_block *	iter_get_funcblock (void)
	Get the iterator function block.
const char *	iter_state_to_string (enum iter_state state)
	Get iterator state as a string.
int	iter_state_is_responsestate (enum iter_state s)
	See if iterator state is a response state.
int	iter_init (struct module_env *env, int id)
	iterator init
void	iter_deinit (struct module_env *env, int id)
	iterator deinit
void	iter_operate (struct module_qstate *qstate, enum module_ev event, int id, struct outbound_entry *outbound)
	iterator operate on a query
void	iter_inform_super (struct module_qstate *qstate, int id, struct module_qstate *super)
	Return priming query results to interested super querystates.
void	iter_clear (struct module_qstate *qstate, int id)
	iterator cleanup query state
size_t	iter_get_mem (struct module_env *env, int id)
	iterator alloc size routine

Variables
int	MAX_GLOBAL_QUOTA
	max number of upstream queries for a query and its subqueries, it is never reset.
int	UNKNOWN_SERVER_NICENESS
	how nice is a server without further information, in msec Equals rtt initial timeout value.
int	USEFUL_SERVER_TOP_TIMEOUT
	maximum timeout before a host is deemed unsuitable, in msec.
int	BLACKLIST_PENALTY
	penalty to validation failed blacklisted IPs Equals USEFUL_SERVER_TOP_TIMEOUT*4, and thus when RTT_MAX_TIMEOUT is overwritten by config infra_cache_max_rtt, it will be overwritten as well.

Detailed Description

This file contains a module that performs recursive iterative DNS query processing.

Macro Definition Documentation

MAX_REFERRAL_COUNT

#define MAX_REFERRAL_COUNT   130

max number of referrals.

Makes sure resolver does not run away

MAX_MINIMISE_COUNT

#define MAX_MINIMISE_COUNT   10

max number of QNAME minimisation iterations.

Limits number of queries for QNAMEs with a lot of labels.

RTT_BAND

#define RTT_BAND   400

RTT band, within this amount from the best, servers are chosen randomly.

Chosen so that the UNKNOWN_SERVER_NICENESS falls within the band of a fast server, this causes server exploration as a side benefit. msec.

Enumeration Type Documentation

minimisation_state

enum minimisation_state

QNAME minimisation state.

Enumerator
INIT_MINIMISE_STATE	(Re)start minimisation. Outgoing QNAME should be set to dp->name. State entered on new query or after following referral or CNAME.
MINIMISE_STATE	QNAME minimisation ongoing. Increase QNAME on every iteration.
SKIP_MINIMISE_STATE	Don't increment QNAME this iteration.
DONOT_MINIMISE_STATE	Send out full QNAME + original QTYPE.

iter_state

enum iter_state

State of the iterator for a query.

Enumerator
INIT_REQUEST_STATE	Externally generated queries start at this state. Query restarts are reset to this state.
INIT_REQUEST_2_STATE	Root priming events reactivate here, most other events pass through this naturally as the 2nd part of the INIT_REQUEST_STATE.
INIT_REQUEST_3_STATE	Stub priming events reactivate here, most other events pass through this naturally as the 3rd part of the INIT_REQUEST_STATE.
QUERYTARGETS_STATE	Each time a delegation point changes for a given query or a query times out and/or wakes up, this state is (re)visited. This state is responsible for iterating through a list of nameserver targets.
QUERY_RESP_STATE	Responses to queries start at this state. This state handles the decision tree associated with handling responses.
PRIME_RESP_STATE	Responses to priming queries finish at this state.
COLLECT_CLASS_STATE	Collecting query class information, for qclass=ANY, when it spawns off queries for every class, it returns here.
DSNS_FIND_STATE	Find NS record to resolve DS record from, walking to the right NS spot until we find it.
FINISHED_STATE	Responses that are to be returned upstream end at this state. As well as responses to target queries.

target_count_variables

enum target_count_variables

Shared counters for queries.

Enumerator
TARGET_COUNT_REF	Reference count for the shared iter_qstate->target_count.
TARGET_COUNT_QUERIES	Number of target queries spawned for the query and subqueries.
TARGET_COUNT_NX	Number of nxdomain responses encountered.
TARGET_COUNT_GLOBAL_QUOTA	Global quota on number of queries to upstream servers per client request, that is never reset.
TARGET_COUNT_MAX	This should stay last here, it is used for the allocation.

Function Documentation

iter_get_funcblock()

struct module_func_block * iter_get_funcblock

(

void

)

Get the iterator function block.

Returns

: function block with function pointers to iterator methods.

References iter_block.

Referenced by checkconf(), and module_funcs_avail().

iter_state_to_string()

const char * iter_state_to_string

(

enum iter_state

state

)

Get iterator state as a string.

Parameters

state

to convert

Returns

constant string that is printable.

References COLLECT_CLASS_STATE, DSNS_FIND_STATE, FINISHED_STATE, INIT_REQUEST_2_STATE, INIT_REQUEST_3_STATE, INIT_REQUEST_STATE, PRIME_RESP_STATE, QUERY_RESP_STATE, and QUERYTARGETS_STATE.

Referenced by iter_handle().

iter_state_is_responsestate()

int iter_state_is_responsestate

(

enum iter_state

s

)

See if iterator state is a response state.

Parameters

s	to inspect

Returns

true if response state.

References COLLECT_CLASS_STATE, INIT_REQUEST_2_STATE, INIT_REQUEST_3_STATE, INIT_REQUEST_STATE, and QUERYTARGETS_STATE.

Referenced by next_state().

iter_inform_super()

void iter_inform_super	(	struct module_qstate *	qstate,
		int	id,
		struct module_qstate *	super
	)

Return priming query results to interested super querystates.

Sets the delegation point and delegation message (not nonRD queries). This is a callback from walk_supers.

Parameters

qstate	query state that finished.
id	module id.
super	the qstate to inform.

References DSNS_FIND_STATE, error_supers(), module_qstate::is_priming, LDNS_RR_CLASS_ANY, LDNS_RR_TYPE_DS, module_qstate::minfo, prime_supers(), processClassResponse(), processDSNSResponse(), processTargetResponse(), query_info::qclass, module_qstate::qinfo, query_info::qtype, and module_qstate::return_rcode.

Referenced by fptr_whitelist_mod_inform_super().

Variable Documentation

USEFUL_SERVER_TOP_TIMEOUT

int USEFUL_SERVER_TOP_TIMEOUT

extern

maximum timeout before a host is deemed unsuitable, in msec.

After host_ttl this will be timed out and the host will be tried again. Equals RTT_MAX_TIMEOUT, and thus when RTT_MAX_TIMEOUT is overwritten by config infra_cache_max_rtt, it will be overwritten as well.

Referenced by config_apply_max_rtt(), dump_infra_host(), infra_get_lame_rtt(), infra_host(), infra_rtt_update(), infra_test(), iter_filter_order(), iter_filter_unsuitable(), iter_server_selection(), print_dp_details(), and still_useful_timeout().