153 lines
4.9 KiB
HTML
153 lines
4.9 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<title>SPF Macro Guide - Explanation of all SPF macros with examples</title>
|
|
<link rel="stylesheet" href="/assets/styles/main.css">
|
|
<script type="module" src="/assets/scripts/ui/validator.js"></script>
|
|
</head>
|
|
<body>
|
|
<h1>SPF Macro Guide</h1>
|
|
|
|
<main>
|
|
<h2>Overview of SPF macros</h2>
|
|
|
|
<p>
|
|
Using SPF, you can specify which IP addresses are authorized to send emails from a mail server.
|
|
Many of the directives you can use allow you to specify a domain name, but here SPF comes with an
|
|
extra feature: Macros.
|
|
</p>
|
|
|
|
<p>
|
|
Macros allow you to insert dynamic values into the values of SPF directives, which can be used for
|
|
e.g. per-user authentication and more. This guide will go through all macros, along with some examples.
|
|
</p>
|
|
|
|
<p>
|
|
The mechanisms and modifiers that allow macros are: <b>include</b>, <b>a</b>, <b>mx</b>, <b>ptr</b>,
|
|
<b>exists</b>, <b>redirect</b> and <b>exp</b>.
|
|
</p>
|
|
|
|
<h3>List of macros</h3>
|
|
|
|
<ul>
|
|
<li>
|
|
<p><code>%{s}</code> - Sender email address</p>
|
|
|
|
<p>Expands to the email address which the current email is being sent from, e.g. <code>john@example.com</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>%{o}</code> - Sender domain</p>
|
|
|
|
<p>Expands to only the domain part of the sender email address, e.g. <code>example.com</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>%{l}</code> - Sender username</p>
|
|
|
|
<p>Expands to only the local part of the sender email address, e.g. <code>john</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>%{d}</code> - Current domain</p>
|
|
|
|
<p>
|
|
This starts out identical to the sender domain, but when hitting an <b>include</b> mechanism or
|
|
a <b>redirect</b> modifier, this value will change to the domain specified in that term
|
|
during the processing of it.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p><code>%{i}</code> - IP address</p>
|
|
|
|
<p>
|
|
Expands to the IP address of the email client that is sending the mail.
|
|
This can both be an IPv4 and IPv6 address.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p><code>%{v}</code> - IP version</p>
|
|
</li>
|
|
<li>
|
|
<p>Expands to the string <b>"in-addr"</b> if the sender address is IPv4, or <b>"ip6"</b> if it is IPv6.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>%{p}</code> - Validated domain name</p>
|
|
|
|
<p>
|
|
Does a reverse DNS lookup of the sender IP address, and validates that the resulting domain
|
|
is a subdomain of the current domain. Expands to the validated domain, or the string "unknown".
|
|
<b>NOTE:</b> It is not recommended to use this macro. From the specification:
|
|
</p>
|
|
|
|
<blockquote>
|
|
This mechanism is slow, it is not as reliable as other
|
|
mechanisms in cases of DNS errors, and it places a large burden on
|
|
the .arpa name servers. If used, proper PTR records have to be in
|
|
place for the domain's hosts and the "ptr" mechanism SHOULD be one of
|
|
the last mechanisms checked. After many years of SPF deployment
|
|
experience, it has been concluded that it is unnecessary and more
|
|
reliable alternatives should be used instead.
|
|
</blockquote>
|
|
</li>
|
|
<li>
|
|
<p><code>%{h}</code> - HELO/EHLO domain</p>
|
|
|
|
<p>Expands to the domain given on the SMTP HELO/EHLO commands.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>Transformers</h3>
|
|
|
|
<p>SPF macros can be transformed in a few different ways, by adding another character after the macro letter.</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>Reverse transformer (r)</p>
|
|
|
|
<p>
|
|
Adding "r" after a macro will reverse the domain name or IP address.
|
|
E.g. if <code>%{d}</code> expands to <b>example.com</b>, <code>%{dr}</code> will be
|
|
<b>com.example</b>.
|
|
Likewise, if <code>%{i}</code> expands to <b>192.0.2.1</b>, <code>%{ir}</code> will become
|
|
<b>1.2.0.192</b>.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>Digit transformer (1-9)</p>
|
|
|
|
<p>
|
|
Adding a number after a macro, will take that amount of right-hand parts of the domain name /
|
|
IP address. This may be combined with reversing. E.g. for the domain <b>mail.example.com</b>,
|
|
<code>%{d2}</code> will expand to <b>example.com</b>.
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>Explanations</h3>
|
|
|
|
<p>
|
|
SPF allows you to set custom error messages in case of failed validations using the <b>exp</b> modifier.
|
|
The message is retrieved from the TXT records of the domain name defined by the modifier.
|
|
This error message also supports macros, and has extended support for a few more than the ones above:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p><code>{%c}</code> - SMTP client IP (easily readable format)</p>
|
|
</li>
|
|
<li>
|
|
<p><code>{%r}</code> - Domain name of host performing the check</p>
|
|
</li>
|
|
<li>
|
|
<p><code>{%t}</code> - Current timestamp</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<center>
|
|
<h3>SPF tools:</h3>
|
|
<a href="/spf-validator">SPF Validator Tool</a> •
|
|
<a href="/spf-creator">SPF Creator Tool</a>
|
|
</center>
|
|
</main>
|
|
</body>
|
|
</html>
|