NAME¶

inet_res - A rudimentary DNS client.

DESCRIPTION¶

This module performs DNS name resolving to recursive name servers.

See also ERTS User's Guide: Inet Configuration for more information about how to configure an Erlang runtime system for IP communication, and how to enable this DNS client by defining 'dns' as a lookup method. The DNS client then acts as a backend for the resolving functions in inet.

This DNS client can resolve DNS records even if it is not used for normal name resolving in the node.

This is not a full-fledged resolver, only a DNS client that relies on asking trusted recursive name servers.

NAME RESOLVING¶

UDP queries are used unless resolver option usevc is true, which forces TCP queries. If the query is too large for UDP, TCP is used instead. For regular DNS queries, 512 bytes is the size limit.

When EDNS is enabled (resolver option edns is set to the EDNS version (that is, 0 instead of false), resolver option udp_payload_size sets the limit. If a name server replies with the TC bit set (truncation), indicating that the answer is incomplete, the query is retried to that name server using TCP. Resolver option udp_payload_size also sets the advertised size for the maximum allowed reply size, if EDNS is enabled, otherwise the name server uses the limit 512 bytes. If the reply is larger, it gets truncated, forcing a TCP requery.

For UDP queries, resolver options timeout and retry control retransmission. Each name server in the nameservers list is tried with a time-out of timeout/retry. Then all name servers are tried again, doubling the time-out, for a total of retry times.

But before all name servers are tried again, there is a (user configurable) timeout, servfail_retry_timeout. The point of this is to prevent the new query to be handled by a server's servfail cache (a client that is too eager will actually only get what is in the servfail cache). If there is too little time left of the resolver call's timeout to do a retry, the resolver call may return before the call's timeout has expired.

For queries not using the search list, if the query to all nameservers results in {error,nxdomain} or an empty answer, the same query is tried for alt_nameservers.

RESOLVER TYPES¶

The following data types concern the resolver:

DATA TYPES¶

res_option() = 


    {alt_nameservers, [nameserver()]} |


    {edns, 0 | false} |


    {inet6, boolean()} |


    {nameservers, [nameserver()]} |


    {recurse, boolean()} |


    {retry, integer()} |


    {timeout, integer()} |


    {udp_payload_size, integer()} |


    {usevc, boolean()} |


    {nxdomain_reply, boolean()}

nameserver() = {inet:ip_address(), Port :: 1..65535}

res_error() = 


    formerr | qfmterror | servfail | nxdomain | notimp | refused |


    badvers | timeout

DNS TYPES¶

The following data types concern the DNS client:

DATA TYPES¶

dns_name() = string()

dns_rr_type() = 


    a | aaaa | caa | cname | gid | hinfo | ns | mb | md | mg |


    mf | minfo | mx | naptr | null | ptr | soa | spf | srv | txt |


    uid | uinfo | unspec | uri | wks

dns_class() = in | chaos | hs | any

dns_msg() = term()

dns_msg() = DnsMsg


    inet_dns:msg(DnsMsg) ->


        [ {header, dns_header()}


        | {qdlist, dns_query()}


        | {anlist, dns_rr()}


        | {nslist, dns_rr()}


        | {arlist, dns_rr()} ]


    inet_dns:msg(DnsMsg, header) -> dns_header() % for example


    inet_dns:msg(DnsMsg, Field) -> Value
dns_header() = DnsHeader


    inet_dns:header(DnsHeader) ->


        [ {id, integer()}


        | {qr, boolean()}


        | {opcode, query | iquery | status | integer()}


        | {aa, boolean()}


        | {tc, boolean()}


        | {rd, boolean()}


        | {ra, boolean()}


        | {pr, boolean()}


        | {rcode, integer(0..16)} ]


    inet_dns:header(DnsHeader, Field) -> Value
query_type() = axfr | mailb | maila | any | dns_rr_type()
dns_query() = DnsQuery


    inet_dns:dns_query(DnsQuery) ->


        [ {domain, dns_name()}


        | {type, query_type()}


        | {class, dns_class()} ]


    inet_dns:dns_query(DnsQuery, Field) -> Value
dns_rr() = DnsRr


    inet_dns:rr(DnsRr) -> DnsRrFields | DnsRrOptFields


    DnsRrFields = [ {domain, dns_name()}


                  | {type, dns_rr_type()}


                  | {class, dns_class()}


                  | {ttl, integer()}


                  | {data, dns_data()} ]


    DnsRrOptFields = [ {domain, dns_name()}


                     | {type, opt}


                     | {udp_payload_size, integer()}


                     | {ext_rcode, integer()}


                     | {version, integer()}


                     | {z, integer()}


                     | {data, dns_data()} ]


    inet_dns:rr(DnsRr, Field) -> Value

inet_dns:record_type(dns_msg()) -> msg;
inet_dns:record_type(dns_header()) -> header;
inet_dns:record_type(dns_query()) -> dns_query;
inet_dns:record_type(dns_rr()) -> rr;
inet_dns:record_type(_) -> undefined.

dns_data() = 


    dns_name() |


    inet:ip4_address() |


    inet:ip6_address() |


    {MName :: dns_name(),


     RName :: dns_name(),


     Serial :: integer(),


     Refresh :: integer(),


     Retry :: integer(),


     Expiry :: integer(),


     Minimum :: integer()} |


    {inet:ip4_address(), Proto :: integer(), BitMap :: binary()} |


    {CpuString :: string(), OsString :: string()} |


    {RM :: dns_name(), EM :: dns_name()} |


    {Prio :: integer(), dns_name()} |


    {Prio :: integer(),


     Weight :: integer(),


     Port :: integer(),


     dns_name()} |


    {Order :: integer(),


     Preference :: integer(),


     Flags :: string(),


     Services :: string(),


     Regexp :: string(),


     dns_name()} |


    [string()] |


    binary()

hostent() = 


    {hostent,


     H_name :: inet:hostname(),


     H_aliases :: [inet:hostname()],


     H_addrtype :: dns_rr_type(),


     H_length :: integer() >= 0,


     H_addr_list :: [dns_data()]}

EXPORTS¶

getbyname(Name, Type) -> {ok, Hostent} | {error, Reason}

getbyname(Name, Type, Timeout) -> {ok, Hostent} | {error, Reason}

gethostbyaddr(Address) -> {ok, Hostent} | {error, Reason}

gethostbyaddr(Address, Timeout) -> {ok, Hostent} | {error, Reason}

gethostbyname(Name) -> {ok, Hostent} | {error, Reason}

gethostbyname(Name, Family) -> {ok, Hostent} | {error, Reason}

gethostbyname(Name, Family, Timeout) ->



                 {ok, Hostent} | {error, Reason}

lookup(Name, Class, Type) -> [dns_data()]

lookup(Name, Class, Type, Opts) -> [dns_data()]

lookup(Name, Class, Type, Opts, Timeout) -> [dns_data()]

resolve(Name, Class, Type) -> {ok, dns_msg()} | Error

resolve(Name, Class, Type, Opts) -> {ok, dns_msg()} | Error

resolve(Name, Class, Type, Opts, Timeout) ->



           {ok, dns_msg()} | Error

EXAMPLE¶

This access functions example shows how lookup/3 can be implemented using resolve/3 from outside the module:

example_lookup(Name, Class, Type) ->


    case inet_res:resolve(Name, Class, Type) of


        {ok,Msg} ->


            [inet_dns:rr(RR, data)


             || RR <- inet_dns:msg(Msg, anlist),


                 inet_dns:rr(RR, type) =:= Type,


                 inet_dns:rr(RR, class) =:= Class];


        {error,_} ->


            []


     end.

LEGACY FUNCTIONS¶

These are deprecated because the annoying double meaning of the name servers/time-out argument, and because they have no decent place for a resolver options list.

EXPORTS¶

nslookup(Name, Class, Type) -> {ok, dns_msg()} | {error, Reason}

nslookup(Name, Class, Type, Timeout) ->



            {ok, dns_msg()} | {error, Reason}

nslookup(Name, Class, Type, Nameservers) ->



            {ok, dns_msg()} | {error, Reason}

nnslookup(Name, Class, Type, Nameservers) ->



             {ok, dns_msg()} | {error, Reason}

nnslookup(Name, Class, Type, Nameservers, Timeout) ->



             {ok, dns_msg()} | {error, Reason}