1inet_res(3) Erlang Module Definition inet_res(3)
2
6 inet_res - A rudimentary DNS client.
7
9 This module performs DNS name resolving to recursive name servers.
10 See also ERTS User's Guide: Inet Configuration for more information
12 about how to configure an Erlang runtime system for IP communication,
13 and how to enable this DNS client by defining 'dns' as a lookup method.
14 The DNS client then acts as a backend for the resolving functions in
15 inet.
16 This DNS client can resolve DNS records even if it is not used for nor‐
18 mal name resolving in the node.
19 This is not a full-fledged resolver, only a DNS client that relies on
21 asking trusted recursive name servers.
22
24 UDP queries are used unless resolver option usevc is true, which forces
25 TCP queries. If the query is too large for UDP, TCP is used instead.
26 For regular DNS queries, 512 bytes is the size limit.
27 When EDNS is enabled (resolver option edns is set to the EDNS version
29 (that is, 0 instead of false), resolver option udp_payload_size sets
30 the limit. If a name server replies with the TC bit set (truncation),
31 indicating that the answer is incomplete, the query is retried to that
32 name server using TCP. Resolver option udp_payload_size also sets the
33 advertised size for the maximum allowed reply size, if EDNS is enabled,
34 otherwise the name server uses the limit 512 bytes. If the reply is
35 larger, it gets truncated, forcing a TCP requery.
36 For UDP queries, resolver options timeout and retry control retransmis‐
38 sion. Each name server in the nameservers list is tried with a time-out
39 of timeout/retry. Then all name servers are tried again, doubling the
40 time-out, for a total of retry times.
41 But before all name servers are tried again, there is a (user config‐
43 urable) timeout, servfail_retry_timeout. The point of this is to pre‐
44 vent the new query to be handled by a server's servfail cache (a client
45 that is too eager will actually only get what is in the servfail
46 cache). If there is too little time left of the resolver call's timeout
47 to do a retry, the resolver call may return before the call's timeout
48 has expired.
49 For queries not using the search list, if the query to all nameservers
51 results in {error,nxdomain} or an empty answer, the same query is tried
52 for alt_nameservers.
53
55 The following data types concern the resolver:
56
58 res_option() =
59 {alt_nameservers, [nameserver()]} |
60 {edns, 0 | false} |
61 {inet6, boolean()} |
62 {nameservers, [nameserver()]} |
63 {recurse, boolean()} |
64 {retry, integer()} |
65 {timeout, integer()} |
66 {udp_payload_size, integer()} |
67 {dnssec_ok, boolean()} |
68 {usevc, boolean()} |
69 {nxdomain_reply, boolean()}
70 nameserver() = {inet:ip_address(), Port :: 1..65535}
72 res_error() =
74 formerr | qfmterror | servfail | nxdomain | notimp | refused |
75 badvers | timeout
76
78 The following data types concern the DNS client:
79
81 dns_name() = string()
82 A string with no adjacent dots.
84 dns_rr_type() =
86 a | aaaa | caa | cname | gid | hinfo | ns | mb | md | mg |
87 mf | minfo | mx | naptr | null | ptr | soa | spf | srv | txt |
88 uid | uinfo | unspec | uri | wks
89 dns_class() = in | chaos | hs | any
91 dns_msg() = term()
93 This is the start of a hierarchy of opaque data structures that
95 can be examined with access functions in inet_dns, which return
96 lists of {Field,Value} tuples. The arity 2 functions only return
97 the value for a specified field.
98 dns_msg() = DnsMsg
100 inet_dns:msg(DnsMsg) ->
101 [ {header, dns_header()}
102 | {qdlist, dns_query()}
103 | {anlist, dns_rr()}
104 | {nslist, dns_rr()}
105 | {arlist, dns_rr()} ]
106 inet_dns:msg(DnsMsg, header) -> dns_header() % for example
107 inet_dns:msg(DnsMsg, Field) -> Value
108 dns_header() = DnsHeader
110 inet_dns:header(DnsHeader) ->
111 [ {id, integer()}
112 | {qr, boolean()}
113 | {opcode, query | iquery | status | integer()}
114 | {aa, boolean()}
115 | {tc, boolean()}
116 | {rd, boolean()}
117 | {ra, boolean()}
118 | {pr, boolean()}
119 | {rcode, integer(0..16)} ]
120 inet_dns:header(DnsHeader, Field) -> Value
121 query_type() = axfr | mailb | maila | any | dns_rr_type()
123 dns_query() = DnsQuery
125 inet_dns:dns_query(DnsQuery) ->
126 [ {domain, dns_name()}
127 | {type, query_type()}
128 | {class, dns_class()} ]
129 inet_dns:dns_query(DnsQuery, Field) -> Value
130 dns_rr() = DnsRr
132 inet_dns:rr(DnsRr) -> DnsRrFields | DnsRrOptFields
133 DnsRrFields = [ {domain, dns_name()}
134 | {type, dns_rr_type()}
135 | {class, dns_class()}
136 | {ttl, integer()}
137 | {data, dns_data()} ]
138 DnsRrOptFields = [ {domain, dns_name()}
139 | {type, opt}
140 | {udp_payload_size, integer()}
141 | {ext_rcode, integer()}
142 | {version, integer()}
143 | {z, integer()}
144 | {data, dns_data()} ]
145 inet_dns:rr(DnsRr, Field) -> Value
146 There is an information function for the types above:
148 inet_dns:record_type(dns_msg()) -> msg;
150 inet_dns:record_type(dns_header()) -> header;
151 inet_dns:record_type(dns_query()) -> dns_query;
152 inet_dns:record_type(dns_rr()) -> rr;
153 inet_dns:record_type(_) -> undefined.
154 So, inet_dns:(inet_dns:record_type(X))(X) converts any of these
156 data structures into a {Field,Value} list.
157 dns_data() =
159 dns_name() |
160 inet:ip4_address() |
161 inet:ip6_address() |
162 {MName :: dns_name(),
163 RName :: dns_name(),
164 Serial :: integer(),
165 Refresh :: integer(),
166 Retry :: integer(),
167 Expiry :: integer(),
168 Minimum :: integer()} |
169 {inet:ip4_address(), Proto :: integer(), BitMap :: binary()} |
170 {CpuString :: string(), OsString :: string()} |
171 {RM :: dns_name(), EM :: dns_name()} |
172 {Prio :: integer(), dns_name()} |
173 {Prio :: integer(),
174 Weight :: integer(),
175 Port :: integer(),
176 dns_name()} |
177 {Order :: integer(),
178 Preference :: integer(),
179 Flags :: string(),
180 Services :: string(),
181 Regexp :: string(),
182 dns_name()} |
183 [string()] |
184 binary()
185 Regexp is a string with characters encoded in the UTF-8 coding
187 standard.
188 hostent() =
190 {hostent,
191 H_name :: inet:hostname(),
192 H_aliases :: [inet:hostname()],
193 H_addrtype :: dns_rr_type(),
194 H_length :: integer() >= 0,
195 H_addr_list :: [dns_data()]}
196
198 getbyname(Name, Type) -> {ok, Hostent} | {error, Reason}
199 getbyname(Name, Type, Timeout) -> {ok, Hostent} | {error, Reason}
201 Types:
203 Name = dns_name()
205 Type = dns_rr_type()
206 Timeout = timeout()
207 Hostent = inet:hostent() | hostent()
208 Reason = inet:posix() | res_error()
209 Resolves a DNS record of the specified Type for the specified
211 host, of class in. Returns, on success, when resolving a Type =
212 a|aaaa DNS record, a #hostent{} record with #hostent.h_addrtype
213 = inet|inet6, respectively; see inet:hostent().
214 When resolving other Type = dns_rr_type():s (of class in), also
216 returns a #hostent{} record but with dns_rr_type() in #hos‐
217 tent.h_addrtype, and the resolved dns_data() in #hos‐
218 tent.h_addr_list; see hostent().
219 This function uses resolver option search that is a list of do‐
221 main names. If the name to resolve contains no dots, it is
222 prepended to each domain name in the search list, and they are
223 tried in order. If the name contains dots, it is first tried as
224 an absolute name and if that fails, the search list is used. If
225 the name has a trailing dot, it is supposed to be an absolute
226 name and the search list is not used.
227 gethostbyaddr(Address) -> {ok, Hostent} | {error, Reason}
229 gethostbyaddr(Address, Timeout) -> {ok, Hostent} | {error, Reason}
231 Types:
233 Address = inet:ip_address()
235 Timeout = timeout()
236 Hostent = inet:hostent()
237 Reason = inet:posix() | res_error()
238 Backend functions used by inet:gethostbyaddr/1.
240 gethostbyname(Name) -> {ok, Hostent} | {error, Reason}
242 gethostbyname(Name, Family) -> {ok, Hostent} | {error, Reason}
244 gethostbyname(Name, Family, Timeout) ->
246 {ok, Hostent} | {error, Reason}
247 Types:
249 Name = dns_name()
251 Hostent = inet:hostent()
252 Timeout = timeout()
253 Family = inet:address_family()
254 Reason = inet:posix() | res_error()
255 Backend functions used by inet:gethostbyname/1,2.
257 This function uses resolver option search just like getby‐
259 name/2,3.
260 If resolver option inet6 is true, an IPv6 address is looked up.
262 lookup(Name, Class, Type) -> [dns_data()]
264 lookup(Name, Class, Type, Opts) -> [dns_data()]
266 lookup(Name, Class, Type, Opts, Timeout) -> [dns_data()]
268 Types:
270 Name = dns_name() | inet:ip_address()
272 Class = dns_class()
273 Type = dns_rr_type()
274 Opts = [res_option() | verbose]
275 Timeout = timeout()
276 Resolves the DNS data for the record of the specified type and
278 class for the specified name. On success, filters out the answer
279 records with the correct Class and Type, and returns a list of
280 their data fields. So, a lookup for type any gives an empty an‐
281 swer, as the answer records have specific types that are not
282 any. An empty answer or a failed lookup returns an empty list.
283 Calls resolve/* with the same arguments and filters the result,
285 so Opts is described for those functions.
286 resolve(Name, Class, Type) -> {ok, dns_msg()} | Error
288 resolve(Name, Class, Type, Opts) -> {ok, dns_msg()} | Error
290 resolve(Name, Class, Type, Opts, Timeout) ->
292 {ok, dns_msg()} | Error
293 Types:
295 Name = dns_name() | inet:ip_address()
297 Class = dns_class()
298 Type = dns_rr_type()
299 Opts = [Opt]
300 Opt = res_option() | verbose | atom()
301 Timeout = timeout()
302 Error = {error, Reason} | {error, {Reason, dns_msg()}}
303 Reason = inet:posix() | res_error()
304 Resolves a DNS record of the specified type and class for the
306 specified name. The returned dns_msg() can be examined using ac‐
307 cess functions in inet_db, as described in section in DNS Types.
308 If Name is an ip_address(), the domain name to query for is gen‐
310 erated as the standard reverse ".IN-ADDR.ARPA." name for an IPv4
311 address, or the ".IP6.ARPA." name for an IPv6 address. In this
312 case, you most probably want to use Class = in and Type = ptr,
313 but it is not done automatically.
314 Opts overrides the corresponding resolver options. If option
316 nameservers is specified, it is assumed that it is the complete
317 list of name serves, so resolver option alt_nameserves is ig‐
318 nored. However, if option alt_nameserves is also specified to
319 this function, it is used.
320 Option verbose (or rather {verbose,true}) causes diagnostics
322 printout through io:format/2 of queries, replies retransmis‐
323 sions, and so on, similar to from utilities, such as dig and
324 nslookup.
325 Option nxdomain_reply (or rather {nxdomain_reply,true}) causes
327 nxdomain errors from DNS servers to be returned as {error, {nx‐
328 domain, dns_msg()}}. dns_msg() contains the additional sections
329 that where included by the answering server. This is mainly use‐
330 ful to inspect the SOA record to get the TTL for negative
331 caching.
332 If Opt is any atom, it is interpreted as {Opt,true} unless the
334 atom string starts with "no", making the interpretation
335 {Opt,false}. For example, usevc is an alias for {usevc,true} and
336 nousevc is an alias for {usevc,false}.
337 Option inet6 has no effect on this function. You probably want
339 to use Type = a | aaaa instead.
340
342 This access functions example shows how lookup/3 can be implemented us‐
343 ing resolve/3 from outside the module:
344 example_lookup(Name, Class, Type) ->
346 case inet_res:resolve(Name, Class, Type) of
347 {ok,Msg} ->
348 [inet_dns:rr(RR, data)
349 || RR <- inet_dns:msg(Msg, anlist),
350 inet_dns:rr(RR, type) =:= Type,
351 inet_dns:rr(RR, class) =:= Class];
352 {error,_} ->
353 []
354 end.
355
357 These are deprecated because the annoying double meaning of the name
358 servers/time-out argument, and because they have no decent place for a
359 resolver options list.
360
362 nslookup(Name, Class, Type) -> {ok, dns_msg()} | {error, Reason}
363 nslookup(Name, Class, Type, Timeout) ->
365 {ok, dns_msg()} | {error, Reason}
366 nslookup(Name, Class, Type, Nameservers) ->
368 {ok, dns_msg()} | {error, Reason}
369 Types:
371 Name = dns_name() | inet:ip_address()
373 Class = dns_class()
374 Type = dns_rr_type()
375 Timeout = timeout()
376 Nameservers = [nameserver()]
377 Reason = inet:posix() | res_error()
378 Resolves a DNS record of the specified type and class for the
380 specified name.
381 nnslookup(Name, Class, Type, Nameservers) ->
383 {ok, dns_msg()} | {error, Reason}
384 nnslookup(Name, Class, Type, Nameservers, Timeout) ->
386 {ok, dns_msg()} | {error, Reason}
387 Types:
389 Name = dns_name() | inet:ip_address()
391 Class = dns_class()
392 Type = dns_rr_type()
393 Timeout = timeout()
394 Nameservers = [nameserver()]
395 Reason = inet:posix()
396 Resolves a DNS record of the specified type and class for the
398 specified name.
399Ericsson AB kernel 9.1 inet_res(3)