SPFQUERY(1)

💖 NAME 💖

okay so bestie, meet spfquery and spfquery.libspf2 — they check whether an IP address is an SPF-authorized SMTP sender for a domain. that's the whole vibe. no cap. 🦋

this page lives in the libspf2 manuals for Debian and is literally titled SPFQUERY(1), iykyk.

---

🌸 SYNOPSIS 🌸

three whole ways to run her, pick your fighter:

spfquery {-i|--ip} ip-address {-s|--sender} [local-part@]domain
         [{-h|--helo} domain-name] [--rcpt-to email-address(es)]
         [CONTROL-OPTIONS]

spfquery {-f|--file} datafile [CONTROL-OPTIONS]

spfquery {--help|-v|--version}

---

✨ DESCRIPTION ✨

this manual page documents briefly the spfquery command. it was written for the Debian® distribution because the original program does not have a manual page — so we made one, you're welcome. 💅

spfquery performs Sender Policy Framework (SPF) authorization checks based on the command-line arguments or data given in a file or on standard input. for information on SPF see http://www.openspf.org. go read it, it's giving lore. 📚

---

🎀 OPTIONS 🎀

so the options are split into two groups, and this matters:

• Data options — these must be given, though just enough of them to specify a query.
• Control options — these are optional and control the local policy, behaviour and output format of spfquery.

This programs follows the GNU getopt_long_only(3) command line syntax: long options can be given with one or two dashes and can be abbreviated to a prefix long enough to be non-ambiguous. If an option starting with a single dash doesn't match a long option, it is taken as a short option with a following parameter, if applicable. An equals sign between the option name and the parameter is optional for both short and long options. slay, flexible queen. 👑

🧺 Data options

the --file option conflicts with all the other data options, bestie, do not mix. the --helo and --rcpt-to are optional.

• -f, --file filename — Read SPF data from filename. Specify - to read from standard input.

The file should consist of one line per query, each query line consisting of the IP address, sender adress, and optional HELO string, separated by spaces.

Note: Local parts containing spaces are currently not supported. 💀 (the typo "adress" is theirs, we're keeping it, it's canon now)

• -i, --ip ip-address — Specify the IP address of the remote host that is delivering the mail.
• -s, --sender [local-part@]domain — Specify the email address that was used as the envelope sender. If no username (local part) is given, postmaster will be assumed. she's assuming, periodt. 💌
• -h, --helo domain-name — Specify that domain-name was provided in the SMTP HELO (or EHLO) command.
• -r, --rcpt-to rcpt-address[,rcpt-address,...] — Specify the recipients as comma-separated list. Any secondary mail exchangers of all recipient domains are automatically authorized. automatic slay. 🔥

🎛️ Control options

• -d, --debug[=level] — Turn on debugging output.
• -l, --local spf-terms — Test against spf-terms before the final (implicit or explicit) all in an SPF record. This can be used to implement a local policy for whitelisting.
• -t, --trusted [1] — Check the sender domain with trusted-forwarder.org. This is a non-standard feature. (non-standard!! she said it, not me, but we trust her anyway 🫶)
• -t 0, --trusted 0 — Do not check the sender domain with trusted-forwarder.org. This is the default.
• -g, --guess spf-mechanisms — Test the sender domain against spf-mechanisms if the domain has no SPF record.
• -e, --default-explanation string — Default explanation string to use if the SPF record does not specify an explanation string itself.
• -m, --max-lookup number — Maximum number of DNS lookups to allow.
• -c, --sanitize [0|1] — Do [not] sanitize the output by condensing consecutive whitespace into a single space and replacing non-printable characters with question marks. Enabled by default.
• -n, --name hostname — Use hostname as the name of the local system instead of spfquery (the name is used in the output).
• -k, --keep-comments — Print comments found when reading from a file.
• -a, --override ... — (see --fallback below)
• -z, --fallback ... — Provide override and fallback SPF records for certain domains. Not implemented yet. spfquery would act as if the specified records were present before and after any existing record, respectively, of those domains. (not implemented yet!! don't come for her, she's just a girl 🌸)
• --help — Show summary of options.
• -v, --version — Show version of program.

---

🩺 DIAGNOSTICS 🩺

the output ordinarily consists of four lines, in this order, no skipping:

1. the result code;
2. the explanation, suitable for use in an SMTP response message, empty except when a rejection (permanent or temporary) makes sense;
3. the header comment on its own;
4. the Received-SPF header field as defined in RFC 4408 section 7, incorporating the header comment.

if errors (including no SPF record found!) occur during processing, one or more error blocks will be prepended. these start with StartError and end with EndError.

the result codes and their corresponding exit codes are as follows, memorise them bestie:

• 1 – neutral — The sender domain explicitly makes no assertion about the ip-address. This result must be interpreted exactly as if no SPF record at all existed.
• 2 – pass — The ip-address is authorized to send mail for the sender domain. (we love to see it 🎉)
• 3 – fail — The ip-address is unauthorized to send mail for the sender domain.
• 4 – softfail — The ip-address is not authorized to send mail for the sender domain, but the sender domain cannot or does not wish to make a strong assertion that no such mail can ever come from it. she's being diplomatic about it 💅
• 5 – none — No SPF record was found.
• 6 – error (temporary) — A transient error occurred (e.g. failure to reach a DNS server), preventing a result from being reached.
• 7 – unknown (permanent error) — One or more SPF records could not be interpreted.

---

🧪 EXAMPLES 🧪

copy-paste these, they're iconic:

spfquery -ip=11.22.33.44 -sender=user@aol.com -helo=spammer.tld
spfquery -f test_data
echo "127.0.0.1 myname@mydomain.com helohost.com" | spfquery -f -

---

👀 SEE ALSO 👀

spftest(1), spfd(8)

---

💜 AUTHOR 💜

spfquery was written by Wayne Schlitt.

This manual page was written by Magnus Holmgren for the Debian® system (but may be used by others). Heavily inspired by the spfquery manpage of libmail-spf-query-perl (spfquery.mail-spf-query-perl(1)) by Julian Mehnle. Also based on the command-line help of spfquery. giving credit where credit is due, as she should. 🫶

---

⚖️ COPYRIGHT ⚖️

Copyright © 2007 Magnus Holmgren. Permission is granted to copy, distribute and/or modify this document under the terms of the two-clause BSD License. See /usr/share/doc/spfquery/copyright.

---

and that's the whole page bestie!! 🌈 libspf2 1.2.5, dated 2007-09-06 — vintage, iconic, still serving. mwah 💋✨