1 This directory contains the source files for libmilter.
3 The sendmail Mail Filter API (Milter) is designed to allow third-party
4 programs access to mail messages as they are being processed in order to
5 filter meta-information and content.
7 This README file describes the steps needed to compile and run a filter,
8 through reference to a sample filter which is attached at the end of this
9 file. It is necessary to first build libmilter.a, which can be done by
10 issuing the './Build' command in SRCDIR/libmilter .
12 NOTE: If you intend to use filters in sendmail, you must compile sendmail
13 with -DMILTER defined. You can do this by adding the following to
14 your devtools/Site/site.config.m4 file:
16 APPENDDEF(`conf_sendmail_ENVDEF', `-DMILTER')
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. There is a
27 compile time option _FFR_MILTER_ROOT_UNSAFE which keeps libmilter
28 from unlinking a socket when running as root. It is recommended
29 to turn on this option:
31 APPENDDEF(`conf_libmilter_ENVDEF', `-D_FFR_MILTER_ROOT_UNSAFE ')
38 The following command presumes that the sample code from the end of this
39 README is saved to a file named 'sample.c' and built in the local platform-
40 specific build subdirectory (SRCDIR/obj.*/libmilter).
42 cc -I../../include -o sample sample.c libmilter.a ../libsm/libsm.a -pthread
44 It is recommended that you build your filters in a location outside of
45 the sendmail source tree. Modify the compiler include references (-I)
46 and the library locations accordingly. Also, some operating systems may
47 require additional libraries. For example, SunOS 5.X requires '-lresolv
48 -lsocket -lnsl'. Depending on your operating system you may need a library
49 instead of the option -pthread, e.g., -lpthread.
51 Filters must be thread-safe! Many operating systems now provide support for
52 POSIX threads in the standard C libraries. The compiler flag to link with
53 threading support differs according to the compiler and linker used. Check
54 the Makefile in your appropriate obj.*/libmilter build subdirectory if you
55 are unsure of the local flag used.
57 Note that since filters use threads, it may be necessary to alter per
58 process limits in your filter. For example, you might look at using
59 setrlimit() to increase the number of open file descriptors if your filter
63 +----------------------------------------+
64 | SPECIFYING FILTERS IN SENDMAIL CONFIGS |
65 +----------------------------------------+
67 Filters are specified with a key letter ``X'' (for ``eXternal'').
71 Xfilter1, S=local:/var/run/f1.sock, F=R
72 Xfilter2, S=inet6:999@localhost, F=T, T=C:10m;S:1s;R:1s;E:5m
73 Xfilter3, S=inet:3333@localhost
75 specifies three filters. Filters can be specified in your .mc file using
78 INPUT_MAIL_FILTER(`filter1', `S=local:/var/run/f1.sock, F=R')
79 INPUT_MAIL_FILTER(`filter2', `S=inet6:999@localhost, F=T, T=C:10m;S:1s;R:1s;E:5m')
80 INPUT_MAIL_FILTER(`filter3', `S=inet:3333@localhost')
82 The first attaches to a Unix-domain socket in the /var/run directory; the
83 second uses an IPv6 socket on port 999 of localhost, and the third uses an
84 IPv4 socket on port 3333 of localhost. The current flags (F=) are:
86 R Reject connection if filter unavailable
87 T Temporary fail connection if filter unavailable
89 If neither F=R nor F=T is specified, the message is passed through sendmail
90 in case of filter errors as if the failing filters were not present.
92 Finally, you can override the default timeouts used by sendmail when
93 talking to the filters using the T= equate. There are four fields inside
97 C Timeout for connecting to a filter (if 0, use system timeout)
98 S Timeout for sending information from the MTA to a filter
99 R Timeout for reading reply from the filter
100 E Overall timeout between sending end-of-message to filter
101 and waiting for the final acknowledgment
103 Note the separator between each is a ';' as a ',' already separates equates
104 and therefore can't separate timeouts. The default values (if not set in
107 T=C:5m;S:10s;R:10s;E:5m
109 where 's' is seconds and 'm' is minutes.
111 Which filters are invoked and their sequencing is handled by the
112 InputMailFilters option. Note: if InputMailFilters is not defined no filters
115 O InputMailFilters=filter1, filter2, filter3
117 This is is set automatically according to the order of the
118 INPUT_MAIL_FILTER commands in your .mc file. Alternatively, you can
119 reset its value by setting confINPUT_MAIL_FILTERS in your .mc file.
120 This options causes the three filters to be called in the same order
121 they were specified. It allows for possible future filtering on output
122 (although this is not intended for this release).
124 Also note that a filter can be defined without adding it to the input
125 filter list by using MAIL_FILTER() instead of INPUT_MAIL_FILTER() in your
128 To test sendmail with the sample filter, the following might be added (in
129 the appropriate locations) to your .mc file:
131 INPUT_MAIL_FILTER(`sample', `S=local:/var/run/f1.sock')
138 Once you have compiled a filter, modified your .mc file and restarted
139 the sendmail process, you will want to test that the filter performs as
142 The sample filter takes one argument -p, which indicates the local port
143 on which to create a listening socket for the filter. Maintaining
144 consistency with the suggested options for sendmail.cf, this would be the
145 UNIX domain socket located in /var/run/f1.sock.
147 % ./sample -p local:/var/run/f1.sock
149 If the sample filter returns immediately to a command line, there was either
150 an error with your command or a problem creating the specified socket.
151 Further logging can be captured through the syslogd daemon. Using the
152 'netstat -a' command can ensure that your filter process is listening on
153 the appropriate local socket.
155 Email messages must be injected via SMTP to be filtered. There are two
156 simple means of doing this; either using the 'sendmail -bs' command, or
157 by telnetting to port 25 of the machine configured for milter. Once
158 connected via one of these options, the session can be continued through
159 the use of standard SMTP commands.
162 220 test.sendmail.com ESMTP Sendmail 8.11.0/8.11.0; Tue, 10 Nov 1970 13:05:23 -0500 (EST)
164 250 test.sendmail.com Hello testy@localhost, pleased to meet you
166 250 2.1.0 <testy>... Sender ok
168 250 2.1.5 <root>... Recipient ok
170 354 Enter mail, end with "." on a line by itself
171 From: testy@test.sendmail.com
172 To: root@test.sendmail.com
173 Subject: testing sample filter
177 250 2.0.0 dB73Zxi25236 Message accepted for delivery
179 221 2.0.0 test.sendmail.com closing connection
181 In the above example, the lines beginning with numbers are output by the
182 mail server, and those without are your input. If everything is working
183 properly, you will find a file in /tmp by the name of msg.XXXXXXXX (where
184 the Xs represent any combination of letters and numbers). This file should
185 contain the message body and headers from the test email entered above.
187 If the sample filter did not log your test email, there are a number of
188 methods to narrow down the source of the problem. Check your system
189 logs written by syslogd and see if there are any pertinent lines. You
190 may need to reconfigure syslogd to capture all relevant data. Additionally,
191 the logging level of sendmail can be raised with the LogLevel option.
192 See the sendmail(8) manual page for more information.
199 libmilter requires pthread support in the operating system. Moreover, it
200 requires that the library functions it uses are thread safe; which is true
201 for the operating systems libmilter has been developed and tested on. On
202 some operating systems this requires special compile time options (e.g.,
203 not just -pthread). libmilter is currently known to work on (modulo problems
204 in the pthread support of some specific versions):
210 Linux (recent versions/distributions)
212 libmilter is currently not supported on:
217 Feedback about problems (and possible fixes) is welcome.
219 +--------------------------+
220 | SOURCE FOR SAMPLE FILTER |
221 +--------------------------+
223 Note that the filter below may not be thread safe on some operating
224 systems. You should check your system man pages for the functions used
225 below to verify the functions are thread safe.
227 /* A trivial filter that logs all email to a file. */
229 #include <sys/types.h>
233 #include <sysexits.h>
236 #include "libmilter/mfapi.h"
250 #define MLFIPRIV ((struct mlfiPriv *) smfi_getpriv(ctx))
252 extern sfsistat mlfi_cleanup(SMFICTX *, bool);
255 mlfi_envfrom(ctx, envfrom)
259 struct mlfiPriv *priv;
262 /* allocate some private memory */
263 priv = malloc(sizeof *priv);
266 /* can't accept this message right now */
267 return SMFIS_TEMPFAIL;
269 memset(priv, '\0', sizeof *priv);
271 /* open a file to store this message */
272 priv->mlfi_fname = strdup("/tmp/msg.XXXXXXXX");
273 if (priv->mlfi_fname == NULL)
276 return SMFIS_TEMPFAIL;
278 if ((fd = mkstemp(priv->mlfi_fname)) < 0 ||
279 (priv->mlfi_fp = fdopen(fd, "w+")) == NULL)
283 free(priv->mlfi_fname);
285 return SMFIS_TEMPFAIL;
288 /* save the private data */
289 smfi_setpriv(ctx, priv);
291 /* continue processing */
292 return SMFIS_CONTINUE;
296 mlfi_header(ctx, headerf, headerv)
301 /* write the header to the log file */
302 fprintf(MLFIPRIV->mlfi_fp, "%s: %s\r\n", headerf, headerv);
304 /* continue processing */
305 return SMFIS_CONTINUE;
312 /* output the blank line between the header and the body */
313 fprintf(MLFIPRIV->mlfi_fp, "\r\n");
315 /* continue processing */
316 return SMFIS_CONTINUE;
320 mlfi_body(ctx, bodyp, bodylen)
325 /* output body block to log file */
326 if (fwrite(bodyp, bodylen, 1, MLFIPRIV->mlfi_fp) <= 0)
329 (void) mlfi_cleanup(ctx, false);
330 return SMFIS_TEMPFAIL;
333 /* continue processing */
334 return SMFIS_CONTINUE;
341 return mlfi_cleanup(ctx, true);
355 return mlfi_cleanup(ctx, false);
359 mlfi_cleanup(ctx, ok)
363 sfsistat rstat = SMFIS_CONTINUE;
364 struct mlfiPriv *priv = MLFIPRIV;
372 /* close the archive file */
373 if (priv->mlfi_fp != NULL && fclose(priv->mlfi_fp) == EOF)
375 /* failed; we have to wait until later */
376 rstat = SMFIS_TEMPFAIL;
377 (void) unlink(priv->mlfi_fname);
381 /* add a header to the message announcing our presence */
382 if (gethostname(host, sizeof host) < 0)
383 snprintf(host, sizeof host, "localhost");
384 p = strrchr(priv->mlfi_fname, '/');
386 p = priv->mlfi_fname;
389 snprintf(hbuf, sizeof hbuf, "%s@%s", p, host);
390 smfi_addheader(ctx, "X-Archived", hbuf);
394 /* message was aborted -- delete the archive file */
395 (void) unlink(priv->mlfi_fname);
398 /* release private memory */
399 free(priv->mlfi_fname);
401 smfi_setpriv(ctx, NULL);
407 struct smfiDesc smfilter =
409 "SampleFilter", /* filter name */
410 SMFI_VERSION, /* version code -- do not change */
411 SMFIF_ADDHDRS, /* flags */
412 NULL, /* connection info filter */
413 NULL, /* SMTP HELO command filter */
414 mlfi_envfrom, /* envelope sender filter */
415 NULL, /* envelope recipient filter */
416 mlfi_header, /* header filter */
417 mlfi_eoh, /* end of header */
418 mlfi_body, /* body block filter */
419 mlfi_eom, /* end of message */
420 mlfi_abort, /* message aborted */
421 mlfi_close /* connection cleanup */
430 bool setconn = false;
432 const char *args = "p:";
434 /* Process command line options */
435 while ((c = getopt(argc, argv, args)) != -1)
440 if (optarg == NULL || *optarg == '\0')
442 (void) fprintf(stderr, "Illegal conn: %s\n",
446 (void) smfi_setconn(optarg);
454 fprintf(stderr, "%s: Missing required -p argument\n", argv[0]);
457 if (smfi_register(smfilter) == MI_FAILURE)
459 fprintf(stderr, "smfi_register failed\n");
460 exit(EX_UNAVAILABLE);
467 $Revision: 8.35.2.2 $, Last updated $Date: 2003/05/26 04:10:06 $