GeoIP ACLs Plugin¶

This is a simple ATS plugin for denying (or allowing) requests based on the source IP geo-location. Currently only the Maxmind APIs are supported, but we’d be happy to other (open) APIs if you let us know. This plugin comes with the standard distribution of Apache Traffic Server, and should be installed as part of the normal build process.

Configuration¶

Once installed, there are three primary use cases, which we will discuss in details. Note that in all configurations, the first plugin parameter must specify what the matches should be applied to. Currently, only one rule set is supported, for Country ISO codes. This is specified with a parameter of

@pparam=country

Future additions to this plugin could include other regions, such as city, state, continent etc.

The three typical use cases are as follows:

Per remap configurations, applicable to the entire remap rule. This is useful when you can partition your content so that entire prefix paths should be filtered. For example, lets assume that http://example.com/music is restricted to US customers only, and everything else is world wide accessible. In remap.config, you would have something like
```
map http://example.com/music http://music.example.com \
  @plugin=geoip_acl.so @pparam=country @pparam=allow @pparam=US
map http://example.com http://other.example.com
```
If you can not partition the data with a path prefix, you can specify a separate regex mapping filter. The remap.config file might then look like
```
map http://example.com http://music.example.com \
  @plugin=geoip_acl.so @pparam=country \
  @pparam=regex::/etc/music.regex
```

where music.regex is a format with PCRE (perl compatible) regular expressions, and unique rules for match. E.g.:

.*\.mp3  allow  US
.*\.ogg  deny   US

Note that the default in the case of no matches on the regular expressions is to “allow” the request. This can be overridden, see next use case.

You can also combine 1) and 2), and provide defaults in the remap.config configuration, which then applies for the cases where no regular expressions matches at all. This would be useful to override the default which is to allow all requests that don’t match. For example
```
map http://example.com http://music.example.com \
  @plugin=geoip_acl.so @pparam=country @pparam=allow @pparam=US \
  @pparam=regex::/etc/music.regex
```

This tells the plugin that in the situation where there is no matching regular expression, only allow requests originating from the US.

Finally, there’s one additional parameter option that can be used

@pparam=html::/some/path.html

This will override the default response body for the denied responses with a custom piece of HTML. This can be useful to explain to your users why they are getting denied access to a particular piece of content. This configuration can be used with any of the use cases described above.