Skip to content

technicalguru/docker-mailserver-opendkim

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

32 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

docker-mailserver-opendkim

This is a Docker image for an OpenDKIM milter server. The project is part of the docker-mailserver project but can run separately without the other components. However, a database server is always required to store keys and configuration.

Related images:

Tags

The following versions are available from DockerHub. The image tag matches the Postfix version.

Features

  • Bootstrap from scratch: See more information below.
  • DKIM signing and verification
  • Key creation (under development, see open issues)
  • Key storage in database

License

docker-mailserver-opendkim is licensed under GNU LGPL 3.0. As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained).

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.

Prerequisites

The following components must be available at runtime:

Usage

Environment Variables

mailserver-opendkim requires various environment variables to be set. The container startup will fail when the setup is incomplete.

Variable Description Default Value
DKIM_SETUP_PASS The password of the database administrator (root). This value is required for the initial bootstrap only in order to setup the database structure. It can and shall be removed after successful setup.
DKIM_DB_HOST The hostname or IP address of the database server localhost
DKIM_DB_USER The name of the database user. Attention! You shall not use an administrator account. opendkim
DKIM_DB_PASS The password of the database user opendkim
DKIM_DB_NAME The name of the database opendkim
DKIM_DOMAIN The first and primary mail domain of this server. localdomain
DKIM_PORT The milter port the docker image shall offer its service 41001

Ports

docker-mailserver-opendkim exposes 2 ports by default:

  • Port 80 - A webserver port that will provide a Key Management service in later stages. Currently it does not provide anything but a static page.
  • Port 41001 - the DKIM signing and verification port

Running the Container

The main mailserver project has examples of container configurations:

Bootstrap and Setup

Once you have started your OpenDKIM container successfully, it is now time to create your DKIM signing keys for each domain. This is what you need to do:

  1. Login to the container by executing /bin/bash interactively on the container.
  2. For each of your domains DOMAIN perform the following steps:
    1. Create a temporary directory: mkdir /etc/opendkim/keys/$DOMAIN

    2. Create the actual key: opendkim-genkey -b 2048 -d $DOMAIN -D /etc/opendkim/keys/$DOMAIN -s default -v. You will find public and private key in the temporary directory.

    3. Insert public and private key into your database by signing in: mysql -u opendkim -p opendkim and enter your database password. Then enter these SQL statement and hit enter for each of them:

      INSERT INTO `dkim_keys` (`domain_name`, `selector`, `private_key`, `public_key`) VALUES ('$DOMAIN', 'default', '-----BEGIN RSA PRIVATE KEY-----\r\n***$YOUR_PRIVATE_KEY*** \r\n-----END RSA PRIVATE KEY-----', '-----BEGIN RSA PUBLIC KEY-----\r\n***$YOUR_PUBLIC_KEY***-----END RSA PUBLIC KEY-----');`
      SELECT `id` FROM `dkim_keys` WHERE `domain_name` = '$DOMAIN'; 
      INSERT INTO `dkim_signing` (`author`, `dkim_id`) VALUES ('$DOMAIN', $KEYID_FROM_SELECT);
      INSERT INTO `ignore_list` (`hostname`) VALUES ('*@$DOMAIN');
      INSERT INTO `internal_hosts` (`hostname`) VALUES ('*@$DOMAIN');
      
    4. Insert the Public Key as described by step 2 output into your DNS TXT record for the domain. It can look like this:

      v=DKIM1; h=sha256; k=rsa; p=***PUBLIC_KEY_WITHOUT_SPACE_OR_NEWLINE***
      

      The TXT record needs to be named default._domainkey.$DOMAIN - the default can be varied when using a different value in SQL statement in step 3. This would enable you to use different keys e.g. for subdomains and individual mail addresses. You would need to change the SQL commands accordingly (Table dkim_keys decides which key will be used. You can use full mail addresses in column author then.)

Additional OpenDKIM customization

You can further customize the OpenDKIM configuration files. Please follow these instructions:

  1. Check the /usr/local/mailserver/templates folder for already existing customizations.
  2. Customize your OpenDKIM configuration file.
  3. Provide your customized file back into the appropriate template folder at /usr/local/mailserver/templates by using volume mappings.
  4. (Re)Start the container. If you configuration was not copied correctly then log into the container (bash is available) and issue /usr/local/mailserver/reset-server.sh. Then restart again.

Testing your DKIM setup.

Here are some useful links that help you to test whether your DKIM setup works as intended:

  • DMARC DKIM Record Checker - checks correctness of your DNS TXT entry
  • DKIM Check - verifies your DKIM signing feature by giving you a temporary recipient address where you send a test mail

Issues

This Docker image is mature in its DKIM signing and verification feature. However, creation of DKIM keys is still cumbersome and needs to be improved. A web page service is planned to ease that step.

Contribution

Report a bug, request an enhancement or pull request at the GitHub Issue Tracker. Make sure you have checked out the Contribution Guideline