Building the image

docker build --rm -t opendkim:latest .

Generating private key

Before running the container, a private key must be generated using opendkim-genkey or supplied manually.

# Generate private key and DNS record files.
opendkim-genkey --bits=2048 --selector=dkim --restrict --verbose --domain=example.com

# Generated files:
#   dkim.private
#   dkim.txt

To extract the public key value for a DNS TXT record:

cat dkim.txt | tr -d "\"\n\" \t" | sed -r "s/.*\((.*)\).*/\\1\n/"

Example DNS record name:

dkim._domainkey.example.com

Running the image

docker run -it --rm \
  --name opendkim \
  -p 8892:8892 \
  -v /path/to/dkim.private:/opt/opendkim/keys/dkim.private:ro \
  opendkim:latest

Example with custom domain and selector:

docker run -it --rm \
  --name opendkim \
  -p 8892:8892 \
  -e OPENDKIM_DOMAIN=example.com \
  -e OPENDKIM_SELECTOR=mail \
  -e OPENDKIM_SOCKET="inet:8892@0.0.0.0" \
  -v /path/to/mail.private:/opt/opendkim/keys/dkim.private:ro \
  opendkim:latest

Environment variables

These values are defaults and can be overridden by setting environment variables.

# Runtime user name.
OPENDKIM_USER="opendkim"

# Runtime group name.
OPENDKIM_GROUP="opendkim"

# User and group used by OpenDKIM. Format: user:group
OPENDKIM_USERID="opendkim:opendkim"

# Socket used by the milter service.
OPENDKIM_SOCKET="inet:8892@0.0.0.0"

# Domain whose mail should be signed.
OPENDKIM_DOMAIN="example.com"

# DKIM selector.
OPENDKIM_SELECTOR="dkim"

# Path to private key mounted into the container.
OPENDKIM_KEYFILE="/opt/opendkim/keys/dkim.private"

# Canonicalization method used when signing.
OPENDKIM_CANONICALIZATION="relaxed/simple"

# Operating mode:
#   s = signer
#   v = verifier
#   sv = sign and verify
OPENDKIM_MODE="sv"

# Whether to sign subdomains too.
OPENDKIM_SUBDOMAINS="true"

# Headers to oversign.
OPENDKIM_OVERSIGNHEADERS="From"

# Optional DNSSEC trust anchor file.
# Added to config only if the file exists.
OPENDKIM_TRUSTANCHORFILE=""

# Internal hosts whose mail should be signed instead of verified.
OPENDKIM_INTERNALHOSTS="127.0.0.1,localhost,127.0.0.0/8,192.168.0.0/16,172.16.0.0/12,10.0.0.0/8"

# ExternalIgnoreList value for OpenDKIM.
OPENDKIM_EXTERNALIGNORELIST="refile:/etc/opendkim/TrustedHosts"

# Path to KeyTable.
OPENDKIM_KEYTABLE="/etc/opendkim/KeyTable"

# Path to SigningTable.
OPENDKIM_SIGNINGTABLE="refile:/etc/opendkim/SigningTable"

# PID file path.
OPENDKIM_PIDFILE="/run/opendkim/opendkim.pid"

# Umask used by OpenDKIM.
OPENDKIM_UMASK="002"

# Whether OpenDKIM should auto-restart.
OPENDKIM_AUTO_RESTART="no"

# Auto restart rate.
OPENDKIM_AUTO_RESTART_RATE="10/1h"

# DNS query timeout in seconds.
OPENDKIM_DNS_TIMEOUT="5"

# Signing algorithm.
OPENDKIM_SIGNATURE_ALGORITHM="rsa-sha256"

# Refuse unsafe private key permissions.
OPENDKIM_REQUIRE_SAFE_KEYS="yes"

# Remove old signatures before signing.
OPENDKIM_REMOVE_OLD_SIGNATURES="no"

# Add SoftwareHeader.
OPENDKIM_LOGRESULTS="yes"

# Milter debug level.
OPENDKIM_MILTER_DEBUG="6"

# Optional custom nameservers.
OPENDKIM_NAMESERVERS=""

Behavior

At startup the container:

• creates OpenDKIM runtime directories
• copies the mounted private key to /var/opendkim/dkim.private
• sets secure ownership and permissions on the copied key
• generates TrustedHosts, KeyTable, and SigningTable if they are empty
• generates /etc/opendkim.conf from environment variables
• starts OpenDKIM using /etc/opendkim.conf

Generated files

The entrypoint generates these files automatically:

/etc/opendkim.conf
/etc/opendkim/TrustedHosts
/etc/opendkim/KeyTable
/etc/opendkim/SigningTable
/var/opendkim/dkim.private

Default generated tables

For example, with:

OPENDKIM_DOMAIN=example.com
OPENDKIM_SELECTOR=dkim

the generated files look like this:

/etc/opendkim/KeyTable

dkim._domainkey.example.com example.com:dkim:/var/opendkim/dkim.private

/etc/opendkim/SigningTable

*@example.com dkim._domainkey.example.com

/etc/opendkim/TrustedHosts

127.0.0.1
localhost
127.0.0.0/8
192.168.0.0/16
172.16.0.0/12
10.0.0.0/8

Postfix example

Example Postfix settings when OpenDKIM runs in another container named opendkim:

smtpd_milters = inet:opendkim:8892
non_smtpd_milters = inet:opendkim:8892
milter_protocol = 6
milter_default_action = accept

Notes

• The private key must be mounted into the container at the path specified by OPENDKIM_KEYFILE.
• The entrypoint copies the private key to /var/opendkim/dkim.private and locks down permissions to 0600.
• OPENDKIM_TRUSTANCHORFILE is optional and is only written to config if the file exists.
• OPENDKIM_NAMESERVERS is optional and is only written to config if non-empty.
• OPENDKIM_DOMAIN="*" is allowed by the script, but for real signing setups you usually want a concrete domain such as example.com.
• The default socket is inet:8892@0.0.0.0, so map port 8892 unless you override OPENDKIM_SOCKET.
• The current entrypoint starts OpenDKIM with:

  ./usr/sbin/opendkim -x /etc/opendkim.conf
  syslogd -n -f /etc/rsyslog.d/stdout.conf
  

  so the image expects syslog configuration to be present.