XXXX update sendmail to 8.14.9
1 # 2 # Copyright 2006 Sun Microsystems, Inc. All rights reserved. 3 # Use is subject to license terms. 4 # 5 6 The sendmail Mail Filter API (Milter) is designed to allow third-party 7 programs access to mail messages as they are being processed in order to 8 filter meta-information and content. 9 10 This README file describes the steps needed to compile and run a filter, 11 through reference to a sample filter which is attached at the end of this 12 file. 13 14 Note: if you want to write a milter in Java, then see 15 http://sendmail-jilter.sourceforge.net/ or 16 http://iws.cs.uni-magdeburg.de/~elkner/milter4j.tgz 17 18 +----------------+ 19 | SECURITY HINTS | 20 +----------------+ 21 22 Note: we strongly recommend not to run any milter as root. Libmilter 23 does not need root access to communicate with sendmail. It is a 24 good security practice to run a program only with root privileges 25 if really necessary. A milter should probably check first whether 26 it runs as root and refuse to start in that case. libmilter will 27 not unlink a socket when running as root. 28 29 +-------------------+ 30 | BUILDING A FILTER | 31 +-------------------+ 32 33 The following command presumes that the sample code from the end of this 34 README is saved to a file named 'sample.c'. 35 36 cc -D_REENTRANT -o sample sample.c -lmilter 37 38 Filters must be thread-safe! 39 40 Note that since filters use threads, it may be necessary to alter per 41 process limits in your filter. For example, you might look at using 42 setrlimit() to increase the number of open file descriptors if your filter 43 is going to be busy. 44 45 46 +----------------------------------------+ 47 | SPECIFYING FILTERS IN SENDMAIL CONFIGS | 48 +----------------------------------------+ 49 50 Filters are specified with a key letter ``X'' (for ``eXternal''). 51 52 For example: 53 54 Xfilter1, S=local:/var/run/f1.sock, F=R 55 Xfilter2, S=inet6:999@localhost, F=T, T=C:10m;S:1s;R:1s;E:5m 56 Xfilter3, S=inet:3333@localhost 57 58 specifies three filters. Filters can be specified in your .mc file using 59 the following: 60 61 INPUT_MAIL_FILTER(`filter1', `S=local:/var/run/f1.sock, F=R') 62 INPUT_MAIL_FILTER(`filter2', `S=inet6:999@localhost, F=T, T=C:10m;S:1s;R:1s;E:5m') 63 INPUT_MAIL_FILTER(`filter3', `S=inet:3333@localhost') 64 65 The first attaches to a Unix-domain socket in the /var/run directory; the 66 second uses an IPv6 socket on port 999 of localhost, and the third uses an 67 IPv4 socket on port 3333 of localhost. The current flags (F=) are: 68 69 R Reject connection if filter unavailable 70 T Temporary fail connection if filter unavailable 71 4 Shut down connection if filter unavailable 72 (with a 421 temporary error). 73 74 If none of these is specified, the message is passed through sendmail 75 in case of filter errors as if the failing filters were not present. 76 77 Finally, you can override the default timeouts used by sendmail when 78 talking to the filters using the T= equate. There are four fields inside 79 of the T= equate: 80 81 Letter Meaning 82 C Timeout for connecting to a filter (if 0, use system timeout) 83 S Timeout for sending information from the MTA to a filter 84 R Timeout for reading reply from the filter 85 E Overall timeout between sending end-of-message to filter 86 and waiting for the final acknowledgment 87 88 Note the separator between each is a ';' as a ',' already separates equates 89 and therefore can't separate timeouts. The default values (if not set in 90 the config) are: 91 92 T=C:5m;S:10s;R:10s;E:5m 93 94 where 's' is seconds and 'm' is minutes. 95 96 Which filters are invoked and their sequencing is handled by the 97 InputMailFilters option. Note: if InputMailFilters is not defined no filters 98 will be used. 99 100 O InputMailFilters=filter1, filter2, filter3 101 102 This is is set automatically according to the order of the 103 INPUT_MAIL_FILTER commands in your .mc file. Alternatively, you can 104 reset its value by setting confINPUT_MAIL_FILTERS in your .mc file. 105 This options causes the three filters to be called in the same order 106 they were specified. It allows for possible future filtering on output 107 (although this is not intended for this release). 108 109 Also note that a filter can be defined without adding it to the input 110 filter list by using MAIL_FILTER() instead of INPUT_MAIL_FILTER() in your 111 .mc file. 112 113 To test sendmail with the sample filter, the following might be added (in 114 the appropriate locations) to your .mc file: 115 116 INPUT_MAIL_FILTER(`sample', `S=local:/var/run/f1.sock') 117 118 119 +------------------+ 120 | TESTING A FILTER | 121 +------------------+ 122 123 Once you have compiled a filter, modified your .mc file and restarted 124 the sendmail process, you will want to test that the filter performs as 125 intended. 126 127 The sample filter takes one argument -p, which indicates the local port 128 on which to create a listening socket for the filter. Maintaining 129 consistency with the suggested options for sendmail.cf, this would be the 130 UNIX domain socket located in /var/run/f1.sock. 131 132 % ./sample -p local:/var/run/f1.sock 133 134 If the sample filter returns immediately to a command line, there was either 135 an error with your command or a problem creating the specified socket. 136 Further logging can be captured through the syslogd daemon. Using the 137 'netstat -a' command can ensure that your filter process is listening on 138 the appropriate local socket. 139 140 Email messages must be injected via SMTP to be filtered. There are two 141 simple means of doing this; either using the 'sendmail -bs' command, or 142 by telnetting to port 25 of the machine configured for milter. Once 143 connected via one of these options, the session can be continued through 144 the use of standard SMTP commands. 145 146 % sendmail -bs 147 220 test.sendmail.com ESMTP Sendmail 8.14.0/8.14.0; Thu, 22 Jun 2006 13:05:23 -0500 (EST) 148 HELO localhost 149 250 test.sendmail.com Hello testy@localhost, pleased to meet you 150 MAIL From:<testy> 151 250 2.1.0 <testy>... Sender ok 152 RCPT To:<root> 153 250 2.1.5 <root>... Recipient ok 154 DATA 155 354 Enter mail, end with "." on a line by itself 156 From: testy@test.sendmail.com 157 To: root@test.sendmail.com 158 Subject: testing sample filter 159 160 Sample body 161 . 162 250 2.0.0 dB73Zxi25236 Message accepted for delivery 163 QUIT 164 221 2.0.0 test.sendmail.com closing connection 165 166 In the above example, the lines beginning with numbers are output by the 167 mail server, and those without are your input. If everything is working 168 properly, you will find a file in /tmp by the name of msg.XXXXXXXX (where 169 the Xs represent any combination of letters and numbers). This file should 170 contain the message body and headers from the test email entered above. 171 172 If the sample filter did not log your test email, there are a number of 173 methods to narrow down the source of the problem. Check your system 174 logs written by syslogd and see if there are any pertinent lines. You 175 may need to reconfigure syslogd to capture all relevant data. Additionally, 176 the logging level of sendmail can be raised with the LogLevel option. 177 See the sendmail(8) manual page for more information. 178 179 180 $Revision: 8.42 $, Last updated $Date: 2006/06/29 17:10:16 $ --- EOF ---