doc/dns.txt
736a8194
 
 Kamailio and DNS Overview
b7e2b56c
 ---------------------------
dcb59e67
 
736a8194
  The DNS subsystem in Kamailio can either directly use libresolv and a combination
   of the locally configured DNS server, /etc/hosts and the local Network 
dcb59e67
   Information Service (NIS/YP a.s.o) or cache the query results (both positive
   and negative) and look first in its internal cache.
736a8194
 
  When its internal DNS cache is enabled, Kamailio can also use DNS failover: if
   one destination resolves to multiple addresses Kamailio can try all of them until
37209e14
   it finds one to which it can successfully send the packet or it exhausts all 
736a8194
   of them. Kamailio (The tm module to be more precise) uses the DNS failover also 
e783a10d
   when the destination host doesn't send any reply to a forwarded invite within the
   SIP timeout interval (whose value can be configured using the tm fr_timer
   parameter).
736a8194
   When SRV based load balancing is enabled Kamailio can even do DNS based load 
   balancing (see RFC2782 and the dns_srv_lb option below). This is using the
   weight value in the DNS SRV record.
dcb59e67
 
 
 DNS Cache and Failover Drawbacks
e783a10d
 --------------------------------
dcb59e67
 
e783a10d
  Using the DNS cache and the DNS failover has also some drawbacks: 
dcb59e67
 
736a8194
   1. Only the locally configured DNS server (usually in /etc/resolv.conf) is
      used for the requests (/etc/hosts and the local Network Information Service
      are ignored). 
      Workaround: disable the DNS cache (use_dns_cache=off or compile without -DUSE_DNS_CACHE).
dcb59e67
 
736a8194
   2. The DNS cache uses extra memory
e783a10d
       Workaround: disable the DNS cache.
dcb59e67
 
736a8194
   3. The DNS failover introduces a very small performance penalty 
e783a10d
      Workaround: disable the DNS failover (use_dns_failover=off).
dcb59e67
 
736a8194
   4. The DNS failover increases the memory usage (the internal structures
e783a10d
      used to represent the transaction are bigger when the DNS failover support is
      compiled).
      Workaround: compile without DNS failover support (-DUSE_DNS_FAILOVER).
      Turning it off from the config file is not enough in this case (the extra
      memory will still be used).
dd4ffbb7
  
e783a10d
  On the other hand using the DNS cache saves lots of DNS queries and makes
dd4ffbb7
  DNS based failover and DNS based load balancing possible. If the destination
736a8194
  blacklist is enabled, Kamailio can do failover even if forwarding in stateless 
dd4ffbb7
  mode.
736a8194
  In the ideal case with the DNS cache enabled Kamailio will do only one query for
dd4ffbb7
  a NAPTR (if enabled) or SRV lookup and then it will use the results for the
  record's TTL (for example if all the resulting records have 1 minute TTL,
e783a10d
  the server won't make another query for this domain for 1 minute). Even negative
dd4ffbb7
  answers will be cached.
e783a10d
  Without the DNS cache, each NAPTR or SRV lookup will result in at least 2 
dd4ffbb7
  queries. These queries will happen every time, for each message (even if 
  all of them go to the same domain).
dcb59e67
 
 
 DNS Resolver Options
e783a10d
 --------------------
dcb59e67
 
736a8194
  The DNS resolver options control how Kamailio will interact with the external
dcb59e67
  DNS servers. These options (with the dns_try_ipv6 exception) are passed to
736a8194
  libresolv and are used each time a DNS request is made.
e783a10d
 
dcb59e67
  The default values are system specific and generally depend on the
  /etc/resolv.conf content. For servers doing a lot of DNS requests it is
736a8194
  highly recommended to change the default values in the Kamailio config file
   (even if using Kamailio's internal DNS cache).
dcb59e67
 
736a8194
    dns_try_ipv6 = on | off - if on and Kamailio listens on at least one ipv6 socket,
dcb59e67
       ipv6 (AAAA) lookups will be performed if the ipv4 (A) lookups fail. 
       If off only ipv4 (A) lookups will be used.
736a8194
       Default: on if Kamailio is compiled with ipv6 support.
dcb59e67
 
736a8194
    dns_try_naptr = on | off - if on Kamailio will first try a NAPTR lookup for
dd4ffbb7
       destinations that don't have the protocol or port specified and 
       are not simple ip addresses (as described in RFC 3263). This will 
       introduce a slight performance penalty and will probably cause extra
       DNS lookups. For example a lookup for a non-existing domain will
       produce one extra query: NAPTR(domain), SRV(_sip._udp.domain) 
       and A/AAAA(domain).
736a8194
       If the result of a query contains several NAPTR records, Kamailio will select
       among them according to the RFC2915 and Kamailio preference towards a
dd4ffbb7
       specific protocol (see dns_udp_pref, dns_tcp_pref and dns_tls_pref 
       below). For an RFC3263 compliant configuration (choose the remote side
       preferred protocol if supported), set dns_udp_pref, dns_tcp_pref and
       dns_tls_pref to the same value (>=0), e.g. 0.
       Default: off
 
    dns_udp_pref = number - udp protocol preference when doing NAPTR lookups.
7d11cc0c
       This option works together with dns_tcp_pref, dns_tls_pref and 
       dns_sctp_pref. If all this options have the same positive value and more
736a8194
       NAPTR records are available, Kamailio will select the NAPTR record preferred
7d11cc0c
       by the remote side (according to RFC2915). If the values are positive
736a8194
       but different, Kamailio will select the NAPTR record whose protocol it
7d11cc0c
       prefers the most (the protocol with the highest dns_<proto>_pref
       number). If there are several NAPTR records with the same preferred
736a8194
       protocol, Kamailio will select among them based on their order and preference
7d11cc0c
       (see RFC2915).
dd4ffbb7
       To completely disable selecting a specific protocol, use  a negative
740a5978
       number. For example dns_tcp_pref=-1 will completely disable selection
       of tcp NAPTR records, even if this will result in the NAPTR lookup
736a8194
       failure. Note: if a protocol is disabled in Kamailio (e.g. tls_disable=1)
7d11cc0c
       the corresponding NAPTR records selection will be also disabled,
       irrespective of the dns_<proto>_preference value.
       Default: dns_udp_pref=30, dns_tcp_pref=20,  dns_tls_pref=10 and 
       dns_sctp_pref=20.
740a5978
       (prefer udp, but if no udp NAPTR record found or no SRV-resolvable 
7d11cc0c
       udp NAPTR record found use tcp or sctp records and if this fails too
       use tls)
dd4ffbb7
 
    dns_tcp_pref = number  (see dns_udp_pref above)
 
    dns_tls_pref = number (see dns_udp_pref above)
 
7d11cc0c
    dns_sctp_pref = number (see dns_udp_pref above)
 
736a8194
    dns_retr_time = time - time in s before retrying a DNS request.
dcb59e67
       Default: system specific, depends also on the/etc/resolv.conf content
       (usually 5 s).
 
736a8194
    dns_retr_no = no. - number of DNS retransmissions before giving up.
dcb59e67
       Default: see above (usually 4)
 
736a8194
    dns_servers_no = no. - how many DNS servers from the ones defined in 
dcb59e67
       /etc/resolv.conf will be used. Default: all of them.
 
    dns_use_search_list= yes/no - if no, the search list in /etc/resolv.conf
       will be ignored (=> fewer lookups => gives up faster).
       Default: yes.
       HINT: even if you don't have a search list defined, setting this option
       to "no" will still be "faster", because an empty search list is in 
       fact search "" (so even if the search list is empty/missing there will
736a8194
       still be 2 DNS queries, eg. foo+'.' and foo+""+'.')
dcb59e67
 
740a5978
    dns_search_full_match = yes/no - controls the check of the name part
       which is found in the answer expanding the searched name before
       the answer is treated as correct and "link" (fake CNAME record)
       between the short name (query) and long name (answer) is created
       which is then stored in dns_cache and reused for next queries.
       If set to no - no additional check is done.
       If set to yes - the additional part is checked against the search list.
 
736a8194
  The maximum time a DNS request can take (before failing) is:
  (dns_retr_time*dns_retr_no) * (search_list_domains) If dns_try_ipv6 is yes,
dcb59e67
  mutliply it again by 2.
 
736a8194
  The option combination that produces the "fastest" DNS resolver config
dcb59e67
   (the "faster" in the sense that it gives up the quickest) is:
 
       dns_try_ipv6=no
       dns_retr_time=1
       dns_retr_no=1
       dns_servers_no=1
       dns_use_search_list=no
 
736a8194
  The recommended DNS configuration is to have a "close" DNS caching recursive
  server configured in /etc/resolv.conf, set the DNS resolver options in Kamailio's
  config as in the above example and enable the DNS cache (in Kamailio).
dcb59e67
  Pay particular attention to dns_servers_no and dns_use_search_list. It's a
37209e14
  good idea to make sure you don't need / use the search list or more then one
736a8194
  DNS server (to avoid unnecessary extra lookups).
dcb59e67
 
 
dd4ffbb7
 DNS Resolver Compile Options
e783a10d
 ----------------------------
dd4ffbb7
 
    USE_NAPTR - if defined the naptr lookup support will be compiled in.
736a8194
       NAPTR support still has to be enabled from Kamailio's config file (it's
dd4ffbb7
       off by default).
 
    RESOLVE_DBG - if defined, the resolver will be very verbose: it will log
       a lot of debugging information at L_DBG level.
 
    NAPTR_DBG - if defined the NAPTR related resolver functions will be very
        verbose.
 
 
dcb59e67
 DNS Cache and Failover Config Variables
e783a10d
 ---------------------------------------
dcb59e67
 
736a8194
    use_dns_cache = on | off - if off the DNS cache won't be used (all dns
       lookups will result into a DNS request).  When on all the DNS request
dcb59e67
       results will be cached.
       WARNING: when enabled /etc/hosts will be completely bypassed, all the dns
       request will go directly to the system configured (resolv.conf) dns
       server.
       Default: on.
 
    use_dns_failover = on |off - if on and sending a request fails (due to not
       being allowed from an onsend_route, send failure, blacklisted destination
       or, when using tm, invite timeout), and the destination resolves to
       multiple ip addresses and/or multiple SRV records, the send will be
       re-tried using the next ip/record. In tm's case a new branch will be
       created for each new send attempt.
       Default: off.
736a8194
    Depends on use_dns_cache being on. If tm is used along with DNS failover is
dcb59e67
    recommended to also turn on dst_blacklist.
 
dd4ffbb7
    dns_srv_lb = on | off or
736a8194
    dns_srv_loadbalancing = on | off - if on instead of doing simple DNS 
         failover (like above), Kamailio will load balance requests to different srv
         records of the same priority based on the SRV records weights (like 
dd4ffbb7
         described in RFC2782). For a destination which has different priorities
736a8194
         for all its SRV records, this option will be equivalent with simple
         DNS failover.
         Note: this option requires having DNS failover enabled (see 
dd4ffbb7
         use_dns_failover above).
         Default: off.
 
    dns_try_ipv6 = on | off - shared with the resolver (see resolver 
         description).
 
    dns_try_naptr = on | off - shared with the resolver (see resolver 
         description).
 
    dns_udp_pref =  number - shared with the resolver (see resolver 
         description).
 
    dns_tcp_pref =  number - shared with the resolver (see resolver 
         description).
 
    dns_tls_pref =  number - shared with the resolver (see resolver 
         description).
 
736a8194
    dns_cache_flags = DNS cache specific resolver flags, used for overriding
dcb59e67
      the default behaviour (low level).
       Possible values:
736a8194
          1 - ipv4 only: only DNS A requests are performed, even if Kamailio listens
dcb59e67
                         also on ipv6 addresses.
          2 - ipv6 only: only DNS AAAA requests are performed. Ignored if
736a8194
                         dns_try_ipv6 is off or Kamailio doesn't listen on any ipv6
dcb59e67
                         address.
          4 - prefer ipv6: try first to resolve a host name to an ipv6 address
                           (DNS AAAA request) and only if this fails try an ipv4
                           address (DNS A request).
                           By default the ipv4 addresses are preferred.
       Default: 0
 
    dns_cache_negative_ttl = time to live for negative results ("not found") in
       seconds. Use 0 to disable.
       Default: 60 s.
 
    dns_cache_min_ttl = minimum accepted time to live for a record, in seconds.
       If a record has a lower ttl, its value will be discarded and
       dns_cache_min_ttl will be used instead.
       Default: 0
 
    dns_cache_max_ttl = maximum accepted time to live for a record, in seconds.
       If a record has a higher ttl, its value will be discarded and
       dns_cache_max_ttl will be used instead.
       Default: MAXINT
 
736a8194
    dns_cache_mem = maximum memory used for the DNS cache in Kb.
dcb59e67
       Default: 500 Kb
 
736a8194
    dns_cache_gc_interval = how often (in s) the DNS cache will be garbage 
dcb59e67
       collected.
       Default:  120 s.
4136d191
       
    dns_cache_del_nonexp = yes | no or
    dns_cache_delete_nonexpired = yes | no - allow deletion of non-expired
       records from the cache when there is no more space left for new
       ones. The last-recently used entries are deleted first.
       Default: no
dcb59e67
 
736a8194
    dns_cache_init = on | off - if off, the DNS cache is not initialized
7905e2d6
       at startup and cannot be enabled runtime, that saves some memory.
       Default: on
dcb59e67
 
 DNS Cache Compile Options
e783a10d
 -------------------------
dcb59e67
 
736a8194
    USE_DNS_CACHE - if defined the DNS cache support will be compiled in 
dcb59e67
       (default). If not needed/wanted the dns_cache can be disabled from the
736a8194
       Kamailio's config file. The only advantages for not compiling the DNS cache
dcb59e67
       support is a slight decrease of the executable size and an extremely 
736a8194
       small performance increase (1 less comparison per DNS request).
dcb59e67
 
736a8194
    USE_DNS_FAILOVER - if defined the DNS failover support will be compiled in.
       (default). Compiling the DNS failover support has a few disadvantages,
dcb59e67
       see the "Drawbacks" section.
dd4ffbb7
 
    DNS_SRV_LB  - if defined (default) support for load balancing using 
736a8194
        SRV records weights (as described in RFC2782) will be compiled in.
        Note however that it still must be enabled from the Kamailio config, it's
dd4ffbb7
        disabled by default (see the dns_srv_lb config option).
 
    USE_NAPTR  - (shared with the resolver)  if defined NAPTR support will
        be compiled in (default). Note that even if compiled, NAPTR support
736a8194
        must be enabled also from the Kamailio config (see the dns_try_naptr option).
dd4ffbb7
 
    NAPTR_CACHE_ALL_ARS - if defined all the additional records in a NAPTR
736a8194
        answer will be cached. Normally Kamailio would cache only "related" records
dd4ffbb7
        (records that are directly referred), but for answers with lots of 
         A/AAAA records it might happen that not all of the SRV records will fit
736a8194
        in the AR section. In this case, without this compile option Kamailio will 
dd4ffbb7
        not cache the un-referred A/AAAA records. BY default this option is
        disabled.
 
    CACHE_RELEVANT_RECS_ONLY - if defined (default), records in the AR section
        of an answer will be cached only if they are "related" to the query.
        For example if the query is for a SRV record, A & AAAA records in the
        AR section will be cached only if there are SRV records pointing to 
        them. This avoids adding possible garbage to the cache.
        If this option is not defined (experimental), everything in the AR
        section will be added to the cache.
 
736a8194
    DNS_CACHE_DEBUG - if defined the DNS cache will be very verbose (it will
dd4ffbb7
        log lots of messages at the L_DBG levell).
dcb59e67
  
736a8194
  Note: To remove a compile options,  edit Kamailio's Makefile.defs and remove it 
e783a10d
    from DEFS list. To add a compile options add it to the make command line,
dcb59e67
      e.g.: make proper; make all extra_defs=-DUSE_DNS_FAILOVER
    or for a permanent solution, edit Makefile.defs and add it to DEFS 
dd4ffbb7
    (don't foget to prefix it with -D). Some options require editing 
    dns_cache.c or resolve.[ch] (just grep after them).