IP rate-limiting and white-listing enables one to restrict access to Zato objects based on two sets of conditions:
It is possible to express scenarios of varying complexity, such as the simple one below:
Or a more intricate one, such as this:
Rate-limiting definitions can be attached to several kinds of objects, each of which is checked in run-time in the order described below:
Note that while the order of checks is fixed, all of these steps are optional and if a particular object does not have any definition, or if it is not enabled, it will not be checked at all.
A definition for each type of object possible is always of the same format:
For instance, below is a sample definition for a service object - all the other object types follow the same style:
Enabled - dictates whether a given definition is to be processed or not. If it is not on, the definition will be skipped completely, as though it did not exist.
Return errors - if on, clients whose rate limits have been reached will be given details of such a situation, otherwise a generic error message will be returned.
With the exception of SSO users, definitions may be of two types: exact or approximate ones.
Exact - the definition is shared by all Zato server processes and all checks and comparisons of whether it is already reached are serialized. This is not as fast as approximate ones but comes with a stronger guarantee that if a limit is reached by one server then all the rest will recognize it immediately.
Approximate - the definition is specified by each server process rather than on a cluster-level. This means that checks and comparisons are after than in exact ones but it may lead to situations when one server reaches the limit while the rest can still accept requests - ultimately though all servers will reach the same limit.
Note that SSO users always use exact definitions, it is not possible to change it to an approximate one.
Each definition contains zero or more rules that are matched in runtime against incoming requests. Each rule is in its own line. Rules are matched in the same order as they are listed in the definition.
Processing stops as soon as the first matching rule is found. If no rule matches, the request is rejected.
Note that it is possible to create empty rules, that is, without any lines to match at all. This will indiscriminately reject all requests.
Each line is in the format of source = limit. Whitespace around the equals sign is ignored.
Source may be one of:
An asterisk to denote "any source address"
Limit is a rate expressed in units of time, where:
d = day
* 10/m = ten times a minute * 500/h = five hundred times an hour * 10000/d = ten thousand times a day
Any part of a rate-limiting definition can be changed at any time, e.g. limits may be freely changed whenever it is required.
Each time a definition is changed its internal hit counter is reset - for instance:
The only change that does not reset the counter is modifying the "Is active" flag - toggling the definition's state between active or inactive, no matter how many times, does not reset its hit counter.
No matter the source address, this object may be accessed at most one thousand times a day:
Users from the first network block may access the object a hundred times a minute whereas the ones from another block only five times a day:
Some addresses networks will have limits but for localhost there will be no limits:
No limits all, no matter the source address: