NAME
ispMailGate - a general purpose filtering MDA for sendmail
WARNING! WARNING! WARNING!
This is an alpha release! What you are using now is tested by
using a comparatively small test suite in our local environment.
You are perhaps planning to include this software in a
production environment. We don't discourage to do so, but we
strongly advise you to be extremely carefull. In particular,
start by filtering only mails for a very small number of email
adresses, perhaps your own and something similar. That is, be
extremely cautios when modifying your sendmail configuration.
See INSTALLATION and SENDMAIL CONFIGURATION below for a detailed
description of your sendmail setup.
SYNOPSIS
For running standalone:
ispMailGateD -f <sender> <recipient1> [... <recipientN>]
For running as a daemon (not yet possible, as the wrapper is
still missing):
ispMailGateD -s [-d] [-t <tmpdir>] [-a <facility>] [-p <pidfile>]
[-u <unixsock>]
DESCRIPTION
IspMailGate is a general purpose email filtering system. The
program gets included into a sendmail configuration as a
delivery agent (MDA) and the usual sendmail rules can be applied
for deciding which emails to feed into ispMailGate. The true
filters are implemented as modules, so its easy to extend the
possibilities of ispMailGate. Current modules offer automatic
compression and decompression, encryption, decryption and
certification with PGP or virus scanning.
The program can run in a usual standalone mode, but that's not
recommended, except for debugging and similar tasks. The
recommended mode will be running the program as a server,
completely independent from sendmail. A small C program (called
a wrapper) will instead be configured as sendmails MDA. This
wrapper connects to the server via a well known Unix socket (by
default ), passes its command line arguments and standard input
to the server and disconnects. Obviously this second solution
has much better performance as you load the Perl interpreter
only once.
Unfortunately the wrapper is not yet available, due to some
problems with Perl's I/O. (Perl won't notice EOF on the socket
as long as the client doesn't close the connection. On the other
hand the client has to hold the connection open for receiving
error messages which will be written to stderr so that sendmail
recognizes them. We are thankfull for any suggestion to solve
this.
Command Line Interface
The following options affect ispMailGate's behaviour:
-a <fac>, -facilty <fac>, --facility <fac>
Advices the ispMailGate to use syslog facility <fac>. By
default syslog entries are written as facility mail.
-d, -debug, --debug
The program runs in debugging mode, logging information into
the syslog. Perhaps more information than you like ... :-)
-f <sender>, -from <sender>, --from <sender>
Sets a mails sender.
-s, -server, --server
Tells the program not to run in standalone mode and instead
detach from the shell to enter server mode. This mode is
currently not usable, as the wrapper is not yet available.
-t <dir>, -tmpdir <dir>, --tmpdir <dir>
Sets the programs directory for temporary files to <dir>.
When unpacking a complex and big multipart mail, the
ispMailGate may need surprisingly much space. By default
/var/spool/ispmailgate is used.
-u <sock>, -unixsock <sock>, --unixsocket <sock>
Tells the server to listen on file <sock> for unix socket
connections. By default the server uses
/var/run/ispMailGate.sock.
INSTALLATION
Requirements
To start with the requirements: You need
1.) A running sendmail (recommended: 8.8.5 or later); if you
don't have sendmail or an older version, you find the current
release at
ftp://ftp.sendmail.org/pub/sendmail
2.) A late version of Perl (recommended: 5.004 or later); if you
don't have Perl, shoot yourself in the foot (;-) or get it from
any CPAN mirror, for example
ftp://ftp.funet.fi/pub/languages/perl/CPAN/src/5.0
3.) The MIME-tools module (version 4.116 or later), its
prerequired modules (MailTools, MIME-Base64 and IO-Stringy) and
the IO::Tee module (version 0.61 or later). All these modules
are available from any CPAN mirror, for example
ftp://ftp.funet.fi/pub/languages/perl/CPAN/modules/Mail
ftp://ftp.funet.fi/pub/languages/perl/CPAN/modules/MIME
ftp://ftp.funet.fi/pub/languages/perl/CPAN/modules/IO
Installing a Perl module is quite easy, btw. Either you use the
automatic CPAN interface (requires an Internet connection or
something similar) by executing
perl -MCPAN -e shell
or you fetch the modules with FTP, extract the tar.gz files, go
into the distribution directory (for example MIME-tools-4.116)
and do a
perl Makefile.PL
make
make test
make install
You'll like it! :-)
System preparation
Although ispMailGate is usually started as root, because certain
initialization setting need root permissions, it must not
continue running as root. Instead it impersonates itself to a
user ID that you select. I recommend creating a separate user
`ispmailgate' and a separate group `ispmailgate'.
IspMailGate needs its own directory for creating temporary
files. Usually this could be `/var/spool/IspMailGate' or
something similar. Make sure that the ispmailgate user (but
noone else) has access to this directory:
mkdir /var/spool/IspMailGate
chown ispmailgate /var/spool/IspMailGate
chgrp ispmailgate /var/spool/IspMailGate
chmod 700 /var/spool/IspMailGate
Program installation
The program is installable like any other Perl module. However,
you cannot use the automatic CPAN installation in that case.
Instead, fetch the current archive from any CPAN mirror, for
example
ftp://ftp.funet.fi/pub/languages/perl/CPAN/authors/id/JWIED
extract the archive with
gzip -cd Mail-IspMailGate-<version>.tar.gz | tar xf -
After that, do a
cd Mail-IspMailGate-<version>
and start with editing the Configuration module
lib/Mail/IspMailGate/Config.pm
In particular you might like to modify the installation
directories. For example, to install into
/usr/local/IspMailGate/sbin, /usr/local/IspMailGate/lib and so
on, you'd change the variable
$PREFIX = "/usr/local/IspMailGate";
For a detailed description of the configuration file see the
section on "CONFIGURATION FILE" below. Once this is done,
install the program with
perl -Ilib Makefile.PL
make
make test
make install
Finally make sure that the ispMailGate binary can connect to the
server. Assuming that you have installed in
/usr/local/IspMailGate and that your sendmail is running as
group `mail', do the following:
chown ispmailgate /usr/local/IspMailGate/sbin/ispMailGate
chgrp mail /usr/local/IspMailGate/sbin/ispMailGate
chmod 4750 /usr/local/IspMailGate/sbin/ispMailGate
SENDMAIL CONFIGURATION
Before modifying your sendmail configuration, think about the
following: The crucial problem of using IspMailGate without
damage is that you are working in a number of different steps.
For example:
second sendmail.cf
In the first step you leave your /etc/sendmail.cf completely
untouched. Instead you create a second file
/etc/sendmail.cf.new, create files containing email messages
(for example by saving them from your preferred email
client) and then feed them into sendmail by using the
following command:
cat mymail | sendmail -v -i -f<sender> <recipient>
single user action
If the first step seems to look good, you can go on
modifying your true sendmail.cf. But don't let all mails be
filtered! Instead let sendmail filter only mails for or from
some selected people, that are aware of potential problems,
for example your own mail. (You know of things that might
happen, don't you? :-)
Stay in this stage for at least a week or two. Contact
different kind of people using all sort of email clients,
send them mails and advise them to reply with all possible
kinds of emails: Simple text documents, multipart messages,
word documents (interesting thing if you verify the virus
scanner ... ;-)
Final stage
Finally if all seems to be working well, you can enter the
final stage and do the things you really want.
Selecting the mails to feed into sendmail
The main problem with sendmail is that ruleset 0 (the set of
rules deciding about how to handle an email) decides by looking
at the recipient only. (At least I don't know of other
possibilities, perhaps someone can tell?) IspMailGate is smarter
and can make decisions based on both sender and recipients.
However, it cannot decide on mails that don't reach it, thus you
probably must feed mails into IspMailGate that aren't really
interesting for it. For example, if you have an IspMailGate rule
concerning mails sent from
[email protected] to *@perl.com then you
must feed all mails into IspMailGate that have *@perl.com as
recipient, regardless of the sender. IspMailGate fixes this
problem by just ignoring such mails and just feeding them back
into sendmail. However, a performance problem is still
remaining.
Another problem is, that IspMailGate rules are based on Perl
regular expressions. Of course they have a much finer
granularity than sendmail rules have, but that may rarely be a
problem in practice.
To sum it up: Sendmail must be configured to feed any mail into
IspMailGate that has a recipient which *might* receive a mail
that ought to be filtered via IspMailGate. In the extreme case
this can mean that sendmail must feed all email traffic into
IspMailGate before really delivering it.
Now for the real stuff. In what follows I assume some knowledge
of sendmail configuration. In particular you should be able to
configure sendmail based on m4 macros, a detailed explanation of
this process is contained in the file cf/README of the sendmail
sources. Additionally you should know the concept of sendmail
classes and how to work with them.
We start with creating a file that holds a new sendmail class,
called IMGR. The file might look as follows:
#
[email protected] is a possible IspMailGate recipient.
[email protected] :ispmailgate
# Any mail going to *@ispsoft.de will be feed into IspMailGate
@ispsoft.de :ispmailgate
# And finally *@*.uni-tuebingen.de
.uni-tuebingen.de :ispmailgate
In what follows I assume that this file is stored as
/etc/ispMailGateRecipients. Now we add the following section to
sendmail.mc:
define(`ISPMAILGATE_MAILER_PATH', `/usr/local/bin/ispMailGateD')
define(`ISPMAILGATE_MAILER_FLAGS', `fgmDFMu')
define(`ISPMAILGATE_MAILER_ARGS', `ispMailGateD $f $u')
MAILER_DEFINITIONS
##################################################
### IspMailGate Mailer specification ###
##################################################
Mispmailgate, P=ISPMAILGATE_MAILER_PATH, F=ISPMAILGATE_MAILER_FLAGS,
S=11/31, R=21/31, T=DNS/RFC822/X-Unix, A=ISPMAILGATE_MAILER_ARGS
LOCAL_CONFIG
KIMGR hash -o /etc/mail/ispMailGateRecipients
CPISPMAILGATE
LOCAL_RULE_0
# Make "user < @ host >" to "<user @ host > user < @ host . >"
R$* < @ $+ > $* $: < $1 @ $2 > $1 < @ $2 > $3
# At this point we might have "< user @ host . > user < @ host . >"
# Remove the dot from the host part, if any.
R< $+ . > $* < $+ > $* $: < $1 > $2 < $3 > $4
# Is "user@host" in /etc/mail/ispMailGateRecipients?
R< $* @ $+ > $* < $+ > $*
$: < $1 @ $2 $(IMGR $1 @ $2 $: $) > $3 < $4 > $5
# Is "@host" in /etc/mail/ispMailGateRecipients?
R< $* @ $+ > $* < $+ > $*
$: < $1 @ $2 $(IMGR @ $2 $: $) > $3 < $4 > $5
# Is "host" = "@any.domain" with "domain" in
# /etc/mail/ispMailGateRecipients?
R< $* @ $+ . $+ > $* < $+ > $*
$: < $1 @ $2 . $3 $(IMGR . $3 $: $) > $4 < $5 > $6
# Did any of the last three rules match? If so, call IspMailGate
R< $* @ $+ : ispmailgate > $* < $+ > $*
$# ispmailgate $@ $2 $: $1 < @ $2 >
# Remove the preceding < user @ host >
R< $* @ $+ > $* < $+ > $* $: $3 < $4 > $5
# Remove a .ISPMAILGATE, if present; call ruleset 3 for
# canonicalization
R$* < @ $+ .ISPMAILGATE. > $* $: $>3 $1 @ $2
If you do not know too much about sendmail.cf, you should at
least note the following: In the above example we have typically
three kinds of lines: Lines beginning with a '#' are comments.
The LOCAL_CONFIG and LOCAL_RULE_0 lines are m4 macros, the rest
are so-called sendmail rules. These consist of a left hand and a
right hand side (LHS and RHS), separated by tabs. If the lines
become too long, you may use continutation lines, starting with
a blank or tab. In the above example there are three rules using
line continuation: The LHS is on the first line, the RHS
(introduced with two tabs) is on the second line.
But what does the above example mean? For understanding that,
you have two know that sendmail starts with bringing the
recipient address into a canonical form, looking like
user<@host> other information
The host part might have a trailing dot, so the above may indeed
be
user<@host.> other information
So the first lines modify the above to
<user@host>user<@host> other information
or
<user@host>user<@host.> other information
The idea is that we work with the first part and may fall back
to the original information by just dropping the part
<user@host>.
The three rules using the IMGR map verify whether "user@host"
has a match in the recipient list of IspMailGate. If so, the RHS
of the map in /etc/mail/ispMailGateRecipients is added and we
receive
<user@host:ispmailgate>user<@host.> other information
which will be sent to the ispmailgate mailer. Finally the first
part is removed. But what does the last rule do?
When a mail is sent to IspMailGate, it may do something with the
mail, but finally it is passed back to sendmail for true
delivery. To avoid loops, we have to tell sendmail that the mail
must not be processed by IspMailGate a second time. To achieve
that we modify the recipient from user@host to
[email protected]. That guarantees, that the maps in
/etc/mail/ispMailGateRecipients don't match thus we are
guaranteed that the last rule of the above example will be
applied finally. All it does is removing this .ispmailgate, if
any. (Sometimes I agree, that sendmail configuration is a
tedious thing ...)
CONFIGURATION FILE
The program depends on a local configuration file, read as the
Mail::IspMailGate::Config module. In other words, this
configuration file is pure Perl code defining certain variables
under the name space Mail::IspMailGate::Config. The module is
read from the file /usr/local/IspMailGate-
1.002/lib/Mail/IspMailGate/Config.pm.
The following variables are meaningfull to the program:
$VERSION
The programs version; do not modify without a good reason.
$PREFIX
The installation prefix; typically the program files are
stored in the directories $PREFIX/sbin, $PREFIX/lib,
$PREFIX/man and so on. (Modifiable, see below.) The current
prefix is /usr/local/IspMailGate-1.002.
$LIBDIR
The directory where the program's own perl modules are
stored, currently /usr/local/IspMailGate-1.002/lib.
$SCRIPTDIR
A directory for storing the executable Perl files, currently
/usr/local/IspMailGate-1.002/sbin.
$MANDIR
The program's man pages are stored here, currently
/usr/local/IspMailGate-1.002/man.
$TMPDIR
Set's the default directory for creating temporary files,
currently /var/spool/ispmailgate. You can modify this with
the `--tmpdir' directive, see above.
$UNIXSOCK
The unix socket that the client connects to, currently
/var/run/ispMailGate.sock. You can use the `--unixsock'
argument for overwriting the default.
$PIDFILE
The PID file where a running server stores its PID,
currently /var/run/ispMailGate.pid. You can use the `--
pidfile' argument for overwriting the default.
$USER
$GROUP
IspMailGate is running as this user and group, daemon and
mail.
$MAILHOST
The host to use for passing mails after processing them by
the mail filter. By default 'localhost' is used, in other
words, the mails are immediately passed back to sendmail.
To omit a possible loop problem, sendmail must be ready for
handling email addresses like
[email protected]. For
such addresses it must rip off the .ispmailgate and
guarantee not to feed the mails back into ispMailGate. See
the section on "SENDMAIL CONFIGURATION" below.
@RECIPIENTS
A list of possible recipients/senders and filter lists that
describe how to handle mails being sent from the senders to
the recipients.
Each element of the list is a hash ref with the following
elements:
recipient
A regular expression (Perl regular expression, that is)
for matching the recipient address. An empty string
matches any recipient.
sender A regular expression (Perl regular expression, again) for
matching the sender address. An empty string matches any
sender.
filters An array ref to a list of filters. A mail will be fed into
that list (from the left to the right) and the final
result will be returned to sendmail. See the
Mail::IspMailGate::Filter(3) manpage for a description
of creating filters.
The recipient list will be read top to bottom, the first
match decides which rule to choose. See the example
configuration below for some example rules.
@DEFAULT_FILTER
If no element of the @RECIPIENTS list matches an emails
senders and recipients, the filters from this variable will
be choosen. By default it contains a dummy filter.
%PACKER
This variable belongs to the Packer module. See the
Mail::IspMailGate::Packer(3) manpage for details.
$VIRSCAN
%DEFLATER
$HAS_VIRUS
These belong to the VirScan module. See the
Mail::IspMailGate::VirScan(3) manpage.
$PGP_UID
$PGP_UIDS
$PGP_ENCRYPT_COMMAND
$PCP_DECRYPT_COMMAND
These belong to the PGP module. See the
Mail::IspMailGate::PGP(3) manpage for details.
Example Configuration
It might help to look at a commented example of the
configuration file:
# Yes, this is a module. Thus we have to introduce the file with
# forcing the modules namespace.
package Mail::IspMailGate::Config;
# We load the modules here that will later be used for
# creating recipient lists.
require Mail::IspMailGate::Filter::Packer;
require Mail::IspMailGate::Filter::Dummy;
require Mail::IspMailGate::Filter::VirScan;
require Mail::IspMailGate::Filter::PGP;
# Directory settings and the like
$VERSION = '1.000';
$PREFIX = "/usr/local/IspMailGate-${VERSION}";
$LIBDIR = "${PREFIX}/lib";
$ETCDIR = "${PREFIX}/etc";
$SCRIPTDIR = "${PREFIX}/sbin";
$MANDIR = "${PREFIX}/man";
$TMPDIR = '/var/spool/IspMailgate';
$UNIXSOCK = '/var/run/ispMailGate.sock';
$PIDFILE = '/var/run/ispMailGate.pid';
$USER = 'daemon';
$GROUP = 'mail';
$MAILHOST = 'localhost';
#
# The packer module's configuration
#
%PACKER = ( 'gzip' => { 'pos' => '/bin/gzip -c',
'neg' => '/bin/gzip -cd' } );
#
# The virus scanner's configuration
#
$VIRSCAN = '/usr/local/bin/virusx $ipaths';
@DEFLATER = ( { pattern => '\\.(tgz|tar\\.gz|tar\\.[zZ])$',
cmd => '/bin/gzip -cd $ipath | /bin/tar -xf -C $odir'
},
{ pattern => '\\.tar$',
cmd => '/bin/tar -xf -C $odir'
},
{ pattern => '\\.(gz|[zZ])$',
cmd => '/bin/gzip -cd $ipath >$opath'
},
{ pattern => '\\.zip$',
cmd => '/usr/bin/unzip $ifile -d $odir'
}
);
#
# sub which determines by a given string if a virus has been found.
# It returns a non-empty string if a virus has been found, else it
# returns ''
#
$HASVIRUS = sub ($) {
my($str) = @_;
if($str ne '') {
return "Virus has been found: $str";
} else {
return '';
}
};
#
# The list of recpients; first match will be used. Any recipient not
# matching one of the elements will be filtered through the
# DEFAULT_FILTER.
#
@DEFAULT_FILTER = (Mail::IspMailGate::Filter::Dummy->new({}));
#
# Now the list of email senders/recipients that will handled by the
# filter.
#
my($pgp) = 'Mail::IspMailGate::Filter::PGP';
my($packer) = 'Mail::IspMailGate::Filter::Packer';
@RECIPIENTS = (
# Mail to hamburg.company.com (our branch in Hamburg, say)
# will be compressed with gzip and encrypted with PGP, key
# 'stuttgart.company.com'
{ 'recipient' => '\\@muenchen\\.company\\.com$',
'filters' => [ $packer->new({'packer' => 'gzip',
'direction' => 'pos'}),
$pgp->new({'uid' => 'stuttgart\\.company\\.com',
'direction' => 'pos'}) ]
},
# The departure in munich doesn't use IspMailGate, but all
# clients have AK-Mail installed. Mail to muenchen.company.com
# (our branch in munich, say) will be encrypted with PGP, user
# ID 'stuttgart.company.com'.
{ 'recipient' => '\\@muenchen\\.company\\.com$',
'filters' => [ $pgp->new({'uid' => 'stuttgart\\.company\\.com',
'direction' => 'pos'}) ]
},
# Mail from muenchen.company.com or hamburg.company.com to
# stuttgart.company.com (incoming mail from the munich branch,
# say) will be decompressed and decrypted. Note we handle both
# sources with a single rule: The Packer module detects if a
# mail is not compressed.
{ 'recipient' => '\\@stuttgart\\.company\\.com',
'sender' => '\\@(muenchen|hamburg)\\.company\\.com',
'filters' => [ $packer->new({'direction' => 'neg'}),
$pgp->new({'direction' => 'neg'}) ]
},
#
[email protected] is a very special user. We send him an
# email bomb. (Filter to be being written. :-)
{ 'recipient' => 'joe\\@ispsoft\\.de'
'filters' => [ Mail::IspMailGate::Filter::Bomb->new({
'file' => 'X11R6.tar.gz' }) ]
}
);
1;
AUTHORS, COPYRIGHT AND LICENSE
This module is
Copyright (C) 1998 Amar Subramanian
Grundstr. 32
72810 Gomaringen
Germany
Email:
[email protected]
Phone: +49 7072 920696
and Jochen Wiedmann
Am Eisteich 9
72555 Metzingen
Germany
Email:
[email protected]
Phone: +49 7123 14887
All Rights Reserved.
Permission to use, copy and modify this software and its
documentation, is hereby granted to non-commercial entities
without fee, provided that this license information and
copyright notice appear in all copies.
A "non-commercial entity" is defined within the scope of this
license as an educational institution (excluding a commercial
training organisation), non-commercial research organisation,
registered charity, registered not-for-profit organisation, or
full-time student.
Use of this software by any other person or organisation for any
purpose requires that a usage license be obtained from the
authors for that person or organisation.
Commercial redistribution of this software, by itself or as part
of another application is allowed only under express written
permission of the authors.
AMAR SUBRAMANIAN AND JOCHEN WIEDMANN DISCLAIM ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL AMAR
SUBRAMANIAN OR JOCHEN WIEDMANN BE LIABLE FOR ANY SPECIAL,
INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
SOFTWARE.
The Plain English Version
You can use this software free of charge if you are an
educational institution (excluding commercial training
organisations), non-commercial research organisation, registered
charity, registered not-for-profit organisation, or full-time
student.
If you want to use it and you do not fit into any of the above
listed categories, you must register your copy using the invoice
form provided.
You cannot sell IspMailGate or bundle it with a product you
develop without obtaining written persmission and a "Commercial
Redistribution License" from us.
If something goes wrong and you lose data, system uptime, CPU
cycles, profits or anything else, neither of us is responsible.
The future of this license
It might well happen that this program will be distributed under
the GPL or the Perl Artistic License in a future version. Even
(Even? No, cut that word. :-) as professional software
developers we are using and recommending a lot of free software,
including sendmail, Perl or the MIME::Entity modules which are
the base of this product. We beg to understand, that we first
would like to be payed for the time we have put into
IspMailGate. We'll see what happens.
SEE ALSO
the Mail::IspMailGate::Filter(3) manpage, the
Mail::IspMailGate::Packer(3) manpage, the
Mail::IspMailGate::VirScan(3) manpage, the
Mail::IspMailGate::PGP(3) manpage and the MIME::Entity(3)
manpage
