change README.md

README.md

@@ -2,12 +2,10 @@
 A pymilter based sendmail/postfix pre-queue filter with the ability to quarantine e-mails, send notifications and modify e-mail headers and/or bodies.  
 The project is currently in beta status, but it is already used in a productive enterprise environment that processes about a million e-mails per month.  
 
-It is useful in many cases due to its flexible configuration and the ability to handle any number of quarantines and/or modifications sequential.
+It is useful in many cases due to its flexible configuration and the ability to handle any number of quarantines and/or modifications sequential and conditional.
-
-The basic idea is to configure rules with optional conditions. If all conditions match, the configured actions (e.g. quarantine, modify, ...) within the rule are performed on the e-mail. Each action can have its own conditions as well.  
 
 ## Dependencies
-pyquarantine is depending on these python packages, but they are installed automatically if you are working with pip.
+pyquarantine is depending on these python packages, they are installed automatically if you are working with pip.
 * [jsonschema](https://github.com/Julian/jsonschema)
 * [pymilter](https://github.com/sdgathman/pymilter)
 * [netaddr](https://github.com/drkjam/netaddr)
@@ -15,34 +13,41 @@ pyquarantine is depending on these python packages, but they are installed autom
 * [BeautifulSoup](https://www.crummy.com/software/BeautifulSoup/)
 
 ## Installation
-* Install pyquarantine with pip and copy the example config file.
 ```sh
+# Install pyquarantine with pip.
 pip install pyquarantine
-cp /etc/pyquarantine/pyquarantine.conf.example /etc/pyquarantine/pyquarantine.conf
-```
-* Modify /etc/pyquarantine/pyquarantine.conf according to your needs.
 
-## Configuration options
+# Copy the example config file and modify it according to your needs.
-pyquarantine uses a config file in JSON format. The config file has to be JSON valid with the exception of allowed comment lines starting with **#**.  
+cp /etc/pyquarantine/pyquarantine.conf.example /etc/pyquarantine/pyquarantine.conf
-Rules and actions are processed in the given order.
+
+# Check the validity of the config file.
+pyquarantine-milter -t
+```
+
+## Configuration
+pyquarantine uses a config file in JSON format. It has to be JSON valid with the exception of allowed comment lines starting with **#**.  
+
+The basic idea is to configure rules that contain actions. Both rules and actions may have conditions. An example of using rules is separating incoming and outgoing e-mails using the **local** condition. Rules and actions are always processed in the given order.  
 
 ### Global
 Global config options:
 * **socket** (optional)  
-  The socket used to communicate with the MTA. If it is not specified in the config, it has to be set as command line option.
+  Socket used to communicate with the MTA. If it is not specified in the config, it has to be set as command line option.
 * **local_addrs** (optional)  
-  A list of hosts and network addresses which are considered local. It is used for the condition option [local](#Conditions).  
+  List of hosts and network addresses which are considered local. It is used for the condition option [local](#Conditions).  
-  Default: **fe80::/64, ::1/128, 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16**
+  Default: **[fe80::/64, ::1/128, 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16]**
-* **loglevel**  (optional)
+* **loglevel**  (optional)  
   Set the log level. This option may be overriden by any rule or action object. Possible values are:
   * **error**  
   * **warning**  
   * **info**  
   * **debug**  
+
   Default: **info**
-* **pretend** (optional)
+* **pretend** (optional)  
-  Pretend actions, for test purposes. This option may be overriden by any rule or action object.
+  Pretend actions, for test purposes. This option may be overriden by any rule or action object.  
-* **rules**
+  Default: **false**
+* **rules**  
   List of rule objects.
 
 ### Rule
@@ -50,9 +55,9 @@ Rule config options:
 * **name**  
   Name of the rule.  
 * **actions**  
-  A list of action objects which are processed in the given order.
+  List of action objects.
 * **conditions** (optional)  
-  A list of conditions which all have to be true to process the rule.
+  See section [Conditions](#Conditions).
 * **loglevel** (optional)  
   See section [Global](#Global).
 * **pretend** (optional)  
@@ -65,14 +70,38 @@ Action config options:
 * **type**  
   See section [Actions](#Actions).
 * **options**  
-  Options for the action according to action type (see section [Actions](#Actions)).
+  Options depending on the action type, see section [Actions](#Actions).
 * **conditions** (optional)  
-  A list of conditions which all have to be true to process the action.
+  See section [Conditions](#Conditions).
 * **loglevel** (optional)  
   See section [Global](#Global).
 * **pretend** (optional)  
   See section [Global](#Global).
 
+### Conditions
+Config options for **conditions** objects:
+* **local** (optional)  
+  Matches outgoing e-mails (sender address matches **local_addrs**) if set to **true** or matches incoming e-mails if set to **false**.
+* **hosts** (optional)  
+  Matches e-mails originating from the given list of hosts and network addresses.
+* **envfrom** (optional)  
+  Matches e-mails for which the envelope-from address matches the given regular expression.
+* **envto** (optional)  
+  Matches e-mails for which all envelope-to addresses match the given regular expression.
+* **headers** (optional)  
+  Matches e-mails for which all regular expressions in the given list are matching at least one e-mail header.
+* **whitelist** (optional)  
+  Matches e-mails for which the whitelist has no entry for the envelope-from and envelope-to address combination, see section [Whitelist](#Whitelist).
+* **var** (optional)  
+  Matches e-mails for which a previous action or condition has set the given meta variable.
+* **metavar** (optional)  
+  Prefix for the name of meta variables which are provided by the **envfrom**, **envto** and **headers** condition. If not set, no meta variables will be provided.
+
+### Whitelist
+Config options for **whitelist** objects:
+* **type**  
+  See section [Whitelists](#Whitelists).
+
 ### Actions
 The following action types and options are available.
 * **add_header**  
@@ -116,6 +145,7 @@ The following action types and options are available.
       Ignore the error and do nothing.
     * **reject**  
       Reject the e-mail.
+
     Default: **wrap**
   * **add_html_body** (optional)  
     Generate a html body with the content of the text body if no html body is present.
@@ -142,23 +172,23 @@ The following action types and options are available.
 * **quarantine**  
   Quarantine e-mail.
   * **store**  
-  Options for e-mail storage (see action **store** in section [Actions](#Actions)).
+  Options for e-mail storage, see action **store** in section [Actions](#Actions).
   * **smtp_host**  
   SMTP host used to release e-mails from quarantine.
   * **smtp_port**  
   SMTP port used to release e-mails from quarantine.
   * **notify** (optional)  
-  Options for e-mail notifications (see action **notify** in section [Actions](#Actions)).
+  Options for e-mail notifications, see action **notify** in section [Actions](#Actions).
   * **milter_action** (optional)  
   Milter action to perform. Possible values are:
     * **ACCEPT**   (Tell MTA to accept the e-mail, skip following rules/actions.)
     * **REJECT**   (Tell MTA to reject the e-mail.)
     * **DISCARD**  (Tell MTA to discard the e-mail.)
   * **reject_reason** (optional)  
-  Reject message if milter_action is set to reject.
+  Reject message used if milter_action is set to reject.
   Default: **Message rejected**
   * **whitelist** (optional)  
-  Options for a whitelist (see **whitelist** in section [Conditions](#Conditions)).
+  Options for a whitelist, see **whitelist** in section [Conditions](#Conditions).
 
 ### Storages
 The following storage types are and options are available:
@@ -192,20 +222,14 @@ The following notification types and options are available:
   * **embed_imgs** (optional)  
   List of images to embed into the notification e-mail.
 
-### Conditions
+### Whitelists
-Config options for **conditions** objects:
+The following whitelist types and options are available.
-* **local** (optional)  
+* **db**  
-  If set to true, the rule is only executed for e-mails originating from addresses defined in local_addrs and vice versa.
+  Whitelist stored in database. The table is created automatically if it does not exist yet.
-* **hosts** (optional)  
+  * **connection**  
-  A list of hosts and network addresses for which the rule should be executed.
+    Database connection string, see [Peewee Playhouse Extension](https://docs.peewee-orm.com/en/latest/peewee/playhouse.html#db-url).
-* **envfrom** (optional)  
+  * **table**  
-  A regular expression to match against the evenlope-from addresses for which the rule should be executed.
+    Database table to use.
-* **envto** (optional)  
-  A regular expression to match against all evenlope-to addresses. All addresses must match to fulfill the condition.
-* **headers** (optional)  
-* **whitelist** (optional)  
-* **var** (optional)  
-* **metavar** (optional)  
 
 ## Developer information
 Everyone who wants to improve or extend this project is very welcome.