The following software is required for MIMEDefang:

• A UNIX or UNIX-like operating system. MIMEDefang is known to run on Linux, FreeBSD, OpenBSD, NetBSD, Solaris, HP-UX, Tru64 UNIX, and AIX.
• Sendmail 8.12 or newer with Milter support, or Postfix with Milter support.
• Perl 5.8.9 or newer.
• The following Perl modules:
  • MIME::tools 5.420 or higher
  • IO::Stringy 1.212 or higher
  • MIME::Base64 2.11 or higher
  • MailTools 1.1401 or higher
  • Digest::SHA1 2.00 or higher
• (Optional) Other Perl modules like Mail::SpamAssassin
• A C compiler and C development environment

First, download MIMEDefang from the download page.

Next, unpack the MIMEDefang tar file and follow the instructions in the README file.
Depending on how your Sendmail binary was compiled, you may need to recompile it to add Milter support.
Note that modern systems Milter support included in their versions of Sendmail.

Please note that you need a UNIX or UNIX-like system with Perl and a C development environment to install MIMEDefang from source.

The MIMEDefang system consists of three main programs:

• mimedefang is a C “Milter” program. It talks directly to Sendmail using the multi-threaded Milter library.
• mimedefang-multiplexor is a C program that accepts requests from mimedefang and forwards them to one of a pool of slave Perl processes.
• mimedefang.pl is a Perl program that does the actual mail filtering. The multiplexor manages a pool of these processes, forwarding idle processes work and reading the results.

A complete description of the architecture may be found in the PDF presentation slides.

Symptom: When you build MIMEDefang, it detects SpamAssassin just fine. But when you run it, it doesn’t seem to find the SpamAssassin Perl modules.

Probable Cause: This is often caused by a permissions problem. Make sure all of the SpamAssassin Perl modules and data files are world-readable.

Underlying Cause: What made the file permissions wrong in the first place? Some installation scripts will explicitly change the permissions on all files they install.
Others will just create the files, meaning they get created with whatever are the default permissions for the user.
Since most installs are done by root, you need to look at root’s umask setting to see what the default permissions are.

Symptom: Network-related SpamAssassin tests don’t seem to have any effect.

Probable Cause: These tests must be specially enabled when SpamAssassin is used in conjunction with MIMEDefang. To enable them, you must do two things:

1. Enable them in the file /etc/mail/spamassassin/sa-mimedefang.cf. MIMEDefang uses this file for its global SpamAssassin configuration.
2. In your filter, add the line: $SALocalTestsOnly = 0;

You may also need to add these lines to /etc/mail/spamassassin/sa-mimedefang.cf:

          use_dcc 1
          dcc_timeout 10
          dcc_path /usr/local/bin/dccproc

(Substitute appropriate paths for your system.)

Symptom: On log files there are some errors like Worker 1 stderr: Unable to convert text in character set GB18030 to UTF-8

Cause: This is almost certainly due to missing support in Perl installation for the GB18030 character encoding, a comprehensive encoding for Chinese characters.
That support requires the Encode::HanExtra module, which you can install via CPAN.

Symptom: I used action_add_header to add a new “To:” (or “Cc:” or “Bcc:”) field to a message,
or used action_change_header to change the “To:” field, but the message didn’t go where I thought it should.

Cause: Changing headers does not change the destination of the email message.
That is controlled by the envelope recipient(s) in the SMTP dialog.
You will have to use add_recipient and/or delete_recipient to change the destination for a message.

Symptom: I configured SpamAssassin to add the spam score to the subject, but it won’t do it.

Cause: When you run SpamAssassin under MIMEDefang, SpamAssassin cannot change the message in any way.
If you want to add any spam-related headers, you will have to do this in your rules file (mimedefang-filter).
Most people seem to do this in filter_end (after all parts have been checked for viruses).
The sample filter has code to call SA and add an X-Spam-Score: header to messages SA tags as spam.

If you want to change the subject, use something like this in filter_end:

          action_change_header('Subject', "***SPAM*** $Subject");

Symptom: I am running MIMEDefang, but now I am getting a lot of messages in my syslog that look like this:

Milter change: header MIME-Version: from 1.0 to 1.0

Cause: It is actually the Milter engine of sendmail that is logging all those. To reduce the amount of logging, try putting this line:

define(\confMILTER_LOG_LEVEL', `8')dnl`

in your sendmail.mc file and then re-generate your sendmail.cf.

MIMEDefang runs as the configured defang user, hence, SpamAssassin’s integration into MIMEDefang runs as this user, too.

In order to test the configuration use this command (as root):

su defang -s /bin/bash -c ‘spamassassin -x -p /etc/mail/sa-mimedefang.cf -D –lint’

• use the correct name for defang you have configured to run MIMEDefang under,
• use the correct path for the MIMEDefang-SpamAssassin configuration file /etc/mail/sa-mimedefang.cf
• -s /bin/bash ensures that su uses a valid shell, because normally the defang user does not need one
• instead of –lint you can pipe or redirect any message to check into this call, e.g.:
  su defang -s /bin/bash -c ‘spamassassin -x -p /etc/mail/sa-mimedefang.cf -D’ \< message

/bin/mount -t tmpfs -o size=500m,mode=0700,uid=${md_user},gid=${md_group} /dev/shm $md_spooldir

/dev/shm is provided in most newer Linux systems, maybe none works for you, too.

Adjust the size, of course.

Replace ${md_user} and ${md_group} with the appropriate UID and GID, in order to give MIMEDefang write permission to the directories.

Replace ${md_spooldir} with the directory specified with the --with-spooldir= option during the ./configure of MIMEDefang.

The idea is to have all temporary files of MIMEDefang been spooled on a very fast RAM disk. None of these files are required after SMTP phase is over. Hence, make sure that --with-quarantinedir= points somewhere else!

MIMEDefang communicates with Postfix via the Milter protocol. Postfix has supported Milter since version 2.3.

The MIMEDefang system uses two separate sockets:

• The Milter socket is created by mimedefang (the C milter daemon) and is the one Postfix connects to. It is configured with the -p option of mimedefang.
• The multiplexor socket is created by mimedefang-multiplexor and is used for communication between mimedefang and the Perl worker pool. It is configured with the -s option of mimedefang-multiplexor and referenced by the -m option of mimedefang.

Step 1: Set the milter socket when starting mimedefang-multiplexor and mimedefang. For example:

mimedefang-multiplexor -s /var/spool/MIMEDefang/mx.sock [other options]
mimedefang -p unix:/var/spool/MIMEDefang/mimedefang.sock \
           -m /var/spool/MIMEDefang/mx.sock \
           -U defang [other options]

Refer to mimedefang(8) and mimedefang-multiplexor(8) for the full list of options. If you installed MIMEDefang from a distribution package, the startup script or systemd unit file already sets these parameters via a configuration file. On RPM-based systems that file may be present at /etc/sysconfig/mimedefang; on Debian-based systems it may be at /etc/default/mimedefang. If the file exists, set the socket paths there rather than editing the startup script directly.

Step 2: Add the following lines to /etc/postfix/main.cf, using the same path you passed to mimedefang -p:

smtpd_milters = unix:/var/spool/MIMEDefang/mimedefang.sock
non_smtpd_milters = unix:/var/spool/MIMEDefang/mimedefang.sock
milter_default_action = accept

• smtpd_milters applies the filter to mail received via the SMTP daemon.
• non_smtpd_milters applies the filter to locally-submitted mail (e.g. from sendmail(1)). Omit this line if you only want to filter inbound SMTP mail.
• milter_default_action = accept instructs Postfix to accept mail if MIMEDefang is temporarily unavailable, preventing mail loss during restarts.

Step 3: Ensure the postfix user (or the user Postfix runs as) has read permission on the MIMEDefang spool directory so it can connect to the milter socket.

Step 4: Reload Postfix:

postfix reload

OpenSMTPD has supported the Milter protocol since version 6.7.0. MIMEDefang can be used as a Milter filter with OpenSMTPD.

The socket OpenSMTPD connects to is the Milter socket created by mimedefang. It is set via the -p option of mimedefang (not via a wrapper-script variable). The separate multiplexor socket (used internally between mimedefang and its Perl workers) is set via -s on mimedefang-multiplexor and -m on mimedefang. See mimedefang(8) and mimedefang-multiplexor(8) for details.

Step 1: Start mimedefang-multiplexor and mimedefang with explicit socket paths, for example:

mimedefang-multiplexor -s /var/spool/MIMEDefang/mx.sock [other options]
mimedefang -p unix:/var/spool/MIMEDefang/mimedefang.sock \
           -m /var/spool/MIMEDefang/mx.sock \
           -U defang [other options]

If you installed from a distribution package, a configuration file may already be present at /etc/sysconfig/mimedefang (RPM-based systems) or /etc/default/mimedefang (Debian-based systems). If it exists, set the socket paths there rather than editing the startup script directly.

Step 2: Add a filter definition to /etc/mail/smtpd.conf, using the same path passed to mimedefang -p:

filter mimedefang proc-exec "filter-milter unix:/var/spool/MIMEDefang/mimedefang.sock"

If your OpenSMTPD version uses the older filter syntax (6.7.x), declare the Milter filter with:

filter mimedefang milter socket "unix:/var/spool/MIMEDefang/mimedefang.sock"

Step 3: Apply the filter to your SMTP listener(s):

listen on all filter mimedefang

Step 4: Ensure the _smtpd user has read/write access to the MIMEDefang socket directory.

Step 5: Check and reload the configuration:

smtpd -n && rcctl reload smtpd

Note that OpenSMTPD's Milter support covers a subset of the full Milter API. Features that rely on SMFIF_CHGFROM (envelope sender rewriting) or SMFIF_ADDRCPT_PAR may not be available on all OpenSMTPD versions.

Modern Linux distributions and BSDs ship MIMEDefang as a ready-to-install package, so you do not need a C compiler or manual source compilation. Milter support is also enabled by default in the Sendmail and Postfix packages on these systems.

Fedora / RHEL 9+ / AlmaLinux / Rocky Linux

dnf install mimedefang

On RHEL 8 and CentOS Stream 8, enable EPEL first:

dnf install epel-release
dnf install mimedefang

Debian / Ubuntu

apt install mimedefang

FreeBSD

Install from ports:

cd /usr/ports/mail/mimedefang && make install clean

Or with pkg:

pkg install mimedefang

OpenBSD

pkg_add mimedefang

After installation

Enable and start the service with your system's service manager (e.g. systemctl enable --now mimedefang on systemd-based systems, or rcctl enable mimedefang on OpenBSD).

Edit the filter script at /etc/mail/mimedefang-filter (or the path shown by mimedefang -help) to suit your site's policy, then connect MIMEDefang to your MTA as described in the Postfix or Sendmail integration FAQs.

Yes, for Postfix and Sendmail. Official MIMEDefang Docker images are published on Docker Hub, one per supported MTA:

• mimedefang/postfix
• mimedefang/sendmail

Pull the latest image:

docker pull mimedefang/postfix
docker pull mimedefang/sendmail

The images are suitable for running MIMEDefang in containerized environments. Refer to the image page on Docker Hub for available tags, environment variables, and volume mount points.

OpenSMTPD is also a supported MTA, but no Docker image is published for it yet.