			INSTALLING OPENDKIM


OVERVIEW
========

To install opendkim as a milter filter for your MTA:

  * Install the prerequisites listed below.
  * Build opendkim with CMake.
  * Configure opendkim for signing and/or verification.
  * Configure your MTA to connect to the opendkim socket.
  * Enable and start the opendkim service.

"OpenDKIM" is the package, containing the library (libopendkim), the
filter daemon (opendkim), and supporting tools.  "opendkim" is the
milter filter daemon within that package.

libopendkim is a C library for building DKIM-aware applications.  Its
API is documented in the HTML files under docs/.

The opendkim filter works with any MTA that supports the milter protocol,
including Sendmail and Postfix.


PREREQUISITES
=============

Required:

  * A C17-capable compiler: GCC 8+ or Clang 5+
  * CMake >= 3.20
  * OpenSSL >= 3.0, or LibreSSL >= 3.7  (dynamically linked against the
    system library; LibreSSL is the base libcrypto on OpenBSD)
  * LMDB
  * libmilter  (from Sendmail or as a standalone package)
  * libresolv
  * libidn2      -- RFC 8616 U-label (IDN) signing-domain resolution
                    (-DWITH_IDN=ON, default on; -DWITH_IDN=OFF to omit)

Optional:

  * Lua 5.4      -- policy scripting hooks and data set scripts
                    (-DWITH_LUA=ON; also enables miltertest)
  * libunbound   -- DNSSEC-aware DNS resolution (-DWITH_UNBOUND=ON)
  * libsystemd   -- systemd Type=notify readiness + watchdog
                    (-DWITH_SYSTEMD; auto-detected on Linux)
  * libbsd       -- provides strlcpy/strlcat on older Linux systems
                    (not needed on glibc 2.38+, FreeBSD, or OpenBSD)

Installing prerequisites on common platforms:

  Debian / Ubuntu:
    apt install build-essential cmake libssl-dev liblmdb-dev \
                libmilter-dev liblua5.4-dev libidn2-dev libunbound-dev \
                libsystemd-dev

  RHEL / AlmaLinux / Rocky:
    dnf install gcc cmake openssl-devel lmdb-devel sendmail-devel \
                lua-devel libidn2-devel unbound-devel systemd-devel

  FreeBSD:
    pkg install cmake openssl lmdb milter lua54 libidn2 unbound


BUILDING
========

(1) Obtain the source.  Either clone the repository:

      git clone https://github.com/edmundlod/opendkim-ng.git
      cd opendkim-ng

    or unpack a release archive:

      tar -xzf opendkim-ng-<version>.tar.gz
      cd opendkim-ng-<version>

(2) Configure the build:

      cmake -B build

    Common configuration options:

      -DSSL_PROVIDER=auto        Crypto provider: auto (system default --
                                 OpenSSL on Linux, LibreSSL on OpenBSD),
                                 openssl, or libressl.  Non-auto values
                                 validate the located library is that provider.
      -DSSL_ROOT_DIR=<prefix>    Build against a non-default OpenSSL/LibreSSL
                                 install -- e.g. a side-installed LibreSSL, or
                                 an OpenSSL 4 prefix for compat testing:
                                   -DSSL_PROVIDER=openssl -DSSL_ROOT_DIR=/opt/openssl-4
      -DWITH_LUA=ON              Enable Lua 5.4 scripting (default: OFF)
      -DWITH_UNBOUND=ON          Enable DNSSEC resolver (default: ON)
      -DWITH_SYSTEMD=ON          Require systemd sd_notify support; configure
                                 fails if libsystemd is absent.  Default AUTO
                                 detects it; OFF disables it.
      -DCMAKE_BUILD_TYPE=Release Production build without debug symbols
      -DCMAKE_INSTALL_PREFIX=/   Installation prefix (default: /usr/local)

    Example with all options:

      cmake -B build \
            -DWITH_LUA=ON \
            -DWITH_UNBOUND=ON \
            -DCMAKE_BUILD_TYPE=Release

(3) Compile:

      cmake --build build

(4) Run the test suite (optional but recommended):

      ctest --test-dir build

(5) Install (requires appropriate privileges):

      cmake --install build

    On most Linux systems the defaults install to /usr/local.  To install
    to /usr instead:

      cmake -B build -DCMAKE_INSTALL_PREFIX=/usr
      cmake --install build


WHAT GETS INSTALLED
===================

  /usr/local/sbin/opendkim
  /usr/local/sbin/opendkim-genkey
  /usr/local/sbin/opendkim-testkey
  /usr/local/sbin/opendkim-genzone
  /usr/local/lib/libopendkim.so (and associated files)
  /usr/local/include/opendkim/dkim.h
  /usr/local/share/man/man5/opendkim.conf.5
  /usr/local/share/man/man8/opendkim.8
  /usr/local/share/man/man8/opendkim-genkey.8
  /usr/local/share/man/man8/opendkim-testkey.8
  /usr/local/share/man/man8/opendkim-genzone.8
  /etc/opendkim/opendkim.conf.sample
  /usr/lib/systemd/system/opendkim.service  (Linux with systemd)


NEXT STEPS
==========

See opendkim/README.md for instructions on generating keys, publishing
DNS records, and configuring the filter for your mail server.

See opendkim.conf(5) for the full configuration reference.
