Browse code

doc: updated references to block lists

Daniel-Constantin Mierla authored on 30/10/2020 12:52:06
Showing 1 changed files
... ...
@@ -44,7 +44,7 @@ DNS Cache and Failover Drawbacks
44 44
  
45 45
  On the other hand using the DNS cache saves lots of DNS queries and makes
46 46
  DNS based failover and DNS based load balancing possible. If the destination
47
- blacklist is enabled, Kamailio can do failover even if forwarding in stateless 
47
+ blocklist is enabled, Kamailio can do failover even if forwarding in stateless 
48 48
  mode.
49 49
  In the ideal case with the DNS cache enabled Kamailio will do only one query for
50 50
  a NAPTR (if enabled) or SRV lookup and then it will use the results for the
... ...
@@ -183,14 +183,14 @@ DNS Cache and Failover Config Variables
183 183
       Default: on.
184 184
 
185 185
    use_dns_failover = on |off - if on and sending a request fails (due to not
186
-      being allowed from an onsend_route, send failure, blacklisted destination
186
+      being allowed from an onsend_route, send failure, blocklisted destination
187 187
       or, when using tm, invite timeout), and the destination resolves to
188 188
       multiple ip addresses and/or multiple SRV records, the send will be
189 189
       re-tried using the next ip/record. In tm's case a new branch will be
190 190
       created for each new send attempt.
191 191
       Default: off.
192 192
    Depends on use_dns_cache being on. If tm is used along with DNS failover is
193
-   recommended to also turn on dst_blacklist.
193
+   recommended to also turn on dst_blocklist.
194 194
 
195 195
    dns_srv_lb = on | off or
196 196
    dns_srv_loadbalancing = on | off - if on instead of doing simple DNS 
Browse code

docs: remove documentation about removed dns related defines as well

Henning Westerholt authored on 08/06/2018 22:09:14
Showing 1 changed files
... ...
@@ -170,12 +170,6 @@ DNS Resolver Compile Options
170 170
       NAPTR support still has to be enabled from Kamailio's config file (it's
171 171
       off by default).
172 172
 
173
-   RESOLVE_DBG - if defined, the resolver will be very verbose: it will log
174
-      a lot of debugging information at L_DBG level.
175
-
176
-   NAPTR_DBG - if defined the NAPTR related resolver functions will be very
177
-       verbose.
178
-
179 173
 
180 174
 DNS Cache and Failover Config Variables
181 175
 ---------------------------------------
... ...
@@ -307,9 +301,6 @@ DNS Cache Compile Options
307 301
        If this option is not defined (experimental), everything in the AR
308 302
        section will be added to the cache.
309 303
 
310
-   DNS_CACHE_DEBUG - if defined the DNS cache will be very verbose (it will
311
-       log lots of messages at the L_DBG levell).
312
- 
313 304
  Note: To remove a compile options,  edit Kamailio's Makefile.defs and remove it 
314 305
    from DEFS list. To add a compile options add it to the make command line,
315 306
      e.g.: make proper; make all extra_defs=-DUSE_DNS_FAILOVER
Browse code

doc: reorganized the content of doc folder

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