spacefreak/pyquarantine-milter
1
0
Fork 0
Code Issues Pull Requests Releases Activity

change README.md

Browse Source
This commit is contained in:
Thomas Oettli
2022-01-11 17:48:42 +01:00
parent 57b74a83ba
commit 5ede9ac0f7
1 changed files with 121 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
README.md
View File

@@ -1,4 +1,7 @@
# pyquarantine-milter # pyquarantine-milter
A pymilter based sendmail/postfix pre-queue filter with the ability to quarantine e-mails, sending notifications and modify e-mail headers and bodies.
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. 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.
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. 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.
@@ -29,25 +32,25 @@ pyquarantine uses a config file in JSON format. It has to be JSON valid with the
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. 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
Global config options: Global config options:
* **socket** (optional) * **socket** (optional)
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, 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]**) * **local_addrs** (optional, 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])
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).
* **loglevel** (optional, default: **info**) * **loglevel** (optional, default: "info")
Set the log level. This option may be overriden by any rule or action object. Set the log level. This option may be overriden by any rule or action object.
Possible values: Possible values:
* **error** * **error**
* **warning** * **warning**
* **info** * **info**
* **debug** * **debug**
* **pretend** (optional, default: **false**) * **pretend** (optional, default: false)
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** * **rules**
List of rule objects. List of rule objects.
### Rule #### Rule
Config options for rule objects: Config options for rule objects:
* **name** * **name**
Name of the rule. Name of the rule.
@@ -60,7 +63,7 @@ Config options for rule objects:
* **pretend** (optional) * **pretend** (optional)
See section [Global](#Global). See section [Global](#Global).
### Action #### Action
Config options for action objects: Config options for action objects:
* **name** * **name**
Name of the action. Name of the action.
@@ -75,7 +78,7 @@ Config options for action objects:
* **pretend** (optional) * **pretend** (optional)
See section [Global](#Global). See section [Global](#Global).
### Conditions #### Conditions
Config options for conditions objects: Config options for conditions objects:
* **local** (optional) * **local** (optional)
Matches outgoing e-mails (sender address matches **local_addrs**) if set to **true** or matches incoming e-mails if set to **false**. Matches outgoing e-mails (sender address matches **local_addrs**) if set to **true** or matches incoming e-mails if set to **false**.
@@ -95,14 +98,14 @@ Config options for conditions objects:
Prefix for the name of metavariables which are possibly provided by the **envfrom**, **envto** or **headers** condition. Meta variables will be provided if the regular expressions contain named subgroups, see [python.re](https://docs.python.org/3/library/re.html) for details. Prefix for the name of metavariables which are possibly provided by the **envfrom**, **envto** or **headers** condition. Meta variables will be provided if the regular expressions contain named subgroups, see [python.re](https://docs.python.org/3/library/re.html) for details.
If not set, no metavariables will be provided. If not set, no metavariables will be provided.
### Whitelist #### Whitelist
Config options for whitelist objects: Config options for whitelist objects:
* **type** * **type**
See section [Whitelists](#Whitelists). See section [Whitelists](#Whitelists).
### Actions #### Actions
Available action types: Available action types:
* **add_header** ##### add_header
Add new header. Add new header.
Options: Options:
* **field** * **field**
@@ -110,7 +113,7 @@ Available action types:
* **value** * **value**
Value of the header. Value of the header.
* **del_header** ##### del_header
Delete header(s). Delete header(s).
Options: Options:
* **field** * **field**
@@ -118,7 +121,7 @@ Available action types:
* **value** (optional) * **value** (optional)
Regular expression to match against the headers value. Regular expression to match against the headers value.
* **mod_header** ##### mod_header
Modify header(s). Modify header(s).
Options: Options:
* **field** * **field**
@@ -128,7 +131,7 @@ Available action types:
* **value** * **value**
New value of the header. New value of the header.
* **add_disclaimer** ##### add_disclaimer
Append or prepend disclaimer to text and/or html body parts. Append or prepend disclaimer to text and/or html body parts.
Options: Options:
* **action** * **action**
@@ -140,7 +143,7 @@ Available action types:
Path to a file which contains the html representation of the disclaimer. Path to a file which contains the html representation of the disclaimer.
* **text_template** * **text_template**
Path to a file which contains the text representation of the disclaimer. Path to a file which contains the text representation of the disclaimer.
* **error_policy** (optional, default: **wrap**) * **error_policy** (optional, default: "wrap")
Set the error policy in case the disclaimer cannot be added (e.g. if the html part cannot be parsed). Set the error policy in case the disclaimer cannot be added (e.g. if the html part cannot be parsed).
Possible values: Possible values:
* **wrap** * **wrap**
@@ -149,17 +152,17 @@ Available action types:
Ignore the error and do nothing. Ignore the error and do nothing.
* **reject** * **reject**
Reject the e-mail. Reject the e-mail.
* **add_html_body** (optional, default: **false**) * **add_html_body** (optional, default: false)
Generate a html body with the content of the text body if no html body is present. Generate a html body with the content of the text body if no html body is present.
* **store** ##### store
Store e-mail. Store e-mail.
Options: Options:
* **type** * **type**
See section [Storages](#Storages). See section [Storages](#Storages).
* **original** (optional, default: **false**) * **original** (optional, default: false)
If set to true, store the message as received by the MTA instead of storing the current state of the message, that may was modified already by other actions. If set to true, store the message as received by the MTA instead of storing the current state of the message, that may was modified already by other actions.
* **metadata** (optional, default: **false**) * **metadata** (optional, default: false)
Store metadata. Store metadata.
* **metavar** (optional) * **metavar** (optional)
Prefix for the metavariable names. If not set, no metavariables will be provided. Prefix for the metavariable names. If not set, no metavariables will be provided.
@@ -168,13 +171,13 @@ Available action types:
* **DATAFILE** (path to the data file) * **DATAFILE** (path to the data file)
* **METAFILE** (path to the meta file if **metadata** is set to **true**) * **METAFILE** (path to the meta file if **metadata** is set to **true**)
* **notify** ##### notify
Send notification. Send notification.
Options: Options:
* **type** * **type**
See section [Notifications](#Notifications). See section [Notifications](#Notifications).
* **quarantine** ##### quarantine
Quarantine e-mail. Quarantine e-mail.
Options: Options:
* **store** * **store**
@@ -191,26 +194,26 @@ Available action types:
* **ACCEPT** (Tell MTA to accept the e-mail, skip following rules/actions.) * **ACCEPT** (Tell MTA to accept the e-mail, skip following rules/actions.)
* **REJECT** (Tell MTA to reject the e-mail.) * **REJECT** (Tell MTA to reject the e-mail.)
* **DISCARD** (Tell MTA to discard the e-mail.) * **DISCARD** (Tell MTA to discard the e-mail.)
* **reject_reason** (optional, default: **Message rejected**) * **reject_reason** (optional, default: "Message rejected")
Reject message used if milter_action is set to reject. Reject message used if milter_action is set to reject.
* **whitelist** (optional) * **whitelist** (optional)
Options for a whitelist, see **whitelist** in section [Conditions](#Conditions). Options for a whitelist, see **whitelist** in section [Conditions](#Conditions).
### Storages #### Storages
Available storage types: Available storage types:
* **file** ##### file
File storage. File storage.
Options: Options:
* **directory** * **directory**
Directory used to store e-mails. Directory used to store e-mails.
* **metadata** (optional, default: **false**) * **metadata** (optional, default: false)
Store metadata file. Store metadata file.
* **mode** (optional, default: system default) * **mode** (optional, default: system default)
File mode when new files are created. File mode when new files are created.
### Notifications #### Notifications
Available notification types: Available notification types:
* **email** ##### email
E-Mail notification. E-Mail notification.
Options: Options:
* **smtp_host** * **smtp_host**
@@ -230,9 +233,9 @@ Available notification types:
* **embed_imgs** (optional) * **embed_imgs** (optional)
List of images to embed into the notification e-mail. List of images to embed into the notification e-mail.
### Whitelists #### Whitelists
Available whitelist types: Available whitelist types:
* **db** ##### db
Whitelist stored in database. The table is created automatically if it does not exist yet. Whitelist stored in database. The table is created automatically if it does not exist yet.
Options: Options:
* **connection** * **connection**