Geolocation enables developers to enhance the user experience. Content and advertising may be customized for a specific user's country, showing pages more relevant to the location of the user. Admins can further enhance a site's security by blocking a client based on country.  Displays can be customized for the user's environment.

This wiki describes the new GeoLite2 database (with the .mmdb extension), downloadable from here.  To use the legacy databases (.dat extension) see the description for setting up legacy databaseshere.

Step 1. Install

The GeoLite2 databases are updated frequently and will regularly have to be downloaded. The description of automating this download by MaxMind is here.  It is strongly recommended that while you may want to test by downloading the databases manually that you have them updated automatically.

Full support for all of the databases (both the free ones and the subscription ones) are included.  You need to download the databases to a known location on your system.  The automatic update will load them into /usr/local/share/GeoIP and the instructions will assume that you are loading the two free ones: GeoLite2-Country.mmdb and GeoLite2-City.mmdb and can be followed to setup access to the paid databases as well..

Step 2. Setup

In OLS WebAdmin, configure the database location. Navigate to Configuration > Server > General > General settings > IP to GeoLocation DB Enter DB File Path:

/usr/local/share/GeoIP/GeoLite2-Country.mmdb

Set DB Name to: COUNTRY_DB

openlitespeed.org_wp-content_uploads_2018_07_iptogeo_config-2.jpg

Similarly, add the city database by specifying DB File Path: /usr/local/share/GeoIP/GeoLite2-City.mmdb and DB Name: to: CITY_DB

Navigate to Web Admin > Configurations > Your Virtual Hosts > Rewrite to add rewrite rules that will control the redirect:

<IfModule LiteSpeed>
 RewriteEngine on
 RewriteRule .* - [E=Cache-Control:vary=%{ENV:GEO_COUNTRY}]
</IfModule>

Refer to Maxmind for more rewrite examples.

Step 3. Verify

Change Your Source IP by Proxy

Method 1:

From This site, we can simply put in a web IP and choose a country from three(USA, Germany, Netherlands). If you want more than three countries, then you need to register for a paid plan.

Method 2:

You can choose a free proxy server from online free resources, e.g. Free_Proxy

Setup the proxy IP with your browser. Here are the steps for Chrome:

  1. Click on Settings.
  2. Click Show advanced settings
  3. Scroll further down the list until you see System
  4. Click Open proxy settings
  5. Click the LAN settings button.
  6. On the Internet Properties window, click the LAN settings button.
  7. LAN Settings: uncheck the box that says Automatically detect settings.
  8. Proxy Server section: click the checkbox to enable Use a proxy server for your LAN
  9. In the Address field, enter the IP Address and Port Number of your Proxy Server.
  10. Press the OK button and then press OK again to save your settings.
  11. Now when you surf the web, you will be surfing by using the Proxy Server.

Step 4. Check Correct IP is Set

You can check source IP via LiteSpeed default php page http://yourdomain/index.php?act=phpinfo.  Check the $_SERVER variables, and look for the ones which begin with GEOIP_.

openlitespeed.org_wp-content_uploads_2018_07_geoenv.jpg

The environment variables are based on the default environment definitions.  The advanced section below shows you how to customize them for your environment to allow you to specify environment names, display language, additional databases, etc.

Step 5. Check DB by Lookup Command

A very useful MaxMind tool is downloaded and compiled with the source code release: mmdblookup.  Use this tool to view an entry in the database for a specific IP. For example, to see the country name definition for the IP address 47.22.54.182 enter from a command prompt in the openlitespeed directory:

libmaxminddb/bin/mmdblookup --file /usr/local/share/GeoIP/GeoLite2-Country.mmdb --ip 47.22.54.182 -v

The output is very detailed and can be informative as it shows you the information available in the database:

Database metadata
    Node count:    561374
    Record size:   24 bits
    IP version:    IPv6
    Binary format: 2.0
    Build epoch:   1530653013 (2018-07-03 21:23:33 UTC)
    Type:          GeoLite2-Country
    Languages:     de en es fr ja pt-BR ru zh-CN
    Description:
      en:   GeoLite2 Country database


  {
    "continent": 
      {
        "code": 
          "NA" <utf8_string>
        "geoname_id": 
          6255149 <uint32>
        "names": 
          {
            "de": 
              "Nordamerika" <utf8_string>
            "en": 
              "North America" <utf8_string>
            "es": 
              "Norteamérica" <utf8_string>
            "fr": 
              "Amérique du Nord" <utf8_string>
            "ja": 
              "北アメリカ" <utf8_string>
            "pt-BR": 
              "América do Norte" <utf8_string>
            "ru": 
              "Северная Америка" <utf8_string>
            "zh-CN": 
              "北美洲" <utf8_string>
          }
      }
    "country": 
      {
        "geoname_id": 
          6252001 <uint32>
        "iso_code": 
          "US" <utf8_string>
        "names": 
          {
            "de": 
              "USA" <utf8_string>
            "en": 
              "United States" <utf8_string>
            "es": 
              "Estados Unidos" <utf8_string>
            "fr": 
              "États-Unis" <utf8_string>
            "ja": 
              "アメリカ合衆国" <utf8_string>
            "pt-BR": 
              "Estados Unidos" <utf8_string>
            "ru": 
              "США" <utf8_string>
            "zh-CN": 
              "美国" <utf8_string>
          }
      }
    "registered_country": 
      {
        "geoname_id": 
          6252001 <uint32>
        "iso_code": 
          "US" <utf8_string>
        "names": 
          {
            "de": 
              "USA" <utf8_string>
            "en": 
              "United States" <utf8_string>
            "es": 
              "Estados Unidos" <utf8_string>
            "fr": 
              "États-Unis" <utf8_string>
            "ja": 
              "アメリカ合衆国" <utf8_string>
            "pt-BR": 
              "Estados Unidos" <utf8_string>
            "ru": 
              "США" <utf8_string>
            "zh-CN": 
              "美国" <utf8_string>
          }
      }
  }

In the example above you can see:

  • Date and time of the database update: 2018-07-03 21:23:33 UTC
  • Type of database: GeoLite2-Country
  • List of languages available: de en es fr ja pt-BR ru zh-CN
  • And the list of available environment variable options.  For example: country/names/es is the Spanish language version of the United States and would be displayed as Estados Unidos

Note that this list is not the complete list of available options as it's only for the specific database, in this case the Country database.  The City database has even more fields.

Step 6. Set Rewrite Rules

Navigate to Web Admin > Configurations > Your Virtual Hosts > Rewrite:

  • Set Rewrite to Yes
  • For testing purpose, set Log Level to 9.
  • Add the following rules to Rewrite Rules content:
# Redirect two specific countries
RewriteCond %{ENV:GEOIP_COUNTRY_CODE} ^(CA)$
RewriteRule ^(.*)$ https://en.wikipedia.org/wiki/Canada [R,L]
RewriteCond %{ENV:GEOIP_COUNTRY_CODE} ^(EU)$
RewriteRule ^(.*)$ https://en.wikipedia.org/wiki/Europe [R,L]

Step 7. Check Log

tail -f /PATH_TO_LSWS/log/error.log

When you are using a CA IP:

[REWRITE] Rule: Match '/' with pattern '^(.*)$', result: 2
[REWRITE] Cond: Match 'CA' with pattern '^(CA)$', result: 2
[REWRITE] Source URI: '/' => Result URI: 'https://en.wikipedia.org/wiki/Canada'

With a Germany IP:

[REWRITE] Rule: Match '/' with pattern '^(.*)$', result: 2
[REWRITE] Cond: Match 'EU' with pattern '^(EU)$', result: 2
[REWRITE] Source URI: '/' => Result URI: 'https://en.wikipedia.org/wiki/Europe'

Using a Netherlands IP:

[REWRITE] Rule: Match '/' with pattern '^(.*)$', result: 2
[REWRITE] Cond: Match 'NL' with pattern '^(CA)$', result: -1
[REWRITE] Rule: Match '/' with pattern '^(.*)$', result: 2
[REWRITE] Cond: Match 'NL' with pattern '^(EU)$', result: -1

2 is match, -1 is not match

Step 8. Troubleshooting

  • If the module is not working, make sure that the httpd user (e.g. nobody) has read access to the GeoIP database file(s) you are using.
  • If the GeoIP variables do not show up please make sure that the client IP address is not on a private network such as 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16. GeoIP can only look up public IP addresses.
  • The server error.log will show geolocation messages with a prefix of [GEO].  Turning on Debug mode will provide quite a bit of details.

The full power of the GeoIP2 facility requires use of the environment variables in the Litespeed Configuration.  The description of the format used is designed to be as similar as possible as the Apache mod_maxminddb environment described here specifically for the MaxMindDBEnv variable.  Each environment variable is specified in the environment text box as one line:

  • The name of the environment variable that will be exported, for example GEOIP_COUNTRY_NAME
  • A space
  • The logical name of the environment variable.  That consists of:
    • It uses the name of the database as specified in the DB Name field as the prefix.  For example COUNTRY_DB
    • A forward slash /
    • The forward slash separated name of the field as displayed in mmdblookup.  For example: country/names/en

Thus the default generates: GEOIP_COUNTRY_NAME COUNTRY_DB/country/names/en If you wanted the country code to be displayed in Spanish, you would enter the environment variable: GEOIP_COUNTRY_NAME COUNTRY_DB/country/names/es Note that if a variable is used by multiple databases (for example, the default GEOIP_COUNTRY_NAME) you need to override the value in the last database specified (or all databases in case they get reordered, just to be safe). The default environment variables vary by database and are designed to be as similar to the legacy GeoIP environment variables as possible.

County Database Defaults

Database name: GeoLite2-Country.mmdb Logical name: COUNTRY_DB

Variable Definition Notes
GEOIP_CONTINENT_CODE COUNTRY_DB/continent/code 2 digit string ('NA' for North America)
GEOIP_COUNTRY_CODE COUNTRY_DB/country/iso_code2 digit string ('US' for United States)
GEOIP_COUNTRY_CONTINENTCOUNTRY_DB/continent/code Same as GEOIP_CONTINENT_CODE
GEOIP_COUNTRY_NAME COUNTRY_DB/country/names/enDefault is English, you may want to change this

City Database Defaults

Database name: GeoLite2-City.mmdb Logical name: CITY_DB

Variable Definition Notes
GEOIP_CITY CITY_DB/city/names/en Nationalized, default is English, you may want to change this
GEOIP_CONTINENT_CODE CITY_DB/continent/code 2 digit string ('NA' for North America)
GEOIP_COUNTRY_CODE CITY_DB/country/iso_code 2 digit string ('US' for United States)
GEOIP_COUNTRY_CONTINENTCITY_DB/continent/code Same as GEOIP_CONTINENT_CODE
GEOIP_COUNTRY_NAME CITY_DB/country/names/en Nationalized, default is English, you may want to change this
GEOIP_DMA_CODE CITY_DB/location/metro_code An integer number
GEOIP_LATITUDE CITY_DB/location/latitude A signed floating point (double)
GEOIP_LONGITUDE CITY_DB/location/longitude A signed floating point (double)
GEOIP_METRO_CODE CITY_DB/location/metro_code An integer number
GEOIP_POSTAL_CODE CITY_DB/postal/code Varies by country (ZIP code in U.S.)
GEOIP_REGION CITY_DB/subdivisions/iso_codeVaries by country (State in U.S.)
GEOIP_REGION_NAME CITY_DB/subdivisions/name/en Nationalized, default is English, varies by country (State in U.S.)

ASN Database Defaults

Database name: GeoLite2-ASN.mmdb Logical name: ASN_DB

Variable Definition Notes
GEOIP_ISP ASN_DB/autonomous_system_number A 32-bit integer
GEOIP_ORGANIZATIONASN_DB/autonomous_system_organizationA vendor specific string
  • Admin
  • Last modified: 2018/07/18 14:23
  • by Lisa Clarke