1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
|
<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.52
from spec on 25 November 2000 -->
<TITLE>Exim Specification - 47. System-wide message filtering</TITLE>
</HEAD>
<body bgcolor="#FFFFFF" text="#00005A" link="#FF6600" alink="#FF9933" vlink="#990000">
Go to the <A HREF="spec_1.html">first</A>, <A HREF="spec_46.html">previous</A>, <A HREF="spec_48.html">next</A>, <A HREF="spec_59.html">last</A> section, <A HREF="spec_toc.html">table of contents</A>.
<P><HR><P>
<H1><A NAME="SEC815" HREF="spec_toc.html#TOC815">47. System-wide message filtering</A></H1>
<P>
<A NAME="IDX1795"></A>
<A NAME="IDX1796"></A>
<A NAME="IDX1797"></A>
The previous chapters describe checks that can be applied to messages before
they are accepted by a host. There are also mechanisms for checking messages
once they have been received, but before they are delivered. If a <EM>system
message filter</EM> is defined, it is run each time a delivery process is started
for a message. It is also possible to run a centrally-defined filter file once
for each local address, as part of the directing for that address.
</P>
<P>
<H2><A NAME="SEC816" HREF="spec_toc.html#TOC816">47.1 The system message filter</A></H2>
<P>
The system message filter operates in a similar manner to users' filter files,
but it is run just once per message (however many recipients is has) at the
start of a delivery attempt, before any routing or directing is done. If a
message fails to be completely delivered at the first attempt, the filter is
run again at the start of every retry.
</P>
<P>
<A NAME="IDX1798"></A>
There are two special conditions which, though available in users' filter
files, are designed for use in system filters. The condition <EM>first_delivery</EM>
is true only for the first attempt at delivering a message, while
<EM>manually_thawed</EM> is true only if the message has been frozen, and
subsequently thawed by an admin user. An explicit forced delivery counts as a
manual thaw, but thawing as a result of the <EM>auto_thaw</EM> setting does not.
</P>
<P>
If the filter sets up any deliveries of its own, an extra header line is added
to them with the name <EM>X-Envelope-to:</EM>. This contains up to 100 of the original
message's envelope recipients. If the filter specifies any significant
deliveries, the message's own recipient list is ignored; otherwise it is
added to any recipients set up by the filter.
</P>
<P>
<A NAME="IDX1799"></A>
<A NAME="IDX1800"></A>
The <EM>message_filter</EM> option names the filter file, while
<EM>message_filter_user</EM> and <EM>message_filter_group</EM> specify the uid and gid to
be used while processing it. If they are not set, the Exim uid is used if
available and if <EM>seteuid()</EM> is available; otherwise <EM>root</EM> is used.
</P>
<P>
<font color=green>
<b>Important</b>: If the system filter generates any deliveries directly to
files or pipes (via the <EM>save</EM> or <EM>pipe</EM> commands), transports to handle theses
deliveries must be specified by setting <EM>message_filter_file_transport</EM> and
<EM>message_filter_pipe_transport</EM>, respectively. Similarly,
<EM>message_filter_reply_transport</EM> must be set to handle any autoreplies.
</P>
<P>
The filter file can contain any of the normal filtering commands, as described
in the separate document <EM>Exim's interface to mail filtering</EM>. However,
remember that the system filter is run just once, at the start of a delivery
process, however many recipients the message may have. For this reason, the
variables $<EM>local_part</EM> and $<EM>domain</EM> are not available, nor does the
`personal' condition make any sense.
</font>
</P>
<P>
The filter variables $<EM>n0</EM> -- $<EM>n9</EM> can be used in a system filter; when it
finishes, their values are copied into $<EM>sn0</EM> -- $<EM>sn9</EM> and are thereby made
available to users' filter files. Thus a system filter can, for example, set up
a `score' for a message to which users' filter files can refer.
</P>
<H2><A NAME="SEC817" HREF="spec_toc.html#TOC817">47.2 Additional commands for system filters</A></H2>
<P>
<font color=green>
In a system filter, if a <EM>deliver</EM> command is followed by
<PRE>
errors_to <<EM>some address</EM>>
</PRE>
<P>
in order to change the envelope sender (and hence the error reporting) for that
delivery, any address is permitted. (In a user filter, only the current user's
address can be set.)
</font>
For example, if some mail is being monitored, you might use
<PRE>
unseen deliver monitor@spying.example errors_to root@local.domain
</PRE>
<P>
to take a copy which would not be sent back to the normal error reporting
address if its delivery failed.
</P>
<P>
There are also some extra commands which are available only in system filter
files:
<PRE>
fail
freeze
headers add <<EM>string</EM>>
headers remove <<EM>string</EM>>
</PRE>
<P>
<A NAME="IDX1801"></A>
As well as the additional commands, there is also an extra expansion variable,
$<EM>recipients</EM>, containing a list of all the recipients of the message,
separated by commas and white space. The extra commands and variable are not
available in ordinary users' filter files. They are faulted in normal use and
in testing via -<EM>bf</EM>, but not if -<EM>bF</EM> is used.
</P>
<P>
The <EM>freeze</EM> and <EM>fail</EM> commands can optionally be followed by the word <EM>text</EM>
and a string containing an error message, for example:
<PRE>
fail text "this message looks like spam to me"
</PRE>
<P>
The keyword <EM>text</EM> is optional if the next character is a double quote. The
<EM>fail</EM> command causes all recipients to be failed, while <EM>freeze</EM> suspends all
delivery attempts. It is ignored if the message has been manually unfrozen and
not manually frozen since. This means that automatic freezing by a system
filter can be used as a way of checking out suspicious messages. If a message
is found to be all right, manually unfreezing it allows it to be delivered.
</P>
<P>
<font color=green>
The interpretation of a system filter file ceases after a <EM>freeze</EM> or <EM>fail</EM>
command is obeyed. However, any deliveries that were set up earlier in the
filter file are honoured, so you can use a sequence such as
<PRE>
mail ...
freeze
</PRE>
<P>
to send a specified message when the system filter is freezing (or failing)
something. The normal deliveries for the message do not, of course, take place.
</font>
</P>
<P>
The argument for the <EM>headers add</EM> is a string which is expanded and then added
to the end of the message's headers. It is the responsibility of the filter
maintainer to make sure it conforms to RFC 822 syntax.
Leading white space is ignored, and if the string is otherwise empty, or if the
expansion is forced to fail, the command has no effect. A newline is added at
the end of the string if it lacks one.
More than one header may be added in one command by including `\n' within the
string.
</P>
<P>
The argument for <EM>headers remove</EM> is a colon-separated list of header names.
This command applies only to those headers that are stored with the message;
ones such as <EM>Envelope-To:</EM> and <EM>Return-Path:</EM> that are added at delivery time
cannot be removed by this means.
</P>
<P>
<A NAME="IDX1802"></A>
Take great care with the <EM>fail</EM> command when basing the decision to fail on the
contents of the message, because this option causes a normal delivery error
message to be generated, and it will of course include the contents of the
original message and will therefore trigger the <EM>fail</EM> command again (causing a
mail loop) unless steps are taken to prevent this. Testing the <EM>error_message</EM>
condition is one way to prevent this. You could use, for example
<PRE>
if $message_body contains "this is spam" and not error_message
then fail text "spam is not wanted here" endif
</PRE>
<P>
though of course that might still let through unwanted messages. The
alternative is clever checking of the body and/or headers to detect error
messages caused by the filter.
</P>
<H2><A NAME="SEC818" HREF="spec_toc.html#TOC818">47.3 Per-address filtering</A></H2>
<P>
In contrast to the system filter, which is run just once per message for each
delivery attempt, it is also possible to set up a system-wide filtering
operation that runs once for each address, for local addresses only. In this
case, variables such as $<EM>local_part</EM> and $<EM>domain</EM> can be used, and indeed,
the choice of filter file could be made dependent on them. This is an example
of a director which implements such a filter:
<PRE>
central_filter:
driver = forwardfile
file = /central/filters/$local_part
no_check_local_user
no_verify
filter
allow_system_actions
</PRE>
<P>
The setting of <EM>allow_system_actions</EM> permits the use of <EM>freeze</EM> and <EM>fail</EM>
in the filter file, but not the <EM>headers</EM> command or the $<EM>recipients</EM>
variable.
<font color=green>
As in the case of a system filter, <EM>freeze</EM> and <EM>fail</EM> cause filter
interpretation to cease, but any deliveries that were previously set up are
honoured.
</font>
</P>
<P><HR><P>
Go to the <A HREF="spec_1.html">first</A>, <A HREF="spec_46.html">previous</A>, <A HREF="spec_48.html">next</A>, <A HREF="spec_59.html">last</A> section, <A HREF="spec_toc.html">table of contents</A>.
</BODY>
</HTML>
|
