inet_res
A rudimentary DNS client.
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.
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:
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()}
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:
Types
dns_name() = string()
A string with no adjacent dots.
rr_type() =
a |
aaaa |
cname |
gid |
hinfo |
ns |
mb |
md |
mg |
mf |
minfo |
mx |
naptr |
null |
ptr |
soa |
spf |
srv |
txt |
uid |
uinfo |
unspec |
wks
dns_class() = in | chaos | hs | any
dns_msg() = term()
This is the start of a hiearchy of opaque data structures
that can be examined with access functions in inet_dns
, which
return lists of {Field,Value}
tuples. The arity 2 functions
only return the value for a specified field.
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 | 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, 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
There is an information function for the types above:
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.
So, inet_dns:(inet_dns:record_type(X))(X)
converts
any of these data structures into a {Field,Value}
list.
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()
is a string with characters encoded
in the UTF-8 coding standard.
Functions
getbyname(Name, Type) -> {ok, Hostent} | {error, Reason}
Name = dns_name()
Type = rr_type()
Hostent = inet:hostent()
Reason = inet:posix() | res_error()
getbyname(Name, Type, Timeout) -> {ok, Hostent} | {error, Reason}
Name = dns_name()
Type = rr_type()
Timeout = timeout()
Hostent = inet:hostent()
Reason = inet:posix() | res_error()
Resolves a DNS record of the specified type for the specified host,
of class in
. Returns, on success, a hostent()
record
with dns_data()
elements in the address list field.
This function uses resolver option search
that
is a list of domain names. If the name to resolve contains
no dots, it is prepended to each domain name in the
search list, and they are tried in order. If the name
contains dots, it is first tried as an absolute name
and if that fails, the search list is used. If the name
has a trailing dot, it is supposed to be
an absolute name and the search list is not used.
gethostbyaddr(Address) -> {ok, Hostent} | {error, Reason}
Address = inet:ip_address()
Hostent = inet:hostent()
Reason = inet:posix() | res_error()
gethostbyaddr(Address, Timeout) -> {ok, Hostent} | {error, Reason}
Address = inet:ip_address()
Timeout = timeout()
Hostent = inet:hostent()
Reason = inet:posix() | res_error()
Backend functions used by
inet:gethostbyaddr/1
.
gethostbyname(Name) -> {ok, Hostent} | {error, Reason}
Name = dns_name()
Hostent = inet:hostent()
Reason = inet:posix() | res_error()
gethostbyname(Name, Family) -> {ok, Hostent} | {error, Reason}
Name = dns_name()
Hostent = inet:hostent()
Family = inet:address_family()
Reason = inet:posix() | res_error()
gethostbyname(Name, Family, Timeout) ->
{ok, Hostent} | {error, Reason}
Name = dns_name()
Hostent = inet:hostent()
Timeout = timeout()
Family = inet:address_family()
Reason = inet:posix() | res_error()
Backend functions used by
inet:gethostbyname/1,2
.
This function uses resolver option search
just like
getbyname/2,3
.
If resolver option inet6
is true
,
an IPv6 address is looked up. If that fails,
the IPv4 address is looked up and returned on
IPv6-mapped IPv4 format.
lookup(Name, Class, Type) -> [dns_data()]
Name = dns_name() | inet:ip_address()
Class = dns_class()
Type = rr_type()
lookup(Name, Class, Type, Opts) -> [dns_data()]
Name = dns_name() | inet:ip_address()
Class = dns_class()
Type = rr_type()
Opts = [res_option() | verbose]
lookup(Name, Class, Type, Opts, Timeout) -> [dns_data()]
Name = dns_name() | inet:ip_address()
Class = dns_class()
Type = rr_type()
Opts = [res_option() | verbose]
Timeout = timeout()
Resolves the DNS data for the record of the specified type and class
for the specified name. On success, filters out the answer records
with the correct
and
, and returns
a list of their data fields. So, a lookup for type any
gives an empty answer, as the answer records have
specific types that are not any
. An empty answer
or a failed lookup returns an empty list.
Calls
resolve/*
with the same arguments and filters the result, so
is described for those functions.
resolve(Name, Class, Type) -> {ok, dns_msg()} | Error
Name = dns_name() | inet:ip_address()
Class = dns_class()
Type = rr_type()
Error = {error, Reason} | {error, {Reason, dns_msg()}}
Reason = inet:posix() | res_error()
resolve(Name, Class, Type, Opts) -> {ok, dns_msg()} | Error
Name = dns_name() | inet:ip_address()
Class = dns_class()
Type = rr_type()
Opts = [Opt]
Opt = res_option() | verbose | atom()
Error = {error, Reason} | {error, {Reason, dns_msg()}}
Reason = inet:posix() | res_error()
resolve(Name, Class, Type, Opts, Timeout) ->
{ok, dns_msg()} | Error
Name = dns_name() | inet:ip_address()
Class = dns_class()
Type = rr_type()
Opts = [Opt]
Opt = res_option() | verbose | atom()
Timeout = timeout()
Error = {error, Reason} | {error, {Reason, dns_msg()}}
Reason = inet:posix() | res_error()
Resolves a DNS record of the specified type and class for the
specified name. The returned dns_msg()
can be examined using
access functions in inet_db
, as described in section
in DNS Types.
If
is an ip_address()
, the domain
name to query for is generated as the standard reverse
".IN-ADDR.ARPA."
name for an IPv4 address, or the
".IP6.ARPA."
name for an IPv6 address.
In this case, you most probably want to use
and
,
but it is not done automatically.
overrides the corresponding resolver
options. If option nameservers
is specified, it is
assumed that it is the complete list of name serves,
so resolver option alt_nameserves
is ignored.
However, if option alt_nameserves
is also specified to this
function, it is used.
Option verbose
(or rather {verbose,true}
)
causes diagnostics printout through
io:format/2
of queries, replies retransmissions, and so on, similar
to from utilities, such as dig
and nslookup
.
If
is any atom, it is interpreted
as {
unless the atom string starts with
"no"
, making the
interpretation {
.
For example, usevc
is an alias for {usevc,true}
and nousevc
is an alias for {usevc,false}
.
Option inet6
has no effect on this function. You
probably want to use
instead.
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.
Functions
nslookup(Name, Class, Type) -> {ok, dns_msg()} | {error, Reason}
Name = dns_name() | inet:ip_address()
Class = dns_class()
Type = rr_type()
Reason = inet:posix() | res_error()
nslookup(Name, Class, Type, Timeout) ->
{ok, dns_msg()} | {error, Reason}
nslookup(Name, Class, Type, Nameservers) ->
{ok, dns_msg()} | {error, Reason}
Name = dns_name() | inet:ip_address()
Class = dns_class()
Type = rr_type()
Timeout = timeout()
Reason = inet:posix() | res_error()
Nameservers = [nameserver()]
Resolves a DNS record of the specified type and class for the specified name.
nnslookup(Name, Class, Type, Nameservers) ->
{ok, dns_msg()} | {error, Reason}
Name = dns_name() | inet:ip_address()
Class = dns_class()
Type = rr_type()
Nameservers = [nameserver()]
Reason = inet:posix()
nnslookup(Name, Class, Type, Nameservers, Timeout) ->
{ok, dns_msg()} | {error, Reason}
Name = dns_name() | inet:ip_address()
Class = dns_class()
Type = rr_type()
Timeout = timeout()
Nameservers = [nameserver()]
Reason = inet:posix()
Resolves a DNS record of the specified type and class for the specified name.