README
1qmail-qfilter
2qmail-queue multi-filter front end
3Bruce Guenter <bruceg@em.ca>
4Version 2.1
52005-08-12
6
7This program allows the body and/or envelope of a message to be filtered
8through a series of filters before being passed to the real qmail-queue
9program, and injected into the qmail queue.
10
11A mailing list has been set up to discuss this and other packages.
12To subscribe, send an email to:
13 bgware-subscribe@lists.untroubled.org
14A mailing list archive is available at:
15 http://lists.untroubled.org/?list=bgware
16
17Development versions of qmail-qfilter are available via Subversion at:
18 svn://bruce-guenter.dyndns.org/qmail-qfilter/trunk
19
20Requirements:
21
22- bglibs is required for system dependancies.
23
24- This program is designed to take advantage of my QMAILQUEUE patch,
25 which causes programs that would execute qmail-queue (such as
26 qmail-smtpd etc.) to execute an alternative program.
27
28How to install:
29
30- Check the definitions at the top of qmail-qfilter.c, especially the
31 value of TMPDIR. This should be set to a temporary directory that
32 only the executor of qmail-qfilter has write access to.
33- Check the conf-* files for appropriate values for your compiler and
34 linker, and installation paths.
35- Run "make"
36- As root, run "make install"
37
38How to use, with the QMAILQUEUE patch applied to qmail:
39
40- Create a script containing an invocation of qmail-qfilter. For
41 example, a script that uses qmail-inject as a front end to qmail-queue
42 would contain:
43 #!/bin/sh
44 exec /path/to/qmail-qfilter /var/qmail/bin/qmail-inject -n
45- Set the environment variable QMAILQUEUE to the location of this
46 script. For example, in a SMTP rules files, put:
47 A.B.C.D:allow,RELAYCLIENT="",QMAILQUEUE="/usr/local/bin/qmail-qftest"
48 and rebuild the SMTP CDB file.
49- You're all set! In our example, all messages sent from the IP A.B.C.D
50 will have their content filtered through qmail-inject, which will add
51 missing "From:", "Date:", and "Message-Id:" headers.
52
53How to use, without the QMAILQUEUE patch:
54- Change the definition of QMAIL_QUEUE in qmail-qfilter.c to a different
55 value, either by editing the source file or by modifying the DEFINES
56 line in the Makefile to read:
57 -DQMAIL_QUEUE=\"/var/qmail/bin/qmail-queue-old\"
58- Compile qmail-qfilter.
59- Rename qmail-queue to the new filename specified above.
60- Create a script to replace qmail-queue that contains an invocation of
61 qmail-qfilter, as described in the previous example.
62- You're all set! All mail entering the queue will be filtered by your
63 filter.
64
65Notes on writing a filter program:
66- If you want to block an email, exit from the filter with code 31.
67 This will cause qmail-qfilter to exit with the same error code, and
68 qmail-smtpd (for example) to send an error code to the client.
69- If you want to silently drop an email, exit with code 99.
70- The filter script that executes qmail-queue MUST NOT be setuid, and
71 MUST BE readable. Only the real qmail-queue binary needs to be
72 setuid.
73
74See the scripts in the "samples" directory for example scripts.
75
76This program is Copyright(C) 2001,2004-2005 Bruce Guenter, and may be
77copied according to the GNU GENERAL PUBLIC LICENSE (GPL) Version 2 or a
78later version. A copy of this license is included with this package.
79This package comes with no warranty of any kind.
80