.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Mail::SpamAssassin::Plugin::AskDNS 3"
.TH Mail::SpamAssassin::Plugin::AskDNS 3 "2015-04-29" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
AskDNS \- form a DNS query using tag values, and look up the DNSxL lists
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  loadplugin  Mail::SpamAssassin::Plugin::AskDNS
\&  askdns D_IN_DWL _DKIMDOMAIN_._vouch.dwl.spamhaus.org TXT /\eb(transaction|list|all)\eb/
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Using a \s-1DNS\s0 query template as specified in a parameter of a askdns rule,
the plugin replaces tag names as found in the template with their values
and launches \s-1DNS\s0 queries as soon as tag values become available. When \s-1DNS\s0
responses trickle in, filters them according to the requested \s-1DNS\s0 resource
record type and optional subrule filtering expression, yielding a rule hit
if a response meets filtering conditions.
.SH "USER SETTINGS"
.IX Header "USER SETTINGS"
.IP "rbl_timeout t [t_min] [zone]		(default: 15 3)" 4
.IX Item "rbl_timeout t [t_min] [zone] (default: 15 3)"
The rbl_timeout setting is common to all \s-1DNS\s0 querying rules (as implemented
by other plugins). It can specify a \s-1DNS\s0 query timeout globally, or individually
for each zone. When the zone parameter is specified, the settings affects \s-1DNS\s0
queries when their query domain equals the specified zone, or is its subdomain.
See the \f(CW\*(C`Mail::SpamAssassin::Conf\*(C'\fR \s-1POD\s0 for details on \f(CW\*(C`rbl_timeout\*(C'\fR.
.SH "RULE DEFINITIONS"
.IX Header "RULE DEFINITIONS"
.IP "askdns \s-1NAME_OF_RULE\s0 query_template [rr_type [subqueryfilter]]" 4
.IX Item "askdns NAME_OF_RULE query_template [rr_type [subqueryfilter]]"
A query template is a string which will be expanded to produce a domain name
to be used in a \s-1DNS\s0 query. The template may include SpamAssassin tag names,
which will be replaced by their values to form a final query domain.
The final query domain must adhere to rules governing \s-1DNS\s0 domains, i.e.
must consist of fields each up to 63 characters long, delimited by dots.
There may be a trailing dot at the end, but it is redundant / carries
no semantics, because SpamAssassin uses a Net::DSN::Resolver::send method
for querying \s-1DNS,\s0 which ignores any 'search' or 'domain' \s-1DNS\s0 resolver options.
Domain names in \s-1DNS\s0 queries are case-insensitive.
.Sp
A tag name is a string of capital letters, preceded and followed by an
underscore character. This syntax mirrors the add_header setting, except that
tags cannot have parameters in parenthesis when used in askdns templates.
Tag names may appear anywhere in the template \- each queried \s-1DNS\s0 zone
prescribes how a query should be formed.
.Sp
A query template may contain any number of tag names including none,
although in the most common anticipated scenario exactly one tag name would
appear in each askdns rule. Specified tag names are considered dependencies.
Askdns rules with dependencies on the same set of tags are grouped, and all
queries in a group are launched as soon as all their dependencies are met,
i.e. when the last of the awaited tag values becomes available by a call
to \fIset_tag()\fR from some other plugin or elsewhere in the SpamAssassin code.
.Sp
Launched queries from all askdns rules are grouped too according to a pair
of: query type and an expanded query domain name. Even if there are multiple
rules producing the same type/domain pair, only one \s-1DNS\s0 query is launched,
and a reply to such query contributes to all the constituent rules.
.Sp
A tag may produce none, one or multiple values. Askdns rules awaiting for
a tag which never receives its value never result in a \s-1DNS\s0 query. Tags which
produce multiple values will result in multiple queries launched, each with
an expanded template using one of the tag values. An example is a \s-1DKIMDOMAIN\s0
tag which yields a list of signing domains, one for each valid signature in
a signed message.
.Sp
When more than one distinct tag name appears in a template, each potentially
resulting in multiple values, a Cartesian product is formed, and each tuple
results in a launch of one \s-1DNS\s0 query (duplicates excluded). For example,
a query template _A_._B_.example._A_.com where tag A is a list (11,22)
and B is (xx,yy,zz), will result in queries: 11.xx.example.11.com,
22.xx.example.22.com, 11.yy.example.11.com, 22.yy.example.22.com,
11.zz.example.11.com, 22.zz.example.22.com .
.Sp
A parameter rr_type following the query template is a comma-separated list
of expected \s-1DNS\s0 resource record (\s-1RR\s0) types. Missing rr_type parameter implies
an 'A'. A \s-1DNS\s0 result may bring resource records of multiple types, but only
resource records of a type found in the rr_type parameter list are considered,
other resource records found in the answer section of a \s-1DNS\s0 reply are ignored
for this rule. A value \s-1ANY\s0 in the rr_type parameter list matches any resource
record type. An empty \s-1DNS\s0 answer section does not match \s-1ANY.\s0
.Sp
The rr_type parameter not only provides a filter for \s-1RR\s0 types found in
the \s-1DNS\s0 answer, but also determines the \s-1DNS\s0 query type. If only a single
\&\s-1RR\s0 type is specified in the parameter (e.g. \s-1TXT\s0), than this is also the \s-1RR\s0
type of a query. When more than one \s-1RR\s0 type is specified (e.g. A, \s-1AAAA, TXT\s0)
or if \s-1ANY\s0 is specified, then the \s-1DNS\s0 query type will be \s-1ANY\s0 and the rr_type
parameter will only act as a filter on a result.
.Sp
Currently recognized \s-1RR\s0 types in the rr_type parameter are: \s-1ANY, A, AAAA,
MX, TXT, PTR, NAPTR, NS, SOA, CERT, CNAME, DNAME, DHCID, HINFO, MINFO,
RP, HIP, IPSECKEY, KX, LOC, SRV, SSHFP, SPF.\s0
.Sp
http://www.iana.org/assignments/dns\-parameters/dns\-parameters.xml
.Sp
The last optional parameter of a rule is a filtering expression, a.k.a. a
subrule. Its function is much like the subrule in \s-1URIDNSBL\s0 plugin rules,
or in the check_rbl eval rules. The main difference is that with askdns
rules there is no need to manually group rules according to their queried
zone, as the grouping is automatic and duplicate queries are implicitly
eliminated.
.Sp
The subrule filtering parameter can be: a plain string, a regular expression,
a single numerical value or a pair of numerical values, or a list of rcodes
(\s-1DNS\s0 status codes of a response). Absence of the filtering parameter implies
no filtering, i.e. any positive \s-1DNS\s0 response (rcode=NOERROR) of the requested
\&\s-1RR\s0 type will result in a rule hit, regardless of the \s-1RR\s0 value returned with
the response.
.Sp
When a plain string is used as a filter, it must be enclosed in single or
double quotes. For the rule to hit, the response must match the filtering
string exactly, and a \s-1RR\s0 type of a response must match the query type.
Typical use is an exact text string for \s-1TXT\s0 queries, or an exact quad-dotted
IPv4 address. In case of a \s-1TXT\s0 or \s-1SPF\s0 resource record which can return
multiple character-strings (as defined in Section 3.3 of [\s-1RFC1035\s0]), these
strings are concatenated with no delimiters before comparing the result
to the filtering string. This follows requirements of several documents,
such as \s-1RFC 5518, RFC 4408, RFC 4871, RFC 5617. \s0 Examples of a plain text
filtering parameter: \*(L"127.0.0.1\*(R", \*(L"transaction\*(R", 'list' .
.Sp
A regular expression follows a familiar perl syntax like /.../ or m{...}
optionally followed by regexp flags (such as 'i' for case-insensitivity).
If a \s-1DNS\s0 response matches the requested \s-1RR\s0 type and the regular expression,
the rule hits.  Examples: /^127\e.0\e.0\e.\ed+$/, m{\ebdial up\eb}i .
.Sp
A single numerical value can be a decimal number, or a hexadecimal number
prefixed by 0x. Such numeric filtering expression is typically used with
\&\s-1RR\s0 type-A \s-1DNS\s0 queries. The returned value (an IPv4 address) is masked
with a specified filtering value and tested to fall within a 127.0.0.0/8
network range \- the rule hits if the result is nonzero:
((r & n) != 0) && ((r & 0xff000000) == 0x7f000000).  An example: 0x10 .
.Sp
A pair of numerical values (each a decimal, hexadecimal or quad-dotted)
delimited by a '\-' specifies an IPv4 address range, and a pair of values
delimited by a '/' specifies an IPv4 address followed by a bitmask. Again,
this type of filtering expression is primarily intended with \s-1RR\s0 type-A
\&\s-1DNS\s0 queries. The rule hits if the \s-1RR\s0 type matches, and the returned \s-1IP\s0
address falls within the specified range: (r >= n1 && r <= n2), or
masked with a bitmask matches the specified value: (r & m) == (n & m) .
.Sp
As a shorthand notation, a single quad-dotted value is equivalent to
a n\-n form, i.e. it must match the returned value exactly with all its bits.
.Sp
Some typical examples of a numeric filtering parameter are: 127.0.1.2,
127.0.1.20\-127.0.1.39, 127.0.1.0/255.255.255.0, 0.0.0.16/0.0.0.16,
0x10/0x10, 16, 0x10 .
.Sp
Lastly, the filtering parameter can be a comma-separated list of \s-1DNS\s0 status
codes (rcode), enclosed in square brackets. Rcodes can be represented either
by their numeric decimal values (0=NOERROR, 3=NXDOMAIN, ...), or their names.
See http://www.iana.org/assignments/dns\-parameters for the list of names. When
testing for a rcode where rcode is nonzero, a \s-1RR\s0 type parameter is ignored
as a filter, as there is typically no answer section in a \s-1DNS\s0 reply when
rcode indicates an error.  Example: [\s-1NXDOMAIN\s0], or [FormErr,ServFail,4,5] .