.. _admin-plugins-geoip-acl:

GeoIP ACLs Plugin
*****************

.. Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.

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:

1. 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

2. 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.

3. 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.