change README.md
This commit is contained in:
163
README.md
163
README.md
@@ -1,4 +1,7 @@
|
||||
# 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.
|
||||
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.
|
||||
|
||||
### Global
|
||||
#### Global
|
||||
Global config options:
|
||||
* **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.
|
||||
* **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).
|
||||
* **loglevel** (optional, default: **info**)
|
||||
* **loglevel** (optional, default: "info")
|
||||
Set the log level. This option may be overriden by any rule or action object.
|
||||
Possible values:
|
||||
* **error**
|
||||
* **warning**
|
||||
* **info**
|
||||
* **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.
|
||||
* **rules**
|
||||
List of rule objects.
|
||||
|
||||
### Rule
|
||||
#### Rule
|
||||
Config options for rule objects:
|
||||
* **name**
|
||||
Name of the rule.
|
||||
@@ -60,7 +63,7 @@ Config options for rule objects:
|
||||
* **pretend** (optional)
|
||||
See section [Global](#Global).
|
||||
|
||||
### Action
|
||||
#### Action
|
||||
Config options for action objects:
|
||||
* **name**
|
||||
Name of the action.
|
||||
@@ -75,7 +78,7 @@ Config options for action objects:
|
||||
* **pretend** (optional)
|
||||
See section [Global](#Global).
|
||||
|
||||
### Conditions
|
||||
#### 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**.
|
||||
@@ -95,52 +98,52 @@ 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.
|
||||
If not set, no metavariables will be provided.
|
||||
|
||||
### Whitelist
|
||||
#### Whitelist
|
||||
Config options for whitelist objects:
|
||||
* **type**
|
||||
See section [Whitelists](#Whitelists).
|
||||
|
||||
### Actions
|
||||
#### Actions
|
||||
Available action types:
|
||||
* **add_header**
|
||||
Add new header.
|
||||
Options:
|
||||
* **field**
|
||||
##### add_header
|
||||
Add new header.
|
||||
Options:
|
||||
* **field**
|
||||
Name of the header.
|
||||
* **value**
|
||||
* **value**
|
||||
Value of the header.
|
||||
|
||||
* **del_header**
|
||||
Delete header(s).
|
||||
Options:
|
||||
* **field**
|
||||
##### del_header
|
||||
Delete header(s).
|
||||
Options:
|
||||
* **field**
|
||||
Regular expression to match against header names.
|
||||
* **value** (optional)
|
||||
* **value** (optional)
|
||||
Regular expression to match against the headers value.
|
||||
|
||||
* **mod_header**
|
||||
Modify header(s).
|
||||
Options:
|
||||
* **field**
|
||||
##### mod_header
|
||||
Modify header(s).
|
||||
Options:
|
||||
* **field**
|
||||
Regular expression to match against header names.
|
||||
* **search** (optional)
|
||||
* **search** (optional)
|
||||
Regular expression to match against header values. You may use subgroups or named subgroups (python syntax) to include parts of the original value in the new value.
|
||||
* **value**
|
||||
* **value**
|
||||
New value of the header.
|
||||
|
||||
* **add_disclaimer**
|
||||
Append or prepend disclaimer to text and/or html body parts.
|
||||
Options:
|
||||
* **action**
|
||||
##### add_disclaimer
|
||||
Append or prepend disclaimer to text and/or html body parts.
|
||||
Options:
|
||||
* **action**
|
||||
Action to perform with the disclaimer.
|
||||
Possible values:
|
||||
* append
|
||||
* prepend
|
||||
* **html_template**
|
||||
* **html_template**
|
||||
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.
|
||||
* **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).
|
||||
Possible values:
|
||||
* **wrap**
|
||||
@@ -149,95 +152,95 @@ Available action types:
|
||||
Ignore the error and do nothing.
|
||||
* **reject**
|
||||
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.
|
||||
|
||||
* **store**
|
||||
Store e-mail.
|
||||
Options:
|
||||
* **type**
|
||||
##### store
|
||||
Store e-mail.
|
||||
Options:
|
||||
* **type**
|
||||
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.
|
||||
* **metadata** (optional, default: **false**)
|
||||
* **metadata** (optional, default: false)
|
||||
Store metadata.
|
||||
* **metavar** (optional)
|
||||
* **metavar** (optional)
|
||||
Prefix for the metavariable names. If not set, no metavariables will be provided.
|
||||
The storage provides the following metavariables:
|
||||
* **ID** (the storage ID of the e-mail)
|
||||
* **DATAFILE** (path to the data file)
|
||||
* **METAFILE** (path to the meta file if **metadata** is set to **true**)
|
||||
|
||||
* **notify**
|
||||
Send notification.
|
||||
Options:
|
||||
* **type**
|
||||
##### notify
|
||||
Send notification.
|
||||
Options:
|
||||
* **type**
|
||||
See section [Notifications](#Notifications).
|
||||
|
||||
* **quarantine**
|
||||
Quarantine e-mail.
|
||||
Options:
|
||||
* **store**
|
||||
Options for e-mail storage, see action **store** in section [Actions](#Actions).
|
||||
* **smtp_host**
|
||||
##### quarantine
|
||||
Quarantine e-mail.
|
||||
Options:
|
||||
* **store**
|
||||
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**
|
||||
SMTP port used to release e-mails from quarantine.
|
||||
* **notify** (optional)
|
||||
* **notify** (optional)
|
||||
Options for e-mail notifications, see action **notify** in section [Actions](#Actions).
|
||||
* **milter_action** (optional)
|
||||
* **milter_action** (optional)
|
||||
Final milter action to perform. If set, no further rules or actions will be processed.
|
||||
Possible values:
|
||||
* **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, default: **Message rejected**)
|
||||
* **reject_reason** (optional, default: "Message rejected")
|
||||
Reject message used if milter_action is set to reject.
|
||||
* **whitelist** (optional)
|
||||
* **whitelist** (optional)
|
||||
Options for a whitelist, see **whitelist** in section [Conditions](#Conditions).
|
||||
|
||||
### Storages
|
||||
#### Storages
|
||||
Available storage types:
|
||||
* **file**
|
||||
File storage.
|
||||
Options:
|
||||
* **directory**
|
||||
##### file
|
||||
File storage.
|
||||
Options:
|
||||
* **directory**
|
||||
Directory used to store e-mails.
|
||||
* **metadata** (optional, default: **false**)
|
||||
* **metadata** (optional, default: false)
|
||||
Store metadata file.
|
||||
* **mode** (optional, default: system default)
|
||||
* **mode** (optional, default: system default)
|
||||
File mode when new files are created.
|
||||
|
||||
### Notifications
|
||||
#### Notifications
|
||||
Available notification types:
|
||||
* **email**
|
||||
E-Mail notification.
|
||||
Options:
|
||||
* **smtp_host**
|
||||
##### email
|
||||
E-Mail notification.
|
||||
Options:
|
||||
* **smtp_host**
|
||||
SMTP host used to send notifications.
|
||||
* **smtp_port**
|
||||
* **smtp_port**
|
||||
SMTP port used to send notifications.
|
||||
* **envelope_from**
|
||||
* **envelope_from**
|
||||
Envelope-From address.
|
||||
* **from_header**
|
||||
* **from_header**
|
||||
Value of the From header.
|
||||
* **subject**
|
||||
* **subject**
|
||||
Subject of the notification.
|
||||
* **template**
|
||||
* **template**
|
||||
Notification template.
|
||||
* **repl_img** (optional)
|
||||
* **repl_img** (optional)
|
||||
Replacement image used to replace all images in the e-mail body.
|
||||
* **embed_imgs** (optional)
|
||||
* **embed_imgs** (optional)
|
||||
List of images to embed into the notification e-mail.
|
||||
|
||||
### Whitelists
|
||||
#### Whitelists
|
||||
Available whitelist types:
|
||||
* **db**
|
||||
Whitelist stored in database. The table is created automatically if it does not exist yet.
|
||||
Options:
|
||||
* **connection**
|
||||
##### db
|
||||
Whitelist stored in database. The table is created automatically if it does not exist yet.
|
||||
Options:
|
||||
* **connection**
|
||||
Database connection string, see [Peewee Playhouse Extension](https://docs.peewee-orm.com/en/latest/peewee/playhouse.html#db-url).
|
||||
* **table**
|
||||
* **table**
|
||||
Database table to use.
|
||||
|
||||
## Developer information
|
||||
|
||||
Reference in New Issue
Block a user