1
1
AMAVIS POLICY DELEGATION PROTOCOL (AM.PDP)
2
2
==========================================
3
3
Author: Mark Martinec <Mark.Martinec@ijs.si>
4
Created: 2003-11-10, last modified 2004-09-09, 2005-03-18, 2005-06-22
6
6
NOTE: at the end of this document there is a description
7
7
(by Stephane Lentz) of the currently used protocol.
10
10
Amavis policy delegation protocol is intended to replace the old amavis
11
11
client protocol as spoken between amavisd-new helper programs (amavis.c
12
or amavis-milter.c) and the amavisd daemon. The server side is already
13
implemented and will be available with the next major release or amavisd-new.
12
or amavis-milter.c) and the amavisd daemon. The server side is
13
implemented by amavisd-new daemon. A sample AM.PDP client in Perl is
14
helper-prog/samavis.pl, and a rewrite by Petr Rehor of the helper
15
program amavis-milter.c to use the new AM.PDP protocol is available
16
as a separate project, see:
17
http://sourceforge.net/projects/amavisd-milter/
16
20
The new amavisd client/server protocol is based on the
114
118
The attribute value syntax is specified in rfc2821 as 'Forward-path'.
116
120
tempdir=/var/amavis/amavis-milter-MWZmu9Di
117
specifies a temporary directory where a file named 'email.txt'
118
is prepared, containing the full mail with header and body.
119
This attribute should be present exactly once. The server is allowed
120
to use the specified directory to create additional temporary files
121
Specifies a temporary work directory to be used for mail unpacking,
122
typically also containing the original mail file - see attribute
123
'mail_file' below. This attribute should be present exactly once.
124
The server is allowed to use the specified directory to create
125
additional temporary files if it chooses so.
123
127
tempdir_removed_by=client
124
128
Specifies the client will be responsible for removing the temporary
125
directory. The server must not remove the file email.txt nor the directory.
129
directory. The server must not remove the file email.txt nor the directory,
130
but it may remove temporary files and subdirectories it has created.
127
132
tempdir_removed_by=server
128
133
Specifies the server is responsible to remove the temporary directory
129
134
if/when it deems appropriate. This is a default in the absence of this
130
135
attribute (for compatibility with traditional amavis clients).
137
mail_file=/var/amavis/amavis-milter-MWZmu9Di/email.txt
138
Specifies a file name (full file path) of a file containing the original
139
mail with header and body. This attribute should be present at most once.
140
In its absence the file name defaults to <tempdir>/email.txt.
132
142
delivery_care_of=client
133
143
Specifies that server should NOT actively forward the mail to recipients,
134
144
but should only report its opinion in its reply, and let the client
278
===============================================================================
279
Releasing a message from a quarantine:
283
secret_id=xxxxxxxxxxxx (authorizes a release)
284
quar_type=x F/Z/B/Q/M (file/zipfile/bsmtp/sql/mailbox)
285
mail_file=... (optional: overrides automatics; $QUARANTINEDIR prepended)
286
requested_by=<releaser@example.com> (optional: lands in Resent-From:)
287
sender=<foo@example.com> (optional: replaces envelope sender)
288
recipient=<bar1@example.net> (optional: replaces envelope recips)
289
recipient=<bar2@example.net>
292
In reply, for each recipient a SMTP status response is returned
295
quar_type defaults to Q if spam_quarantine_method is sql:, otherwise to F.
266
297
===============================================================================
267
298
AMAVIS SIMPLE CLIENT/SERVER PROTOCOL (traditional)
268
299
description by Stephane Lentz
271
amavisd is the daemon part of AMAVIS in charge of scanning SMTP messages.
272
It receives messages from other applications (clients) using either
273
SMTP or a simple protocol which is detailed in this document.
302
amavisd is the daemon part of AMAVIS in charge of scanning SMTP messages.
303
It receives messages from other applications (clients) using either
304
SMTP or a simple protocol which is detailed in this document.
274
305
The protocol being used depends on the MTA and architecture chosen.
275
The "simple protocol" is most often used with sendmail in a MILTER
276
set-up (the client program in such a case is amavis-client).
306
The "simple protocol" is most often used with sendmail in a MILTER
307
set-up (the client program in such a case is amavis-client).
278
AMAVISD receives messages from clients through a UNIX socket :
309
AMAVISD receives messages from clients through a UNIX socket :
279
310
The UNIX socket used is by default /var/amavis/amavisd.sock .
281
312
- at the amavisd server level in amavisd.conf as $unix_socketname
282
313
- at the client level when using MILTER (amavis-milter available in
283
helper-progs) as a configure option : --with-sockname swith
314
helper-progs) as a configure option : --with-sockname swith
285
316
The protocol used between the client and server is simple (basic & limited).
286
There is no possibility for the server to ask the client to remove/add/change
287
headers. The server can only say if the message was detected as CLEAN, as
317
There is no possibility for the server to ask the client to remove/add/change
318
headers. The server can only say if the message was detected as CLEAN, as
288
319
UNSAFE and to be rejected/discarded) or not analysed successfully due to
291
PROTOCOL IN DETAILS :
293
The client connects to the AMAVISD server's socket.
322
PROTOCOL IN DETAILS :
324
The client connects to the AMAVISD server's socket.
294
325
IF successful then for each incoming message :
295
326
- the client computes and create a new temporary directory ($tempdir)
296
to store the new incoming message.
327
to store the new incoming message.
297
328
- the incoming message is stored as $tempdir/email.txt
298
329
- the client sends the directory name to the SERVER
299
330
- the server sends \1 to the client if the directory is ok
301
332
- the server sends \1 to the client if ok
302
333
- the client sends the envelope recipient addresses one by one to the server:
303
334
the client trims the address if it is longer than the maximum length possible
304
the client sends this address to the server
335
the client sends this address to the server
305
336
the server sends \1 to the client if ok
306
337
- the client sends some request to analyze the message to the SERVER.
307
The character used is EOT (end of transmission) :\3
308
- the server processes the mail stored in the directory ($tempdir/email.txt)
338
The character used is EOT (end of transmission) :\3
339
- the server processes the mail stored in the directory ($tempdir/email.txt)
309
340
- the server sends a STATUS number to the CLIENT. This number returned is
311
342
EX_OK (2) : message CLEAN
312
343
EX_UNAVAILABLE (69) : message UNSAFE to be rejected at the SMTP LEVEL
314
345
99 : message UNSAFE to be silently (250 code) discarded
316
347
EX_TEMPFAIL (75) : message not processed successfully (error in
317
348
communication, or server error, ...)
added
removed
README_FILES/README.protocol
