Overview
This guide will walk you through the process of setting up email notifications in OPNsense using Gmail as the SMTP server. Since Gmail requires app-specific passwords for enhanced security, we will use an app password for authentication.
Prerequisites
- An OPNsense firewall installed and running.
- A Google account with two-factor authentication (2FA) enabled.
- Access to the OPNsense web interface.
Here is the video version of this written tutorial:
Step 1: Generate a Gmail App Password
- Sign in to your Google account.
- Go to Google Account Security.
- Enable Two-Factor Authentication (if not already enabled).
- Under the “Signing in to Google” section, click on 2-Step Verification and follow the prompts to enable it.
- Generate an App Password.
- Create and manage your app passwords.
- Choose Mail for the app and Other (Custom name) for the device.
- Enter a name like “OPNsense SMTP” and click Create.
- Copy the generated password (a 16-character string) for later use.
Step 2: Configure Email Notifications in OPNsense
- Log in to the OPNsense web interface.
- Navigate to
System>Settings>Notifications.
- Navigate to
- Set up SMTP settings.
- Under the General Settings section, configure the following fields:
- Enable Monit: Check the box to enable email notifications.
- Polling Interval: determine how often it checks a particular service, resource, or system parameter. I recommended 30 seconds.
- Start Delay: 120 (default). Monit waits before monitoring a service after the system starts or after a service has been restarted. This setting is helpful because it gives the service time to initialize properly before Monit starts checking its status.
- Mai Server Address:
smtp.gmail.com - Mail Port:
587 - Server Authentication:
- Mial Server Username: Your full Gmail email address (e.g.,
your-email@gmail.com). - Mail Server Password: Enter the app password generated earlier.
- Mial Server Username: Your full Gmail email address (e.g.,
- Mail Server SSL Connection: Check the box to enable SSL Connection.
- Under the General Settings section, configure the following fields:
Step 3: Set up Alert settings.
- Under the Alert Settings section, configure the following fields:
- Enable Alert: Check the box to enable alerts.
- Recipient: Your full Gmail email address (e.g.,
your-email@gmail.com). - Not on: Reserve selection. If this box is checked, Monit will not send alerts for the selected events but for all others.
- Events: Select an event or events that you want Monit to monitor.
- Mail format: you can use my custom template below:
reply-to: noreply@domain.com
Subject: OPNSense Alerts $DATE
Message: $SERVICE $DATE $DESCRIPTION
Yours sincerely,
Tech Support
Step 4: Sevice Settings
Trigger an event that sends notifications, such as:
- $HOST: monitor load average, CPU Usage, Memory Usage, etc.
- $RootFs: monitor for disk space usage, health, or errors.
- carp_status_change: This variable is specific to CARP (Common Address Redundancy Protocol), which is used for high availability (HA) in OPNsense. You can use this variable to monitor the status of the CARP interfaces and get alerts when there is a failover or a change in the status of your HA system. For example, if your primary node fails, the secondary node will take over, and Monit will alert you that there has been a CARP status change.
- gateway_alert: is useful for alerting when a gateway becomes unreachable or is back online. If your system is configured with multiple gateways (e.g., for redundancy or load balancing), you can set up Monit to notify you if one of the gateways goes down or comes back online.
- Note: OPNSense uses a custom script for gateway_alert, which requires Gateways Group to be configured.
- Custom Alerts: you can create custom alerts. I will go over this in a separate tutorial.
Sevice Tests Settings
A Service Test in Monit is a test that runs periodically to check whether a particular service or process is operating as expected. The test can involve a variety of conditions, such as:
- Checking if a process is running.
- Checking if a service is accessible (e.g., an HTTP service is reachable on a certain port).
- Verifying system resources (e.g., disk space or memory usage).
- Running a custom command or script to validate service health.
If the Service Test fails, Monit can take action such as restarting the service, sending an alert, or executing a custom script.
Troubleshooting
- Authentication failed error:
- Ensure you’ve copied the app password correctly without spaces.
- Verify that 2FA is enabled on your Google account.
- Emails not received:
- Check spam/junk folders.
- Ensure correct “To” email address is set.