- use_dns_cache can be enabled/disabled runtime
[sip-router] / doc / dns.txt
1 # $Id$
2 #
3 # History:
4 # --------
5 # 2006-09-08  created by andrei
6 # 2007-06-18  added naptr & friends, dns_srv_lb, more compile options (andrei)
7 #
8
9 Overview
10
11  The dns subsystem in ser can either directly use libresolv and a combination
12   of the locally configured dns server, /etc/hosts and the local Network 
13   Information Service (NIS/YP a.s.o) or cache the query results (both positive
14   and negative) and look first in its internal cache.
15  When its internal dns cache is enabled, ser can also use dns failover: if
16   one destination resolves to multiple addresses ser can try all of them until
17   it finds one to which it can successfully send the packet or it exhausts all 
18   of them. ser (tm to be more precise) uses the dns failover also when the
19   destination host doesn't send any reply to a forwarded invite within the
20   sip timeout interval (whose value can be configured using the tm fr_timer
21    parameter).
22  When SRV based load balancing is enabled ser can even do DNS based load 
23  balancing (see RFC2782 and the dns_srv_lb option below).
24
25
26 DNS Cache and Failover Drawbacks
27
28  Using the dns cache and the dns failover has also some drawbacks: 
29
30   1. only the locally configured dns server (usually in /etc/resolv.conf) is
31   used for the requests (/etc/hosts and the local Network Information Service
32   are ignored). 
33      Workaround: disable the dns cache (use_dns_cache=off or
34   compile without -DUSE_DNS_CACHE).
35
36   2. the dns cache uses extra memory
37       Workaround: disable the dns cache.
38
39   3. the dns failover introduces a very small performance penalty 
40      Workaround: disable the dns failover (use_dns_failover=off).
41
42   4. the dns failover increases the memory usage (the internal structures
43   used to represent the transaction are bigger when the dns failover support is
44   compiled).
45      Workaround: compile without dns failover support (-DUSE_DNS_FAILOVER).
46   Turning it off from the config file is not enough in this case (the extra
47    memory will still be used).
48  
49  On the other hand using the dns cache saves lots of DNS queries and makes
50  DNS based failover and DNS based load balancing possible. If the destination
51  blacklist is enabled, ser can do failover even if forwarding in stateless 
52  mode.
53  In the ideal case with dns cache enabled ser will do only one query for
54  a NAPTR (if enabled) or SRV lookup and then it will use the results for the
55  record's TTL (for example if all the resulting records have 1 minute TTL,
56   ser won't make another query for this domain for 1 minute). Even negative
57  answers will be cached.
58  Without the dns cache, each NAPTR or SRV lookup will result in at least 2 
59  queries. These queries will happen every time, for each message (even if 
60  all of them go to the same domain).
61
62
63 DNS Resolver Options
64
65  The DNS resolver options control how ser will interact with the external
66  DNS servers. These options (with the dns_try_ipv6 exception) are passed to
67  libresolv and are used each time a dns request is made.
68  The default values are system specific and generally depend on the
69  /etc/resolv.conf content. For servers doing a lot of DNS requests it is
70  highly recommended to change the default values in the ser config file
71   (even if using ser's internal dns cache).
72
73    dns_try_ipv6 = on | off - if on and ser listens on at least one ipv6 socket,
74       ipv6 (AAAA) lookups will be performed if the ipv4 (A) lookups fail. 
75       If off only ipv4 (A) lookups will be used.
76       Default: on if ser is compiled with ipv6 support.
77
78    dns_try_naptr = on | off - if on ser will first try a NAPTR lookup for
79       destinations that don't have the protocol or port specified and 
80       are not simple ip addresses (as described in RFC 3263). This will 
81       introduce a slight performance penalty and will probably cause extra
82       DNS lookups. For example a lookup for a non-existing domain will
83       produce one extra query: NAPTR(domain), SRV(_sip._udp.domain) 
84       and A/AAAA(domain).
85       If the result of a query contains several NAPTR records, ser will select
86       among them according to the RFC2915 and ser preference towards a
87       specific protocol (see dns_udp_pref, dns_tcp_pref and dns_tls_pref 
88       below). For an RFC3263 compliant configuration (choose the remote side
89       preferred protocol if supported), set dns_udp_pref, dns_tcp_pref and
90       dns_tls_pref to the same value (>=0), e.g. 0.
91       Default: off
92
93    dns_udp_pref = number - udp protocol preference when doing NAPTR lookups.
94       This option works together with dns_tcp_pref and dns_tls_pref. If all
95       this options have the same positive value and more NAPTR records are
96       available, ser will select the NAPTR record preferred by the remote side
97       (according to RFC2915). If the values are positive but different, ser
98       will select the NAPTR record whose protocol it prefers the most
99       (the protocol with the highest dns_<proto>_pref number). If there are 
100       several NAPTR records with the same preferred protocol, ser will select
101       among them based on their order and preference (see RFC2915).
102       To completely disable selecting a specific protocol, use  a negative
103       number. For example dns_tcp_pref=-1 will completely disable selection
104       of tcp NAPTR records, even if this will result in the NAPTR lookup
105       failure.
106       Default: dns_udp_pref=3, dns_tcp_pref=2 and dns_tls_pref=1
107       (prefer udp, but if no udp NAPTR record found or no SRV-resolvable 
108       udp NAPTR record found use tcp records and if this fails too use tls)
109
110    dns_tcp_pref = number  (see dns_udp_pref above)
111
112    dns_tls_pref = number (see dns_udp_pref above)
113
114    dns_retr_time = time - time in s before retrying a dns request.
115       Default: system specific, depends also on the/etc/resolv.conf content
116       (usually 5 s).
117
118    dns_retr_no = no. - number of dns retransmissions before giving up.
119       Default: see above (usually 4)
120
121    dns_servers_no = no. - how many dns servers from the ones defined in 
122       /etc/resolv.conf will be used. Default: all of them.
123
124    dns_use_search_list= yes/no - if no, the search list in /etc/resolv.conf
125       will be ignored (=> fewer lookups => gives up faster).
126       Default: yes.
127       HINT: even if you don't have a search list defined, setting this option
128       to "no" will still be "faster", because an empty search list is in 
129       fact search "" (so even if the search list is empty/missing there will
130       still be 2 dns queries, eg. foo+'.' and foo+""+'.')
131
132    dns_search_full_match = yes/no - controls the check of the name part
133       which is found in the answer expanding the searched name before
134       the answer is treated as correct and "link" (fake CNAME record)
135       between the short name (query) and long name (answer) is created
136       which is then stored in dns_cache and reused for next queries.
137       If set to no - no additional check is done.
138       If set to yes - the additional part is checked against the search list.
139
140  The maximum time a dns request can take (before failing) is:
141  (dns_retr_time*dns_retr_no)*(search_list_domains) If dns_try_ipv6 is yes,
142  mutliply it again by 2.
143
144  The option combination that produces the "fastest" dns resolver config
145   (the "faster" in the sense that it gives up the quickest) is:
146
147       dns_try_ipv6=no
148       dns_retr_time=1
149       dns_retr_no=1
150       dns_servers_no=1
151       dns_use_search_list=no
152
153  The recommended dns configuration is to have a "close" dns caching recursive
154  server configured in /etc/resolv.conf, set the dns resolver options in ser's
155  config as in the above example and enable the dns cache (in ser).
156  Pay particular attention to dns_servers_no and dns_use_search_list. It's a
157  good idea to make sure you don't need / use the search list or more then one
158  dns server (to avoid unnecessary extra lookups).
159
160
161 DNS Resolver Compile Options
162
163    USE_NAPTR - if defined the naptr lookup support will be compiled in.
164       NAPTR support still has to be enabled from ser's config file (it's
165       off by default).
166
167    RESOLVE_DBG - if defined, the resolver will be very verbose: it will log
168       a lot of debugging information at L_DBG level.
169
170    NAPTR_DBG - if defined the NAPTR related resolver functions will be very
171        verbose.
172
173
174 DNS Cache and Failover Config Variables
175
176    use_dns_cache = on | off - if off the dns cache won't be used (all dns
177       lookups will result into a dns request).  When on all the dns request
178       results will be cached.
179       WARNING: when enabled /etc/hosts will be completely bypassed, all the dns
180       request will go directly to the system configured (resolv.conf) dns
181       server.
182       Default: on.
183
184    use_dns_failover = on |off - if on and sending a request fails (due to not
185       being allowed from an onsend_route, send failure, blacklisted destination
186       or, when using tm, invite timeout), and the destination resolves to
187       multiple ip addresses and/or multiple SRV records, the send will be
188       re-tried using the next ip/record. In tm's case a new branch will be
189       created for each new send attempt.
190       Default: off.
191    Depends on use_dns_cache being on. If tm is used along with dns failover is
192    recommended to also turn on dst_blacklist.
193
194    dns_srv_lb = on | off or
195    dns_srv_loadbalancing = on | off - if on instead of doing simple dns 
196         failover (like above), ser will load balance requests to different srv
197         records of the same priority based on the srv records weights (like 
198         described in RFC2782). For a destination which has different priorities
199         for all its srv records, this option will be equivalent with simple
200         dns failover.
201         Note: this option requires having dns failover enabled (see 
202         use_dns_failover above).
203         Default: off.
204
205    dns_try_ipv6 = on | off - shared with the resolver (see resolver 
206         description).
207
208    dns_try_naptr = on | off - shared with the resolver (see resolver 
209         description).
210
211    dns_udp_pref =  number - shared with the resolver (see resolver 
212         description).
213
214    dns_tcp_pref =  number - shared with the resolver (see resolver 
215         description).
216
217    dns_tls_pref =  number - shared with the resolver (see resolver 
218         description).
219
220    dns_cache_flags = dns cache specific resolver flags, used for overriding
221      the default behaviour (low level).
222       Possible values:
223          1 - ipv4 only: only DNS A requests are performed, even if ser listens
224                         also on ipv6 addresses.
225          2 - ipv6 only: only DNS AAAA requests are performed. Ignored if
226                         dns_try_ipv6 is off or ser doesn't listen on any ipv6
227                         address.
228          4 - prefer ipv6: try first to resolve a host name to an ipv6 address
229                           (DNS AAAA request) and only if this fails try an ipv4
230                           address (DNS A request).
231                           By default the ipv4 addresses are preferred.
232       Default: 0
233
234    dns_cache_negative_ttl = time to live for negative results ("not found") in
235       seconds. Use 0 to disable.
236       Default: 60 s.
237
238    dns_cache_min_ttl = minimum accepted time to live for a record, in seconds.
239       If a record has a lower ttl, its value will be discarded and
240       dns_cache_min_ttl will be used instead.
241       Default: 0
242
243    dns_cache_max_ttl = maximum accepted time to live for a record, in seconds.
244       If a record has a higher ttl, its value will be discarded and
245       dns_cache_max_ttl will be used instead.
246       Default: MAXINT
247
248    dns_cache_mem = maximum memory used for the dns cache in Kb.
249       Default: 500 Kb
250
251    dns_cache_gc_interval = how often (in s) the dns cache will be garbage 
252       collected.
253       Default:  120 s.
254       
255    dns_cache_del_nonexp = yes | no or
256    dns_cache_delete_nonexpired = yes | no - allow deletion of non-expired
257       records from the cache when there is no more space left for new
258       ones. The last-recently used entries are deleted first.
259       Default: no
260
261    dns_cache_init = on | off - if off, the dns cache is not initialized
262       at startup and cannot be enabled runtime, that saves some memory.
263       Default: on
264
265 DNS Cache Compile Options
266
267    USE_DNS_CACHE - if defined the dns cache support will be compiled in 
268       (default). If not needed/wanted the dns_cache can be disabled from the
269       ser's config file. The only advantages for not compiling the dns cache
270       support is a slight decrease of the executable size and an extremely 
271       small performance increase (1 less comparison per dns request).
272
273    USE_DNS_FAILOVER - if defined the dns failover support will be compiled in.
274       (default). Compiling the dns failover support has a few disadvantages,
275       see the "Drawbacks" section.
276
277    DNS_SRV_LB  - if defined (default) support for load balancing using 
278        srv records weights (as described in RFC2782) will be compiled in.
279        Note however that it still must be enabled from the ser config, it's
280        disabled by default (see the dns_srv_lb config option).
281
282    USE_NAPTR  - (shared with the resolver)  if defined NAPTR support will
283        be compiled in (default). Note that even if compiled, NAPTR support
284        must be enabled also from the ser config (see the dns_try_naptr option).
285
286    NAPTR_CACHE_ALL_ARS - if defined all the additional records in a NAPTR
287        answer will be cached. Normally ser would cache only "related" records
288        (records that are directly referred), but for answers with lots of 
289         A/AAAA records it might happen that not all of the SRV records will fit
290        in the AR section. In this case, without this compile option ser will 
291        not cache the un-referred A/AAAA records. BY default this option is
292        disabled.
293
294    CACHE_RELEVANT_RECS_ONLY - if defined (default), records in the AR section
295        of an answer will be cached only if they are "related" to the query.
296        For example if the query is for a SRV record, A & AAAA records in the
297        AR section will be cached only if there are SRV records pointing to 
298        them. This avoids adding possible garbage to the cache.
299        If this option is not defined (experimental), everything in the AR
300        section will be added to the cache.
301
302    DNS_CACHE_DEBUG - if defined the dns cache will be very verbose (it will
303        log lots of messages at the L_DBG levell).
304  
305  Note: To remove a compile options,  edit ser's Makefile.defs and remove it 
306    form DEFS list. To add a compile options add it to the make command line,
307      e.g.: make proper; make all extra_defs=-DUSE_DNS_FAILOVER
308    or for a permanent solution, edit Makefile.defs and add it to DEFS 
309    (don't foget to prefix it with -D). Some options require editing 
310    dns_cache.c or resolve.[ch] (just grep after them).