From Qmailwiki
Jump to: navigation, search


About throttling

When speaking about throttling, it generally consists of throttling overall messaging from a single source to one or more sources. Throttling can be implemented by limiting byte counts, as well as message counts.

This specific document is about messaging throttling --Limiting the number of messages a single user can send to multiple sources. More specifically, this document refers to the Inter7 patch regarding throttling of one's own userbase. It throttles only authenticated users of your system, not external sources.


In order to use Inter7's throttling patch, you must also have eMPF installed and have eMPF set to require authentication on users claiming to be of that system even when not relaying.


Control files

The throttling patch adds several control files. These files are re-read for each new connection, and each new message being sent to keep the system as close to real-time as possible. Understanding the control files will help you to come up with a global default for messaging limitations.

These files exist only in the qmail control directory, and contain only a single value, an integer, describing a limitation or time period.


This control file specifies how long to keep collected data, in seconds. Every time a message is sent, a record is kept of the number of recipients involved in the transaction. After the throttleexpire time has expired since a message was sent, the record is removed.

  • Recommended value: 172800 (48 hours)
  • Minimum value: 60 (1 minute)
  • Default value: 60 (1 minute)


throttleseconds describes how much past data, in seconds, to evaluate when determining how much messaging a particular user of your system has done. When setting messaging limits, you may want to limit users to 500 messages in a 24 hour period. The 24 hour period is the throttleseconds configuration. In the case of 24 hours, the value would be 86400.

Note that this value should be less than throttleexpire, but does not require this for reasons outside the scope of this document.

  • Recommended value: 86400 (24 hours)
  • Minimum value: 0 (disabled)
  • Default value: 0 (disabled)


throttleuser describes how many recipients a user may send to in throttleseconds. This is tallied in real time, system-wide.

  • Recommended value: 500
  • Minimum value: 0 (disabled)
  • Default value: 0 (disabled)


throttledomain limits the number of recipients users on a single domain may send to in throttleseconds. Again, this value is tallied in real-time, system-wide.

  • Recommended value: 0
  • Minimum value: 0 (disabled)
  • Default value: 0 (disabled)


throttleip limits the number of recipients a specific IP may send to in throttleseconds. This value is tallied in real-time, system-wide.

  • Recommended value: 0
  • Minimum value: 0 (disabled)
  • Default value: 0 (disabled)


Sets the order in which throttle settings are compared to user usages and exceptions, where u is user, d is domain, and i is IP. All three values must appear, and must be lowercase.

NOTE: This configuration is only available in version 2 of the patch

  • Recommended value: udi
  • Default value: udi


The recommended values above describe a system with very basic limitations mostly focused on stopping users infected with viruses from causing problems for the mail system. Because of how the throttling patch limits users, it also empowers users to contact you when they can no longer send mail, taking away the hassle of having to monitor how throttling is limiting specific users.

 echo 172800 > /var/qmail/control/throttleexpire
 echo 500 > /var/qmail/control/throttleuser
 echo 86400 > /var/qmail/control/throttleseconds
 echo udi > /var/qmail/control/throttleprecedence

In this example, users are limited to 500 recipients in any 24 hour period. Note that the throttling patch is not aware of bounces generated as a result of messaging, or even undeliverable messages. If a user is authenticated, and adds a recipient to an envelope, it is counted as if it has been delivered to that recipient.

If any throttling exceptions are set, user-level exceptions take precedence over domain-level exceptions, which take precedence over IP-level exceptions, which take precedence over the global throttling configuration.

throttleexpire and throttleseconds

throttleexpire and throttleseconds appear to be doing the same job, but this is not true. throttleexpire states when messaging data should be removed from the database. throttleseconds states how much data from the database to evaluate. At first inspection it would seem that throttleseconds could do the job of throttleexpire, and it could, but throttleexpire adds one key feature: The ability to slide throttleseconds' value around while maintaining a full dataset to evaluate against.

If throttleexpire is set to 72 hours, and throttleseconds is set to 24 hours, even though you're only evaluating 24 hours of data, if you decided you wanted to instead evaluate against 48 hours of data rather than just 24, you're have a full 48 hours of data to evaluate against, whereas, if throttleexpire had been set to 24 hours, you'd be missing 24 hours of data.


Most systems will have users who have a variety of different needs. Throttling for one user may not work for yet another user. For this reason, the throttling patch also includes exceptions. You may add exceptions to the global policy defined by the control files, by user, domain, and by IP.

There are currently two versions of the throttling patch. Version 1 uses files and environment variables to configure exceptions, and version 2 uses the database backend.

Version 1

User exceptions

To create an exception to the global policy, a file under the user's home directory called 'throttle' should be created.

 echo 300 > /home/vpopmail/domains/

This will set the throttleuser setting to 300 when evaluating that user.

Domain exceptions

Creating an exception for a domain is just as easy as creating a user exception. It modifies the throttledomain setting when evaluating that domain only. To do this, add a file named 'throttle' under the domain's root directory.

 echo 300 > /home/vpopmail/domains/

IP exceptions

IP exceptions are done via environment variables. The environment THROTTLE will be evaluated and used to replace throttleip. To do this with tcpserver:

 echo,THROTTLE="300" >> /home/vpopmail/etc/tcp.smtp

(Don't forget to recompile the CDB file)

Version 2

Version 2 of the patch allows you to configure all exceptions from within the database, rather than creating files on the file system.

The throttleprecedence setting will determine in what order they are applied.

There are four fields per exception configuration. user, domain, ip, and limits. A particular exception type can be set depending upon what fields are filled, and what fields are NULL. There is a strict requirement on what fields must be set, and which must not be set in order as to not accidentally set a rule that applies to several exception types.

User exceptions

To configure a user exception, the fields user, domain, and limits must be set, and the ip field must be NULL.

Domain exceptions

Domain exceptions must have the fields domain and limits set, while the user and ip fields must be NULL.

IP exceptions

All fields must be NULL except the ip and limits fields.

Personal tools