1SPFQUERY(1)           User Contributed Perl Documentation          SPFQUERY(1)
2
3
4

NAME

6       spfquery - (Mail::SPF) - Checks if a given set of e-mail parameters
7       matches a domain's SPF policy
8

VERSION

10       2.501
11

SYNOPSIS

13       Preferred usage:
14           spfquery [--versions|-v 1|2|1,2] [--scope|-s helo|mfrom|pra]
15           --identity|--id identity --ip-address|--ip ip-address
16           [--helo-identity|--helo-id helo-identity] [OPTIONS]
17
18           spfquery [--versions|-v 1|2|1,2] [--scope|-s helo|mfrom|pra]
19           --file|-f filename|- [OPTIONS]
20
21       Legacy usage:
22           spfquery --helo helo-identity --ip-address|--ip ip-address
23           [OPTIONS]
24
25           spfquery --mfrom mfrom-identity --ip-address|--ip ip-address
26           [--helo helo-identity] [OPTIONS]
27
28           spfquery --pra pra-identity --ip-address|--ip ip-address [OPTIONS]
29
30       Other usage:
31           spfquery --version|-V
32
33           spfquery --help
34

DESCRIPTION

36       spfquery checks if a given set of e-mail parameters (e.g., the SMTP
37       sender's IP address) matches the responsible domain's Sender Policy
38       Framework (SPF) policy.  For more information on SPF see
39       <http://www.openspf.org>.
40
41   Preferred Usage
42       The following usage forms are preferred over the legacy forms used by
43       older spfquery versions:
44
45       The --identity form checks if the given ip-address is an authorized
46       SMTP sender for the given "helo" hostname, "mfrom" envelope sender
47       e-mail address, or "pra" (so-called purported resonsible address)
48       e-mail address, depending on the value of the --scope option (which
49       defaults to mfrom if omitted).
50
51       The --file form reads "ip-address identity [helo-identity]" tuples from
52       the file with the specified filename, or from standard input if
53       filename is -, and checks them against the specified scope (mfrom by
54       default).
55
56       Both forms support an optional --versions option, which specifies a
57       comma-separated list of the SPF version numbers of SPF records that may
58       be used.  1 means that "v=spf1" records should be used.  2 means that
59       "spf2.0" records should be used.  Defaults to 1,2, i.e., uses any SPF
60       records that are available.  Records of a higher version are preferred.
61
62   Legacy Usage
63       spfquery versions before 2.500 featured the following usage forms,
64       which are discouraged but still supported for backwards compatibility:
65
66       The --helo form checks if the given ip-address is an authorized SMTP
67       sender for the "HELO" hostname given as the identity (so-called "HELO"
68       check).
69
70       The --mfrom form checks if the given ip-address is an authorized SMTP
71       sender for the envelope sender email-address (or domain) given as the
72       identity (so-called "MAIL FROM" check).  If a domain is given instead
73       of an e-mail address, "postmaster" will be substituted for the
74       localpart.
75
76       The --pra form checks if the given ip-address is an authorized SMTP
77       sender for the PRA (Purported Responsible Address) e-mail address given
78       as the identity.
79
80   Other Usage
81       The --version form prints version information of spfquery.  The --help
82       form prints usage information for spfquery.
83

OPTIONS

85   Standard Options
86       The preferred and legacy forms optionally take any of the following
87       OPTIONS:
88
89       --default-explanation string
90       --def-exp string
91           Use the specified string as the default explanation if the
92           authority domain does not specify an explanation string of its own.
93
94       --hostname hostname
95           Use hostname as the host name of the local system instead of auto-
96           detecting it.
97
98       --keep-comments
99       --no-keep-comments
100           Do (not) print any comments found when reading from a file or from
101           standard input.
102
103       --sanitize (currently ignored)
104       --no-sanitize (currently ignored)
105           Do (not) sanitize the output by condensing consecutive white-space
106           into a single space and replacing non-printable characters with
107           question marks.  Enabled by default.
108
109       --debug (currently ignored)
110           Print out debug information.
111
112   Black Magic Options
113       Several options that were supported by earlier versions of spfquery are
114       considered black magic (i.e. potentially dangerous for the innocent
115       user) and are thus disabled by default.  If the Mail::SPF::BlackMagic
116       Perl module is installed, they may be enabled by specifying
117       --enable-black-magic.
118
119       --max-dns-interactive-terms n
120           Evaluate a maximum of n DNS-interactive mechanisms and modifiers
121           per SPF check.  Defaults to 10.  Do not override the default unless
122           you know what you are doing!
123
124       --max-name-lookups-per-term n
125           Perform a maximum of n DNS name look-ups per mechanism or modifier.
126           Defaults to 10.  Do not override the default unless you know what
127           you are doing!
128
129       --authorize-mxes-for email-address|domain,...
130           Consider all the MXes of the comma-separated list of email-
131           addresses and domains as inherently authorized.
132
133       --tfwl
134           Perform "trusted-forwarder.org" accreditation checking.
135
136       --guess spf-terms
137           Use spf-terms as a default record if no SPF record is found.
138
139       --local spf-terms
140           Process spf-terms as local policy before resorting to a default
141           result (the implicit or explicit "all" mechanism at the end of the
142           domain's SPF record).  For example, this could be used for white-
143           listing one's secondary MXes: "mx:mydomain.example.org".
144
145       --override domain=spf-record
146       --fallback domain=spf-record
147           Set overrides and fallbacks.  Each option can be specified multiple
148           times.  For example:
149
150               --override example.org='v=spf1 -all'
151               --override '*.example.net'='v=spf1 a mx -all'
152               --fallback example.com='v=spf1 -all'
153

RESULT CODES

155       pass        The specified IP address is an authorized SMTP sender for
156                   the identity.
157
158       fail        The specified IP address is not an authorized SMTP sender
159                   for the identity.
160
161       softfail    The specified IP address is not an authorized SMTP sender
162                   for the identity, however the authority domain is still
163                   testing out its SPF policy.
164
165       neutral     The identity's authority domain makes no assertion about
166                   the status of the IP address.
167
168       permerror   A permanent error occurred while evaluating the authority
169                   domain's policy (e.g., a syntax error in the SPF record).
170                   Manual intervention is required from the authority domain.
171
172       temperror   A temporary error occurred while evaluating the authority
173                   domain's policy (e.g., a DNS error).  Try again later.
174
175       none        There is no applicable SPF policy for the identity domain.
176

EXIT CODES

178         Result    | Exit code
179        -----------+-----------
180         pass      |     0
181         fail      |     1
182         softfail  |     2
183         neutral   |     3
184         permerror |     4
185         temperror |     5
186         none      |     6
187

EXAMPLES

189           spfquery --scope mfrom --id user@example.com --ip 1.2.3.4
190           spfquery --file test_data
191           echo "127.0.0.1 user@example.com helohost.example.com" | spfquery -f -
192

COMPATIBILITY

194       spfquery has undergone the following interface changes compared to
195       earlier versions:
196
197       2.500
198           •   A new preferred usage style for performing individual SPF
199               checks has been introduced.  The new style accepts a unified
200               --identity option and an optional --scope option that specifies
201               the type (scope) of the identity.  In contrast, the legacy
202               usage style requires a separate usage form for every supported
203               scope.  See "Preferred usage" and "Legacy usage" for details.
204
205           •   The former "unknown" and "error" result codes have been renamed
206               to "permerror" and "temperror", respectively, in order to
207               comply with RFC 4408 terminology.
208
209           •   SPF checks with an empty identity are no longer supported.  In
210               the case of an empty "MAIL FROM" SMTP transaction parameter,
211               perform a check with the "helo" scope directly.
212
213           •   The --debug and --(no-)sanitize options are currently ignored
214               by this version of spfquery.  They will again be supported in
215               the future.
216
217           •   Several features that were supported by earlier versions of
218               spfquery are considered black magic and thus are now disabled
219               by default.  See "Black Magic Options".
220
221           •   Several option names have been deprecated.  This is a list of
222               them and their preferred synonyms:
223
224                 Deprecated options  | Preferred options
225                ---------------------+-----------------------------
226                 --sender, -s        | --mfrom
227                 --ipv4, -i          | --ip-address, --ip
228                 --name              | --hostname
229                 --max-lookup-count, | --max-dns-interactive-terms
230                   --max-lookup      |
231                 --rcpt-to, -r       | --authorize-mxes-for
232                 --trusted           | --tfwl
233

SEE ALSO

235       Mail::SPF, spfd(8)
236
237       <http://tools.ietf.org/html/rfc4408>
238

AUTHORS

240       This version of spfquery is a complete rewrite by Julian Mehnle
241       <julian@mehnle.net>, based on an earlier version written by Meng Weng
242       Wong <mengwong+spf@pobox.com> and Wayne Schlitt <wayne@schlitt.net>.
243
244
245
246perl v5.34.0                      2021-07-22                       SPFQUERY(1)
Impressum