115 lines
4.5 KiB
Markdown
115 lines
4.5 KiB
Markdown
# pymodmilter
|
|
A pymilter based sendmail/postfix pre-queue filter with the ability to add, remove and modify e-mail headers.
|
|
The project is currently in beta status, but it is already used in a productive enterprise environment which processes about a million e-mails per month.
|
|
|
|
The basic idea is to define rules with conditions and modifications which are processed when all conditions are true.
|
|
|
|
## Dependencies
|
|
Pymodmilter is depending on these python packages, but they are installed automatically if you are working with pip.
|
|
* [pymilter](https://pythonhosted.org/pymilter/)
|
|
* [netaddr](https://github.com/drkjam/netaddr/)
|
|
|
|
## Installation
|
|
* Install pymodmilter with pip and copy the example configuration file.
|
|
```sh
|
|
pip install pymodmilter
|
|
cp /etc/pymodmilter/pymodmilter.conf.example /etc/pymodmilter/pymodmilter.conf
|
|
```
|
|
* Modify /etc/pymodmilter/pymodmilter.conf according to your needs.
|
|
|
|
## Configuration options
|
|
Pymodmilter uses a configuration file in JSON format. The options are described below. Make a copy of the [example configuration file](https://github.com/spacefreak86/pymodmilter/blob/master/docs/pymodmilter.conf.example) in the [docs](https://github.com/spacefreak86/pymodmilter/tree/master/docs) folder to start with.
|
|
Rules and modifications are processed in the given order.
|
|
|
|
### Global
|
|
The following global configuration options are optional:
|
|
* **socket**
|
|
The socket used to communicate with the MTA.
|
|
* **local_addrs**
|
|
A list of hosts and network addresses which are considered local. It is used to for the condition option [local](#Conditions). This option may be overriden within a rule object.
|
|
* **log**
|
|
Enable or disable logging. This option may be overriden by a rule or modification object.
|
|
|
|
### Rules
|
|
The following configuration options are mandatory for each rule:
|
|
* **modifications**
|
|
A list of modification objects which are processed in the given order.
|
|
|
|
The following configuration options are optional for each rule:
|
|
* **name**
|
|
Name of the rule.
|
|
* **conditions**
|
|
A list of conditions which all have to be true to process the rule.
|
|
* **local_addrs**
|
|
As described above in the [Global](#Global) section.
|
|
* **log**
|
|
As described above in the [Global](#Global) section.
|
|
* **pretend**
|
|
Just pretend to make the modifications, for test purposes.
|
|
|
|
### Modifications
|
|
The following configuration options are mandatory for each modification:
|
|
* **type**
|
|
Set the modification type. Possible values are:
|
|
* **add_header**
|
|
* **del_header**
|
|
* **mod_header**
|
|
* **add_disclaimer**
|
|
|
|
The following configuration options are mandatory based on the modification type in use.
|
|
* **add_header**
|
|
* **header**
|
|
Name of the header.
|
|
* **value**
|
|
Value of the header.
|
|
|
|
* **del_header**
|
|
* **header**
|
|
Regular expression to match against header lines.
|
|
|
|
* **mod_header**
|
|
* **header**
|
|
Regular expression to match against header lines.
|
|
* **search**
|
|
Regular expression to match against the value of header lines. You may use subgroups or named subgroups (python syntax) to include parts of the original value in the new value.
|
|
* **value**
|
|
New value of the header.
|
|
|
|
* **add_disclaimer**
|
|
* **action**
|
|
Action to perform with the disclaimer. Possible values are:
|
|
* append
|
|
* prepend
|
|
* **html_template**
|
|
Path to a file that contains the html representation of the disclaimer.
|
|
* **text_template**
|
|
Path to a file that contains the text representation of the disclaimer.
|
|
* **error_policy**
|
|
Set what should be done if the disclaimer could not be added (e.g. no body text found). Possible values are:
|
|
* wrap
|
|
The original e-mail will be attached to a new one containing the disclaimer.
|
|
* ignore
|
|
Ignore the error and do nothing.
|
|
* reject
|
|
Reject the e-mail.
|
|
|
|
The following configuration options are optional for each modification:
|
|
* **name**
|
|
Name of the modification.
|
|
* **log**
|
|
As described above in the global object section.
|
|
|
|
### Conditions
|
|
The following condition options are optional:
|
|
* **local**
|
|
If set to true, the rule is only executed for e-mails originating from addresses defined in local_addrs and vice versa.
|
|
* **hosts**
|
|
A list of hosts and network addresses for which the rule should be executed.
|
|
* **envfrom**
|
|
A regular expression to match against the evenlope-from addresses for which the rule should be executed.
|
|
* **envto**
|
|
A regular expression to match against all evenlope-to addresses. All addresses must match to fulfill the condition.
|
|
|
|
## Developer information
|
|
Everyone who wants to improve or extend this project is very welcome.
|