< Security Configuration

Internationalization >

16. Throttling Configuration

16.1. Introduction

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.

16.2. Throttling configuration

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.

16.2.1. Main throttling configuration

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.log
  • blackListMail - A list of comma separated emails that will be notified every time an IP is added or removed from the blacklist.
  • buffer.*.period and buffer.*.maxRequest - Buffers configuration. Read Section 16.2.2, “Throttling rules configuration” to see how buffers works.

16.2.2. Throttling rules configuration

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

16.2.3. Whitelist configuration

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: is the ip address and /32 is the network mask.

To include a whole IP network, you have to write:

Where represent the network and /24 the network mask. In this case, the whitelist will include all addresses from to

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

valid xhtml 1.0 valid css