Why DKIM Signatures Break After an OpenDKIM Upgrade

How to Fix DKIM Validation After an OpenDKIM Upgrade

An OpenDKIM upgrade went fine. Your mail server restarted cleanly. But a day later, you start seeing dkim=fail counts spike in your DMARC reports, or receivers report that your DKIM signatures are invalid. Your DNS TXT record has not changed. The upgrade is the only thing that changed.

The specific failure mode looks like this: a DKIM validation error appears in DMARC aggregate reports, showing dkim=fail for messages your server actually signed. You check your DNS record and it looks correct. You check OpenDKIM and it says it is signing. But the receiving server cannot verify the signature, because the public key in DNS does not match the private key OpenDKIM is now using.

This matters because DMARC policy enforcement at receiving servers relies on DKIM validation. When your signatures break, mail that should pass authentication starts failing DMARC checks. That means undelivered newsletters, rejected transactional emails, and a damaged sender reputation that takes weeks to rebuild. The upgrade moved where OpenDKIM stores its private keys, or regenerated them, while your DNS record still points to the old public key.

The fastest way to catch this before it hurts your delivery rates is to monitor your DMARC aggregate reports. A spike in dkim=fail after an upgrade is the signal. DMARCFlow aggregates these reports and alerts on authentication failures immediately, so you know something changed and have the data to diagnose it fast.

How OpenDKIM Stores Keys Across Versions

OpenDKIM has changed where it keeps private keys between major versions. Before version 2.10, keys were typically stored under /var/db/dkim/ or /etc/opendkim/keys/ depending on how OpenDKIM was installed. Version 2.10 introduced a change aligned with Debian packaging standards, and keys moved to /var/lib/opendkim/keys/.

If you upgraded from an older package version to 2.10 or later via apt upgrade or a similar package manager, your old keys are probably still sitting in /var/db/dkim/ while the new OpenDKIM process is looking for them in /var/lib/opendkim/keys/. The DNS selector record has not changed, but OpenDKIM cannot find the private key it needs to create valid signatures.

This is not the only way it breaks, but it is the most common one after a routine upgrade.

Diagnosing the Key Path Problem

Before changing anything, confirm what is actually happening.

Step 1: Check your opendkim.conf settings

Your selector and key table are defined in the OpenDKIM configuration. Look for these lines:


KeyTable        /etc/opendkim/key.table
SigningTable    refile:/etc/opendkim/signing.table
Selector        default

The KeyTable file maps each selector (selector name) to the path of the private key.

Step 2: Find where OpenDKIM is actually looking for keys

Run this command to see the active OpenDKIM configuration:


sudo postconf | grep opendkim

This shows what opendkim.conf is being used and any milter settings that reference OpenDKIM.

Step 3: Check where keys actually live on disk

If you have shell access to the server, find the actual key files:


sudo find /var -name "*.private" 2>/dev/null
sudo find /etc -name "*.private" 2>/dev/null

Common locations:

/etc/opendkim/keys/

/var/db/dkim/

/var/lib/opendkim/keys/

Step 4: Check your DNS TXT record

Run this to see what your DNS TXT record says for the selector:


dig TXT default._domainkey.yourdomain.com

Replace "default" with your actual selector name and yourdomain.com with your domain. The record shows the public key that receivers use to verify your signatures. Compare the "p=" value in this record against the public key in your key table.

Step 5: Check DMARC reports for dkim=fail spikes

Look at your DMARC aggregate reports for a spike in dkim=fail counts after the upgrade date. This is the fastest way to confirm the upgrade caused the problem and to see which receivers are failing. If you do not have DMARC reports configured, set that up now. DMARCFlow aggregates these reports and sends alerts when authentication failures spike, which catches DKIM upgrade problems within hours rather than days.

Three Ways to Fix It

Choose the path that matches your situation.

Path A: Keys exist, but OpenDKIM is looking in the wrong place

If your keys are intact but in a different directory than OpenDKIM expects, update the KeyTable entry to point to the correct path. Then restart OpenDKIM.

Example key table entry:


default._domainkey.yourdomain.com yourdomain.com:default:/var/db/dkim/yourdomain.com/default.private

After updating, test with:


sudo opendkim-testkey -d yourdomain.com -s default -vvv

This confirms OpenDKIM can find and read the key.

Path B: Keys are gone, but the DNS record is still valid

If you have a backup of the private key, restore it to the location OpenDKIM expects and update the KeyTable if needed.

If you do not have a backup, generate a new key pair:


sudo opendkim-genkey -d yourdomain.com -s default -D /etc/opendkim/keys/yourdomain.com/
sudo chown opendkim:opendkim /etc/opendkim/keys/yourdomain.com/default.private
sudo chmod 600 /etc/opendkim/keys/yourdomain.com/default.private

Then update your DNS TXT record with the new public key from default.txt. Wait for DNS propagation, then test:


sudo opendkim-testkey -d yourdomain.com -s default -vvv

Path C: OpenDKIM regenerated keys and the old DNS record is now stale

Some upgrade paths do not preserve the existing keys. Instead, the package upgrade reinstalls the default key directory and generates new private keys, which means the public key you have published in DNS no longer matches what OpenDKIM is signing with.

The tell is this: the key files exist on disk but opendkim-testkey passes, yet receivers still fail validation. In that case, compare the public key in DNS against what OpenDKIM is actually using:


sudo opendkim-testkey -d yourdomain.com -s default --printKeys

This prints the public key OpenDKIM is loading. Compare it against the p= value in your DNS TXT record. If they differ, either restore the old private key from your pre-upgrade backup, or update DNS with the new public key from default.txt.

How to Prevent This on Future Upgrades

Before upgrading OpenDKIM, do three things:

1. Back up your key directory. Copy the entire keys folder to a safe location before the upgrade.
2. Document your selector and key paths. Record the Selector name, KeyTable path, and the contents of your DNS TXT record before you touch anything.
3. Test DKIM validation after every OpenDKIM upgrade. Run opendkim-testkey immediately after restarting the service. Checking before downstream receivers start failing DMARC checks is much cheaper than repairing your sender reputation later.

After you fix the immediate problem, set up ongoing monitoring so the next upgrade does not catch you off guard. DMARCFlow aggregates your DMARC reports and alerts on dkim=fail spikes, which is the fastest signal that something changed on your signing infrastructure. It does not prevent the upgrade problem, but it tells you about it fast enough to fix it before your sender reputation takes a hit.

FAQ

Can I have multiple DKIM selectors active at the same time?

Yes. You can publish multiple TXT records under different selector names and configure OpenDKIM to sign with both. This is useful during key rotation or when transitioning between key sizes. The KeyTable file can list multiple entries.

How long should I wait after updating DNS before testing?

DKIM DNS propagation is usually fast, but some receivers cache DNS records for the TTL value in your TXT record. After updating a DKIM record, wait at least the TTL duration (commonly 3600 seconds to 86400 seconds) before assuming all receivers will see the new key.

Will restarting OpenDKIM disrupt mail flow?

Restarting the milter (the mail filter process) interrupts mail signing briefly, but queued mail will retry and sign on the next attempt. Always test in a maintenance window if possible, but a short restart should not cause permanent delivery failures.

My opendkim-testkey says the key is OK, but receivers still report failures. What now?

The testkey tool checks that OpenDKIM can read and parse the key. If receivers are still failing, the problem is likely DNS propagation or a mismatch between the public key in DNS and the private key OpenDKIM is using. Double-check that the p= value in your DNS TXT record exactly matches the public key OpenDKIM is signing with. Even a small character difference causes validation to fail.