2 * iterator/iterator.h - iterative resolver DNS query response module
4 * Copyright (c) 2007, NLnet Labs. All rights reserved.
6 * This software is open source.
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
12 * Redistributions of source code must retain the above copyright notice,
13 * this list of conditions and the following disclaimer.
15 * Redistributions in binary form must reproduce the above copyright notice,
16 * this list of conditions and the following disclaimer in the documentation
17 * and/or other materials provided with the distribution.
19 * Neither the name of the NLNET LABS nor the names of its contributors may
20 * be used to endorse or promote products derived from this software without
21 * specific prior written permission.
23 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
25 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
26 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
27 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
28 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
29 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
30 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
31 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
32 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
33 * POSSIBILITY OF SUCH DAMAGE.
39 * This file contains a module that performs recusive iterative DNS query
43 #ifndef ITERATOR_ITERATOR_H
44 #define ITERATOR_ITERATOR_H
45 #include "services/outbound_list.h"
46 #include "util/data/msgreply.h"
47 #include "util/module.h"
52 struct iter_prep_list;
55 /** max number of query restarts. Determines max number of CNAME chain. */
56 #define MAX_RESTART_COUNT 8
57 /** max number of referrals. Makes sure resolver does not run away */
58 #define MAX_REFERRAL_COUNT 130
59 /** max number of queries-sent-out. Make sure large NS set does not loop */
60 #define MAX_SENT_COUNT 16
61 /** at what query-sent-count to stop target fetch policy */
62 #define TARGET_FETCH_STOP 3
63 /** how nice is a server without further information, in msec
64 * Equals rtt initial timeout value.
66 #define UNKNOWN_SERVER_NICENESS 376
67 /** maximum timeout before a host is deemed unsuitable, in msec.
68 * After host_ttl this will be timed out and the host will be tried again.
69 * Equals RTT_MAX_TIMEOUT
71 #define USEFUL_SERVER_TOP_TIMEOUT 120000
72 /** Number of lost messages in a row that get a host blacklisted.
73 * With 16, a couple different queries have to time out and no working
74 * queries are happening */
75 #define USEFUL_SERVER_MAX_LOST 16
76 /** number of retries on outgoing queries */
77 #define OUTBOUND_MSG_RETRY 5
78 /** RTT band, within this amount from the best, servers are chosen randomly.
79 * Chosen so that the UNKNOWN_SERVER_NICENESS falls within the band of a
80 * fast server, this causes server exploration as a side benefit. msec. */
82 /** Start value for blacklisting a host, 2*USEFUL_SERVER_TOP_TIMEOUT in sec */
83 #define INFRA_BACKOFF_INITIAL 240
86 * Global state for the iterator.
89 /** A flag to indicate whether or not we have an IPv6 route */
92 /** A flag to indicate whether or not we have an IPv4 route */
95 /** A set of inetaddrs that should never be queried. */
96 struct iter_donotq* donotq;
98 /** private address space and private domains */
99 struct iter_priv* priv;
101 /** The maximum dependency depth that this resolver will pursue. */
102 int max_dependency_depth;
105 * The target fetch policy for each dependency level. This is
106 * described as a simple number (per dependency level):
107 * negative numbers (usually just -1) mean fetch-all,
108 * 0 means only fetch on demand, and
109 * positive numbers mean to fetch at most that many targets.
110 * array of max_dependency_depth+1 size.
112 int* target_fetch_policy;
116 * State of the iterator for a query.
120 * Externally generated queries start at this state. Query restarts are
121 * reset to this state.
123 INIT_REQUEST_STATE = 0,
126 * Root priming events reactivate here, most other events pass
127 * through this naturally as the 2nd part of the INIT_REQUEST_STATE.
129 INIT_REQUEST_2_STATE,
132 * Stub priming events reactivate here, most other events pass
133 * through this naturally as the 3rd part of the INIT_REQUEST_STATE.
135 INIT_REQUEST_3_STATE,
138 * Each time a delegation point changes for a given query or a
139 * query times out and/or wakes up, this state is (re)visited.
140 * This state is reponsible for iterating through a list of
141 * nameserver targets.
146 * Responses to queries start at this state. This state handles
147 * the decision tree associated with handling responses.
151 /** Responses to priming queries finish at this state. */
154 /** Collecting query class information, for qclass=ANY, when
155 * it spawns off queries for every class, it returns here. */
158 /** Find NS record to resolve DS record from, walking to the right
159 * NS spot until we find it */
162 /** Responses that are to be returned upstream end at this state.
163 * As well as responses to target queries. */
168 * Per query state for the iterator module.
172 * State of the iterator module.
173 * This is the state that event is in or should sent to -- all
174 * requests should start with the INIT_REQUEST_STATE. All
175 * responses should start with QUERY_RESP_STATE. Subsequent
176 * processing of the event will change this state.
178 enum iter_state state;
181 * Final state for the iterator module.
182 * This is the state that responses should be routed to once the
183 * response is final. For externally initiated queries, this
184 * will be FINISHED_STATE, locally initiated queries will have
185 * different final states.
187 enum iter_state final_state;
190 * The depth of this query, this means the depth of recursion.
191 * This address is needed for another query, which is an address
192 * needed for another query, etc. Original client query has depth 0.
199 struct dns_msg* response;
202 * This is a list of RRsets that must be prepended to the
203 * ANSWER section of a response before being sent upstream.
205 struct iter_prep_list* an_prepend_list;
206 /** Last element of the prepend list */
207 struct iter_prep_list* an_prepend_last;
210 * This is the list of RRsets that must be prepended to the
211 * AUTHORITY section of the response before being sent upstream.
213 struct iter_prep_list* ns_prepend_list;
214 /** Last element of the authority prepend list */
215 struct iter_prep_list* ns_prepend_last;
217 /** query name used for chasing the results. Initially the same as
218 * the state qinfo, but after CNAMEs this will be different.
219 * The query info used to elicit the results needed. */
220 struct query_info qchase;
221 /** query flags to use when chasing the answer (i.e. RD flag) */
222 uint16_t chase_flags;
223 /** true if we set RD bit because of last resort recursion lame query*/
227 * This is the current delegation point for an in-progress query. This
228 * object retains state as to which delegation targets need to be
229 * (sub)queried for vs which ones have already been visited.
233 /** state for 0x20 fallback when capsfail happens, 0 not a fallback */
235 /** state for capsfail: current server number to try */
237 /** state for capsfail: stored query for comparisons */
238 struct reply_info* caps_reply;
240 /** Current delegation message - returned for non-RD queries */
241 struct dns_msg* deleg_msg;
243 /** number of outstanding target sub queries */
244 int num_target_queries;
246 /** outstanding direct queries */
247 int num_current_queries;
249 /** the number of times this query has been restarted. */
250 int query_restart_count;
252 /** the number of times this query as followed a referral. */
255 /** number of queries fired off */
259 * The query must store NS records from referrals as parentside RRs
260 * Enabled once it hits resolution problems, to throttle retries.
261 * If enabled it is the pointer to the old delegation point with
262 * the old retry counts for bad-nameserver-addresses.
264 struct delegpt* store_parent_NS;
267 * The query is for parent-side glue(A or AAAA) for a nameserver.
268 * If the item is seen as glue in a referral, and pside_glue is NULL,
269 * then it is stored in pside_glue for later.
270 * If it was never seen, at the end, then a negative caching element
272 * The (data or negative) RR cache element then throttles retries.
274 int query_for_pside_glue;
275 /** the parent-side-glue element (NULL if none, its first match) */
276 struct ub_packed_rrset_key* pside_glue;
278 /** If nonNULL we are walking upwards from DS query to find NS */
280 /** length of the dname in dsns_point */
281 size_t dsns_point_len;
284 * expected dnssec information for this iteration step.
285 * If dnssec rrsigs are expected and not given, the server is marked
286 * lame (dnssec-lame).
291 * We are expecting dnssec information, but we also know the server
292 * is DNSSEC lame. The response need not be marked dnssec-lame again.
294 int dnssec_lame_query;
297 * This is flag that, if true, means that this event is
298 * waiting for a stub priming query.
300 int wait_priming_stub;
303 * This is a flag that, if true, means that this query is
304 * for (re)fetching glue from a zone. Since the address should
305 * have been glue, query again to the servers that should have
306 * been returning it as glue.
307 * The delegation point must be set to the one that should *not*
308 * be used when creating the state. A higher one will be attempted.
312 /** list of pending queries to authoritative servers. */
313 struct outbound_list outlist;
317 * List of prepend items
319 struct iter_prep_list {
321 struct iter_prep_list* next;
323 struct ub_packed_rrset_key* rrset;
327 * Get the iterator function block.
328 * @return: function block with function pointers to iterator methods.
330 struct module_func_block* iter_get_funcblock(void);
333 * Get iterator state as a string
334 * @param state: to convert
335 * @return constant string that is printable.
337 const char* iter_state_to_string(enum iter_state state);
340 * See if iterator state is a response state
341 * @param s: to inspect
342 * @return true if response state.
344 int iter_state_is_responsestate(enum iter_state s);
347 int iter_init(struct module_env* env, int id);
349 /** iterator deinit */
350 void iter_deinit(struct module_env* env, int id);
352 /** iterator operate on a query */
353 void iter_operate(struct module_qstate* qstate, enum module_ev event, int id,
354 struct outbound_entry* outbound);
357 * Return priming query results to interestes super querystates.
359 * Sets the delegation point and delegation message (not nonRD queries).
360 * This is a callback from walk_supers.
362 * @param qstate: query state that finished.
363 * @param id: module id.
364 * @param super: the qstate to inform.
366 void iter_inform_super(struct module_qstate* qstate, int id,
367 struct module_qstate* super);
369 /** iterator cleanup query state */
370 void iter_clear(struct module_qstate* qstate, int id);
372 /** iterator alloc size routine */
373 size_t iter_get_mem(struct module_env* env, int id);
375 #endif /* ITERATOR_ITERATOR_H */