README revision 168516
150476SpeterThis directory contains the source files for libmilter. 232283Shelbig 332283ShelbigThe sendmail Mail Filter API (Milter) is designed to allow third-party 432283Shelbigprograms access to mail messages as they are being processed in order to 532283Shelbigfilter meta-information and content. 632283Shelbig 732283ShelbigThis README file describes the steps needed to compile and run a filter, 8174990Sachethrough reference to a sample filter which is attached at the end of this 932283Shelbigfile. It is necessary to first build libmilter.a, which can be done by 1032283Shelbigissuing the './Build' command in SRCDIR/libmilter . 1132283Shelbig 1232283ShelbigStarting with 8.13 sendmail is compiled by default with support for 1332283Shelbigthe milter API. 1432283Shelbig 1532283ShelbigNote: if you want to write a milter in Java, then see 1632283Shelbighttp://sendmail-jilter.sourceforge.net/ 1732283Shelbig 1832283Shelbig+----------------+ 1932283Shelbig| SECURITY HINTS | 2032283Shelbig+----------------+ 2132283Shelbig 2232283ShelbigNote: we strongly recommend not to run any milter as root. Libmilter 23174990Sachedoes not need root access to communicate with sendmail. It is a 2432283Shelbiggood security practice to run a program only with root privileges 2532283Shelbigif really necessary. A milter should probably check first whether 2632283Shelbigit runs as root and refuse to start in that case. libmilter will 2732283Shelbignot unlink a socket when running as root. 2832283Shelbig 2932283Shelbig+----------------------+ 3032283Shelbig| CONFIGURATION MACROS | 3132283Shelbig+----------------------+ 3232283Shelbig 3332283ShelbigLibmilter uses a set of C preprocessor macros to specify platform specific 3432283Shelbigfeatures of the C compiler and standard C libraries. 3532283Shelbig 3632283ShelbigSM_CONF_POLL 3732283Shelbig Set to 1 if poll(2) should be used instead of select(2). 3832283Shelbig 3932283Shelbig+-------------------+ 4032283Shelbig| BUILDING A FILTER | 4132283Shelbig+-------------------+ 4232283Shelbig 4332283ShelbigThe following command presumes that the sample code from the end of this 4432283ShelbigREADME is saved to a file named 'sample.c' and built in the local platform- 4532283Shelbigspecific build subdirectory (SRCDIR/obj.*/libmilter). 4632283Shelbig 4732283Shelbig cc -I../../include -o sample sample.c libmilter.a ../libsm/libsm.a -pthread 4832283Shelbig 4932283ShelbigIt is recommended that you build your filters in a location outside of 5032283Shelbigthe sendmail source tree. Modify the compiler include references (-I) 5132283Shelbigand the library locations accordingly. Also, some operating systems may 5232283Shelbigrequire additional libraries. For example, SunOS 5.X requires '-lresolv 5332283Shelbig-lsocket -lnsl'. Depending on your operating system you may need a library 5432283Shelbiginstead of the option -pthread, e.g., -lpthread. 5532283Shelbig 5632283ShelbigFilters must be thread-safe! Many operating systems now provide support for 5732283ShelbigPOSIX threads in the standard C libraries. The compiler flag to link with 5832283Shelbigthreading support differs according to the compiler and linker used. Check 5932283Shelbigthe Makefile in your appropriate obj.*/libmilter build subdirectory if you 6032283Shelbigare unsure of the local flag used. 6132283Shelbig 6232283ShelbigNote that since filters use threads, it may be necessary to alter per 6332283Shelbigprocess limits in your filter. For example, you might look at using 6474570Sachesetrlimit() to increase the number of open file descriptors if your filter 6532283Shelbigis going to be busy. 6632283Shelbig 6732283Shelbig 6854090Sache+----------------------------------------+ 6932283Shelbig| SPECIFYING FILTERS IN SENDMAIL CONFIGS | 7032283Shelbig+----------------------------------------+ 7132283Shelbig 7232283ShelbigFilters are specified with a key letter ``X'' (for ``eXternal''). 7332283Shelbig 7432283ShelbigFor example: 7532283Shelbig 7632283Shelbig Xfilter1, S=local:/var/run/f1.sock, F=R 7732283Shelbig Xfilter2, S=inet6:999@localhost, F=T, T=C:10m;S:1s;R:1s;E:5m 7832283Shelbig Xfilter3, S=inet:3333@localhost 7932283Shelbig 8054090Sachespecifies three filters. Filters can be specified in your .mc file using 8153943Sachethe following: 82174990Sache 8353943Sache INPUT_MAIL_FILTER(`filter1', `S=local:/var/run/f1.sock, F=R') 8453943Sache INPUT_MAIL_FILTER(`filter2', `S=inet6:999@localhost, F=T, T=C:10m;S:1s;R:1s;E:5m') 8553943Sache INPUT_MAIL_FILTER(`filter3', `S=inet:3333@localhost') 8653943Sache 8753943SacheThe first attaches to a Unix-domain socket in the /var/run directory; the 8853943Sachesecond uses an IPv6 socket on port 999 of localhost, and the third uses an 8953943SacheIPv4 socket on port 3333 of localhost. The current flags (F=) are: 9053943Sache 9153943Sache R Reject connection if filter unavailable 9253943Sache T Temporary fail connection if filter unavailable 9353943Sache 4 Shut down connection if filter unavailable 9453943Sache (with a 421 temporary error). 9553943Sache 9653943SacheIf none of these is specified, the message is passed through sendmail 9774413Sachein case of filter errors as if the failing filters were not present. 9853943Sache 9974413SacheFinally, you can override the default timeouts used by sendmail when 10053961Sachetalking to the filters using the T= equate. There are four fields inside 10174413Sacheof the T= equate: 10253961Sache 10374413SacheLetter Meaning 10474413Sache C Timeout for connecting to a filter (if 0, use system timeout) 105 S Timeout for sending information from the MTA to a filter 106 R Timeout for reading reply from the filter 107 E Overall timeout between sending end-of-message to filter 108 and waiting for the final acknowledgment 109 110Note the separator between each is a ';' as a ',' already separates equates 111and therefore can't separate timeouts. The default values (if not set in 112the config) are: 113 114T=C:5m;S:10s;R:10s;E:5m 115 116where 's' is seconds and 'm' is minutes. 117 118Which filters are invoked and their sequencing is handled by the 119InputMailFilters option. Note: if InputMailFilters is not defined no filters 120will be used. 121 122 O InputMailFilters=filter1, filter2, filter3 123 124This is is set automatically according to the order of the 125INPUT_MAIL_FILTER commands in your .mc file. Alternatively, you can 126reset its value by setting confINPUT_MAIL_FILTERS in your .mc file. 127This options causes the three filters to be called in the same order 128they were specified. It allows for possible future filtering on output 129(although this is not intended for this release). 130 131Also note that a filter can be defined without adding it to the input 132filter list by using MAIL_FILTER() instead of INPUT_MAIL_FILTER() in your 133.mc file. 134 135To test sendmail with the sample filter, the following might be added (in 136the appropriate locations) to your .mc file: 137 138 INPUT_MAIL_FILTER(`sample', `S=local:/var/run/f1.sock') 139 140 141+------------------+ 142| TESTING A FILTER | 143+------------------+ 144 145Once you have compiled a filter, modified your .mc file and restarted 146the sendmail process, you will want to test that the filter performs as 147intended. 148 149The sample filter takes one argument -p, which indicates the local port 150on which to create a listening socket for the filter. Maintaining 151consistency with the suggested options for sendmail.cf, this would be the 152UNIX domain socket located in /var/run/f1.sock. 153 154 % ./sample -p local:/var/run/f1.sock 155 156If the sample filter returns immediately to a command line, there was either 157an error with your command or a problem creating the specified socket. 158Further logging can be captured through the syslogd daemon. Using the 159'netstat -a' command can ensure that your filter process is listening on 160the appropriate local socket. 161 162Email messages must be injected via SMTP to be filtered. There are two 163simple means of doing this; either using the 'sendmail -bs' command, or 164by telnetting to port 25 of the machine configured for milter. Once 165connected via one of these options, the session can be continued through 166the use of standard SMTP commands. 167 168% sendmail -bs 169220 test.sendmail.com ESMTP Sendmail 8.14.0/8.14.0; Thu, 22 Jun 2006 13:05:23 -0500 (EST) 170HELO localhost 171250 test.sendmail.com Hello testy@localhost, pleased to meet you 172MAIL From:<testy> 173250 2.1.0 <testy>... Sender ok 174RCPT To:<root> 175250 2.1.5 <root>... Recipient ok 176DATA 177354 Enter mail, end with "." on a line by itself 178From: testy@test.sendmail.com 179To: root@test.sendmail.com 180Subject: testing sample filter 181 182Sample body 183. 184250 2.0.0 dB73Zxi25236 Message accepted for delivery 185QUIT 186221 2.0.0 test.sendmail.com closing connection 187 188In the above example, the lines beginning with numbers are output by the 189mail server, and those without are your input. If everything is working 190properly, you will find a file in /tmp by the name of msg.XXXXXXXX (where 191the Xs represent any combination of letters and numbers). This file should 192contain the message body and headers from the test email entered above. 193 194If the sample filter did not log your test email, there are a number of 195methods to narrow down the source of the problem. Check your system 196logs written by syslogd and see if there are any pertinent lines. You 197may need to reconfigure syslogd to capture all relevant data. Additionally, 198the logging level of sendmail can be raised with the LogLevel option. 199See the sendmail(8) manual page for more information. 200 201 202+--------------+ 203| REQUIREMENTS | 204+--------------+ 205 206libmilter requires pthread support in the operating system. Moreover, it 207requires that the library functions it uses are thread safe; which is true 208for the operating systems libmilter has been developed and tested on. On 209some operating systems this requires special compile time options (e.g., 210not just -pthread). libmilter is currently known to work on (modulo problems 211in the pthread support of some specific versions): 212 213FreeBSD 3.x, 4.x 214SunOS 5.x (x >= 5) 215AIX 4.3.x 216HP UX 11.x 217Linux (recent versions/distributions) 218 219libmilter is currently not supported on: 220 221IRIX 6.x 222Ultrix 223 224Feedback about problems (and possible fixes) is welcome. 225 226+--------------------------+ 227| SOURCE FOR SAMPLE FILTER | 228+--------------------------+ 229 230Note that the filter example.c may not be thread safe on some operating 231systems. You should check your system man pages for the functions used 232below to verify the functions are thread safe. 233 234$Revision: 8.42 $, Last updated $Date: 2006/06/29 17:10:16 $ 235