opendkim-docker/README.md

# Building the image
```sh
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.

```sh
# 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:

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

Example DNS record name:

```txt
dkim._domainkey.example.com
```

# Running the image
```sh
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:

```sh
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.

```sh
# 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:

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

# Default generated tables
For example, with:

```sh
OPENDKIM_DOMAIN=example.com
OPENDKIM_SELECTOR=dkim
```

the generated files look like this:

## /etc/opendkim/KeyTable
```txt
dkim._domainkey.example.com example.com:dkim:/var/opendkim/dkim.private
```

## /etc/opendkim/SigningTable
```txt
*@example.com dkim._domainkey.example.com
```

## /etc/opendkim/TrustedHosts
```txt
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`:

```conf
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:
  ```sh
  ./usr/sbin/opendkim -x /etc/opendkim.conf
  syslogd -n -f /etc/rsyslog.d/stdout.conf
  ```
  so the image expects syslog configuration to be present.