<p><strong>This post is linked to from the <a href="/project-email.html">Automated Emails Project</a></strong></p>
<h1>What is SPF?</h1>
<p>Sender Policy Framework</p>
<p>SPF uses a DNS attribute assigned to the sending domain name that lists which
hosts are expected to send emails for that domain.</p>
<h1>How to use SPF</h1>
<h2>Find your external IP address</h2>
<p>Many VMs use NAT to accesss the internet. Their <code>ifconfig</code> output won't match
the actual internet IP that the emails will send from.</p>
<p>To check your external IP address, execute:</p>
<pre><code class="language-bash">dig +short myip.opendns.com @resolver1.opendns.com
</code></pre>
<p>Below, the output of this command will be used as <code>&#x3C;ext_ip></code></p>
<p>If you have a static public IP address you can use it as <code>&#x3C;ext_ip></code></p>
<h2>Set the SPF DNS Record</h2>
<p>There used to be a site with reference data at openspf.org but they ran out of
funding so it went offline. You can still get to its reference page from the
<a href="http://web.archive.org/web/20190224184030/http://www.openspf.org/SPF_Record_Syntax">WayBackMachine</a>.</p>
<p>To configure SPF, first
go to your domain registrar's website and create a new entry for your domain.
In Cloudflare, you just go to the DNS page. Cloudflare supports both SPF and
TXT records, some registrars will only offer TXT. If yours offers both, use
both for this.</p>
<p>Create a record for the domain your emails will send from. For instance, if
your emails will send from <a href="mailto:noreply@alerts.example.com">noreply@alerts.example.com</a>, create an entry for
alerts.example.com.</p>
<p>Check the above linked reference for other options such as using A records,
but here's an example of an SPF record stating that emails are expected from
the IP address 1.2.3.4. You can also use subnet masks if you own a range.</p>
<pre><code>v=spf ip4:1.2.3.4 -all
</code></pre>
<p>Set your DNS SPF record, and that's it, you're done. Receiving "milters"
might check this and add a few points or whatever towards your sender's
trustworthiness.</p>


<p>This post covers how to create a bash script that runs every minute to send an
email when a ping fails.</p>
<p>You could use <a href="https://www.pingdom.com/">Pingdom</a> but there's no need to pay
someone else if you have compute resources available. Also, this works from
inside your local network, so it can ping <a href="https://tools.ietf.org/html/rfc1918">RFC1918</a>
addresses.</p>
<p>This script watches for ICMP (ping) availability.
You can replace the ping command with a netcat call to watch a port, or run
whatever other test you like.</p>
<hr>
<h3>Table of Contents</h3>
<ul>
<li><a href="#building-the-alert-tool">Building the Alert Tool</a>
<ul>
<li><a href="#test-the-mail-command">Test the mail command</a></li>
<li><a href="#create-the-bash-script">Create the bash script</a></li>
</ul>
</li>
<li><a href="#create-cron-job">Create cron job</a>
<ul>
<li>
<ul>
<li><a href="#restart-cron-to-apply-the-changes">Restart Cron to apply the changes</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h1>Building the Alert Tool</h1>
<p>Before you begin, consider <a href="/emails-postfix-ubuntu">setting up a local send-only postfix service</a>.</p>
<h2>Test the mail command</h2>
<p>Emails in this script will send using the <code>mail</code> command. Make sure it works
before continuing.</p>
<pre><code class="language-bash">echo "Test alert please ignore" | mail \
    -a "FROM:noreply@alerts.example.com" \
    -s "Test alert" \
    alerts@example.com
</code></pre>
<h2>Create the bash script</h2>
<p>Create a directory to place the script.</p>
<pre><code class="language-bash">mkdir -p /etc/cronjobs &#x26;&#x26; cd /etc/cronjobs
chmod +x ping_alert.sh
</code></pre>
<p>Create the script. Here's a commented example of one I wrote:</p>
<p><code>vi ping_alert.sh</code></p>
<pre><code class="language-bash">#!/usr/bin/env bash

# Positional arguments. If debug is set to '1', debug will echo to stdout
target_ip=$1
debug_enabled=$2

# debug function for troubleshooting
function debug () {
    if [[ "$debug_enabled" == "1" ]]; then
        echo $1
    fi
}

# The token file will be written when an email has been sent, and ensure that
# another email doesn't get sent again too soon. This helps prevent your emails
# from being marked as SPAM and is also way less annoying.

token_file='/etc/cronjobs/.email_sent'
sent_recently=false
now_ts=$(date +%s)
if [ -f $token_file ]; then
    file_ts=$(cat $token_file)
    # hour_in_seconds defined how long between emails to wait before another
    # can be sent.
    hour_in_seconds=3600
    hour_from_file_ts=$(($file_ts+$hour_in_seconds))
    if [[ $now_ts -le $hour_from_file_ts ]]; then
        sent_recently=true
    fi
fi

# The script will gracefully exit if its within the cooldown window.
if [[ $sent_recently == true ]]; then
    debug "sent recently, exiting. Check $token_file"
    exit
fi

# Ping the target IP and collect the return code. If the return code is 0 then
# the ping was OK and this script will exit.
debug "Pigning $target_ip..."
ping -c 1 $target_ip >/dev/null
if [[ $? == 0 ]]; then
    debug "ping ok, exiting"
    exit
fi

# Since the script hasn't exited, the ping failed. Send the warning email.
debug "Sending warning email"
msg="Warning: Ping to IP $target_ip failed."
echo $msg | mail \
    -a  "FROM:noreply@alert.example.com" \
    -s "Test alert" \
    alerts@example.com

# Update the token file to reset the cooldown.
debug "Writing new timestamp $now_ts"
# Write the new timestamp
echo $now_ts > $token_file
</code></pre>
<p>Make the script executable:</p>
<pre><code class="language-bash">chmod +x ping_alert.sh
</code></pre>
<p>Give the script a test run against a valid and invalid IP. It should send an
email for the invalid IP but not the valid one.</p>
<pre><code># test that should pass
/etc/cronjobs/ping_alert.sh 1.1.1.1
# test that should fail
/etc/cronjobs/ping_alert.sh 10.2.3.4
</code></pre>
<hr>
<h1>Create cron job</h1>
<p>We'll run this script every minute. Since it has a cool-down timer it won't
send spam.</p>
<p>This example will ping <a href="https://new.blog.cloudflare.com/announcing-1111/">Cloudflare's DNS</a>,
<code>1.1.1.1</code>, so replace the IP with one that you actually watch to watch.</p>
<p><code>vi /etc/crontab</code></p>
<pre><code># Keep whatever is currently there
*  *    * * *   root    /etc/cronjobs/ping_alert.sh 1.1.1.1 0 | tee -a /var/log/ping_alert.log
</code></pre>
<h3>Restart Cron to apply the changes</h3>
<pre><code>systemctl restart cron
</code></pre>
<p>Now the job will run every minute, and send emails at most every hour.</p>


<p>In order to send emails from a VM you need a mail server. Often you can use
a public, corproate, or cloud mail server, but sometimes you might need to
deploy your own locally.</p>
<p>This guide covers how to configure Postfix as a local send-only mail service on
a dedicated Ubuntu VM.</p>
<hr>
<h3>Table of Contents</h3>
<ul>
<li><a href="#create-a-send-only-mail-server-with-postfix">Create a send-only mail server with Postfix</a>
<ul>
<li><a href="#find-your-external-ip-address">Find your external IP address</a></li>
<li><a href="#set-your-hostname-to-an-fqdn-in-etchosts">Set your hostname to an FQDN in /etc/hosts</a></li>
<li><a href="#install-postfix">Install Postfix</a></li>
<li><a href="#configure-postfix">Configure Postfix</a></li>
<li><a href="#send-a-test-email-from-the-command-line">Send a test email from the command-line</a></li>
</ul>
</li>
<li><a href="#troubleshooting">Troubleshooting</a>
<ul>
<li><a href="#check-for--remove-mail-stuck-in-the-queue">Check for &#x26; remove mail stuck in the queue</a>
<ul>
<li><a href="#outlook-is-blocking-your-emails">Outlook is blocking your emails</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#other-references">Other References</a></li>
</ul>
<h1>Create a send-only mail server with Postfix</h1>
<h2>Find your external IP address</h2>
<p>Many VMs use NAT to accesss the internet. Their <code>ifconfig</code> output won't match
the actual internet IP that the emails will send from.</p>
<p>To check your external IP address, execute:</p>
<pre><code class="language-bash">dig +short myip.opendns.com @resolver1.opendns.com
</code></pre>
<p>Below, the output of this command will be used as <code>&#x3C;ext_ip></code></p>
<p>If you have a static public IP address you can use it as <code>&#x3C;ext_ip></code></p>
<h2>Set your hostname to an FQDN in /etc/hosts</h2>
<p>This step is only required if you don't already have a local DNS server or
internet routed static IP with a valid FQDN.</p>
<p>Lets say that your mail will come from a server named alerts.example.com.
Set the hosts file like this:</p>
<p><code>vi /etc/hosts</code></p>
<pre><code class="language-text">127.0.0.1 alerts.example.com
&#x3C;ext_ip>  alerts.example.com
</code></pre>
<h2>Install Postfix</h2>
<p>This is the software that manages your mail queue and handles SMTP.</p>
<pre><code class="language-bash">apt-get install -y postfix mailutils
</code></pre>
<p>If it asks you which type of server to install, select Internet Site.
Give it an FQDN when prompted. If you will be sending emails from
<a href="mailto:noreply@alerts.example.com">noreply@alerts.example.com</a>, enter <code>alerts.example.com</code>.</p>
<h2>Configure Postfix</h2>
<p>Here's a configuration that's worked for me.
Be sure to change the <code>myhostname</code> field.</p>
<p><code>vi /etc/postfix/main.cf</code></p>
<pre><code class="language-ini">myhostname = alerts.example.com

smtpd_banner = $myhostname ESMTP $mail_name (Ubuntu)
biff = no
append_dot_mydomain = no
readme_directory = no
smtpd_tls_cert_file = /etc/ssl/certs/ssl-cert-snakeoil.pem
smtpd_tls_key_file = /etc/ssl/private/ssl-cert-snakeoil.key
smtpd_use_tls = yes
smtpd_tls_session_cache_database = btree:${data_directory}/smtpd_scache
smtp_tls_session_cache_database = btree:${data_directory}/smtp_scache
smtpd_relay_restrictions = permit_mynetworks permit_sasl_authenticated defer_unauth_destination
alias_maps = hash:/etc/aliases
alias_database = hash:/etc/aliases
mydestination = $myhostname, 63ec22ec9fc1, localhost.localdomain, , localhost
relayhost =
mynetworks = 127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128
mailbox_size_limit = 0
recipient_delimiter = +
inet_interfaces = loopback-only
inet_protocols = all
</code></pre>
<p>Once configured, restart Postfix:</p>
<pre><code class="language-bash">systemctl restart postfix
</code></pre>
<h2>Send a test email from the command-line</h2>
<p>Pipe some stdout to the <a href="https://linux.die.net/man/1/mail">mail</a> command.
This will be used as the body of the email.</p>
<pre><code class="language-bash">echo "Test alert please ignore" | mail \
  -a "FROM:noreply@alerts.example.com" \
  -s "Test alert" kyle@example.com
</code></pre>
<hr>
<h1>Troubleshooting</h1>
<p>Often emails don't go through. There are lots of reasons that can happen.</p>
<h2>Check for &#x26; remove mail stuck in the queue</h2>
<p>Show the mail queue. It might tell you the error if the email is there.</p>
<pre><code class="language-bash">mailq
</code></pre>
<p>If you've got a scheduled job that is adding emails, it can fill the queue up
and make you look like a spammer. Some mail servers will rate limit a sender,
especially if they haven't set up mechanisms by which they can be trusted.</p>
<p>To remove items from the mail queue by ID, run</p>
<pre><code class="language-bash"># If you don't pass &#x3C;ID> it will delete the all.
postsuper -d &#x3C;ID>
</code></pre>
<h3>Outlook is blocking your emails</h3>
<p>If you get a 500 error from outlook.*, it could need a connector or a rule
exception for the filter. I haven't tested the connector.</p>
<ul>
<li><a href="https://docs.sophos.com/central/Customer/help/en-us/central/Customer/tasks/bypassingexchange.html">Disable the spam filter</a></li>
<li><a href="https://docs.microsoft.com/en-us/exchange/mail-flow-best-practices/use-connectors-to-configure-mail-flow/set-up-connectors-to-route-mail">Use a connector (not tested)</a></li>
</ul>
<h1>Other References</h1>
<ul>
<li><a href="https://www.digitalocean.com/community/tutorials/how-to-install-and-configure-postfix-as-a-send-only-smtp-server-on-ubuntu-16-04">Postfix install guide from Digital Ocean</a></li>
<li><a href="https://hostadvice.com/how-to/how-to-setup-postfix-as-send-only-mail-server-on-an-ubuntu-18-04-dedicated-server-or-vps/">Postfix setup guide from hostadvice.com</a></li>
<li><a href="http://www.postfix.org/BASIC_CONFIGURATION_README.html">Basic Postfix config referece</a></li>
<li><a href="http://www.postfix.org/postconf.5.html">Detailed Postfix config docs</a></li>
<li><a href="https://www.cyberciti.biz/faq/how-to-find-my-public-ip-address-from-command-line-on-a-linux/">Whats My IP from Curl</a></li>
<li><a href="https://tecadmin.net/ways-to-send-email-from-linux-command-line/">5 ways to send email from cli</a></li>
<li><a href="https://www.digitalocean.com/community/tutorials/how-to-install-and-configure-dkim-with-postfix-on-debian-wheezy">DigitalOcean DKIM guide</a></li>
</ul>


<p>I've found that it's pretty common that I need to send emails from my software.
At first it seems easy, there are well documented libraries out there. Pretty
soon though, your super critical outage notification email has wound up in the
SPAM filter.</p>
<p>In this project, I explore the tools available to send email alerts from your
automated systems and how to ensure those emails are trusted by their receiving
mail servers.</p>
<p>This will be an ongoing project that I intend to circle back to as time
permits.</p>
<hr>
<h1>Project Posts &#x26; Progress</h1>
<p>This project includes, or will include, the following posts.</p>
<table>
<thead>
<tr>
<th align="left">Date</th>
<th align="left">Article</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">2019-08-15</td>
<td align="left"><a href="/emails-postfix-ubuntu.html">Postfix Send-Only Mail Service: Basic emails from a dedicated VM</a></td>
</tr>
<tr>
<td align="left">2019-08-18</td>
<td align="left"><a href="/emails-bash-cron.html">Sending cron-scheduled ping failure alerts using a bash script</a></td>
</tr>
<tr>
<td align="left">2019-08-20</td>
<td align="left"><a href="/email-spf.html">Using SPF to ensure emails are trusted</a></td>
</tr>
</tbody>
</table>


Kyle Pericak

"It works in my environment"

Categories

Tags