.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 >0, 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::DKIM::DNS 3pm"
.TH Mail::DKIM::DNS 3pm 2024-01-28 "perl v5.38.2" "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
Mail::DKIM::DNS \- performs DNS queries for Mail::DKIM
.SH VERSION
.IX Header "VERSION"
version 1.20240124
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This is the module that performs DNS queries for Mail::DKIM.
.SH CONFIGURATION
.IX Header "CONFIGURATION"
This module has a couple configuration settings that the caller
may want to use to customize the behavior of this module.
.ie n .SS $Mail::DKIM::DNS::TIMEOUT
.el .SS \f(CW$Mail::DKIM::DNS::TIMEOUT\fP
.IX Subsection "$Mail::DKIM::DNS::TIMEOUT"
This global variable specifies the maximum amount of time (in seconds)
to wait for a single DNS query to complete. The default is 10.
.SS \fBMail::DKIM::DNS::resolver()\fP
.IX Subsection "Mail::DKIM::DNS::resolver()"
Use this global subroutine to get or replace the instance of
Net::DNS::Resolver that Mail::DKIM uses. If set to undef (the default),
then a brand new default instance of Net::DNS::Resolver will be
created the first time a DNS query is needed.
.PP
You will call this subroutine if you want to specify non-default options
to Net::DNS::Resolver, such as different timeouts, or to enable use
of a persistent socket. For example:
.PP
.Vb 6
\&  # first, construct a custom DNS resolver
\&  my $res = Net::DNS::Resolver\->new(
\&                    udp_timeout => 3, tcp_timeout => 3, retry => 2,
\&                 );
\&  $res\->udppacketsize(1240);
\&  $res\->persistent_udp(1);
\&
\&  # then, tell Mail::DKIM to use this resolver
\&  Mail::DKIM::DNS::resolver($res);
.Ve
.SS \fBMail::DKIM::DNS::enable_EDNS0()\fP
.IX Subsection "Mail::DKIM::DNS::enable_EDNS0()"
This is a convenience subroutine that will construct an appropriate DNS
resolver that uses EDNS0 (Extension mechanisms for DNS) to support large
DNS replies, and configure Mail::DKIM to use it. (As such, it should NOT
be used in conjunction with the \fBresolver()\fR subroutine described above.)
.PP
.Vb 1
\&  Mail::DKIM::DNS::enable_EDNS0();
.Ve
.PP
Use of EDNS0 is recommended, since it reduces the need for falling back to TCP
when dealing with large DNS packets. However, it is not enabled by default
because some Internet firewalls which do deep inspection of packets are not able
to process EDNS0\-enabled packets. When there is a firewall on a path to a DNS
resolver, the EDNS0 feature should be specifically tested before enabling.
.SH AUTHORS
.IX Header "AUTHORS"
.IP \(bu 4
Jason Long <jason@long.name>
.IP \(bu 4
Marc Bradshaw <marc@marcbradshaw.net>
.IP \(bu 4
Bron Gondwana <brong@fastmailteam.com> (ARC)
.SH THANKS
.IX Header "THANKS"
Work on ensuring that this module passes the ARC test suite was
generously sponsored by Valimail (https://www.valimail.com/)
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
.IP \(bu 4
Copyright (C) 2013 by Messiah College
.IP \(bu 4
Copyright (C) 2010 by Jason Long
.IP \(bu 4
Copyright (C) 2017 by Standcore LLC
.IP \(bu 4
Copyright (C) 2020 by FastMail Pty Ltd
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.6 or,
at your option, any later version of Perl 5 you may have available.