Documentation

Plugins

Client libraries

Publishing

FAQs


Karmasphere Sendmail Plugin: Sendmail milter

Introduction

Karmamilter is a Sendmail milter that performs reputation checks on identities in email messages using Karmasphere .

In this version, a single query per email is issued to Karmasphere, inquiring about one or more of:

  1. The Client IP address
  2. HELO domain
  3. The From address

When Karmamilter has processed an email, it creates a header field X-Karma to store the result. This field can be used, for example, by your antispam tools to inform them whether or not the email is from a reputable source.

Requirements

  1. A C toolchain (compiler, linker, etc).
  2. libkarmaclient.
  3. sendmail with milter support. Check the milter support in sendmail with: 
    $ /usr/sbin/sendmail -d0.4 -bp
Version 8.13.5
 Compiled with: DNSMAP LDAPMAP LDAP_REFERRALS LOG MAP_REGEX MATCHGECOS
 		MILTER MIME7TO8 MIME8TO7 NAMED_BIND NETINET NETINET6
		NETUNIX
		...
  4. A Karmasphere account with query credentials.
  5. Network access to query.karmasphere.com on port 8666 UDP (or TCP if run in TCP mode).

Compilation

  1. Ensure that libkarmaclient is installed.
  2. Download the latest karmamilter.
  3. Run the following commands: 
    tar -zxvf karmamilter-<version>.tar.gz
cd karmamilter-<version>
./configure
make
  4. Ensure that there were no errors in the build.
  5. Become root if necessary, and type: 
    make install

Configuring sendmail

There are two methods for configuring sendmail, either with the M4 configuration system or by hand. The M4 system is much simpler, but if you don't have the m4 source (the .mc file) then you need to edit the .cf by hand. This is a little bit more involved, but shouldn't be too hard.

Configuring sendmail using the M4 system

  1. Edit your sendmail.mc file and add the following line: 
    INPUT_MAIL_FILTER(`karmamilter', `S=local:/var/run/milter/karmamilter.sock')
  2. The following code is also recommended but not required: 
    dnl
dnl Disables VRFY, EXPN, requires HELO, no return receipts,
dnl bounce messages without message body. The important one
dnl required by milter-sender is `goaway'. The others are
dnl recommended.
dnl
define(`confPRIVACY_FLAGS',`goaway,noreceipts,nobodyreturn')
  3. Rebuild your sendmail configuration using make, and install the new configuration file if necessary.
  4. Make sure to start the milter (see below) before restarting sendmail.

Some systems (such as Debian) provide a sendmailconfig script which scans and re-buils the .cf file based on all of the input files, so you can try using that instead.

Configuring sendmail manually

  1. Put the following lines somewhere in the Options section (lines beginning with O). 
    # Input mail filters
O InputMailFilters=karmamilter

# Milter options
#O Milter.LogLevel
O Milter.macros.connect=j, _, {daemon_name}, {if_name}, {if_addr}
O Milter.macros.helo={tls_version}, {cipher}, {cipher_bits}, {cert_subject}, {cert_issuer}
O Milter.macros.envfrom=i, {auth_type}, {auth_authen}, {auth_ssf}, {auth_author}, {mail_mailer}, {mail_host}, {mail_addr}
O Milter.macros.envrcpt={rcpt_mailer}, {rcpt_host}, {rcpt_addr}
O Milter.macros.eom={msg_id}
  2. Add the following line between the rulesets and mailer definitions (above the first M line). 
    Xkarmamilter, S=local:/var/run/milter/karmamilter.sock
  3. Make sure to start the milter (see below) before restarting sendmail.

Usage

Start the milter:

./karmamilter -f karmasphere.email-sender -u milter

This will contact the public karmasphere query servers at query.karmasphere.com, UDP port 8666. Run ./karmamilter -h for a summary of all supported options, including how to use an alternative karmasphere query server. For full usage notes, see the command-line options below.

Restart sendmail (the command for your system may vary):

/etc/init.d/sendmail restart

Testing

Testing is optional but recommended.

Telnet to the mailserver on TCP port 25 and use SMTP commands (RFC2821) to send a message. The machine must either relay for the location from which you're sending, or alternatively the message should be destined for that host itself. (i.e. you don't want to evoke a "550 Relaying denied" response). A sample session is shown below.

HELO a-machine.some.where
MAIL FROM: <your@from-addre.ss>
RCPT TO: <recipient@domain.com>
DATA
From: Karmasphere Test <your@from-addre.ss>
To:  Karmasphere <recipient@domain.com>
Subject: Testing the Karmasphere milter

This sentence would be six words long if it were seven words shorter.
.
QUIT

Things you may check include:

  1. Check that MAIL FROM and RCPT TO get a 2xx response.
  2. Check that DATA gets a 354 response.
  3. Check that . gets a 2xx response.
  4. Check that the message in the recipient mailbox contains the header X-Karma: ... when you select 'view all message headers' in your mail reader

Troubleshooting

The milter hangs or times out.
By default, the milter needs to make connections to query.karmasphere.com on port 8666 UDP (or TCP if running in TCP mode. Some firewalls do not handle UDP very well, and so TCP may work better. Check that this port is open and that you can connect to query.karmasphere.com (use telnet).

Command-line options

 
./karmamilter [flags] [socket]

The default socket is /var/run/milter/karmamilter.sock. Alternative locations for the socket may be specified in any of the following forms:

  1. A named pipe: {unix|local}:/path/to/file
  2. An IPv4 socket: inet:port@{hostname|ip-address}
  3. An IPv6 socket: inet6:port@{hostname|ip-address}
-f <feedset>
--feedset=<feed>
Feedset identifier to query. This specifies both feeds, ruleset and combiner at once.
-F <feed>[,<feed> ...]
--feeds=<feed>[,<feed> ...]
Feed ids to query. The use of a feedset makes this option unnecessary.
-C <name>
--combiner=<name>
Combiner name to use. The use of a feedset makes this option unnecessary.
-d [<amount>]
--debug=[<amount>]
Enable more verbose debugging. Currently, this setting is unused.
-h
--help
Show this help.
-H <hostname>
--host=<hostname>
Hostname of the reputation database to query. This may be a hostname or an IPv4 address. IPv6 is not yet supported. The default is query.karmasphere.com.
-p <filename>
--pidfile=<filename>
Write the process id to the specified file. The default pidfile is /var/run/milter/karmamilter.pid
-l <username>
--login=<username>
Username to perform queries as. This is optional if you're querying a public feedset. See the client configuration page and the query authentication FAQ. Note that this username is different from the email address you use to sign in to the website.
-c <password>
--credential=<password>
Password to go along with the username above.
-P <portnum>
--port=<portnum>
Port number of the reputation database to query. The default is 8666.
-t
--tcp
Use TCP for communication with the karmaserver.
-u <user|uid>
--user=<user|uid>
Run as specified user or UID. By default, privileges are not dropped, but if this option is given, privileges will be dropped immediately after option parsing, and before the creation of the PID file or the socket.
-X
--nodaemon
Do not fork into the background or daemonize.

License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.