CountryIpFilter

Experimantal

The filter is experimental, backward compatibility with upcoming releases is not guaranteed.

The CountryIpFilter can be used to associate a country with each request.

The country is calculated using the requests' IP-address (both IPv4 and IPv6 addresses are supported) and a provided IP-Location database. Currently only mmdb (MaxMind Database) format is supported.

The remote IP address is usually one of the client connecting directly to nevisProxy. If there is a load balancer or similar between the frontend and nevisproxy then the apache module mod_remoteip has to be configured via an ApacheConfigFilter. See the examples further down.

Classname

ch::nevis::nevisproxy::filter::validation::CountryIpFilter

Library

libValidationFilters.so.1

Configuration

DbFile

Type: string
Usage Constraint: required

The path of the IP-location file. Note that currently only mmdb format is supported. The database file is downloadable here (Edition ID: "GeoLite2-Country").

When DbServlet is not configured, the file will be automatically reloaded if the content of the configured DbFile changes. The file modification will be checked in the interval configured under periodicity in the Timer section in the file navajo.xml.

When DbServlet is configured, the file will be written by nevisproxy to cache the downloaded database locally.

A copy of the file will be placed into the run directory of the configured spoolDir in navajo.xml (usually /var/opt/nevisproxy/<instance>). It should be removed automatically once the instance is shut down. But in case of an unexpected behavior we recommend to regularly check the run directory in order to remove those files if the instance is not running.

DbServlet

Type: string
Usage Constraint: optional

The name of the servlet that will be used to periodically download the IP-location database file. The remote server must respond with a 200 status code and with a valid mmdb file.

DbServlet.Path

Type: string
Usage Constraint: optional

The path and query of the request that is sent when downloading the IP-location database file. The path and query has to be URL-encoded and the path cannot contain plus signs.

DbServlet.DownloadPeriodicity

Type: integer
Unit: seconds
Usage Constraints: optional
Default: 86400 (1 day)

The waiting time between two IP-location database downloads in seconds. In case of an issue, the downloading is retried earlier.

Rules

Type: new-line separated list of strings
Usage Constraints: optional
Syntax: <country>:<action>

Defines what action should be taken when the request is from the specified country.

The allowed country names can be found here: https://www.geonames.org/countries/
The allowed actions can be found further down.

DefaultAction

Type: enum
Usage Constraints: optional, conditional
Default: allow

Defines what action to execute when no rules were matched because either the request's country was not in the Rules list or the request's IP-address does not have an associated country.
The allowed actions can be found further down.

SetEnv

Type: boolean
Usage Constraints: optional
Default: false

When enabled the determined location can be accessed for example by a LuaFilter using req:getAttribute('geolocation').

Actions

The following values are supported:

• allow: Allows requests from the specified country.
• log: Creates a log entry for each request from the specified country.
• block: Blocks requests from the specified country.

Examples

Configuration example for the CountryIpFilter

The following CountryIpFilter will allow only requests coming from Austria, Germany or Switzerland:

<filter>
    <filter-name>DACHOnlyCountryIpFilter</filter-name>
    <filter-class>ch::nevis::nevisproxy::filter::validation::CountryIpFilter</filter-class>
    <init-param>
        <param-name>DbFile</param-name>
        <param-value>@PKG_VAR@/@PKG_INSTANCE@/conf/country.mmdb</param-value>
    </init-param>
    <init-param>
        <param-name>Rules</param-name>
        <param-value>
            Germany:allow
            Switzerland:allow
            Austria:allow
        </param-value>
    </init-param>
    <init-param>
        <param-name>DefaultAction</param-name>
        <param-value>block</param-value>
    </init-param>
</filter>

You can find a full example under /opt/nevisproxy/examples/apache_module/RestrictAccessByLocation.example on the host where nevisproxy has been installed.

Configuration example for integrating with a database provider

The following CountryIpFilter will download an IP-location database from http://www.mymmdbprovider.com/db-path?apikey=123 every hour:

<filter>
    <filter-name>CountryIpFilter</filter-name>
    <filter-class>ch::nevis::nevisproxy::filter::validation::CountryIpFilter</filter-class>
    <init-param>
        <param-name>DbFile</param-name>
        <param-value>@PKG_VAR@/@PKG_INSTANCE@/conf/cache.mmdb</param-value>
    </init-param>
    <init-param>
        <param-name>DbServlet.Path</param-name>
        <param-value>/db-path?apikey=123</param-value>
    </init-param>
    <init-param>
        <param-name>DbServlet</param-name>
        <param-value>CountryIpDbDownloaderServlet</param-value>
    </init-param>
    <init-param>
        <param-name>DbServlet.DownloadPeriod</param-name>
        <param-value>3600</param-value>
    </init-param>
    <init-param>
        <param-name>SetEnv</param-name>
        <param-value>true</param-value>
    </init-param>
</filter>
...
<servlet>
    <servlet-name>CountryIpDbDownloaderServlet</servlet-name>
    <servlet-class>ch::nevis::isiweb4::servlet::connector::http::HttpConnectorServlet</servlet-class>
    <init-param>
        <param-name>RequestFlags</param-name>
        <param-value>-NEEDS_COOKIES</param-value>
    </init-param>
    <init-param>
        <param-name>InetAddress</param-name>
        <param-value>www.mymmdbprovider.com</param-value>
    </init-param>
    <init-param>
        <param-name>ResourceManager.RetryTimeout</param-name>
        <param-value>0</param-value>
    </init-param>
    <init-param>
        <param-name>ResourceManager.DisablePing</param-name>
        <param-value>true</param-value>
    </init-param>
</servlet>

Configuration examples for the apache module mod_remoteip

If there is no other component (like a load-balancer or a proxy) between nevisproxy and the frontend, then the CountryIpFilter can be used without configuring the apache module mod_remoteip.

If there is some component between nevisproxy and the frontend then you'll have to configure the apache module mod_remoteip via an ApacheConfigFilter.

Usually an ApacheConfigFilter is enough:

    <filter-name>ConfigureRemoteIpFilter</filter-name>
    <filter-class>ch:nevis:navajo:apglue:httpd_${HTTPD_LIB_VERSION}_x:servlet:ApacheConfigFilter</filter-class>
    
    <init-param>
        <param-name>ServerConfig</param-name>
        <param-value>
            LoadModule remoteip_module /opt/nevisproxy/lib/libmetadata_ap_2_4.so.1
            RemoteIPHeader X-Forwarded-For
        </param-value>
    </init-param>

You can use this configuration if you trust the component between nevisproxy and the frontend to always set the X-Forwarded-For and never pass one which may have been set by the frontend.

To be on the safe side and avoid that malicious clients could fake their IP addresses, you can use the directive RemoteIPTrustedProxy like this:

<filter>
    <filter-name>ConfigureRemoteIpFilter</filter-name>
    <filter-class>ch:nevis:navajo:apglue:httpd_${HTTPD_LIB_VERSION}_x:servlet:ApacheConfigFilter</filter-class>
    
    <init-param>
        <param-name>ServerConfig</param-name>
        <param-value>
            LoadModule remoteip_module /opt/nevisproxy/lib/libmetadata_ap_2_4.so.1
            RemoteIPHeader X-Forwarded-For
            RemoteIPTrustedProxy 10.0.2.16/28
            RemoteIPTrustedProxy proxy.example.com
        </param-value>
    </init-param>
</filter>

You can find a full example under /opt/nevisproxy/examples/apache_module/RestrictAccessByLocation.example on the host where nevisproxy has been installed.

Here you can find more information about the apache module mod_remoteip: https://httpd.apache.org/docs/2.4/mod/mod_remoteip.html