unbound: iterator/iterator.h File Reference

unbound 0.1

Data Structures | Macros | Enumerations | Functions | Variables
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

Referenced by processQueryTargets().

## ◆ 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.

Referenced by processQueryTargets().

## ◆ 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.

Referenced by iter_filter_order(), and still_useful_timeout().

## 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().