====== DNS Subsystem ======
<embed embed:ser-2.1/>
{{tag>spellcheck english revisit}}

====== Overview ======
The DNS subsystem in SER can either directly use ''libresolv'' and a combination of 
the locally configured DNS server, ''/etc/hosts'' and the local Network
Information Service (NIS/YP and so on) or cache the query results (both positive
and negative) and look first in its internal cache. 

When its internal DNS cache is enabled, SER can also use DNS failover: if one 
destination resolves to multiple addresses SER can try all of them until it finds 
one to which it can successfully send the packet or it exhausts all of them. SER 
(tm module to be more precise) uses the DNS failover also 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). When SRV based load balancing 
is enabled SER can even do DNS based load balancing 
(see [[ser:2.1:ref:std:rfc:2782|RFC 2782]] and the dns_srv_lb option below).

====== DNS Cache and Failover Drawbacks ======

Using the DNS cache and the DNS failover has also some drawbacks:

  - 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'').
  - the DNS cache uses extra memory\\ Workaround: disable the DNS cache.
  - the DNS failover introduces a very small performance penalty\\ Workaround: disable the DNS failover (''use_dns_failover=off'').
  - the DNS failover increases the memory usage (the internal structures 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).

On the other hand using the DNS cache saves lots of DNS queries and makes
DNS based failover and DNS based load balancing possible. If the destination
blacklist is enabled, SER can do failover even if forwarding in stateless
mode.

In the ideal case with DNS cache enabled SER will do only one query for
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,
SER won't make another query for this domain for 1 minute). Even negative
answers will be cached.

Without the DNS cache, each NAPTR or SRV lookup will result in at least 2
queries. These queries will happen every time, for each message (even if
all of them go to the same domain).

====== DNS Options ======

These are the options that can be set in the configuration file of SER
and control the behavior of the DNS subsystem.

===== dns =====

When SER receives a SIP request, it compares the source IP address of the
IP datagram with the IP address or hostname in the topmost ''Via'' header
field. If they are different then SER will add ''received'' parameter to
the topmost ''Via'' header field. ''Via'' header fields can contain both 
IP addresses and hostnames.

If this parameter is set to 1 and the topmost Via header field contains a 
hostname then SER will resolve the hostname and then it will compare the 
source IP address of the datagram with all the IP addresses received from 
DNS.

If you set the parameter to 0 then SER will not match the source IP 
address with the hostname in topmost Via and all such Via header fields will 
be modified to include the ''received'' parameter containing the source IP.

This parameter is set to 0 by default, because vast majority of SIP
implementations put IP addresses into ''Via'' headers and thus no hostname
resolution is necessary.

You should only turn this feature on if you have any user agents that put
hostnames in Via headers and if you want to make sure that SIP replies
will be routed to the IP address associated with the hostname in topmost Via 
and not to the source IP address of the SIP request.

<note tip>
See [[ser:2.1:ref:std:rfc:3581|RFC 3581]] for details about ''received'' Via
parameter.
</note>

===== use_dns =====

This option is just another name for [[#dns|dns]] option described above.

===== rev_dns =====

This parameter controls whether SER performs reverse DNS lookups to translate
the source IP address of the datagram to hostname when comparing the source IP
address with the address or hostname in the topmost Via header field.

This parameter is turned off by default (SER does not perform reverse DNS
lookups when comparing the the hostname in Via).

====== DNS Resolver Options ======

The DNS resolver options control how SER will interact with the external
DNS servers. These options (with the ''dns_try_ipv6 exception'') are passed to
''libresolv'' and are used each time a DNS request is made.

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
highly recommended to change the default values in the SER config file
(even if using SER's internal DNS cache).

===== dns_try_ipv6 =====

  dns_try_ipv6 = on | off

If on and SER listens on at least one IPv6 socket, IPv6 (AAAA) lookups will be 
performed if the IPv4 (A) lookups fail. If off only IPv4 (A) lookups will be used.\\
Default: on if SER is compiled with IPv6 support.

===== dns_try_naptr =====

  dns_try_naptr = on | off

If on SER will first try a NAPTR lookup for destinations that don't have the 
protocol or port specified and are not simple IP addresses (as described in [[ser:2.1:ref:std:rfc:3263|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).

If the result of a query contains several NAPTR records, ser will select among them 
according to the [[ser:2.1:ref:std:rfc:2915|RFC 2915]] and ser preference towards a specific protocol (see 
dns_udp_pref, dns_tcp_pref and dns_tls_pref below). For an [[ser:2.1:ref:std:rfc:3263|RFC 3263]] 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 =====

  dns_udp_pref = number

UDP protocol preference when doing NAPTR lookups. This option works together with 
dns_tcp_pref and dns_tls_pref. If all this options have the same positive value and 
more NAPTR records are available, SER will select the NAPTR record preferred by the 
remote side (according to [[ser:2.1:ref:std:rfc:2915|RFC 2915]]). If the values are positive but different, SER
will select the NAPTR record whose protocol it prefers the most (the protocol with 
the highest dns_<proto>_pref number). If there are several NAPTR records with the same 
preferred protocol, SER will select among them based on their order and preference 
(see [[ser:2.1:ref:std:rfc:2915|RFC 2915]]).

To completely disable selecting a specific protocol, use a negative number. For 
example dns_tcp_pref=-1 will completely disable selection of TCP NAPTR records, 
even if this will result in the NAPTR lookup failure.\\
Default: dns_udp_pref=3, dns_tcp_pref=2 and dns_tls_pref=1
(prefer UDP, but if no UDP NAPTR record found or no SRV-resolvable
UDP NAPTR record found use TCP records and if this fails too use TLS)

===== dns_tcp_pref =====
  dns_tcp_pref = number  

(see dns_udp_pref above)


===== dns_tls_pref =====
===== dns_tls_preference =====

   dns_tls_pref = number 

(see dns_udp_pref above)

===== dns_retr_time =====
   dns_retr_time = time

Time in seconds before retrying a DNS request.\\
Default: system specific, depends also on the/etc/resolv.conf content
(usually 5 s).

===== dns_retr_no =====
   dns_retr_no = no.

Number of DNS retransmissions before giving up.\\
Default: see above (usually 4)

===== dns_servers_no =====
   dns_servers_no = no.

How many DNS servers from the ones defined in /etc/resolv.conf will be used. \\
Default: all of them.

===== dns_use_search_list =====
   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
still be 2 DNS queries, eg. foo+'.' and foo+""+'.')

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,
mutliply it again by 2.

The option combination that produces the "fastest" dns resolver config
(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

The recommended DNS configuration is to have a "close" DNS caching recursive
server configured in /etc/resolv.conf, set the DNS resolver options in SER's
configuration file as in the above example and enable the DNS cache (in SER).
Pay particular attention to dns_servers_no and dns_use_search_list. It's a
good idea to make sure you don't need / use the search list or more then one
DNS server (to avoid unnecessary extra lookups).

====== DNS Resolver Compile Options ======

===== USE_NAPTR =====
If defined the naptr lookup support will be compiled in. NAPTR support still 
has to be enabled from SER's config file (it's 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.

====== DNS Cache and Failover Config Variables ======
===== use_dns_cache =====
  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 results will be cached.

<note warning>
When enabled /etc/hosts will be completely bypassed, all the DNS requests will 
go directly to the system configured (resolv.conf) DNS server.
</note>

Default: on.

===== use_dns_failover =====
  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.\\
Depends on use_dns_cache being on. If tm is used along with DNS failover is
recommended to also turn on dst_blacklist.

===== dns_srv_lb =====
===== dns_srv_loadbalancing =====
   dns_srv_lb = on | off or
   dns_srv_loadbalancing = on | off

If on instead of doing simple DNS failover (like above), SER will load balance 
requests to different SRV records of the same priority based on the SRV records 
weights (like described in [[ser:2.1:ref:std:rfc:2782|RFC 2782]]). For a destination which has different 
priorities for all its SRV records, this option will be equivalent with simple
DNS failover.
<note>
This option requires having DNS failover enabled (see use_dns_failover above).
</note>
Default: off.

===== dns_try_ipv6 =====
   dns_try_ipv6 = on | off

Shared with the resolver (see resolver description).

===== dns_try_naptr =====
   dns_try_naptr = on | off

Shared with the resolver (see resolver description).


===== dns_udp_pref =====
===== dns_udp_preference =====

   dns_udp_pref =  number

Shared with the resolver (see resolver description).


===== dns_tcp_pref =====
===== dns_tcp_preference =====

   dns_tcp_pref =  number

Shared with the resolver (see resolver description).

===== dns_tls_pref =====
   dns_tls_pref =  number

Shared with the resolver (see resolver description).

===== dns_cache_flags =====
   dns_cache_flags = dns cache specific resolver flags

Used for overriding the default behavior (low level).

Possible values:
^  value  ^  name  ^  description  ^
|  1  |  IPv4 only  |  Only DNS A requests are performed, even if SER listens also on IPv6 addresses.  |
|  2  |  ipv6 only  |  Only DNS AAAA requests are performed. Ignored if dns_try_ipv6 is off or SER doesn't listen on any ipv6 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 =====
   dns_cache_negative_ttl = time 

Time to live for negative results ("not found") in seconds. Use 0 to disable.\\
Default: 60 s.

===== dns_cache_min_ttl =====
   dns_cache_min_ttl = time 

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 =====
   dns_cache_max_ttl = time

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

===== dns_cache_mem =====
   dns_cache_mem = time

Maximum memory used for the dns cache in Kb.\\
Default: 500 Kb

===== dns_cache_gc_interval =====
   dns_cache_gc_interval = time 

How often (in s) the DNS cache will be garbage collected.\\
Default:  120 s.


====== DNS Cache Compile Options ======
===== USE_DNS_CACHE =====
If defined the DNS cache support will be compiled in (default). If not 
needed/wanted the dns_cache can be disabled from the ser's config file. 
The only advantages for not compiling the DNS cache support is a slight 
decrease of the executable size and an extremely small performance increase 
(1 less comparison per dns request).

===== USE_DNS_FAILOVER =====
If defined the DNS failover support will be compiled in. (default). 
Compiling the DNS failover support has a few disadvantages, see the "Drawbacks" 
section.

===== DNS_SRV_LB =====
If defined (default) support for load balancing using SRV records weights 
(as described in [[ser:2.1:ref:std:rfc:2782|RFC 2782]]) will be compiled in. Note however that it still must 
be enabled from the SER config, it's 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 must be enabled also from the SER config 
(see the dns_try_naptr option).

===== NAPTR_CACHE_ALL_ARS =====
If defined all the additional records in a NAPTR answer will be cached. Normally 
SER would cache only "related" records (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 in the AR section. In this case, without this compile option SER 
will 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.

===== DNS_CACHE_DEBUG =====
If defined the DNS cache will be very verbose (it will log lots of messages at the 
L_DBG level).

<note>
To remove a compile options,  edit SER's Makefile.defs and remove it
from DEFS list. To add a compile options add it to the make command line, e.g.: 
  make proper; make all extra_defs=-DUSE_DNS_FAILOVER
or for a permanent solution, edit ''Makefile.defs'' and add it to DEFS (don't forget 
to prefix it with -D). Some options require editing dns_cache.c or resolve.[ch] 
(just grep after them).

====== See Also ======
  * [[ser:2.1:ref:std:rfc:1034|RFC 1034]]
  * [[ser:2.1:ref:std:rfc:1035|RFC 1035]]
  * [[ser:2.1:ref:std:rfc:2168|RFC 2168]]
  * [[ser:2.1:ref:std:rfc:2396|RFC 2396]]
  * [[ser:2.1:ref:std:rfc:2782|RFC 2782]]