The throttling plugin allows to protect a cartoweb instance
against fast and massive usage from users. For example if a user tries to
download all your map data using a shell script with a combination of
mode=image and recenter_bbox
GET parameters.
If the plugin detects that a user (represented by its IP address) is using the application in a such wrong way, the user will be blacklisted for a configurable number a seconds and will receive an HTTP error code.
The throttling plugin is not a core plugin. That's why you need to enable it if you want to enable users to log-in. See Chapter 4, Configuration Files how to enable it in the list of plugins.
In practice, you have to define rules of maximum request allowed in a certain period. If the user overflow one such rule he is blacklisted as described above.
The plugin configuration file is located in
client_conf/throttling.ini. The configuration
options are:
dontBlock- Set to 1 to populate the black list without blocking the ip. Useful for fine tuning the parameters before really blocking.whiteListPath- White list location. Read Section 16.2.3, “Whitelist configuration” to have more information on this option.blackListPeriod- How long does a blacklisted must remains blocked (in seconds).blackListLog- Location of the log file. If the path is relative it is relative to CARTOWEB_HOME. Note that 'www-data' user (or the user who start apache) have to be able the write into this file. If this file is not writable, the content will be written into CARTOWEB_HOME/www-data/throttling/throttling.logblackListMail- A list of comma separated emails that will be notified every time an IP is added or removed from the blacklist.buffer.*.periodandbuffer.*.maxRequest- Buffers configuration. Read Section 16.2.2, “Throttling rules configuration” to see how buffers works.
Access rules (named buffer in the plugin)
represents the maximum request/period you want to allow for each IP
addresses. You can configure one or more buffers in the
client_conf/throttling.ini file.
Each buffer is defined by a name, a period and a maximum of request. For example, if you want to allow a maximum of 20 request in 10 second for each IP, you will write:
buffer.short.period = 10 buffer.short.maxRequest = 20
Where short is the symbolic buffer name,
this name will be specified in the log file and in the mail.
If you want to create more than one buffer you just have to populate the config file and dont forget to change the symbolic name. For instance:
buffer.short.period = 10 buffer.short.maxRequest = 20 buffer.long.period = 3600 buffer.long.maxRequest = 500 buffer.foo.period = 100 buffer.foo.maxRequest = 500
A list of IP addresses or IP networks can be specified in the main throttling configuration file, this list will contains addresses of hosts or networks that will not be taken into account by the plugin.
Addresses are in Classless Inter-Domain Routing format, if you want to include a single IP address you have to write:
127.0.0.1/32
127.0.0.1 is the ip address and
/32 is the network mask.
To include a whole IP network, you have to write:
192.168.3.0/24
Where 192.168.3.0 represent the network and
/24 the network mask. In this case, the whitelist
will include all addresses from 192.168.3.1 to 192.168.3.255
Note that if the user's IP address can't be properly detected, it
is never declared as belonging to the whitelist. It sometimes happens
if the user's computer is behind a miss-configured proxy: a proxy that
don't properly set the HTTP_X_FORWARDED_FOR,
HTTP_X_FORWARDED or
HTTP_CLIENT_IP header.
For more information about the Classless Inter-Domain Routing format, see: http://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing
