164562SgshapiroThis directory contains the source files for libmilter. 264562Sgshapiro 364562SgshapiroThe sendmail Mail Filter API (Milter) is designed to allow third-party 464562Sgshapiroprograms access to mail messages as they are being processed in order to 564562Sgshapirofilter meta-information and content. 664562Sgshapiro 764562SgshapiroThis README file describes the steps needed to compile and run a filter, 864562Sgshapirothrough reference to a sample filter which is attached at the end of this 964562Sgshapirofile. It is necessary to first build libmilter.a, which can be done by 1064562Sgshapiroissuing the './Build' command in SRCDIR/libmilter . 1164562Sgshapiro 12132943SgshapiroStarting with 8.13 sendmail is compiled by default with support for 13132943Sgshapirothe milter API. 1464562Sgshapiro 15157001SgshapiroNote: if you want to write a milter in Java, then see 16157001Sgshapirohttp://sendmail-jilter.sourceforge.net/ 17157001Sgshapiro 1890792Sgshapiro+----------------+ 1990792Sgshapiro| SECURITY HINTS | 2090792Sgshapiro+----------------+ 2164562Sgshapiro 2290792SgshapiroNote: we strongly recommend not to run any milter as root. Libmilter 2390792Sgshapirodoes not need root access to communicate with sendmail. It is a 2490792Sgshapirogood security practice to run a program only with root privileges 2590792Sgshapiroif really necessary. A milter should probably check first whether 26132943Sgshapiroit runs as root and refuse to start in that case. libmilter will 27132943Sgshapironot unlink a socket when running as root. 2890792Sgshapiro 29132943Sgshapiro+----------------------+ 30132943Sgshapiro| CONFIGURATION MACROS | 31132943Sgshapiro+----------------------+ 3290792Sgshapiro 33132943SgshapiroLibmilter uses a set of C preprocessor macros to specify platform specific 34132943Sgshapirofeatures of the C compiler and standard C libraries. 3590792Sgshapiro 36132943SgshapiroSM_CONF_POLL 37132943Sgshapiro Set to 1 if poll(2) should be used instead of select(2). 38132943Sgshapiro 3964562Sgshapiro+-------------------+ 4064562Sgshapiro| BUILDING A FILTER | 4164562Sgshapiro+-------------------+ 4264562Sgshapiro 4364562SgshapiroThe following command presumes that the sample code from the end of this 4464562SgshapiroREADME is saved to a file named 'sample.c' and built in the local platform- 4564562Sgshapirospecific build subdirectory (SRCDIR/obj.*/libmilter). 4664562Sgshapiro 47110560Sgshapiro cc -I../../include -o sample sample.c libmilter.a ../libsm/libsm.a -pthread 4864562Sgshapiro 4964562SgshapiroIt is recommended that you build your filters in a location outside of 5064562Sgshapirothe sendmail source tree. Modify the compiler include references (-I) 5164562Sgshapiroand the library locations accordingly. Also, some operating systems may 5264562Sgshapirorequire additional libraries. For example, SunOS 5.X requires '-lresolv 5390792Sgshapiro-lsocket -lnsl'. Depending on your operating system you may need a library 5490792Sgshapiroinstead of the option -pthread, e.g., -lpthread. 5564562Sgshapiro 5664562SgshapiroFilters must be thread-safe! Many operating systems now provide support for 5764562SgshapiroPOSIX threads in the standard C libraries. The compiler flag to link with 5864562Sgshapirothreading support differs according to the compiler and linker used. Check 5964562Sgshapirothe Makefile in your appropriate obj.*/libmilter build subdirectory if you 6064562Sgshapiroare unsure of the local flag used. 6164562Sgshapiro 6273188SgshapiroNote that since filters use threads, it may be necessary to alter per 6373188Sgshapiroprocess limits in your filter. For example, you might look at using 6473188Sgshapirosetrlimit() to increase the number of open file descriptors if your filter 6573188Sgshapirois going to be busy. 6664562Sgshapiro 6773188Sgshapiro 6864562Sgshapiro+----------------------------------------+ 6964562Sgshapiro| SPECIFYING FILTERS IN SENDMAIL CONFIGS | 7064562Sgshapiro+----------------------------------------+ 7164562Sgshapiro 7264562SgshapiroFilters are specified with a key letter ``X'' (for ``eXternal''). 7364562Sgshapiro 7464562SgshapiroFor example: 7564562Sgshapiro 7664562Sgshapiro Xfilter1, S=local:/var/run/f1.sock, F=R 7780785Sgshapiro Xfilter2, S=inet6:999@localhost, F=T, T=C:10m;S:1s;R:1s;E:5m 7864562Sgshapiro Xfilter3, S=inet:3333@localhost 7964562Sgshapiro 8064562Sgshapirospecifies three filters. Filters can be specified in your .mc file using 8164562Sgshapirothe following: 8264562Sgshapiro 8364562Sgshapiro INPUT_MAIL_FILTER(`filter1', `S=local:/var/run/f1.sock, F=R') 8480785Sgshapiro INPUT_MAIL_FILTER(`filter2', `S=inet6:999@localhost, F=T, T=C:10m;S:1s;R:1s;E:5m') 8564562Sgshapiro INPUT_MAIL_FILTER(`filter3', `S=inet:3333@localhost') 8664562Sgshapiro 8764562SgshapiroThe first attaches to a Unix-domain socket in the /var/run directory; the 8864562Sgshapirosecond uses an IPv6 socket on port 999 of localhost, and the third uses an 8964562SgshapiroIPv4 socket on port 3333 of localhost. The current flags (F=) are: 9064562Sgshapiro 9164562Sgshapiro R Reject connection if filter unavailable 9264562Sgshapiro T Temporary fail connection if filter unavailable 93168515Sgshapiro 4 Shut down connection if filter unavailable 94168515Sgshapiro (with a 421 temporary error). 9564562Sgshapiro 96168515SgshapiroIf none of these is specified, the message is passed through sendmail 9790792Sgshapiroin case of filter errors as if the failing filters were not present. 9866494Sgshapiro 9964562SgshapiroFinally, you can override the default timeouts used by sendmail when 10080785Sgshapirotalking to the filters using the T= equate. There are four fields inside 10164562Sgshapiroof the T= equate: 10264562Sgshapiro 10390792SgshapiroLetter Meaning 10480785Sgshapiro C Timeout for connecting to a filter (if 0, use system timeout) 10580785Sgshapiro S Timeout for sending information from the MTA to a filter 10680785Sgshapiro R Timeout for reading reply from the filter 10780785Sgshapiro E Overall timeout between sending end-of-message to filter 10880785Sgshapiro and waiting for the final acknowledgment 10964562Sgshapiro 11064562SgshapiroNote the separator between each is a ';' as a ',' already separates equates 11180785Sgshapiroand therefore can't separate timeouts. The default values (if not set in 11280785Sgshapirothe config) are: 11364562Sgshapiro 11490792SgshapiroT=C:5m;S:10s;R:10s;E:5m 11564562Sgshapiro 11664562Sgshapirowhere 's' is seconds and 'm' is minutes. 11764562Sgshapiro 11866494SgshapiroWhich filters are invoked and their sequencing is handled by the 11977349SgshapiroInputMailFilters option. Note: if InputMailFilters is not defined no filters 12077349Sgshapirowill be used. 12164562Sgshapiro 12266494Sgshapiro O InputMailFilters=filter1, filter2, filter3 12366494Sgshapiro 12466494SgshapiroThis is is set automatically according to the order of the 12566494SgshapiroINPUT_MAIL_FILTER commands in your .mc file. Alternatively, you can 12666494Sgshapiroreset its value by setting confINPUT_MAIL_FILTERS in your .mc file. 12766494SgshapiroThis options causes the three filters to be called in the same order 12866494Sgshapirothey were specified. It allows for possible future filtering on output 12966494Sgshapiro(although this is not intended for this release). 13066494Sgshapiro 13164562SgshapiroAlso note that a filter can be defined without adding it to the input 13264562Sgshapirofilter list by using MAIL_FILTER() instead of INPUT_MAIL_FILTER() in your 13364562Sgshapiro.mc file. 13464562Sgshapiro 13564562SgshapiroTo test sendmail with the sample filter, the following might be added (in 13664562Sgshapirothe appropriate locations) to your .mc file: 13764562Sgshapiro 13864562Sgshapiro INPUT_MAIL_FILTER(`sample', `S=local:/var/run/f1.sock') 13964562Sgshapiro 14064562Sgshapiro 14164562Sgshapiro+------------------+ 14264562Sgshapiro| TESTING A FILTER | 14364562Sgshapiro+------------------+ 14464562Sgshapiro 14564562SgshapiroOnce you have compiled a filter, modified your .mc file and restarted 14664562Sgshapirothe sendmail process, you will want to test that the filter performs as 14764562Sgshapirointended. 14864562Sgshapiro 14964562SgshapiroThe sample filter takes one argument -p, which indicates the local port 15064562Sgshapiroon which to create a listening socket for the filter. Maintaining 15164562Sgshapiroconsistency with the suggested options for sendmail.cf, this would be the 15264562SgshapiroUNIX domain socket located in /var/run/f1.sock. 15364562Sgshapiro 15464562Sgshapiro % ./sample -p local:/var/run/f1.sock 15564562Sgshapiro 15664562SgshapiroIf the sample filter returns immediately to a command line, there was either 15764562Sgshapiroan error with your command or a problem creating the specified socket. 15864562SgshapiroFurther logging can be captured through the syslogd daemon. Using the 15964562Sgshapiro'netstat -a' command can ensure that your filter process is listening on 16064562Sgshapirothe appropriate local socket. 16164562Sgshapiro 16264562SgshapiroEmail messages must be injected via SMTP to be filtered. There are two 16364562Sgshapirosimple means of doing this; either using the 'sendmail -bs' command, or 16464562Sgshapiroby telnetting to port 25 of the machine configured for milter. Once 16564562Sgshapiroconnected via one of these options, the session can be continued through 16664562Sgshapirothe use of standard SMTP commands. 16764562Sgshapiro 16864562Sgshapiro% sendmail -bs 169168515Sgshapiro220 test.sendmail.com ESMTP Sendmail 8.14.0/8.14.0; Thu, 22 Jun 2006 13:05:23 -0500 (EST) 17064562SgshapiroHELO localhost 17164562Sgshapiro250 test.sendmail.com Hello testy@localhost, pleased to meet you 17264562SgshapiroMAIL From:<testy> 17364562Sgshapiro250 2.1.0 <testy>... Sender ok 17464562SgshapiroRCPT To:<root> 17564562Sgshapiro250 2.1.5 <root>... Recipient ok 17664562SgshapiroDATA 17764562Sgshapiro354 Enter mail, end with "." on a line by itself 17864562SgshapiroFrom: testy@test.sendmail.com 17964562SgshapiroTo: root@test.sendmail.com 18064562SgshapiroSubject: testing sample filter 18164562Sgshapiro 18264562SgshapiroSample body 18364562Sgshapiro. 18464562Sgshapiro250 2.0.0 dB73Zxi25236 Message accepted for delivery 18564562SgshapiroQUIT 18664562Sgshapiro221 2.0.0 test.sendmail.com closing connection 18764562Sgshapiro 18864562SgshapiroIn the above example, the lines beginning with numbers are output by the 18964562Sgshapiromail server, and those without are your input. If everything is working 19064562Sgshapiroproperly, you will find a file in /tmp by the name of msg.XXXXXXXX (where 19164562Sgshapirothe Xs represent any combination of letters and numbers). This file should 19264562Sgshapirocontain the message body and headers from the test email entered above. 19364562Sgshapiro 19464562SgshapiroIf the sample filter did not log your test email, there are a number of 19564562Sgshapiromethods to narrow down the source of the problem. Check your system 19664562Sgshapirologs written by syslogd and see if there are any pertinent lines. You 19764562Sgshapiromay need to reconfigure syslogd to capture all relevant data. Additionally, 19864562Sgshapirothe logging level of sendmail can be raised with the LogLevel option. 19964562SgshapiroSee the sendmail(8) manual page for more information. 20064562Sgshapiro 20164562Sgshapiro 20290792Sgshapiro+--------------+ 20390792Sgshapiro| REQUIREMENTS | 20490792Sgshapiro+--------------+ 20590792Sgshapiro 20690792Sgshapirolibmilter requires pthread support in the operating system. Moreover, it 20790792Sgshapirorequires that the library functions it uses are thread safe; which is true 20890792Sgshapirofor the operating systems libmilter has been developed and tested on. On 20990792Sgshapirosome operating systems this requires special compile time options (e.g., 21090792Sgshapironot just -pthread). libmilter is currently known to work on (modulo problems 21190792Sgshapiroin the pthread support of some specific versions): 21290792Sgshapiro 21390792SgshapiroFreeBSD 3.x, 4.x 21490792SgshapiroSunOS 5.x (x >= 5) 21590792SgshapiroAIX 4.3.x 21690792SgshapiroHP UX 11.x 21790792SgshapiroLinux (recent versions/distributions) 21890792Sgshapiro 21990792Sgshapirolibmilter is currently not supported on: 22090792Sgshapiro 22190792SgshapiroIRIX 6.x 22290792SgshapiroUltrix 22390792Sgshapiro 22490792SgshapiroFeedback about problems (and possible fixes) is welcome. 22590792Sgshapiro 22664562Sgshapiro+--------------------------+ 22764562Sgshapiro| SOURCE FOR SAMPLE FILTER | 22864562Sgshapiro+--------------------------+ 22964562Sgshapiro 230168515SgshapiroNote that the filter example.c may not be thread safe on some operating 23171345Sgshapirosystems. You should check your system man pages for the functions used 23271345Sgshapirobelow to verify the functions are thread safe. 23371345Sgshapiro 234266692Sgshapiro$Revision: 8.42 $, Last updated $Date: 2006-06-29 17:10:16 $ 235