Added a README and CREATING-RULES file
authorFrederic Jolliton <frederic@jolliton.com>
Sun, 31 Oct 2004 04:26:47 +0000 (04:26 +0000)
committerFrederic Jolliton <frederic@jolliton.com>
Sun, 31 Oct 2004 04:26:47 +0000 (04:26 +0000)
* Added a README file with installation instruction
* Added a CREATING-RULES file with instruction to
  create rules configuration file.
git-archimport-id: frederic@jolliton.com--2004-private/mail-filter--main--0.1--patch-4

CREATING-RULES [new file with mode: 0644]
README [new file with mode: 0644]

diff --git a/CREATING-RULES b/CREATING-RULES
new file mode 100644 (file)
index 0000000..873bce4
--- /dev/null
@@ -0,0 +1,175 @@
+Defining rules
+--------------
+
+There is one file per user.  (If there is no rules file for an user, mail are
+just delivered to its default folder 'INBOX'.)
+
+You can check configuration file from command line by using mail.filter '-c'
+option.  mail.filter will report any syntax error found in the file given as
+argument.  It's HIGHLY recommended to test change with this method prior to
+"commiting" change to user's configuration.
+
+Syntax
+------
+
+The syntax is very simple.
+
+expr = keyword string* { expr* }
+     | keyword string* ;
+
+In english, that mean that an expression is a keyword followed by optionally
+one or more "string", then followed by end of expression character ';', or
+followed by nested expression enclosed by {}.
+
+Examples:
+
+folder 'Spam' { spam ; }
+
+Action
+------
+
+The file contains a set of actions. Each action contains a match description.
+
+Some examples of action:
+
+folder 'Friend.Joe' {
+        header 'from' contains '<some@email.address.com>' ;
+        header 'from' match '@joedomain\.(com|net|org)>' ;
+        header 'subject' contains '[joe]' ;
+}
+
+folder 'Store.Amazon' {
+        header 'to' is 'some@email.address.com' ;
+        and {
+                or {
+                        header 'from' is 'confirmation-commande@amazon.fr' ;
+                        header 'from' is 'confirmation-envoi@amazon.fr' ;
+                        header 'from' is 'modification-commande@amazon.fr' ;
+                }
+                header 'to' is 'another@email.address.com' ;
+        }
+}
+
+reject NOUSER {
+        header 'from' contains '<some@email.address>' ;
+}
+
+
+In the current mail.filter, there is two possible action.
+
+Either 'folder' or 'reject'.
+
+
+Action 'folder'
+---------------
+
+Syntax: folder <folder-name> { matches.. }
+
+The 'folder' action instruct mail.filter to file the mail into a particular
+folder. So, folder take one argument that give the folder name.
+
+
+Action 'reject'
+---------------
+
+Syntax: reject <error-code> { matches.. }
+
+The 'reject' action instruct mail.filter to not file the mail, and instead
+return an error code to sendmail.
+
+Supported textual error code are: nouser, tempfail and dataerr.
+
+But, reject can also take a numeral error code.
+
+
+Matches
+-------
+
+For matches listed in action, only one need to match for the action to be
+taken (logical 'or' by default.)
+
+The following matches are supported:
+
+Match 'header'
+--------------
+
+Syntax: header <HEADER-NAME> <MATCH-TYPE> <MATCH-ARGUMENT> ;
+
+where:
+
+ * HEADER-NAME name a header, where all blanks character sequence are
+   considered as just one space character.
+
+ * MATCH-TYPE give the type of match to perform against the header.
+   Each match type take an argument.
+
+   * 'is' test if the header is equal to the argument (case
+      insensitive)
+   * 'contains' test if argument appear in header (case insensitive.)
+   * 'match' test if regular expression defined by argument match
+     the header.
+
+Match 'broken'
+--------------
+
+Syntax: broken ;
+
+Test if the mail was parsed correctly. Usefull to move such mail apart from the
+INBOX, since most of the time they are spams or viruses.
+
+Match 'infected'
+----------------
+
+Syntax: infected ;
+
+Test with clamav if the mail contains a virus.
+
+Match 'spam'
+------------
+
+Syntax: spam ;
+
+Test with spamprobe if the mail *could* be a spam.
+
+Note that spamprobe need to be "enseigner"(fr->en?).
+
+Match 'and', 'or' and 'not'
+---------------------------
+
+These matches allow you to build logical conditions.
+
+Syntax: and { ... }
+Syntax: or { ... }
+Syntax: not { ... }
+
+For 'and', everything inside it must match.
+For 'or', only one match is required.
+For 'not', everything inside must don't match.
+
+
+Detailed example
+----------------
+
+folder 'Store.Amazon' {
+        header 'to' is 'some@email.address.com' ;
+        and {
+                or {
+                        header 'from' is 'confirmation-commande@amazon.fr' ;
+                        header 'from' is 'confirmation-envoi@amazon.fr' ;
+                        header 'from' is 'modification-commande@amazon.fr' ;
+                }
+                header 'to' is 'another@email.address.com' ;
+        }
+}
+
+Here we fill mail to 'Store.Amazon' IMAP folder for the user specified on
+command line (which sendmail automatically set when calling the script)
+when mail match the following:
+
+Either:
+
+ - The mail is destined to 'some@email.address.com',
+ - OR The mail is both:
+   - destined to 'another@email.address.com'
+   - AND from one of the three emails address listed.
+
diff --git a/README b/README
new file mode 100644 (file)
index 0000000..104a8ba
--- /dev/null
+++ b/README
@@ -0,0 +1,63 @@
+mail.filter is a program called by sendmail, that forward mails to some cyrus
+account.
+
+Optionally, mail.filter use spamprobe for spam detection, and clamav for virus
+detection. (Well, it's not really optional actually.)
+
+For defining rules, see CREATING-RULES file.
+
+Configuring the script
+----------------------
+
+mail.filter contains several variable definition that you should review and
+edit.
+
+Testing
+-------
+
+1] Check that Python is able to run the script by running:
+
+    mail.filter -h
+
+2] Try mail.filter without feeding the mail to Cyrus by running:
+
+    mail.filter -t -v < somemail
+
+   with somemail a file containing a email you want to feed to mail.filter for
+   testing purpose. Output log should show you what action is deduced from mail
+   contents and user rules.
+
+3] You can test again by removing the '-t' option to actually feed Cyrus with
+   the mail, and test if Cyrus accept the mail as expected in the right folder.
+
+4] Check that sendmail can run the script (permission, sendmail restriction,..)
+
+Installation
+------------
+
+Add the following TWO lines:
+
+-=-=-=-=
+Mmailfilter, P=/usr/sbin/mail.filter, F=lsDFMA5:/|@qSPn, A=mail.filter $u
+define(`confLOCAL_MAILER', `mailfilter')dnl
+-=-=-=-=
+
+in your sendmail.mc, then regenerate sendmail.cf (be carefull if sendmail.cf
+was not in sync. with your sendmail.mc ! I suggest to generate 'm4 sendmail.cf'
+to a different file, and use diff to see what really change.)
+
+The first line define a new mailer. The second line define it as default mailer
+for delivering mail to local system.
+
+Then, you just need to restart sendmail.
+
+Todo
+----
+
+[ ] Make spam and antivirus detection more modular, to support other antispam
+    or antiviruses program.
+[ ] Try to create folder if Cyrus answer with unknown folder error, then
+    feed again the mail.
+[ ] Add size match (really usefull?)
+[ ] Support feature such as vacation, automatic answer, forwarding, calling
+    external script (or even "just" python module.)