70827e9236ed58a90b60b656c05cb25ef88a0652
[sip-router] / doc / dns.txt
1 # $Id$
2 #
3 # History:
4 # --------
5 # 2006-09-08  created by andrei
6 #
7
8 Overview
9
10  The dns subsystem in ser can either directly use libresolv and a combination
11   of the locally configured dns server, /etc/hosts and the local Network 
12   Information Service (NIS/YP a.s.o) or cache the query results (both positive
13   and negative) and look first in its internal cache.
14  When its internal dns cache is enabled, ser can also use dns failover: if
15   one destination resolves to multiple addresses ser can try all of them until
16   it finds one to which it can succesfully send the packet or it exhausts all 
17   of them. ser (tm to be more precise) uses the dns failover also when the
18   destination host doesn't send any reply to a forwarded invite within the
19   sip timeout interval (whose value can be configured using the tm fr_timer
20    parameter).
21
22
23 DNS Cache and Failover Drawbacks
24
25  Using the dns cache and the dns failover has also some drawbacks: 
26
27   1. only the locally configured dns server (usually in /etc/resolv.conf) is
28   used for the requests (/etc/hosts and the local Network Information Service
29   are ignored). 
30      Workarround: disable the dns cache (use_dns_cache=off or
31   compile without -DUSE_DNS_CACHE).
32
33   2. the dns cache uses extra memory
34       Workarround: disable the dns cache.
35
36   3. the dns failover introduces a very small performance penalty 
37      Workarround: disable the dns failover (use_dns_failover=off).
38
39   4. the dns failover increases the memory usage (the internal structures
40   used to represent the transaction are bigger when the dns failover support is
41   compiled).
42      Workarround: compile without dns failover support (-DUSE_DNS_FAILOVER).
43   Turning it off from the config file is not enough in this case (the extra
44    memory will still be used).
45
46
47 DNS Resolver Options
48
49  The DNS resolver options control how ser will interact with the external
50  DNS servers. These options (with the dns_try_ipv6 exception) are passed to
51  libresolv and are used each time a dns request is made.
52  The default values are system specific and generally depend on the
53  /etc/resolv.conf content. For servers doing a lot of DNS requests it is
54  highly recommended to change the default values in the ser config file
55   (even if using ser's internal dns cache).
56
57    dns_try_ipv6 = on | off - if on and ser listens on at least one ipv6 socket,
58       ipv6 (AAAA) lookups will be performed if the ipv4 (A) lookups fail. 
59       If off only ipv4 (A) lookups will be used.
60       Default: on if ser is compiled with ipv6 support.
61
62    dns_retr_time = time - time in s before retrying a dns request.
63       Default: system specific, depends also on the/etc/resolv.conf content
64       (usually 5 s).
65
66    dns_retr_no = no. - number of dns retransmissions before giving up.
67       Default: see above (usually 4)
68
69    dns_servers_no = no. - how many dns servers from the ones defined in 
70       /etc/resolv.conf will be used. Default: all of them.
71
72    dns_use_search_list= yes/no - if no, the search list in /etc/resolv.conf
73       will be ignored (=> fewer lookups => gives up faster).
74       Default: yes.
75       HINT: even if you don't have a search list defined, setting this option
76       to "no" will still be "faster", because an empty search list is in 
77       fact search "" (so even if the search list is empty/missing there will
78       still be 2 dns queries, eg. foo+'.' and foo+""+'.')
79
80  The maximum time a dns request can take (before failing) is:
81  (dns_retr_time*dns_retr_no)*(search_list_domains) If dns_try_ipv6 is yes,
82  mutliply it again by 2.
83
84  The option combination that produces the "fastest" dns resolver config
85   (the "faster" in the sense that it gives up the quickest) is:
86
87       dns_try_ipv6=no
88       dns_retr_time=1
89       dns_retr_no=1
90       dns_servers_no=1
91       dns_use_search_list=no
92
93  The recommended dns configuration is to have a "close" dns caching recursive
94  server configured in /etc/resolv.conf, set the dns resolver options in ser's
95  config as in the above example and enable the dns cache (in ser).
96  Pay particular attention to dns_servers_no and dns_use_search_list. It's a
97  good ideea to make sure you don't need / use the search list or more then one
98  dns server (to avoid unnecessary extra lookups).
99
100
101 DNS Cache and Failover Config Variables
102
103    use_dns_cache = on | off - if off the dns cache won't be used (all dns
104       lookups will result into a dns request).  When on all the dns request
105       results will be cached.
106       WARNING: when enabled /etc/hosts will be completely bypassed, all the dns
107       request will go directly to the system configured (resolv.conf) dns
108       server.
109       Default: on.
110
111    use_dns_failover = on |off - if on and sending a request fails (due to not
112       being allowed from an onsend_route, send failure, blacklisted destination
113       or, when using tm, invite timeout), and the destination resolves to
114       multiple ip addresses and/or multiple SRV records, the send will be
115       re-tried using the next ip/record. In tm's case a new branch will be
116       created for each new send attempt.
117       Default: off.
118    Depends on use_dns_cache being on. If tm is used along with dns failover is
119    recommended to also turn on dst_blacklist.
120
121    dns_cache_flags = dns cache specific resolver flags, used for overriding
122      the default behaviour (low level).
123       Possible values:
124          1 - ipv4 only: only DNS A requests are performed, even if ser listens
125                         also on ipv6 addresses.
126          2 - ipv6 only: only DNS AAAA requests are performed. Ignored if
127                         dns_try_ipv6 is off or ser doesn't listen on any ipv6
128                         address.
129          4 - prefer ipv6: try first to resolve a host name to an ipv6 address
130                           (DNS AAAA request) and only if this fails try an ipv4
131                           address (DNS A request).
132                           By default the ipv4 addresses are preferred.
133       Default: 0
134
135    dns_cache_negative_ttl = time to live for negative results ("not found") in
136       seconds. Use 0 to disable.
137       Default: 60 s.
138
139    dns_cache_min_ttl = minimum accepted time to live for a record, in seconds.
140       If a record has a lower ttl, its value will be discarded and
141       dns_cache_min_ttl will be used instead.
142       Default: 0
143
144    dns_cache_max_ttl = maximum accepted time to live for a record, in seconds.
145       If a record has a higher ttl, its value will be discarded and
146       dns_cache_max_ttl will be used instead.
147       Default: MAXINT
148
149    dns_cache_mem = maximum memory used for the dns cache in Kb.
150       Default: 500 Kb
151
152    dns_cache_gc_interval = how often (in s) the dns cache will be garbage 
153       collected.
154       Default:  120 s.
155
156
157 DNS Cache Compile Options
158
159    USE_DNS_CACHE - if defined the dns cache support will be compiled in 
160       (default). If not needed/wanted the dns_cache can be disabled from the
161       ser's config file. The only advantages for not compiling the dns cache
162       support is a slight decrease of the executable size and an extremely 
163       small performance increase (1 less comparison per dns request).
164
165    USE_DNS_FAILOVER - if defined the dns failover support will be compiled in.
166       (default). Compiling the dns failover support has a few disadvantages,
167       see the "Drawbacks" section.
168  
169  Note: To remove a compile options,  edit ser's Makefile.defs and remove it 
170    form DEFS list. To add a compile options add it to the make command line,
171      e.g.: make proper; make all extra_defs=-DUSE_DNS_FAILOVER
172    or for a permanent solution, edit Makefile.defs and add it to DEFS 
173    (don't foget to prefix it with -D).