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 careful. 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:
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 /var/run/ispmailgate.sock), 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.
Command Line Interface
The following options affect ispMailGate's behaviour:
--facility=<fac>
Advices the ispMailGate to use syslog facility <fac>. By
default syslog entries are written as facility mail.
--debug
The program runs in debugging mode, logging information into
the syslog. Perhaps more information than you like ... :-)
--from=<sender>
Sets a mails sender.
--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.
--tmp-dir=<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.
--unix-sock=<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.9.3 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 (5.005 or later); if you don't have
Perl, 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 settings need root permissions, it must not
continue running as root. Instead it impersonates itself to the
same UID and GID that sendmail uses for delivering mails. In
what follows, I assume UID *daemon* and GID <mail>, as used on a
Red Hat Linux box.
IspMailGate needs its own directory for creating temporary
files. Usually this could be `/var/spool/ispmailgate' or
something similar. Make sure that the daemon user from above,
(but noone else) has access to this directory:
mkdir /var/spool/ispmailgate
chown daemon /var/spool/ispmailgate
chgrp mail /var/spool/ispmailgate
chmod 700 /var/spool/ispmailgate
Program installation
The program is installable like any other Perl module. Indeed,
you can even use the automatic CPAN installation. If you are not
used to CPAN installation or cannot use the CPAN shell, you need
to perform a manual installation: First, fetch the archive from
any CPAN mirror, for example
ftp://ftp.funet.fi/pub/languages/perl/CPAN/authors/id/JWIED
and extract the archive with
gzip -cd Mail-IspMailGate-<version>.tar.gz | tar xf -
After that, do a
cd Mail-IspMailGate-<version>
and do a
perl Makefile.PL
make
make test # You need to be root here!
make install # You need to be root here!
While running "perl Makefile.PL", you'll be prompted a lot of
questions. In general you can answer them by simply hitting
return, the defaults should be fine. The questions are explained
in the section CONFIGURATION FILE below, because your answers
are used for creating this config file. the section on
"CONFIGURATION FILE".
If "make test" reports any errors, let me know.
SENDMAIL CONFIGURATION
To understand the required sendmail configuration, let's first
take a look at the following diagram:
+----------------+
| Incoming |
| mail for |
|
[email protected] |
+----------------+
|
| Port 25
| (SMTP)
|
+----------------------+ +---------------------+
| | | |
| Sendmail, with | | IspMailGate |
| IspMailGate support | ----> | receives and |
| integrated | | processes the mail |
| | | |
+----------------------+ +---------------------+
V |
|
+---------------------------+ | Port 26
| mailertable: | |
| ispsoft.de => ispmailgate | |
+---------------------------+ |
+-----------------------+
+-------------------------+ | |
| Other mailertable: | | Second sendmail, |
| ispsoft.de => mailhost | < | without IspMailGate, |
+-------------------------+ | other mailertable |
| |
+-----------------------+
The idea is that we have two sendmail instances: The first one
is accepting mails from the outside world (it could well be
smapd or another SMTP wrapper).
Mails accepted by the first instance will optionally be piped
into IspMailGate, depending on your mailertable or whatever
method you choose for selecting a delivery agent.
As soon as IspMailGate has processed your mails, they cannot be
delivered to the same sendmail: Sendmail would detect the same
recipients as before, and feed the mail back into IspMailGate.
The immediate result would be an endless loop.
Instead we configure another instance of sendmail, running for
example on port 26, which accepts mails by IspMailGate. This
second sendmail will typically be protected to the outside
world, for example by using a packet filter.
Of course it is possible to replace the second sendmail with a
mail server running on another machine. However, I discourage
you to do so, because IspMailGate has no integrated spooling
system: If the foreign host would be down, you mail would be
lost forever! However, you can easily configure the second
sendmail for delivery to the same host, this time using a safe
spooling system.
Details
Before reading on, you should have some basic knowledge on
sendmail configuration. In particular you should be used to work
with
sendmail.mc
the m4 macro file that is used to create sendmail.cf (If you
had the impression that hacking sendmail.cf is the method of
choice for configuring sendmail, your knowledge of sendmail
is a little bit too basic :-)
mailertable
the file that is used for selecting delivery agents, based
on a domain name
sendmail.cw
the file that is used for selecting "local" domains.
All these files are described in the file cf/README from the
sendmail distribution. The same file is available online as
sendmail documentation on
http://www.sendmail.org. I strongly
encourage you to read about it.
In what follows I assume that we have two hosts:
*gate.ispsoft.de* is a firewall running IspMailGate and two
instances of sendmail. *mail.ispsoft.de* is the real mail
server. Mail for the domain *ispsoft.de* shall be checked by
IspMailGate, passed to the second instance of sendmail and
finally delivered to the real mail server.
Furthermore I assume that the cf files from the sendmail
distribution are in /usr/lib/sendmail-cf. This is the case on a
Red Hat Linux box, if you have installed the RPM package
*sendmail-cf*. It may be /usr/share/sendmail with SuSE Linux or
anything else on another system.
First of all we copy the file examples/ispmailgate.m4 from the
IspMailGate distribution to /usr/lib/sendmail-cf/mailer. Then we
create the following files:
/etc/mail/sendmail.mc
divert(-1)
include(`/usr/lib/sendmail-cf/m4/cf.m4')
define(`confCW_FILE', `/etc/mail/sendmail.cw')
define(`ALIAS_FILE', `/etc/mail/aliases')
define(`QUEUE_DIR', `/var/spool/mqueue')
OSTYPE(`linux')
FEATURE(use_cw_file)
FEATURE(mailertable, `hash -o /etc/mail/mailertable')
FEATURE(virtusertable, `hash -o /etc/mail/virtusertable')
FEATURE(access_db)
MAILER(local)
MAILER(smtp)
MAILER(ispmailgate)
/etc/mail2/sendmail.mc
divert(-1)
include(`/usr/lib/sendmail-cf/m4/cf.m4')
define(`confCW_FILE', `/etc/mail/sendmail.cw')
define(`ALIAS_FILE', `/etc/mail/aliases')
define(`QUEUE_DIR', `/var/spool/mqueue2')
define(`confDAEMON_OPTIONS', `port=26')
OSTYPE(`linux')
FEATURE(use_cw_file)
FEATURE(mailertable, `hash -o /etc/mail2/mailertable')
FEATURE(virtusertable, `hash -o /etc/mail/virtusertable')
FEATURE(access_db)
MAILER(local)
MAILER(smtp)
You see, this is almost the same file, with three
exceptions:
1.) The first sendmail is running on the default port 25,
because it has no special port settings. The second
sendmail is running on port 26.
2.) The first sendmail is using /etc/mail/mailertable, the
second has /etc/mail2/mailertable.
3.) The second sendmail doesn't have a mailer ispmailgate.
4.) The first sendmail is using another spool directory,
/var/spool/mqueue2. (I am not sure, whether this is
required, however it doesn't harm, so let's be on the
safe side.)
/etc/mail/mailertable
ispsoft.de ispmailgate:ispsoft.de
/etc/mail2/mailertable
ispsoft.de ispmailgate:mail.ispsoft.de
You see, the only difference between these two instances of
mailertable is that the domain *ispsoft.de* is treated
different.
Finally we have to execute some commands to get this
configuration running:
mkdir /var/spool/mqueue2
# The following should match the settings of
# /var/spool/mqueue exactly.
chown root /var/spool/mqueue2
chgrp root /var/spool/mqueue2
chmod 755 /var/spool/mqueue
cd /etc/mail
m4 sendmail.mc >sendmail.cf
makemap hash mailertable <mailertable
cd /etc/mail2
m4 sendmail.mc >sendmail.cf
makemap hash mailertable <mailertable
The above is fine for Linux. On other operating systems you
might need to use GNU m4 rather than the builtin m4 and replace
the map type *hash* with *dbm*. In particular this applies to
Solaris.
Finally, kill any running sendmail and start the new versions
with
chmod 755 /etc/mail /etc/mail2
chmod 644 /etc/mail/sendmail.cf /etc/mail2/sendmail.cf
/usr/sbin/sendmail -C /etc/mail/sendmail.cf -bd -q1h
/usr/sbin/sendmail -C /etc/mail2/sendmail.cf -bd -q1h
(The chmod commands because sendmail is *really* picky about
group writable files and directories.)
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/lib/perl5/site_perl/5.005/Mail/IspMailGate/Config.pm.
The following variables are meaningful to the program:
VERSION
The programs version; do not modify without a good reason.
tmp_dir
Set's the default directory for creating temporary files,
currently /var/spool/ispmailgate. You can modify this with
the `--tmpdir' directive, see above.
unix_sock
The unix socket that the client connects to, currently
/var/run/ispmailgate.sock. You can use the `--unixsock'
argument for overwriting the default.
pid_file
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.
mail_user
mail_group
IspMailGate is running as this user and group, by default
daemon and mail.
mail_host
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
An array ref with 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:
$cfg->{'default_filter'} = ['Mail::IspMailGate::Filter::Dummy'];
packer
This variable belongs to the Packer module. See the
Mail::IspMailGate::Packer(3) manpage for details.
virscan
These belong to the VirScan module. See the
Mail::IspMailGate::VirScan(3) manpage for details.
pgp This variable 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:
package Mail::IspMailGate::Config;
$Mail::IspMailGate::Config::config = bless( {
# Config file version
'VERSION' => '1.100',
# Path of external virus scanner or empty
'antivir_path' => '/usr/bin/antivir',
# List of filters to use by default
'default_filter' => [
'Mail::IspMailGate::Filter::Dummy'
],
# Facility to use for syslog
'facility' => 'mail',
# Path of the gzip binary (for extracting .gz files) or empty
'gzip_path' => '/usr/bin/gzip',
# Path of the LhA binary (for extracting .lha files) or empty
'lha_path' => '',
# GID under which sendmail is executing external binaries
'mail_group' => 'mail',
# Mail host (with optional :port) to use for final delivery
'mail_host' => 'localhost:26',
# UID under which sendmail is executing external binaries
'mail_user' => 'daemon',
# Configuration of the packer
'packer' => {
'gzip' => {
'neg' => '$gzip_path -cd',
'pos' => '$gzip_path -c'
}
},
# PID file to use for the server
'pid_file' => '/var/run/ispmailgate.pid',
# E-Mail address of the administrator
'postmaster' => '[A',
# List of senders/recipients and associated filters
'recipients' => [
{
'filters' => [
'Mail::IspMailGate::Filter::VirScan'
],
'recipient' => '[@\\.]ispsoft.de$'
}
],
# Path of the tar binary (for extracting .tar files) or empty
'tar_path' => '/usr/bin/gtar',
# Directory to use for temporary files
'tmp_dir' => '/var/spool/ispmailgate',
# Path of the unarj binary (for extracting .arj files) or empty
'unarj_path' => '',
# Path of the Unix socket to connect to a server
'unix_sock' => '/var/run/ispmailgate.sock',
# Domain to assume for email adresses without @domain
'unqualified_domain' => 'ispsoft.de',
# Path of the unzip binary (for extracting .zip files) or empty
'unzip_path' => '/usr/bin/unzip',
# Configuration of the virus scanner
'virscan' => {
'scanner' => '$antivir_path -rs -nolnk -noboot $ipaths',
'deflater' => [
{
'cmd' => '$gzip_path -cd $ipath | $tar_path -xf -C $odir',
'pattern' => '\\.(?:tgz|tar\\.gz|tar\\.[zZ])$'
},
{
'cmd' => '$gzip_path -cd $ipath >$opath',
'pattern' => '\\.(?:gz|[zZ])$'
},
{
'cmd' => '$gzip_path -cd $ipath >$opath',
'pattern' => '\\.tar$'
},
{
'cmd' => '$unzip_path $ifile -d $odir',
'pattern' => '\\.zip$'
},
{
'cmd' => '$gzip_path -cd $ipath | $tar_path -xf -C $odir',
'pattern' => '\\.(?:tgz|tar\\.gz|tar\\.[zZ])$'
},
{
'cmd' => '$gzip_path -cd $ipath >$opath',
'pattern' => '\\.(?:gz|[zZ])$'
},
{
'cmd' => '$gzip_path -cd $ipath >$opath',
'pattern' => '\\.tar$'
},
{
'cmd' => '$unzip_path $ifile -d $odir',
'pattern' => '\\.zip$'
},
{
'cmd' => '$gzip_path -cd $ipath | $tar_path -xf -C $odir',
'pattern' => '\\.(?:tgz|tar\\.gz|tar\\.[zZ])$'
},
{
'cmd' => '$gzip_path -cd $ipath >$opath',
'pattern' => '\\.(?:gz|[zZ])$'
},
{
'cmd' => '$gzip_path -cd $ipath >$opath',
'pattern' => '\\.tar$'
},
{
'cmd' => '$unzip_path $ifile -d $odir',
'pattern' => '\\.zip$'
}
]
},
}, 'Mail::IspMailGate::Install' );
AUTHORS AND COPYRIGHT
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.
You may distribute under the terms of either the GNU General
Public License or the Artistic License, as specified in the Perl
README file.
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
