Alert email with msmtp¶
The server's watchdogs send alert email through msmtp, a small SMTP client, to a Gmail account. msmtp signs in to smtp.gmail.com with a Gmail App Password. app-setup/msmtp-setup.sh installs msmtp, writes its config for the operator account, installs the shared alert library, and sends a test email under the same PATH that launchd gives a LaunchAgent.
Before you start¶
- Choose the Gmail account that sends and receives the alerts. msmtp signs in as
MONITORING_EMAILand sends each alert toMONITORING_EMAIL, so the App Password must belong to that same account. - Turn on 2-Step Verification for that Google account. Google offers App Passwords only when it is on.
-
Set
MONITORING_EMAILinconfig/config.conf:If the key is empty or still has the template value
your-email@example.com,msmtp-setup.shasks for an address and writes it into~/app-setup/config/config.conf. See Configuration keys. -
Set up msmtp before
podman-transmission-setup.shif you can. That script deploys the PIA port watchdog and the stall watchdog only whenMONITORING_EMAILis set and/Users/operator/.config/msmtp/configexists. If you set up msmtp later, runpodman-transmission-setup.shagain.
Set it up¶
- Create the App Password. Sign in to the Google account at myaccount.google.com/apppasswords, enter a name such as
Mac Mini Server, and create it. Google shows a 16-character password once. Keep the page open for the next steps. -
On the server, as
admin, go to the app setup folder: -
Run the script:
-
At
Enter Gmail App Password:, type the 16 characters without the spaces, then press Enter. The script does not show what you type.You can also give the password with
--password PASSWORD. The password is then in the command line and in your shell history, so the prompt is better. -
Enter the
adminpassword whensudoasks for it.
The script does these things:
- It installs
msmtpandjqwith Homebrew, unless they are already installed. -
It writes
/Users/operator/.config/msmtp/config, owned byoperator, mode 600. The App Password is in this file as plain text, because a LaunchAgent cannot unlock the operator keychain. Do not print the file. Its settings are:defaults auth on tls on tls_trust_file /etc/ssl/cert.pem logfile /Users/operator/.local/state/msmtp.log account gmail host smtp.gmail.com port 587 from operator@<hostname> user <MONITORING_EMAIL> password <App Password> account default : gmailGmail replaces the
fromaddress with the account that signed in, so thefromvalue has no effect. -
It copies the alert library to
/Users/operator/.local/lib/alert-lib.sh. Every watchdog sends email through itsalert_sendfunction, which finds msmtp by its absolute Homebrew path. - It sends a test email with the subject
[<hostname>] Monitoring email configured. It sends it asoperator, with onlyPATH=/usr/bin:/bin:/usr/sbin:/sbin,HOMEandMONITORING_EMAILset. That is the environment of a LaunchAgent. If the test fails, the script stops with an error.
When a config with a password already exists, the script keeps it and does not ask for a password. To replace the App Password, run it with --force. The script then asks for the new password.
Check¶
Run these checks as admin.
- The setup output ends with
Test email sent successfully to you@example.com, and the email is in the inbox. -
Send a test alert under launchd's PATH. Replace
you@example.comwith yourMONITORING_EMAILvalue:sudo -u operator /usr/bin/env -i \ PATH=/usr/bin:/bin:/usr/sbin:/sbin \ HOME=/Users/operator \ MONITORING_EMAIL=you@example.com \ /bin/bash -c 'cd ~ && . ~/.local/lib/alert-lib.sh && alert_send "[macmini] test" "launchd-PATH test"'On success the command prints nothing and exits 0. On failure it prints an
[alert-lib] ERROR: ...line.Use
sudo -u, notsudo -iu. A login shell adds Homebrew to PATH, and the test then proves nothing about launchd. -
The last line of msmtp's log shows
exitcode=EX_OK: -
The config file is private to
operator:The output starts with
-rw-------and showsoperator.
If no email arrives, look for ERROR lines in the watchdog's log. The Monitoring page explains each error. An authentication failure in the error text often means that the App Password was revoked. Create a new one and run ./msmtp-setup.sh --force.
Related¶
- Monitoring: the watchdogs, the
alert-lib.shfunctions, and the launchd PATH problem. - Transmission first install: deploys the PIA port watchdog and the stall watchdog.
- Configuration keys
- Logs
- LaunchAgents