1This directory contains the source files for libmilter. 2 3The sendmail Mail Filter API (Milter) is designed to allow third-party 4programs access to mail messages as they are being processed in order to 5filter meta-information and content. 6 7This README file describes the steps needed to compile and run a filter, 8through reference to a sample filter which is attached at the end of this 9file. It is necessary to first build libmilter.a, which can be done by 10issuing the './Build' command in SRCDIR/libmilter . 11 12Starting with 8.13 sendmail is compiled by default with support for 13the milter API. 14 15Note: if you want to write a milter in Java, then see 16http://sendmail-jilter.sourceforge.net/ 17 18 19+----------------+ 20| SECURITY HINTS | 21+----------------+ 22 23Note: we strongly recommend not to run any milter as root. Libmilter 24does not need root access to communicate with sendmail. It is a 25good security practice to run a program only with root privileges 26if really necessary. A milter should probably check first whether 27it runs as root and refuse to start in that case. libmilter will 28not unlink a socket when running as root. 29 30 31+----------------------+ 32| CONFIGURATION MACROS | 33+----------------------+ 34 35Libmilter uses a set of C preprocessor macros to specify platform specific 36features of the C compiler and standard C libraries. 37 38SM_CONF_POLL 39 Set to 1 if poll(2) should be used instead of select(2). 40 41 42+-------------------+ 43| BUILDING A FILTER | 44+-------------------+ 45 46The following command presumes that the sample code from the end of this 47README is saved to a file named 'sample.c' and built in the local platform- 48specific build subdirectory (SRCDIR/obj.*/libmilter). 49 50 cc -I../../include -o sample sample.c libmilter.a ../libsm/libsm.a -pthread 51 52It is recommended that you build your filters in a location outside of 53the sendmail source tree. Modify the compiler include references (-I) 54and the library locations accordingly. Also, some operating systems may 55require additional libraries. For example, SunOS 5.X requires '-lresolv 56-lsocket -lnsl'. Depending on your operating system you may need a library 57instead of the option -pthread, e.g., -lpthread. 58 59Filters must be thread-safe! Many operating systems now provide support for 60POSIX threads in the standard C libraries. The compiler flag to link with 61threading support differs according to the compiler and linker used. Check 62the Makefile in your appropriate obj.*/libmilter build subdirectory if you 63are unsure of the local flag used. 64 65Note that since filters use threads, it may be necessary to alter per 66process limits in your filter. For example, you might look at using 67setrlimit() to increase the number of open file descriptors if your filter 68is going to be busy. 69 70 71+----------------------------------------+ 72| SPECIFYING FILTERS IN SENDMAIL CONFIGS | 73+----------------------------------------+ 74 75Filters are specified with a key letter ``X'' (for ``eXternal''). 76 77For example: 78 79 Xfilter1, S=local:/var/run/f1.sock, F=R 80 Xfilter2, S=inet6:999@localhost, F=T, T=C:10m;S:1s;R:1s;E:5m 81 Xfilter3, S=inet:3333@localhost 82 83specifies three filters. Filters can be specified in your .mc file using 84the following: 85 86 INPUT_MAIL_FILTER(`filter1', `S=local:/var/run/f1.sock, F=R') 87 INPUT_MAIL_FILTER(`filter2', `S=inet6:999@localhost, F=T, T=C:10m;S:1s;R:1s;E:5m') 88 INPUT_MAIL_FILTER(`filter3', `S=inet:3333@localhost') 89 90The first attaches to a Unix-domain socket in the /var/run directory; the 91second uses an IPv6 socket on port 999 of localhost, and the third uses an 92IPv4 socket on port 3333 of localhost. The current flags (F=) are: 93 94 R Reject connection if filter unavailable 95 T Temporary fail connection if filter unavailable 96 4 Shut down connection if filter unavailable 97 (with a 421 temporary error). 98 99If none of these is specified, the message is passed through sendmail 100in case of filter errors as if the failing filters were not present. 101 102Finally, you can override the default timeouts used by sendmail when 103talking to the filters using the T= equate. There are four fields inside 104of the T= equate: 105 106Letter Meaning 107 C Timeout for connecting to a filter (if 0, use system timeout) 108 S Timeout for sending information from the MTA to a filter 109 R Timeout for reading reply from the filter 110 E Overall timeout between sending end-of-message to filter 111 and waiting for the final acknowledgment 112 113Note the separator between each is a ';' as a ',' already separates equates 114and therefore can't separate timeouts. The default values (if not set in 115the config) are: 116 117T=C:5m;S:10s;R:10s;E:5m 118 119where 's' is seconds and 'm' is minutes. 120 121Which filters are invoked and their sequencing is handled by the 122InputMailFilters option. Note: if InputMailFilters is not defined no filters 123will be used. 124 125 O InputMailFilters=filter1, filter2, filter3 126 127This is is set automatically according to the order of the 128INPUT_MAIL_FILTER commands in your .mc file. Alternatively, you can 129reset its value by setting confINPUT_MAIL_FILTERS in your .mc file. 130This options causes the three filters to be called in the same order 131they were specified. It allows for possible future filtering on output 132(although this is not intended for this release). 133 134Also note that a filter can be defined without adding it to the input 135filter list by using MAIL_FILTER() instead of INPUT_MAIL_FILTER() in your 136.mc file. 137 138To test sendmail with the sample filter, the following might be added (in 139the appropriate locations) to your .mc file: 140 141 INPUT_MAIL_FILTER(`sample', `S=local:/var/run/f1.sock') 142 143 144+------------------+ 145| TESTING A FILTER | 146+------------------+ 147 148Once you have compiled a filter, modified your .mc file and restarted 149the sendmail process, you will want to test that the filter performs as 150intended. 151 152The sample filter takes one argument -p, which indicates the local port 153on which to create a listening socket for the filter. Maintaining 154consistency with the suggested options for sendmail.cf, this would be the 155UNIX domain socket located in /var/run/f1.sock. 156 157 % ./sample -p local:/var/run/f1.sock 158 159If the sample filter returns immediately to a command line, there was either 160an error with your command or a problem creating the specified socket. 161Further logging can be captured through the syslogd daemon. Using the 162'netstat -a' command can ensure that your filter process is listening on 163the appropriate local socket. 164 165Email messages must be injected via SMTP to be filtered. There are two 166simple means of doing this; either using the 'sendmail -bs' command, or 167by telnetting to port 25 of the machine configured for milter. Once 168connected via one of these options, the session can be continued through 169the use of standard SMTP commands. 170 171% sendmail -bs 172220 test.sendmail.com ESMTP Sendmail 8.14.0/8.14.0; Thu, 22 Jun 2006 13:05:23 -0500 (EST) 173HELO localhost 174250 test.sendmail.com Hello testy@localhost, pleased to meet you 175MAIL From:<testy> 176250 2.1.0 <testy>... Sender ok 177RCPT To:<root> 178250 2.1.5 <root>... Recipient ok 179DATA 180354 Enter mail, end with "." on a line by itself 181From: testy@test.sendmail.com 182To: root@test.sendmail.com 183Subject: testing sample filter 184 185Sample body 186. 187250 2.0.0 dB73Zxi25236 Message accepted for delivery 188QUIT 189221 2.0.0 test.sendmail.com closing connection 190 191In the above example, the lines beginning with numbers are output by the 192mail server, and those without are your input. If everything is working 193properly, you will find a file in /tmp by the name of msg.XXXXXXXX (where 194the Xs represent any combination of letters and numbers). This file should 195contain the message body and headers from the test email entered above. 196 197If the sample filter did not log your test email, there are a number of 198methods to narrow down the source of the problem. Check your system 199logs written by syslogd and see if there are any pertinent lines. You 200may need to reconfigure syslogd to capture all relevant data. Additionally, 201the logging level of sendmail can be raised with the LogLevel option. 202See the sendmail(8) manual page for more information. 203 204 205+--------------+ 206| REQUIREMENTS | 207+--------------+ 208 209libmilter requires pthread support in the operating system. Moreover, it 210requires that the library functions it uses are thread safe; which is true 211for the operating systems libmilter has been developed and tested on. On 212some operating systems this requires special compile time options (e.g., 213not just -pthread). 214 215So far, libmilter is not supported on: 216IRIX 6.x 217Ultrix 218 219Feedback about problems (and possible fixes) is welcome. 220 221 222+--------------------------+ 223| SOURCE FOR SAMPLE FILTER | 224+--------------------------+ 225 226Note that the filter example.c may not be thread safe on some operating 227systems. You should check your system man pages for the functions used 228to verify they are thread safe. 229