diff --git a/README.md b/README.md index 85befdd..df2acac 100644 --- a/README.md +++ b/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. - -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. +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. ## 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 -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 **#**. -Rules and actions are processed in the given order. +# Copy the example config file and modify it according to your needs. +cp /etc/pyquarantine/pyquarantine.conf.example /etc/pyquarantine/pyquarantine.conf + +# 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). - 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) + 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]** +* **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 actions, for test purposes. This option may be overriden by any rule or action object. -* **rules** +* **pretend** (optional) + Pretend actions, for test purposes. This option may be overriden by any rule or action object. + 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 -Config options for **conditions** objects: -* **local** (optional) - If set to true, the rule is only executed for e-mails originating from addresses defined in local_addrs and vice versa. -* **hosts** (optional) - A list of hosts and network addresses for which the rule should be executed. -* **envfrom** (optional) - A regular expression to match against the evenlope-from addresses for which the rule should be executed. -* **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) +### Whitelists +The following whitelist types and options are available. +* **db** + Whitelist stored in database. The table is created automatically if it does not exist yet. + * **connection** + Database connection string, see [Peewee Playhouse Extension](https://docs.peewee-orm.com/en/latest/peewee/playhouse.html#db-url). + * **table** + Database table to use. ## Developer information Everyone who wants to improve or extend this project is very welcome.