1
<?xml version="1.0" encoding="iso-8859-1"?>
2
1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4
3
<html xmlns="http://www.w3.org/1999/xhtml">
5
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
6
6
<meta name="Author" content="Sam Varshavchik" />
7
7
<title>Maildir filter access</title>
8
8
<meta name="MSSmartTagsPreventParsing" content="TRUE" />
11
<!-- $Id: README.maildirfilter.html,v 1.4 2003/07/24 23:04:54 mrsam Exp $ -->
11
<!-- $Id: README.maildirfilter.html,v 1.5 2004/08/01 18:47:14 mrsam Exp $ -->
12
12
<!-- Copyright 1998 - 1999 Double Precision, Inc. See COPYING for -->
13
13
<!-- distribution information. -->
14
14
<body text="#000000" bgcolor="#FFFFFF" link="#0000EE" vlink="#551A8B"
16
16
<h1>Maildir filter implementation</h1>
18
18
<p>Implementing mail filtering requires a couple of dominos to fall in the
19
right order. This is not difficult to do, but is a bit tricky. Here's how
20
it works, in general. Specifics follow.</p>
19
right order. This is not difficult to do, but is a bit tricky. Here's how it
20
works, in general. Specifics follow.</p>
22
<p>Some people would probably have a difficult time setting it up. That's to
23
be expected. The implementation allows only selected accounts to be set up
22
<p>Some people would probably have a difficult time setting it up. That's to
23
be expected. The implementation allows only selected accounts to be set up
24
24
for mail filtering, so the suggested way is to attempt to set up mail
25
25
filtering for one account only, test it to make sure it works, then roll it
30
30
<p>The <em>maildrop</em> mail filter is used to do the actual mail filter.
31
31
The first thing you need to do is to download and install <em>maildrop</em>.
32
32
Download <em>maildrop</em> from <a
33
href="http://www.flounder.net/~mrsam/maildrop/">http://www.flounder.net/~mrsam/maildrop/</a>.
34
Follow the instruction in the <em>maildrop</em> package to configure it and
35
install it. <em>maildrop</em> must be installed as your mail server's mail
36
delivery agent. <em>maildrop</em> must be used to deliver mail to the
37
maildir, obviously, since that's how filtering takes place. You need to
38
follow the instructions for your mail server in order to install
39
<em>maildrop</em> as the mail delivery agent. <em>maildrop</em> must be
40
configured to locate the recipient's maildir, and dump mail there by default.
41
Review <em>maildrop</em>'s and the mail server's documentation. This can't
42
be any more specific. Different mail servers are configured in different
33
href="http://www.courier-mta.org/maildrop/"
34
target="_top">http://www.courier-mta.org/maildrop/</a>. Follow the
35
instruction in the <em>maildrop</em> package to configure it and install it.
36
<em>maildrop</em> must be installed as your mail server's mail delivery
37
agent. <em>maildrop</em> must be used to deliver mail to the maildir,
38
obviously, since that's how filtering takes place. You need to follow the
39
instructions for your mail server in order to install <em>maildrop</em> as
40
the mail delivery agent. <em>maildrop</em> must be configured to locate the
41
recipient's maildir, and dump mail there by default. Review
42
<em>maildrop</em>'s and the mail server's documentation. This can't be any
43
more specific. Different mail servers are configured in different way.</p>
45
45
<p>For example, with Qmail the usual thing to do is to initialize
46
46
$HOME/.qmail with "| /usr/local/bin/maildrop". <em>maildrop</em> is also
47
included as part of the <a href="http://courier.sourceforge.net/">Courier
48
mail server</a>. If you're running Courier already, you don't need to do
49
actually download and install <em>maildrop</em>. You already have everything
50
you need, all you need to do is to flip the switch that uses
51
<em>maildrop</em> for local mail delivery. This is done by editing the
52
<code>courierd</code> configuration file (usually installed in the
47
included as part of the <a href="http://www.courier-mta.org/">Courier mail
48
server</a>. If you're running Courier already, you don't need to do actually
49
download and install <em>maildrop</em>. You already have everything you need,
50
all you need to do is to flip the switch that uses <em>maildrop</em> for
51
local mail delivery. This is done by editing the <code>courierd</code>
52
configuration file (usually installed in the
53
53
<code>/usr/lib/courier/etc</code> directory), and setting
54
54
<code>DEFAULTDELIVERY</code> according to the instructions in that
55
55
configuration file.</p>
57
57
<p>The next thing to do is to actually learn how <em>maildrop</em> works, and
58
learn its filtering language. Although the mail filter will be automaticaly
58
learn its filtering language. Although the mail filter will be automaticaly
59
59
generated here, you still need to become familiar with the filtering language
60
60
in order to troubleshoot any installation problems. <em>maildrop</em> comes
61
61
with manual pages documenting the filtering language, as well as some
64
64
<h2>The little picture</h2>
66
<p>Here's what's going to happen. The webmail server will automatically
67
generate a <em>maildrop</em> filtering recipe. <em>maildrop</em> reads the
68
recipe, and does its thing. Sounds simple enough, right?</p>
66
<p>Here's what's going to happen. The webmail server will automatically
67
generate a <em>maildrop</em> filtering recipe. <em>maildrop</em> reads the
68
recipe, and does its thing. Sounds simple enough, right?</p>
70
<p>Well, it's not. There are a few little details that need to be
70
<p>Well, it's not. There are a few little details that need to be
73
73
<p>For starters, the default <em>maildrop</em> filtering recipe is
74
<code>$HOME/.mailfilter</code>. That's how things usually are when actual
75
physical system accounts are used. When virtual mailboxes are installed,
76
things are less murky. There is no standard way to do virtual mail
74
<code>$HOME/.mailfilter</code>. That's how things usually are when actual
75
physical system accounts are used. When virtual mailboxes are installed,
76
things are less murky. There is no standard way to do virtual mail
77
77
arrangement, so the actual implementation varies from system to system.
78
78
Somehow or other all or some portion of virtual mailboxes share the same
79
physical account, and have the same $HOME. In that case the usual thing to
80
do is for each virtual mailbox, the corresponding mail filtering recipe is
79
physical account, and have the same $HOME. In that case the usual thing to do
80
is for each virtual mailbox, the corresponding mail filtering recipe is
81
81
manually specified to <em>maildrop</em>, as an extra command line argument.
82
82
Review the <em>maildrop</em> documentation for more information.</p>
84
84
<p>Now, on the other hand, the webmail server doesn't really know anything
85
about physical and virtual accounts. The mapping between a login ID and the
85
about physical and virtual accounts. The mapping between a login ID and the
86
86
maildir is completely encapsulated in a black box-type authentication layer.
87
87
The login ID and password are validated by the authentication layer, which
88
88
obtains the maildir corresponding to the login ID, and the webmail server is
89
started for that maildir. Whether or not a login ID corresponds to an actual
89
started for that maildir. Whether or not a login ID corresponds to an actual
90
90
system account or to virtual account, that's something the webmail server
91
doesn't really know, or care. All it cares about is the maildir where all
92
the mail is, and that's the end of the story.</p>
91
doesn't really know, or care. All it cares about is the maildir where all the
92
mail is, and that's the end of the story.</p>
94
94
<p>So, the issue is that the webmail server needs to find the corresponding
95
95
<em>maildrop</em> filtering recipe, so it knows where to write the mail
96
delivery instructions. This is how it works.</p>
96
delivery instructions. This is how it works.</p>
98
98
<p>In order for mail filtering to be enabled, it is necessary to initialize
99
99
the file named <code>maildirfilterconfig</code> in the maildir itself. This
100
100
is where the webmail server runs, so it will simply look for the file of this
101
name. The contents of this file should be as follows:</p>
101
name. The contents of this file should be as follows:</p>
102
102
<pre>MAILDIRFILTER=<em>pathtomailfilter</em>
103
103
MAILDIR=<em>pathtomaildir</em></pre>
110
110
<p>In most cases, where virtual mailboxes are not used, everyone's maildir is
111
111
<code>$HOME/Maildir</code>, and <em>maildrop</em> uses
112
<code>$HOME/.mailfilter</code> by default. In this case,
112
<code>$HOME/.mailfilter</code> by default. In this case,
113
113
<em>pathtomailfilter</em> must be set to <code>../.mailfilter</code>.</p>
115
115
<p>When virtual mail accounts are used, this will obviously be something
116
116
else. The only restriction is that the <em>maildrop</em> filtering recipe and
117
117
the maildir <strong>must be on the same filesystem or partition</strong>.</p>
119
<p><em>pathtomaildir</em> is the other half of the story. When
119
<p><em>pathtomaildir</em> is the other half of the story. When
120
120
<em>maildrop</em> gets a message to deliver, <em>maildrop</em> needs to know
121
where the mailboxes and folders are. <em>Maildrop</em> begins running in
122
what it considers to be the recipient's home directory, reading either
121
where the mailboxes and folders are. <em>Maildrop</em> begins running in what
122
it considers to be the recipient's home directory, reading either
123
123
<code>.mailfilter</code>, by default, or the file specified on the command
126
126
<p>The webmail server needs to generate filtering instruction that deliver
127
messages to its maildir. By default, the maildir for non-virtual accounts is
127
messages to its maildir. By default, the maildir for non-virtual accounts is
128
128
$HOME/Maildir, so <em>pathtomaildir</em> needs to be set to
129
129
<code>./Maildir</code>.</p>
135
135
<code>./Maildir</code>. When virtual mail accounts are used,
136
136
<em>maildrop</em> still must be used as a mail delivery agent, somethow,
137
137
specifying the correct maildir that corresponds to the recipient's mail
138
account. Usually all or most virtual accounts are set up inside a single
139
physical account. In that case it is necessary to set up a different
138
account. Usually all or most virtual accounts are set up inside a single
139
physical account. In that case it is necessary to set up a different
140
140
<em>maildrop</em> filtering recipe file for each virtual mail account (since
141
141
everyone's <code>$HOME/.mailfilter</code> will be the same file), and in each
142
142
maildir specify the relative path to its corresponding filtering recipe, and
169
169
<p>If everything is set up correctly, SqWebMail will now display a new link
170
170
to a screen where mail filtering rules are defined and installed. A mail
171
filter consists of a condition, and an action. A condition is usually based
171
filter consists of a condition, and an action. A condition is usually based
172
172
on the contents of some header, or the message body. Regular expressions are
173
allowed. Which means that certain special characters must be quoted. For
173
allowed. Which means that certain special characters must be quoted. For
174
174
example, to search for the string "[announce]" verbatim in the subject
175
header, it must be entered as "\[announce\]". Pattern matching, for now, is
175
header, it must be entered as "\[announce\]". Pattern matching, for now, is
176
176
case-insensitive. The regular expression syntax uses pretty much the same
177
syntax as Perl. See the maildropfilter manual page for more information.</p>
177
syntax as Perl. See the maildropfilter manual page for more information.</p>
179
<p>Multiple mail filtering rules can be installed. Their relative order can
179
<p>Multiple mail filtering rules can be installed. Their relative order can
180
180
be rearranged by selecting a filtering rule, then selecting either the "Up"
181
181
or the "Down" button. It is necessary to select "Save all changes" for any
182
changes to the filtering rules to take effect. Leaving that page in any
183
other way will throw away all changes made.</p>
182
changes to the filtering rules to take effect. Leaving that page in any other
183
way will throw away all changes made.</p>
195
195
<li>What's going to happen now with mail grabbed by this filter? In the
196
current implementation this results with a deferred error. The message
197
is not bounced immediately, but will stay in the queue until the mail
198
server times it out. If this condition is caught quickly enough, and the
199
folder is recreated, all pent up mail will be redelivered.<br />
196
current implementation this results with a deferred error. The message is
197
not bounced immediately, but will stay in the queue until the mail server
198
times it out. If this condition is caught quickly enough, and the folder
199
is recreated, all pent up mail will be redelivered.<br />
202
202
<li>There's some school of thought that says that this should result in
203
mail bouncing immediately. No decision has been made at this point.</li>
203
mail bouncing immediately. No decision has been made at this point.</li>
added
removed
maildir/README.maildirfilter.html
