Author: jm
Date: Mon Jan 8 08:00:03 2007
New Revision: 494106
URL: http://svn.apache.org/viewvc?view=rev&rev=494106
Log:
document the new Compress protocol header; clean up protocol doc a bit more, clarifying newlines, headers, and optional stuff
Modified:
spamassassin/trunk/spamd/PROTOCOL
Modified: spamassassin/trunk/spamd/PROTOCOL
URL: http://svn.apache.org/viewvc/spamassassin/trunk/spamd/PROTOCOL?view=diff&rev=494106&r1=494105&r2=494106
==============================================================================
--- spamassassin/trunk/spamd/PROTOCOL (original)
+++ spamassassin/trunk/spamd/PROTOCOL Mon Jan 8 08:00:03 2007
@@ -1,22 +1,24 @@
The SpamAssassin Network Protocol
=================================
-(This document is still a draft)
+(This document is perpetually in draft status)
Synopsis
--------
-The protocol for communication between spamc/spamd is somewhat HTTP like. The
+The protocol for communication between spamc/spamd is somewhat HTTP-like. The
conversation looks like:
- spamc --> PROCESS SPAMC/1.2
- spamc --> Content-length: <size>
- (optional) spamc --> User: <username>
+ spamc --> PROCESS SPAMC/1.2\r\n
+ spamc --> Content-length: <size>\r\n
+ (optional) spamc --> User: <username>\r\n
+ spamc --> [optional \r\n-delimited headers...]
spamc --> \r\n [blank line]
spamc --> --message sent here--
- spamd --> SPAMD/1.1 0 EX_OK
- spamd --> Content-length: <size>
+ spamd --> SPAMD/1.1 0 EX_OK\r\n
+ spamd --> Content-length: <size>\r\n
+ spamc --> [optional \r\n-delimited headers...]
spamd --> \r\n [blank line]
spamd --> --processed message sent here--
@@ -25,12 +27,20 @@
The first line from spamc is the command for spamd to execute (PROCESS a
message is the command in protocol<=1.2) followed by the protocol version.
+There may be additional headers following the command, which are as yet
+undefined. Servers should ignore these, and keep looking for headers which
+they do support, or the "\r\n\r\n" end-of-headers marker.
+
The first line of the response from spamd is the protocol version (note this is
SPAMD here, where it was SPAMC on the other side) followed by a response code
from sysexits.h followed by a response message string which describes the error
if there was one. If the response code is not 0, then the processed message
will not be sent, and the socket will be closed after the first line is sent.
+Again, there may be additional headers following the response line, which are
+as yet undefined. Clients should ignore these, and keep looking for headers
+which they do support, or the "\r\n\r\n" end-of-headers marker.
+
Commands
--------
@@ -67,13 +77,13 @@
score for this message, " / " then the threshold. So the entire response looks
like either:
- SPAMD/1.1 0 EX_OK
- Spam: True ; 15 / 5
+ SPAMD/1.1 0 EX_OK\r\n
+ Spam: True ; 15 / 5\r\n
or
- SPAMD/1.1 0 EX_OK
- Spam: False ; 2 / 5
+ SPAMD/1.1 0 EX_OK\r\n
+ Spam: False ; 2 / 5\r\n
There may be additional headers following the "Spam:" header, which
are as yet undefined. Clients should ignore these, and keep looking for
@@ -90,9 +100,9 @@
REPORT command returns the same as CHECK, followed immediately by the report
generated by spamd:
- SPAMD/1.1 0 EX_OK
- Spam: False ; 2 / 5
-
+ SPAMD/1.1 0 EX_OK\r\n
+ Spam: False ; 2 / 5\r\n
+ \r\n
This mail is probably spam. The original message has been attached
along with this report, so you can recognize or block similar unwanted
mail in future. See http://spamassassin.apache.org/tag/ for more details.
@@ -112,7 +122,7 @@
SKIP) no additional input is expected. It returns a simple confirmation
response, like this:
- SPAMD/1.2 0 PONG
+ SPAMD/1.2 0 PONG\r\n
This facility may be useful for monitoring programs which wish to check that
the daemon is alive and providing at least a basic response within a reasonable
@@ -124,21 +134,52 @@
are some examples:
To learn a message as spam:
-TELL SPAMC/1.3
-Message-class: spam
-Set: local
+TELL SPAMC/1.3\r\n
+Message-class: spam\r\n
+Set: local\r\n
To forget a learned message:
-TELL SPAMC/1.3
-Remove: local
+TELL SPAMC/1.3\r\n
+Remove: local\r\n
To report a spam message:
-TELL SPAMC/1.3
-Message-class: spam
-Set: local, remove
+TELL SPAMC/1.3\r\n
+Message-class: spam\r\n
+Set: local, remove\r\n
To revoke a ham message:
-TELL SPAMC/1.3
-Message-class: spam
-Set: local
-Remove: remote
+TELL SPAMC/1.3\r\n
+Message-class: spam\r\n
+Set: local\r\n
+Remove: remote\r\n
+
+Headers
+-------
+
+The following optional headers are defined as of protocol 1.2:
+
+Content-length
+
+ Length of a request or response body, in bytes (generally a requirement
+ as of protocol 1.2)
+
+Spam
+
+ See above; used in server responses to the CHECK command.
+
+User
+
+ Username of the user on whose behalf this scan is being performed. The
+ meaning of this is up to the server; format is that of a traditional UNIX
+ username ([-A-Za-z0-9_]+).
+
+Compress
+
+ An optional header, sent by the client to the server, whose value may
+ consist of the string "zlib", indicating that the message body transmitted
+ by the client is compressed using Zlib compression. This is new in
+ SpamAssassin 3.2.0.
+
+As-yet-undefined headers should not be treated as errors, and instead
+should be ignored.
+
Date: Mon Jan 8 08:00:03 2007
New Revision: 494106
URL: http://svn.apache.org/viewvc?view=rev&rev=494106
Log:
document the new Compress protocol header; clean up protocol doc a bit more, clarifying newlines, headers, and optional stuff
Modified:
spamassassin/trunk/spamd/PROTOCOL
Modified: spamassassin/trunk/spamd/PROTOCOL
URL: http://svn.apache.org/viewvc/spamassassin/trunk/spamd/PROTOCOL?view=diff&rev=494106&r1=494105&r2=494106
==============================================================================
--- spamassassin/trunk/spamd/PROTOCOL (original)
+++ spamassassin/trunk/spamd/PROTOCOL Mon Jan 8 08:00:03 2007
@@ -1,22 +1,24 @@
The SpamAssassin Network Protocol
=================================
-(This document is still a draft)
+(This document is perpetually in draft status)
Synopsis
--------
-The protocol for communication between spamc/spamd is somewhat HTTP like. The
+The protocol for communication between spamc/spamd is somewhat HTTP-like. The
conversation looks like:
- spamc --> PROCESS SPAMC/1.2
- spamc --> Content-length: <size>
- (optional) spamc --> User: <username>
+ spamc --> PROCESS SPAMC/1.2\r\n
+ spamc --> Content-length: <size>\r\n
+ (optional) spamc --> User: <username>\r\n
+ spamc --> [optional \r\n-delimited headers...]
spamc --> \r\n [blank line]
spamc --> --message sent here--
- spamd --> SPAMD/1.1 0 EX_OK
- spamd --> Content-length: <size>
+ spamd --> SPAMD/1.1 0 EX_OK\r\n
+ spamd --> Content-length: <size>\r\n
+ spamc --> [optional \r\n-delimited headers...]
spamd --> \r\n [blank line]
spamd --> --processed message sent here--
@@ -25,12 +27,20 @@
The first line from spamc is the command for spamd to execute (PROCESS a
message is the command in protocol<=1.2) followed by the protocol version.
+There may be additional headers following the command, which are as yet
+undefined. Servers should ignore these, and keep looking for headers which
+they do support, or the "\r\n\r\n" end-of-headers marker.
+
The first line of the response from spamd is the protocol version (note this is
SPAMD here, where it was SPAMC on the other side) followed by a response code
from sysexits.h followed by a response message string which describes the error
if there was one. If the response code is not 0, then the processed message
will not be sent, and the socket will be closed after the first line is sent.
+Again, there may be additional headers following the response line, which are
+as yet undefined. Clients should ignore these, and keep looking for headers
+which they do support, or the "\r\n\r\n" end-of-headers marker.
+
Commands
--------
@@ -67,13 +77,13 @@
score for this message, " / " then the threshold. So the entire response looks
like either:
- SPAMD/1.1 0 EX_OK
- Spam: True ; 15 / 5
+ SPAMD/1.1 0 EX_OK\r\n
+ Spam: True ; 15 / 5\r\n
or
- SPAMD/1.1 0 EX_OK
- Spam: False ; 2 / 5
+ SPAMD/1.1 0 EX_OK\r\n
+ Spam: False ; 2 / 5\r\n
There may be additional headers following the "Spam:" header, which
are as yet undefined. Clients should ignore these, and keep looking for
@@ -90,9 +100,9 @@
REPORT command returns the same as CHECK, followed immediately by the report
generated by spamd:
- SPAMD/1.1 0 EX_OK
- Spam: False ; 2 / 5
-
+ SPAMD/1.1 0 EX_OK\r\n
+ Spam: False ; 2 / 5\r\n
+ \r\n
This mail is probably spam. The original message has been attached
along with this report, so you can recognize or block similar unwanted
mail in future. See http://spamassassin.apache.org/tag/ for more details.
@@ -112,7 +122,7 @@
SKIP) no additional input is expected. It returns a simple confirmation
response, like this:
- SPAMD/1.2 0 PONG
+ SPAMD/1.2 0 PONG\r\n
This facility may be useful for monitoring programs which wish to check that
the daemon is alive and providing at least a basic response within a reasonable
@@ -124,21 +134,52 @@
are some examples:
To learn a message as spam:
-TELL SPAMC/1.3
-Message-class: spam
-Set: local
+TELL SPAMC/1.3\r\n
+Message-class: spam\r\n
+Set: local\r\n
To forget a learned message:
-TELL SPAMC/1.3
-Remove: local
+TELL SPAMC/1.3\r\n
+Remove: local\r\n
To report a spam message:
-TELL SPAMC/1.3
-Message-class: spam
-Set: local, remove
+TELL SPAMC/1.3\r\n
+Message-class: spam\r\n
+Set: local, remove\r\n
To revoke a ham message:
-TELL SPAMC/1.3
-Message-class: spam
-Set: local
-Remove: remote
+TELL SPAMC/1.3\r\n
+Message-class: spam\r\n
+Set: local\r\n
+Remove: remote\r\n
+
+Headers
+-------
+
+The following optional headers are defined as of protocol 1.2:
+
+Content-length
+
+ Length of a request or response body, in bytes (generally a requirement
+ as of protocol 1.2)
+
+Spam
+
+ See above; used in server responses to the CHECK command.
+
+User
+
+ Username of the user on whose behalf this scan is being performed. The
+ meaning of this is up to the server; format is that of a traditional UNIX
+ username ([-A-Za-z0-9_]+).
+
+Compress
+
+ An optional header, sent by the client to the server, whose value may
+ consist of the string "zlib", indicating that the message body transmitted
+ by the client is compressed using Zlib compression. This is new in
+ SpamAssassin 3.2.0.
+
+As-yet-undefined headers should not be treated as errors, and instead
+should be ignored.
+