1N/A# Copyright 2006 Sun Microsystems, Inc. All rights reserved.
1N/A# Use is subject to license terms.
1N/A# ident "%Z%%M% %I% %E% SMI"
1N/AThe sendmail Mail Filter API (Milter) is designed to allow third-party
1N/Aprograms access to mail messages as they are being processed in order to
1N/Afilter meta-information and content.
1N/AThis README file describes the steps needed to compile and run a filter,
1N/Athrough reference to a sample filter which is attached at the end of this
1N/ANote: if you want to write a milter in Java, then see
1N/ANote: we strongly recommend not to run any milter as root. Libmilter
1N/Adoes not need root access to communicate with sendmail. It is a
1N/Agood security practice to run a program only with root privileges
1N/Aif really necessary. A milter should probably check first whether
1N/Ait runs as root and refuse to start in that case. libmilter will
1N/Anot unlink a socket when running as root.
1N/A+-------------------+
1N/A| BUILDING A FILTER |
1N/A+-------------------+
1N/AThe following command presumes that the sample code from the end of this
1N/AFilters must be thread-safe!
1N/ANote that since filters use threads, it may be necessary to alter per
1N/Aprocess limits in your filter. For example, you might look at using
1N/Asetrlimit() to increase the number of open file descriptors if your filter
1N/A+----------------------------------------+
1N/A| SPECIFYING FILTERS IN SENDMAIL CONFIGS |
1N/A+----------------------------------------+
1N/AFilters are specified with a key letter ``X'' (for ``eXternal'').
1N/A Xfilter2, S=inet6:999@localhost, F=T, T=C:10m;S:1s;R:1s;E:5m
1N/A Xfilter3, S=inet:3333@localhost
1N/Aspecifies three filters. Filters can be specified in your .mc file using
1N/A INPUT_MAIL_FILTER(`filter2', `S=inet6:999@localhost, F=T, T=C:10m;S:1s;R:1s;E:5m')
1N/A INPUT_MAIL_FILTER(`filter3', `S=inet:3333@localhost')
1N/AThe first attaches to a Unix-domain socket in the
/var/run directory; the
1N/Asecond uses an IPv6 socket on port 999 of localhost, and the third uses an
1N/AIPv4 socket on port 3333 of localhost. The current flags (F=) are:
1N/A R Reject connection if filter unavailable
1N/A T Temporary fail connection if filter unavailable
1N/A 4 Shut down connection if filter unavailable
1N/A (with a 421 temporary error).
1N/AIf none of these is specified, the message is passed through sendmail
1N/Ain case of filter errors as if the failing filters were not present.
1N/AFinally, you can override the default timeouts used by sendmail when
1N/Atalking to the filters using the T= equate. There are four fields inside
1N/A C Timeout for connecting to a filter (if 0, use system timeout)
1N/A S Timeout for sending information from the MTA to a filter
1N/A R Timeout for reading reply from the filter
1N/A E Overall timeout between sending end-of-message to filter
1N/A and waiting for the final acknowledgment
1N/ANote the separator between each is a ';' as a ',' already separates equates
1N/Aand therefore can't separate timeouts. The default values (if not set in
1N/AT=C:5m;S:10s;R:10s;E:5m
1N/Awhere 's' is seconds and 'm' is minutes.
1N/AWhich filters are invoked and their sequencing is handled by the
1N/AInputMailFilters option. Note: if InputMailFilters is not defined no filters
1N/A O InputMailFilters=filter1, filter2, filter3
1N/AThis is is set automatically according to the order of the
1N/AINPUT_MAIL_FILTER commands in your .mc file. Alternatively, you can
1N/Areset its value by setting confINPUT_MAIL_FILTERS in your .mc file.
1N/AThis options causes the three filters to be called in the same order
1N/Athey were specified. It allows for possible future filtering on output
1N/A(although this is not intended for this release).
1N/AAlso note that a filter can be defined without adding it to the input
1N/Afilter list by using MAIL_FILTER() instead of INPUT_MAIL_FILTER() in your
1N/ATo test sendmail with the sample filter, the following might be added (in
1N/Athe appropriate locations) to your .mc file:
1N/AOnce you have compiled a filter, modified your .mc file and restarted
1N/Athe sendmail process, you will want to test that the filter performs as
1N/AThe sample filter takes one argument -p, which indicates the local port
1N/Aon which to create a listening socket for the filter. Maintaining
1N/Aconsistency with the suggested options for
sendmail.cf, this would be the
1N/AIf the sample filter returns immediately to a command line, there was either
1N/Aan error with your command or a problem creating the specified socket.
1N/AFurther logging can be captured through the syslogd daemon. Using the
1N/A'netstat -a' command can ensure that your filter process is listening on
1N/Athe appropriate local socket.
1N/AEmail messages must be injected via SMTP to be filtered. There are two
1N/Asimple means of doing this; either using the 'sendmail -bs' command, or
1N/Aby telnetting to port 25 of the machine configured for milter. Once
1N/Aconnected via one of these options, the session can be continued through
1N/Athe use of standard SMTP commands.
1N/A250 2.1.0 <testy>... Sender ok
1N/A250 2.1.5 <root>... Recipient ok
1N/A354 Enter mail, end with "." on a line by itself
1N/AFrom: testy@test.sendmail.com
1N/ATo: root@test.sendmail.com
1N/ASubject: testing sample filter
1N/A250 2.0.0 dB73Zxi25236 Message accepted for delivery
1N/AIn the above example, the lines beginning with numbers are output by the
1N/Amail server, and those without are your input. If everything is working
1N/Athe Xs represent any combination of letters and numbers). This file should
1N/Acontain the message body and headers from the test email entered above.
1N/AIf the sample filter did not log your test email, there are a number of
1N/Amethods to narrow down the source of the problem. Check your system
1N/Alogs written by syslogd and see if there are any pertinent lines. You
1N/Amay need to reconfigure syslogd to capture all relevant data. Additionally,
1N/Athe logging level of sendmail can be raised with the LogLevel option.
1N/ASee the sendmail(8) manual page for more information.
1N/A$Revision: 8.42 $, Last updated $Date: 2006/06/29 17:10:16 $