Policyd rate limit
==================
|github_action| |coverage| |github_version| |pypi_version| |license|
Postfix policyd server allowing to limit the number of mails accepted by
postfix over several time periods, by sasl usernames and/or ip addresses.
Installation
------------
First, create the user that will run the daemon::
adduser --system --group --home /run/policyd-rate-limit --no-create-home policyd-rate-limit
Since version 0.6.0, the configuration file is written using the yaml, so you need the following
package:
* `pyyaml <https://pypi.python.org/pypi/PyYAML>`_
(``sudo apt-get install python3-yaml`` on debian like systems)
Depending of the backend storage you planning to use, you may need to install additional packages.
(The default settings use the sqlite3 bakends and do not need extra packages).
* `mysqldb <https://pypi.org/project/mysqlclient/>`_
(``sudo apt-get install python3-mysqldb`` on debian like systems) for the mysql backend.
* `psycopg2 <https://pypi.python.org/pypi/psycopg2>`_
(``sudo apt-get install python3-psycopg2`` on debian like systems) fot the postgresql backend
Install with pip::
sudo pip3 install policyd-rate-limit
or from source code::
sudo make install
This will install the ``policyd_rate_limit`` module, the ``policyd-rate-limit`` binary,
copy the default config to ``/etc/policyd-rate-limit.conf`` if the file do not exists,
copy an init script to ``/etc/init.d/policyd-rate-limit`` and an unit file to
``/etc/systemd/system/policyd-rate-limit.service``.
After the installation, you may need to run ``sudo systemctl daemon-reload`` for make the unit
file visible by systemd.
You should run ``policyd-rate-limit --clean`` on a regular basis to delete old records from the
database. It could be wise to put it in a daily cron, for example::
0 0 * * * policyd-rate-limit /usr/local/bin/policyd-rate-limit --clean >/dev/null
Options of the ``policyd-rate-limit`` binary
--------------------------------------------
* ``-h``, ``--help``: show the help message and exit
* ``--clean``: clean old records from the database
* ``--get-config PARAMETER_NAME`` return the value of a config parameter
* ``--file CONFIG_PATH``, ``-f CONFIG_PATH``: path to a config file
Settings
--------
If the option ``--file`` is not specified, ``policyd-rate-limit`` try to read its configuration from
the following path and choose the first existing file:
* ~/.config/policyd-rate-limit.conf
* ~/.config/policyd-rate-limit.yaml
* /etc/policyd-rate-limit.conf
* /etc/policyd-rate-limit.yaml
The ``.conf`` are the old configuration format. It was a python module and should not be used.
The ``.yaml`` are the new configuration format using the YAML syntax.
* ``debug``: make ``policyd-rate-limit`` output logs to stderr.
The default is ``True``.
* ``user``: The user ``policyd-rate-limit`` will use to drop privileges.
The default is ``"policyd-rate-limit"``.
* ``group``: The group ``policyd-rate-limit`` will use to drop privileges.
The defaut is ``"policyd-rate-limit"``.
* ``pidfile``: path where the program will try to write its pid to.
The default is ``"/var/run/policyd-rate-limit/policyd-rate-limit.pid"``.
``policyd-rate-limit`` will try to create the parent directory and chown it if it do not exists.
* ``mysql_config``: The config to connect to a mysql server
* ``pgsql_config``: The config to connect to a postgresql server
* ``sqlite_config``: The config to connect to a sqlite3 database.
* ``backend``: Which data backend to use. Possible values are ``0`` for sqlite3, ``1`` for mysql
and ``2`` for postgresql. The default is ``0``, use the sqlite3 backend.
* ``SOCKET``: The socket to bind to. Can be a path to an unix socket or a couple [ip, port].
The default is ``"/var/spool/postfix/ratelimit/policy"``.
``policyd-rate-limit`` will try to create the parent directory and chown it if it do not exists.
* ``socket_permission``: Permissions on the unix socket (if unix socket used).
The default is ``0o666``.
* ``limits``: A list of couple [number of emails, number of seconds]. If one of the element of the
list is exeeded (more than 'number of emails' on 'number of seconds' for an ip address or an sasl
username), postfix will return a temporary failure.
* ``limits_by_id``: A dictionary of id -> limit list (see limits). Used to override limits and use
custom limits for a particular id. Use an empty list for no limits for a particular id.
Ids are sasl usernames or ip addresses. The default is ``{}``.
* ``limit_by_sasl``: Apply limits by sasl usernames. The default is ``True``.
* ``limit_by_sender``: Apply limits by sender addresses if sasl username is not found.
The defaut is ``False``.
* ``limit_by_ip``: Apply limits by ip addresses if sasl username and sender address are not found.
The default is ``False``.
* ``limited_networks``: A list of ip networks in cidr notation on which limits are applied. An empty
list is equal to ``limit_by_ip = False``, put ``"0.0.0.0/0"`` and ``::/0`` for every ip addresses.
* ``success_action``: If not limits are reach, which action postfix should do. The default is
``"dunno"``. See http://www.postfix.org/access.5.html for possible actions.
* ``fail_action``: If a limit is reach, which action postfix should do. The default is
``"defer_if_permit Rate limit reach, retry later"``.
* ``db_error_action`` : If we are unable to to contect the database backend, which action postfix
should do. The default is ``"dunno"``. See http://www.postfix.org/access.5.html for possible
actions.
See http://www.postfix.org/access.5.html for possible actions.
* ``config_file``: This parameter is automatically set to the path of the configuration file
currently in use. You can call it conjunction with **--get-config** to known which configuration
file is used.
* ``report``: if ``True``, send a report to ``report_to`` about users reaching limits each time
--clean is called. The default is ``False``.
* ``report_from``: From who to send emails reports. It must be defined when ``report`` is ``True``.
* ``report_to``: Address to send emails reports to. It must be defined when ``report`` is ``True``.
It can be a single email address or a list of email adresses.
* ``report_subject``: Subject of the report email. The default is ``"policyd-rate-limit report"``.
* ``report_limits``: List of number of seconds from the limits list for which you want to be reported.
The default is ``[86400]``.
* ``report_only_if_needed``: Only send a report if some users have reach a reported limit.
The default is ``True``.
* ``smtp_server``: The smtp server to use to send emails ``["host", port]``.
The default is ``["localhost", 25]``.
* ``smtp_starttls``: Should we use starttls to send mails ? (you should set this to ``True`` if
you use ``smtp_credentials``). The default is ``False``.
* ``smtp_credentials``: Should we use credentials to connect to smtp_server ?
if yes set ``["user", "password"]``, else ``null``. The default is ``null``.
* ``count_mode``: How sent mail are counted
* ``0``: each RCPT TO are counted individualy. This is the how it was done historically. If set to 0,
the postfix check_policy_service must be set in smtpd_recipient_restrictions.
This is deprecated and should not be used anymore
* ``1``: recipient are counted in the DATA stage. The postfix parameter check_policy_service must be
defined in smtpd_data_restrictions.
This is the new default.
* ``2``: Number of submited mails a counted, not recipients. The postfix parameter
check_policy_service must be defined in smtpd_data_restrictions.
This means that if a use send a single mail with 100 recipient, it's count for 1
in the quota instead of 100.
Postfix settings
----------------
For postfix 3.0 and later I recommend using the example below. It ensure that if policyd-rate-limit
become unavailable for any reason, postfix will ignore it and keep accepting mail as if the rule
was not here. I find it nice has in my opinion, policyd-rate-limit is a "non-critical" policy
service.
/etc/postfix/main.cf::
smtpd_data_restrictions =
...,
check_policy_service { unix:ratelimit/policy, default_action=DUNNO },
...
On previous postfix versions, you must use:
/etc/postfix/main.cf::
smtpd_data_restrictions =
...,
check_policy_service unix:ratelimit/policy,
...
.. |github_action| image:: https://github.com/nitmir/policyd-rate-limit/actions/workflows/github-actions.yml/badge.svg?branch=master
:target: https://github.com/nitmir/policyd-rate-limit/actions/workflows/github-actions.yml
.. |coverage| image:: https://badges.genua.fr/coverage/badge/policyd-rate-limit/master.svg
:target: https://badges.genua.fr/coverage/policyd-rate-limit/
.. |pypi_version| image:: https://badges.genua.fr/pypi/v/policyd-rate-limit.svg
:target: https://pypi.python.org/pypi/policyd-rate-limit
.. |github_version| image:: https://badges.genua.fr/github/tag/nitmir/policyd-rate-limit.svg?label=github
:target: https://github.com/nitmir/policyd-rate-limit/releases/latest
.. |license| image:: https://badges.genua.fr/pypi/l/policyd-rate-limit.svg
:target: https://www.gnu.org/licenses/gpl-3.0.html
Raw data
{
"_id": null,
"home_page": "https://github.com/nitmir/policyd-rate-limit",
"name": "policyd-rate-limit",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Postfix,rate,limit,email",
"author": "Valentin Samir",
"author_email": "valentin.samir@crans.org",
"download_url": "https://files.pythonhosted.org/packages/8d/d3/7cbac697cd96c27bce614856338f3ee61a1bc941fe90c00e1ec769696d0d/policyd-rate-limit-1.2.0.tar.gz",
"platform": null,
"description": "Policyd rate limit\n==================\n\n|github_action| |coverage| |github_version| |pypi_version| |license|\n\nPostfix policyd server allowing to limit the number of mails accepted by\npostfix over several time periods, by sasl usernames and/or ip addresses.\n\n\nInstallation\n------------\n\nFirst, create the user that will run the daemon::\n\n adduser --system --group --home /run/policyd-rate-limit --no-create-home policyd-rate-limit\n\nSince version 0.6.0, the configuration file is written using the yaml, so you need the following\npackage:\n\n* `pyyaml <https://pypi.python.org/pypi/PyYAML>`_\n (``sudo apt-get install python3-yaml`` on debian like systems)\n\nDepending of the backend storage you planning to use, you may need to install additional packages.\n(The default settings use the sqlite3 bakends and do not need extra packages).\n\n* `mysqldb <https://pypi.org/project/mysqlclient/>`_\n (``sudo apt-get install python3-mysqldb`` on debian like systems) for the mysql backend.\n* `psycopg2 <https://pypi.python.org/pypi/psycopg2>`_\n (``sudo apt-get install python3-psycopg2`` on debian like systems) fot the postgresql backend\n\nInstall with pip::\n\n sudo pip3 install policyd-rate-limit\n\nor from source code::\n\n sudo make install\n\nThis will install the ``policyd_rate_limit`` module, the ``policyd-rate-limit`` binary,\ncopy the default config to ``/etc/policyd-rate-limit.conf`` if the file do not exists,\ncopy an init script to ``/etc/init.d/policyd-rate-limit`` and an unit file to\n``/etc/systemd/system/policyd-rate-limit.service``.\n\nAfter the installation, you may need to run ``sudo systemctl daemon-reload`` for make the unit\nfile visible by systemd.\n\nYou should run ``policyd-rate-limit --clean`` on a regular basis to delete old records from the\ndatabase. It could be wise to put it in a daily cron, for example::\n\n 0 0 * * * policyd-rate-limit /usr/local/bin/policyd-rate-limit --clean >/dev/null\n\n\nOptions of the ``policyd-rate-limit`` binary\n--------------------------------------------\n\n* ``-h``, ``--help``: show the help message and exit\n* ``--clean``: clean old records from the database\n* ``--get-config PARAMETER_NAME`` return the value of a config parameter\n* ``--file CONFIG_PATH``, ``-f CONFIG_PATH``: path to a config file\n\nSettings\n--------\n\nIf the option ``--file`` is not specified, ``policyd-rate-limit`` try to read its configuration from\nthe following path and choose the first existing file:\n\n* ~/.config/policyd-rate-limit.conf\n* ~/.config/policyd-rate-limit.yaml\n* /etc/policyd-rate-limit.conf\n* /etc/policyd-rate-limit.yaml\n\nThe ``.conf`` are the old configuration format. It was a python module and should not be used.\nThe ``.yaml`` are the new configuration format using the YAML syntax.\n\n\n* ``debug``: make ``policyd-rate-limit`` output logs to stderr.\n The default is ``True``.\n* ``user``: The user ``policyd-rate-limit`` will use to drop privileges.\n The default is ``\"policyd-rate-limit\"``.\n* ``group``: The group ``policyd-rate-limit`` will use to drop privileges.\n The defaut is ``\"policyd-rate-limit\"``.\n* ``pidfile``: path where the program will try to write its pid to.\n The default is ``\"/var/run/policyd-rate-limit/policyd-rate-limit.pid\"``.\n ``policyd-rate-limit`` will try to create the parent directory and chown it if it do not exists.\n* ``mysql_config``: The config to connect to a mysql server\n* ``pgsql_config``: The config to connect to a postgresql server\n* ``sqlite_config``: The config to connect to a sqlite3 database.\n* ``backend``: Which data backend to use. Possible values are ``0`` for sqlite3, ``1`` for mysql\n and ``2`` for postgresql. The default is ``0``, use the sqlite3 backend.\n* ``SOCKET``: The socket to bind to. Can be a path to an unix socket or a couple [ip, port].\n The default is ``\"/var/spool/postfix/ratelimit/policy\"``.\n ``policyd-rate-limit`` will try to create the parent directory and chown it if it do not exists.\n* ``socket_permission``: Permissions on the unix socket (if unix socket used).\n The default is ``0o666``.\n* ``limits``: A list of couple [number of emails, number of seconds]. If one of the element of the\n list is exeeded (more than 'number of emails' on 'number of seconds' for an ip address or an sasl\n username), postfix will return a temporary failure.\n* ``limits_by_id``: A dictionary of id -> limit list (see limits). Used to override limits and use\n custom limits for a particular id. Use an empty list for no limits for a particular id.\n Ids are sasl usernames or ip addresses. The default is ``{}``.\n* ``limit_by_sasl``: Apply limits by sasl usernames. The default is ``True``.\n* ``limit_by_sender``: Apply limits by sender addresses if sasl username is not found.\n The defaut is ``False``.\n* ``limit_by_ip``: Apply limits by ip addresses if sasl username and sender address are not found.\n The default is ``False``.\n* ``limited_networks``: A list of ip networks in cidr notation on which limits are applied. An empty\n list is equal to ``limit_by_ip = False``, put ``\"0.0.0.0/0\"`` and ``::/0`` for every ip addresses.\n* ``success_action``: If not limits are reach, which action postfix should do. The default is\n ``\"dunno\"``. See http://www.postfix.org/access.5.html for possible actions.\n* ``fail_action``: If a limit is reach, which action postfix should do. The default is\n ``\"defer_if_permit Rate limit reach, retry later\"``.\n* ``db_error_action`` : If we are unable to to contect the database backend, which action postfix\n should do. The default is ``\"dunno\"``. See http://www.postfix.org/access.5.html for possible\n actions.\n See http://www.postfix.org/access.5.html for possible actions.\n* ``config_file``: This parameter is automatically set to the path of the configuration file\n currently in use. You can call it conjunction with **--get-config** to known which configuration\n file is used.\n\n\n* ``report``: if ``True``, send a report to ``report_to`` about users reaching limits each time\n --clean is called. The default is ``False``.\n* ``report_from``: From who to send emails reports. It must be defined when ``report`` is ``True``.\n* ``report_to``: Address to send emails reports to. It must be defined when ``report`` is ``True``.\n It can be a single email address or a list of email adresses.\n* ``report_subject``: Subject of the report email. The default is ``\"policyd-rate-limit report\"``.\n* ``report_limits``: List of number of seconds from the limits list for which you want to be reported.\n The default is ``[86400]``.\n* ``report_only_if_needed``: Only send a report if some users have reach a reported limit.\n The default is ``True``.\n\n\n* ``smtp_server``: The smtp server to use to send emails ``[\"host\", port]``.\n The default is ``[\"localhost\", 25]``.\n* ``smtp_starttls``: Should we use starttls to send mails ? (you should set this to ``True`` if\n you use ``smtp_credentials``). The default is ``False``.\n* ``smtp_credentials``: Should we use credentials to connect to smtp_server ?\n if yes set ``[\"user\", \"password\"]``, else ``null``. The default is ``null``.\n\n* ``count_mode``: How sent mail are counted\n\n * ``0``: each RCPT TO are counted individualy. This is the how it was done historically. If set to 0,\n the postfix check_policy_service must be set in smtpd_recipient_restrictions.\n This is deprecated and should not be used anymore\n * ``1``: recipient are counted in the DATA stage. The postfix parameter check_policy_service must be\n defined in smtpd_data_restrictions.\n This is the new default.\n * ``2``: Number of submited mails a counted, not recipients. The postfix parameter\n check_policy_service must be defined in smtpd_data_restrictions.\n This means that if a use send a single mail with 100 recipient, it's count for 1\n in the quota instead of 100.\n\nPostfix settings\n----------------\n\nFor postfix 3.0 and later I recommend using the example below. It ensure that if policyd-rate-limit\nbecome unavailable for any reason, postfix will ignore it and keep accepting mail as if the rule\nwas not here. I find it nice has in my opinion, policyd-rate-limit is a \"non-critical\" policy\nservice.\n\n /etc/postfix/main.cf::\n\n smtpd_data_restrictions =\n ...,\n check_policy_service { unix:ratelimit/policy, default_action=DUNNO },\n ...\n\n\nOn previous postfix versions, you must use:\n\n /etc/postfix/main.cf::\n\n smtpd_data_restrictions =\n ...,\n check_policy_service unix:ratelimit/policy,\n ...\n\n\n.. |github_action| image:: https://github.com/nitmir/policyd-rate-limit/actions/workflows/github-actions.yml/badge.svg?branch=master\n :target: https://github.com/nitmir/policyd-rate-limit/actions/workflows/github-actions.yml\n\n.. |coverage| image:: https://badges.genua.fr/coverage/badge/policyd-rate-limit/master.svg\n :target: https://badges.genua.fr/coverage/policyd-rate-limit/\n\n.. |pypi_version| image:: https://badges.genua.fr/pypi/v/policyd-rate-limit.svg\n :target: https://pypi.python.org/pypi/policyd-rate-limit\n\n.. |github_version| image:: https://badges.genua.fr/github/tag/nitmir/policyd-rate-limit.svg?label=github\n :target: https://github.com/nitmir/policyd-rate-limit/releases/latest\n\n.. |license| image:: https://badges.genua.fr/pypi/l/policyd-rate-limit.svg\n :target: https://www.gnu.org/licenses/gpl-3.0.html",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "Postfix rate limit policy server implemented in Python3.",
"version": "1.2.0",
"project_urls": {
"Download": "https://github.com/nitmir/policyd-rate-limit/releases/latest",
"Homepage": "https://github.com/nitmir/policyd-rate-limit"
},
"split_keywords": [
"postfix",
"rate",
"limit",
"email"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8dd37cbac697cd96c27bce614856338f3ee61a1bc941fe90c00e1ec769696d0d",
"md5": "62c389df21c178f6f63094e98d531094",
"sha256": "fb0e4282821016daffdb277acfa532619262c0fe77b7ca74e6a46b299e048fe1"
},
"downloads": -1,
"filename": "policyd-rate-limit-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "62c389df21c178f6f63094e98d531094",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 43056,
"upload_time": "2023-08-27T09:20:33",
"upload_time_iso_8601": "2023-08-27T09:20:33.958649Z",
"url": "https://files.pythonhosted.org/packages/8d/d3/7cbac697cd96c27bce614856338f3ee61a1bc941fe90c00e1ec769696d0d/policyd-rate-limit-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-27 09:20:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nitmir",
"github_project": "policyd-rate-limit",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "policyd-rate-limit"
}
JSON
