MFL offers two sets of functions for querying the Domain Name
System. The dns_query
function and associated
dns_reply_
functions provide a generalized DNS API.
Other functions provide a simplified API.
This function looks up the domain name name. The type argument specifies type of the query to perform. On success, the function returns DNS reply descriptor, a non-negative integer number identifying the reply. It can then be passed to any of the ‘dns_reply_’ functions discussed below in order to retrieve the information from it.
If no matching records were found, the function returns ‘-1’.
On error, it throws a corresponding exception.
The type argument is one of the following constants (defined in the module ‘dns’):
Query the ‘A’ record. The domain should be the hostname to look up.
Query the ‘NS’ records.
Query the ‘PTR’ record. The domain address should be the IP address in dotted-quad form.
Query the ‘MX’ records.
Query the ‘TXT’ records.
If the query returns multiple RR sets, the optional argument sort controls whether they should be returned in the same order as obtained from the DNS (0, the default), or should be sorted (1).
The optional argument resolve is consulted for type
DNS_TYPE_MX
and DNS_TYPE_NS
. If it is 1, the
DNS_TYPE_MX
query will return host names of the MX servers (by
default, it returns IP addresses) and the DNS_TYPE_NS
query
will return IP addresses of the name servers (by default it returns
hostnames).
To extract actual data from the dns_query
return value, use the
functions dns_reply_count
and dns_reply_string
. The
usual processing sequence is:
require dns # Send the query and save the reply descriptor set n dns_query(DNS_TYPE_NS, domain_name) if n >= 0 # If non-empty set is returned, iterate over each value in it: loop for set i 0, while i < dns_reply_count(n), set i i + 1 do # Get the actual data: echo dns_reply_string(n, i) done # Release the memory associated with the reply. dns_reply_release(n) fi
Release the memory associated with the reply rd. If rd is -1, the function does nothing.
Return the number of records in the reply rd. For convenience, if rd is -1, the function returns 0. If rd is negative (excepting -1), a ‘e_failure’ exception is thrown.
Returns nth record from the DNS reply rd.
Returns nth record from the DNS reply rd, if the reply contains IP addresses.
These functions are implemented in two layers: primitive built-in functions which raise exceptions if the lookup fails, and library calls that are warranted to always return meaningful value without throwing exceptions.
The built-in layer is always available. The library calls become available after requesting the dns module (see Modules):
require dns
Returns a whitespace-separated list of IP addresses (A
records) for domain.
Returns a whitespace-separated list of domain names (PTR
records) for the IPv4 address ipstr.
Returns a whitespace-separated list of ‘MX’ names (if ip is not
given or if it is 0
) or ‘MX’ IP addresses (if
ip!=0
)) for domain. Within the returned
string, items are sorted in order of increasing ‘MX’ priority.
If domain has no ‘MX’ records, an empty string is returned.
If the DNS query fails, getmx
raises an appropriate
exception.
Examples:
getmx("mafra.cz") ⇒ "smtp1.mafra.cz smtp2.mafra.cz relay.iol.cz" getmx("idnes.cz") ⇒ "smtp1.mafra.cz smtp2.mafra.cz relay.iol.cz" getmx("gnu.org") ⇒ "mx10.gnu.org mx20.gnu.org" getmx("org.pl") ⇒ ""
Notes:
getmx(domain)
can
differ from that obtained from getmx(domain, 1)
, e.g.:
getmx("aol.com") ⇒ mailin-01.mx.aol.com mailin-02.mx.aol.com mailin-03.mx.aol.com mailin-04.mx.aol.com getmx("aol.com", 1) ⇒ 64.12.137.89 64.12.137.168 64.12.137.184 64.12.137.249 64.12.138.57 64.12.138.88 64.12.138.120 64.12.138.185 205.188.155.89 205.188.156.185 205.188.156.249 205.188.157.25 205.188.157.217 205.188.158.121 205.188.159.57 205.188.159.217
dns_query
.
If you intend to iterate over returned values, better use
dns_query
directly, e.g. instead of doing
string_list_iterate(getmx(domain), ` ', MX, `do_something(MX)')
use
set n dns_query(DNS_TYPE_MX, domain) if n >= 0 loop for set i 0, while i < dns_reply_count(n), set i i + 1 do do_something(dns_reply_string(n, i)) done dns_reply_release(n) fi
See dns_query, for details about the dns_query
function and
associated dns_reply_*
calls.
It will most probably be removed in future releases, when array data types are implemented.
Returns true
if the domain name given by its argument
has any ‘MX’ records.
If the DNS query fails, this function throws failure
or
temp_failure
.
Returns true
if the domain name given by its argument
has any ‘MX’ records.
Otherwise, if domain has no ‘MX’s or if the DNS query fails,
hasmx
returns false
.
The ip argument should be a string representing an IP address in dotted-quad notation. The function returns the canonical name of the host with this IP address obtained from DNS lookup. For example
primitive_hostname (${client_addr})
returns the fully qualified domain name of the host represented by Sendmail variable ‘client_addr’.
If there is no ‘PTR’ record for ip, primitive_hostname
raises the exception e_not_found
.
If DNS query fails, the function raises failure
or
temp_failure
, depending on the character of the failure.
The ip argument should be a string representing an IP address in dotted-quad notation. The function returns the canonical name of the host with this IP address obtained from DNS lookup.
If there is no ‘PTR’ record for ip, or if the lookup fails, the function returns ip unchanged.
The previous mailfromd
versions used the following
paradigm to check if an IP address resolves:
if hostname(ip) != ip ...
The domain argument is any valid domain name, the host is a host name or IP address.
The function returns true
if host is one of the ‘MX’
records for the domain.
If domain has no ‘MX’ records, primitive_ismx
raises
exception e_not_found
.
If DNS query fails, the function raises failure
or
temp_failure
, depending on the character of the failure.
The domain argument is any valid domain name, the host is a host name or IP address.
The function returns true
if host is one of the ‘MX’
records for the domain. Otherwise it returns false
.
If domain has no ‘MX’ records, or if the DNS query fails, the
function returns false
.
Reverse of primitive_hostname
. The primitive_resolve
function
returns the IP address for the host name specified by host
argument. If host has no A records, the function raises the
exception e_not_found
.
If DNS lookup fails, the function raises failure
or
temp_failure
, depending on the character of the failure.
If the optional domain argument is given, it will be appended to host (with an intermediate dot), before querying the DNS. For example, the following two expressions will return the same value:
primitive_resolve("puszcza.gnu.org.ua") primitive_resolve("puszcza", "gnu.org.ua")
There is a considerable internal difference between one-argument and
two-argument forms of primitive_resolve
: the former
queries DNS for an ‘A’ record, whereas the latter
queries it for any record matching host in the domain
domain and then selects the most appropriate one. For example,
the following two calls are equivalent:
primitive_hostname("213.130.0.22") primitive_resolve("22.0.130.213", "in-addr.arpa")
This makes it possible to use primitive_resolve
for querying
DNS black listing domains. See match_dnsbl, for a
working example of this approach. See also match_rhsbl, for
another practical example of the use of the two-argument form.
Reverse of hostname
. The resolve
function
returns IP address for the host name specified by host
argument. If the host name cannot be resolved, or a DNS failure
occurs, the function returns ‘"0"’.
This function is entirely equivalent to primitive_resolve
(see above), except that it never raises exceptions.
Tests whether the DNS reverse-mapping for ip exists and correctly points to a domain name within a particular domain.
First, it obtains all PTR records for ip. Then, for each record returned, a look up for A records is performed and IP addresses of each record are compared against ip. The function returns true if a matching A record is found.
Returns ‘True’ if the domain domain has at least one ‘NS’ record. Throws exception if DNS lookup fails.
Returns ‘True’ if the domain domain has at least one ‘NS’ record. Returns ‘False’ if there are no ‘NS’ records or if the DNS lookup fails.
Returns a whitespace-separated list of all the ‘NS’ records for the domain domain. Optional parameters resolve and sort control the formatting. If resolve is 0 (the default), the resulting string will contain IP addresses of the NS servers. If resolve is not 0, hostnames will be returned instead. If sort is 1, the returned items will be sorted.
If the DNS query fails, getns
raises an appropriate
exception.
Notes:
dns_query
.
If you intend to iterate over returned values, better use
dns_query
directly, e.g. instead of doing
string_list_iterate(getns(domain), ` ', NS, `do_something(NS)')
use
set n dns_query(DNS_TYPE_NS, domain) if n >= 0 loop for set i 0, while i < dns_reply_count(n), set i i + 1 do do_something(dns_reply_string(n, i)) done dns_reply_release(n) fi
See dns_query, for details about the dns_query
function and
associated dns_reply_*
calls.
It will most probably be removed in future releases, when array data types are implemented.
This document was generated on August 13, 2022 using makeinfo.
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.