2019-12-13

Configure pfSense firewall to email alerts using free SendGrid


Running a relatively sophisticated home server stack has its advantages, especially as a parent of teen children. We have our own domain name. Our mail comes from user@demarcohome.com. We have separate networks in the home for the adults and kids. The kids' network is separate, including a separate DNS. I've challenged the kids to work around my partitioned network concept. The theory goes like this: if they're working hard to beat me, they're not focusing their bored mind on browsing inane content. Inane material often links to some pretty bad stuff.

Mostly, my plan has worked. I'm not a network engineer, a DevOps engineer, etc. Still, I've left few obvious holes. The kids have found social hacks (sneaking a look while I enter a wifi password), but they haven't figured out how to get through my VLANs, my separate wifi, or workaround my DNS restrictions.

The home network is partitioned from the big, crazy internet via the pfSense firewall software. Recently, I've moved the pfSense package from a very obsolete, power hungry mini-ITX PC to a ECS Liva Z mini PC. This hits all the pfSense requirements for very low power, no fan, and dual network ports (one for WAN, one for LAN).

My home network has always been light on reporting. I don't have a syslog server, and I really wasn't doing so well at emailed notifications. In practice, I would be notified of a problem when one of my network users would file a ticket: "Dad, uh, I think the wifi isn't working." We all know these come at the worst times, and certainly test my patience. I mean, is the wifi really a requirement of life? Where does fast internet really fall on Maslow's hierarchy, anyway? I needed reporting.

Like most sentient mammals with opposable thumbs, I use gmail. More specifically, I was one of those who signed up for gsuite (f/k/a Google Apps) when it was available for the very low price of free. The free version does not allow external authentication of mail senders. (If I'm wrong somehow, please just enjoy the rest of this article.) I needed an external sender. In a company I worked for, we created a small mail gateway that would forward emails to gsuite. I didn't really follow how it worked, and it looked like another cobbled together layer in our already overly complicated IT infrastructure. For my home, I wanted something simpler. It had to be easy to understand, maintain, and, well, free. Enter SendGrid.

SendGrid will send mail on your behalf. It seems to specialize in the mail type often characterized as a canned lunchmeat that nobody I know has ever knowingly eaten: Spam. SendGrid tries to be a good broadcast emailer, to be fair to them. You must show SendGrid that you own your sending email domain. You do this with some DNS records at your DNS provider. The theory goes like this: If you control how DNS queries for your domain are resolved, you likely own the domain name. So, put some TXT records into the DNS and SendGrid will start sending mail as you. Their site has fantastic explanations on how this is done.

For the impatient among us, we're getting to the actual recipe for sending mail here. This person also posted a tutorial on the same subject.

The overview is this:
1. Create a SendGrid account and configure it up with the minimum details.
2. In SendGrid, create an API key. Give that API key permission only to send mail.
3. Configure pfSense to send administrative mail through SendGrid.
4. Test your prowess by sending a test email.
5. Verify you received your test email.
6. Sit back and ponder your amazing capabilities. For a long time.

Create a SendGrid account
Go to sendgrid.com and create a new free tier account. This will let you send as many administrative emails as your home network should ever be allowed to produce (100/day). Set up your password, etc.


I circled the Free 100 account choice just in case you were confused on how to select the free account. You're welcome.

SendGrid must have the ability to send emails on your behalf. You do this with Domain Authentication.

1. Go to Settings | Sender Authentication.
2. Choose which DNS host you use. (This is who resolves DNS queries for your domain name. I'm using CloudFlare. If you don't know, you can run a WHOIS query on your domain name, and see what DNS servers are listed there.)
3. Follow the SendGrid prompts to authenticate your domain. Their guided process is far more clear than what I can write here.

Create an API key
The API key is like a special sign in (authentication credential) allowing its holder to do certain things. pfSense will "sign in" to SendGrid and attempt to send mail.

Assuming you set up your API key with restrictions as I'm showing here, if someone got your API key, the worst thing they could do is send up to 100 emails per day on your behalf. It's important that you understand API keys, and that you configure your API keys for the bare minimum of permissions you need.

Don't share API keys across multiple services (i.e. pfSense, FreeNAS, etc.). Just like passwords, if you consider one API key to be compromised, you will only have to change that one key in one service. If you share, when you believe a key may have been compromised, you'll only have to update one service. This is experience talking.

On SendGrid, go to Settings | API Keys | Create API Key.

Choose Restricted Access for the API Key Permissions.

Make your form look like the one below. The name you enter for your API key is for you. It's not parsed or used elsewhere.



When you Create & View your key, the key will be displayed.

** The key will not be displayed again, ever. Copy it and paste it directly into pfSense.**
If you need to see it again, delete the old key, and recreate it. It takes <1 minute, so just recreate one and update pfSense with the new key.

Configure pfSense to send email through SendGrid

On your pfSense firewall, go to System | Advanced | Notifications.

Your API key goes in the field Notification E-Mail auth password field. Copy & paste it in the field and the confirm field.

The from e-mail address field is the sender name you'll see when you get an email. I use the hostname for the firewall (as in '[email protected]'). This way, I am certain which host is sending the email.

Test your prowess by sending a test email

Choose Test SMTP Settings and verify you get an email from pfSense. From now on, you'll get system-related emails from pfSense.

Configure pfSense firewall to email alerts using free SendGrid

Running a relatively sophisticated home server stack has its advantages, especially as a parent of teen children. We have our own domain ...