Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
litespeed_wiki:cache:common:geoip-support [2020/01/29 21:29]
Lisa Clarke Corrected Brand Capitalization
litespeed_wiki:cache:common:geoip-support [2020/11/14 15:24] (current)
Lisa Clarke Redirect to new Documentation Site
Line 1: Line 1:
-====== GeoLocation Support (GeoIP) for LiteSpeed Web Server ​ ====== +~~REDIRECT>​https://​docs.litespeedtech.com/​cp/cpanel/geoip/~~
- +
-LSCache supports GeoIP databases, including MaxMind GeoIP2, MaxMind GeoIP Legacy, and IP2Location. ​ MaxMind discontinued their Legacy databases On January 2, 2019, hence we recommend you no longer use it. +
- +
-For LSWS v5.2.x and earlier, only the MaxMind Legacy Database .dat is supported. As of LSWS v5.3RC2, LSWS supports the [[https://​www.maxmind.com/​en/​geoip2-databases|MaxMind GeoIP2 format database]], ''​.mmdb''​. The database path configuration is in the same location as the legacy DB (**Configuration ​Server > General > General settings > IP to GeoLocation DB**), then set the database path to either ''​.dat''​ or ''​.mmdb''​. +
- +
-There are two sections in the LSWS WEB Admin Console settings: **IP to GeoLocation DB** and **IP2Location DB**. Both the MaxMind legacy db and MaxMind GeoIP2 db should use the **IP to GeoLocation DB** section. ​ Don't use **IP2Location DB** for MaxMind GeoIP2 database since **IP2Location DB** is meant for the  [[https://​www.ip2location.com/​|IP2Location database]]. ​ You should only use one location database at a time.  +
-{{ :​litespeed_wiki:​cache:​common:​lsws-geoip-settings.png?​800 |}} +
-  +
-To setup and enable GeoIP on LSWS, you will need to choose one database, download and install the database to a directory, setup the database path in LSWS Admin, enable GeoIP through the Apache configuration or LSWS native, then finally run some tests.  +
- +
-===== Map MaxMind GeoIP2 Variables to IP2Location ===== +
-If you have switched from the MaxMind GeoIP2 service to an IP2location database on your shared hosting server, many of your PHP scripts may still make use of the ''​GEOIP_*''​ environment variables ''​$SERVER['​GEOIP_COUTRY_CODE'​]''​ and ''​$SERVER['​GEOIP_ADDR'​]''​. Because of the nature of shared hosting servers, it is impossible to remove these environment variables or get all customers to rename them in their scripts.  +
- +
-Luckily, LiteSpeed Web Server handles this scenario for you. +
- +
-Starting from LSWS 5.4.4 build 2, ''​GEOIP_COUNTRY_CODE''​ is automatically mapped to ''​IP2LOCATION_COUNTRY_SHORT''​ and ''​GEOIP_ADDR''​ is automatically mapped to ''​IP2LOCATION_ADDR''​. +
-===== Download and Configure GeoIP Database Path ===== +
- +
-You will need to choose only one database to be used for your GeoIP: MaxMind GeoIP2, MaxMind Legacy Database, or IP2location database. Then, set up the right database path in the appropriate section in the LSWS Web Admin Console. ​   +
- +
-==== MaxMind GeoIP2 Database ====  +
- +
-=== Download and Install Database===  +
-Let's assume that you will store the DB in ''/​usr/​share/​GeoIP/''​. +
- +
-Starting December 30, 2019, you cannot ''​wget''​ the GeoLite2 database anymore. Instead, you will need to register for a MaxMind account and obtain a license key in order to [[https://​blog.maxmind.com/​2019/​12/​18/​significant-changes-to-accessing-and-using-geolite2-databases/​|download GeoLite2 databases]]. +
- +
-After download, you can unzip it: +
-  tar -zxvf GeoLite2-Country_20200114.tar.gz +
- +
-Then, move the file ''​GeoLite2-Country.mmdb''​ to  +
-  /​usr/​share/​GeoIP/​GeoLite2-Country.mmdb +
-   +
-=== Set up Database File Path and Name === +
-In LSWS WebAdmin, configure the database location and name(Both **DB File Path** and **DB Name** are mandatory and can not be empty). Your choice of DB name is important: you must use ''​COUNTRY_DB''​ for a country database, and ''​CITY_DB''​ for a city database. Navigate to **Configuration > Server > General > General settings** and set  **[[https://​www.litespeedtech.com/docs/​webserver/​config/​general#​geolocationDB|IP to GeoLocation DB]]** to the database path. Then set **DB Name** to ''​COUNTRY_DB''​ or ''​CITY_DB''​. **Environment Variables** and **Notes** are optional. +
- +
-{{ :​litespeed_wiki:​cache:​common:​litespeed-enable-geoip2-11.png?​800 |}} +
- +
-{{ :​litespeed_wiki:​cache:​common:​litespeed-enable-geoip2-22.png?​800 |}} +
- +
-Alternately,​ you can edit the LSWS configuration file directly:  +
-<​code>​ vi /​usr/​local/​lsws/​conf/​httpd_config.xml</​code>​  +
- +
-And add the following before ''<​tuning>'':​ +
-<​code>​ +
- <​ipToGeo>​ +
-    <​geoipDB>​ +
-      <​geoipDBFile>/​usr/​share/​GeoIP/​GeoLite2-Country.mmdb</​geoipDBFile>​ +
-      <​geoipDBName>​COUNTRY_DB</​geoipDBName>​ +
-    </​geoipDB>​ +
- </​ipToGeo>​ +
-  </​code>​ +
- +
-==== Advanced Configuration:​GeoIP2 Environment Variables ==== +
- +
-The full power of GeoIP2 requires the use of environment variables in the LiteSpeed configuration. The format used is designed to be as similar as possible to the Apache ''​mod_maxminddb''​ environment described [[https://​github.com/​maxmind/​mod_maxminddb|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, which consists of: +
-    * The name of the database as specified in the **DB Name** field as the prefix. For example, ''​COUNTRY_DB''​ +
-    * A forward slash ''/''​ +
-    * The 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). +
- +
-Note that ''​subdivisions''​ is an array and must be referenced by index (usually ''​0''​ or ''​1''​). +
- +
-The default environment variables vary by database and are designed to be as similar to the legacy GeoIP environment variables as possible. +
- +
-Our default list is: +
- +
-  "​GEOIP_COUNTRY_CODE",​ "/​country/​iso_code"​  +
-  "​GEOIP_CONTINENT_CODE",​ "/​continent/​code"​  +
-  "​GEOIP_REGION",​ "/​subdivisions/​0/​iso_code"​ +
-  "​GEOIP_METRO_CODE",​ "/​location/​metro_code"​ +
-  "​GEOIP_LATITUDE",​ "/​location/​latitude"​ +
-  "​GEOIP_LONGITUDE",​ "/​location/​longitude"​ +
-  "​GEOIP_POSTAL_CODE",​ "/​postal/​code"​ +
-  "​GEOIP_CITY",​ "/​city/​names/​en"​ +
- +
-You can customize the configuration to add the environment variables you want as describe above.  +
- +
-=== Example 1 === +
-Make sure the entry name is correct. +
- +
-You can add the following:  +
-  GEOIP_REGION_NAME CITY_DB/​subdivisions/​0/​names/​en +
-Please make sure the correct entry name is used. For example, the following is incorrect: ''​name''​ should be ''​names''​. +
-  GEOIP_REGION_NAME CITY_DB/​subdivisions/​0/​name/​en +
- +
-=== Example 2 ===  +
-You can customize a name as ''​MyTest_COUNTRY_CODE'',​ like so: +
-  MyTest_COUNTRY_CODE CITY_DB/​country/​iso_code +
-   +
-{{ :​litespeed_wiki:​cache:​common:​litespeed-geoip2-variables-e1.png?​800 |}} +
- +
-It will show on the ''​phpinfo.php''​ page as: +
-   ​_SERVER["​MyTest_COUNTRY_CODE"​] ​ US +
-''​US''​ will be replaced by the country code you are visiting from, such as ''​SG''​ or others. +
- +
-=== Example 3 === +
-You can customize a name as ''​MyTest2_COUNTRY_CODE''​ by using a defined COUNTRY DB name ''​COUNTRY_DB_20190402''​ with a country database. +
-  MyTest2_COUNTRY_CODE COUNTRY_DB_20190402/​country/​iso_code +
-{{ :​litespeed_wiki:​cache:​common:​litespeed-geoip2-variables-e2.png?​800 |}}   +
-It will show on the ''​phpinfo.php''​ page as: +
-  _SERVER["​MyTest2_COUNTRY_CODE"​] US +
- +
-=== Example 4 === +
- +
-You can customize all of the following:​ +
-  HTTP_GEOIP_CITY CITY_DB/​city/​names/​en +
-  HTTP_GEOIP_POSTAL_CODE CITY_DB/​postal/​code +
-  HTTP_GEOIP_CITY_CONTINENT_CODE CITY_DB/​continent/​code +
-  HTTP_GEOIP_CITY_COUNTRY_CODE CITY_DB/​country/​iso_code +
-  HTTP_GEOIP_CITY_COUNTRY_NAME CITY_DB/​country/​names/​en +
-  HTTP_GEOIP_REGION CITY_DB/​subdivisions/​0/​iso_code +
-  HTTP_GEOIP_LATITUDE CITY_DB/​location/​latitude +
-  HTTP_GEOIP_LONGITUDE CITY_DB/​location/​longitude +
- +
-{{ :​litespeed_wiki:​cache:​common:​litespeed-geoip2-variables-e4-1.png?​600 |}} +
- +
-It will show on the ''​phpinfo.php''​ page as: +
-  _SERVER["​HTTP_GEOIP_CITY"​] Montville +
-  _SERVER["​HTTP_GEOIP_POSTAL_CODE"​] 07045 +
-  _SERVER["​HTTP_GEOIP_CITY_CONTINENT_CODE"​] NA +
-  _SERVER["​HTTP_GEOIP_CITY_COUNTRY_CODE"​] US +
-  _SERVER["​HTTP_GEOIP_CITY_COUNTRY_NAME"​] United States +
-  _SERVER["​HTTP_GEOIP_REGION"​] NJ +
-  _SERVER["​HTTP_GEOIP_LATITUDE"​] 40.90490 +
-  _SERVER["​HTTP_GEOIP_LONGITUDE"​] -74.36460 +
- +
-{{ :​litespeed_wiki:​cache:​common:​litespeed-geoip2-variables-e4-2.png?​400 |}} +
- +
-==== MaxMind Legacy Database ==== +
- +
-=== Install MaxMind Legacy Database===  +
- +
-There are a few ways to install a MaxMind Legacy Database: through rpm packages install, or through direct download. +
-For example, for a CentOS user: +
- +
-Install GeoIP database. ​  +
-<​code>​yum install GeoIP</​code>​  +
- +
-Also check the installation location:  +
-<​code>​rpm -ql GeoIP</​code>​  +
- +
-It may return the database path as <​code>/​usr/​share/​GeoIP/​GeoIP.dat</​code>​  +
- +
-**NOTE**: On January 2, 2019, MaxMind discontinued the GeoLite Legacy databases. GeoLite Legacy databases are no longer available for download.  +
- +
-=== Setup Database File Path === +
-In LSWS WebAdmin, configure the database location: Navigate to **Configuration > Server > General > General settings** and set  **[[https://​www.litespeedtech.com/​docs/webserver/​config/​general#​geolocationDB|IP to GeoLocation DB]]** to the database path.  +
- +
-Alternatively,​ you can edit the LSWS configuration file directly:  +
-<​code>​ vi /​usr/​local/​lsws/​conf/​httpd_config.xml</​code>​  +
- +
-And add the following before ''<​tuning>'':<​code>​ +
- <​ipToGeo>​ +
-    <​geoipDB>​ +
-      <​geoipDBFile>/​usr/​share/​GeoIP/​GeoIP.dat</​geoipDBFile>​ +
-    </​geoipDB>​ +
- </​ipToGeo>​ +
-</​code>​ +
- +
-==== IP2Location Database ==== +
-You can download the IP2Location Database from [[https://​www.ip2location.com/​|their website]] and configure the **IP2Location DB File Path** in the **IP2Location DB** section. ​  +
- +
-===== Enable GeoIP in Apache Config or LSWS Native Setting== +
-==== cPanel/WHM ==== +
-  * If using cPanel/WHM navigate to **WHM > Service Configuration > Apache Configuration > Include Editor > Pre Main Include** Select ''​All Versions''​ in the dropdown box and then add the following to the text box:<​code>​ +
-<​IfModule LiteSpeed>​ +
-GeoIPEnable On +
-</​IfModule>​ +
-</​code>​ +
-==== LSWS (Native) ==== +
-  * If not using any control panel, navigate to **LSWS Web GUI > Configuration > Server > General**. Scroll to **Apache Style Configurations**,​ hit **edit** and add the following:<​code>​GeoIPEnable On</​code>​ +
- +
-===== Testing ===== +
-On cPanel/WHM, you can add the following rewrite rules to your ''​.htaccess''​ file to control the redirect. In native LSWS, you can create a "/"​ context or other proper context and place the rewrite rules there. +
- +
-==== Example 1: Block wp-login.php from certain countries ==== +
-For example, to block WordPress ''​wp-login.php''​ or ''​xmlrpc.php''​ access from countries not in (GB|DK|US|IN):​ +
- +
-<​code>​ +
-<​IfModule mod_geoip.c>​ +
-RewriteEngine on +
-RewriteCond %{ENV:​GEOIP_COUNTRY_CODE} !^(GB|DK|US|IN)$ +
-RewriteRule (wp-login|xmlrpc).php$ - [F,L] +
-</​IfModule>​ +
-</​code>​ +
- +
-When you access ''​yourdomain.com/​wp-login.php''​ from AU or any other non GB|DK|US|IN country, you should see a 403 error. +
- +
-==== Example 2: Redirecting a client based on country ==== +
- +
-This example shows you how to redirect a client based on the country code that GeoIP sets. +
- +
-  GeoIPEnable On +
-  # Redirect one country +
-  RewriteEngine on +
-  RewriteCond %{ENV:​GEOIP_COUNTRY_CODE} ^CA$ +
-  RewriteRule ^(.*)$ http://​www.canada.com$1 [R,L] +
-<​code>#​ Redirect multiple countries to a single page +
-  RewriteEngine on +
-  RewriteCond %{ENV:​GEOIP_COUNTRY_CODE} ^(CA|US|MX)$ +
-  RewriteRule ^(.*)$ http://​www.northamerica.com$1 [R,L] +
-</​code>​ +
-Refer to [[http://​dev.maxmind.com/geoip/legacy/​mod_geoip2/#​Redirecting_a_client_based_on_country|Maxmind]] for more rewrite examples. +
- +
-===== Troubleshooting ===== +
-==== ''​GeoIPDBFile''​ directive is for Apache, not LSWS ==== +
-In Apache, you can use ''​GeoIPDBFile''​ directive to define the database, however it cannot be used for LiteSpeed. You should follow the beginning steps in this wiki to define the database path from LSWS Web Admin Console or the LSWS configuration file directly.  +
- +
-==== GeoIP Rewrite Rules Infinite Loop ==== +
- +
-A user would like to set up GeoIP rules to direct traffic to the main domain'​s subfolder based on IP. The following rules have been set in .htaccess, however, it seems to cause a redirect loop. +
-  RewriteEngine on +
-  RewriteCond %{ENV:​GEOIP_COUNTRY_CODE} ^US$ +
-  RewriteRule ^(.*)$ https://​www.example.com/​us/​$1 [R,L] +
-  RewriteCond %{ENV:​GEOIP_COUNTRY_CODE} ^SG$ +
-  RewriteRule ^(.*)$ https://​www.example.com/​sg/​$1 [R,L] +
-  RewriteCond %{ENV:​GEOIP_COUNTRY_CODE} ^MY$ +
-  RewriteRule ^(.*)$ https://​www.example.com/​my/​$1 [R,L] +
- +
-The redirect loop actually indicates the the GeoIP module is working.  +
- +
-The redirect error happens because the rules are evaluated again //after// the redirect is performed. So, if you access ''/'',​ and it gets redirected to e.g. ''/​us'',​ then on ''/​us'',​ it will be asked to redirect //again// to ''/​us''​ - and you end up with a loop. The fix is to add an additional condition to prevent this, such as ''​RewriteCond %{REQUEST_URI} !^/​us[NA]''​. This way, you only redirect to ''/​us''​ if the country code from GeoIP matches US //and// the request URI doesn'​t already start with ''/​us''​. +
- +
-The final rules should be: +
- +
-  RewriteEngine on +
-  RewriteCond %{REQUEST_URI} !^/us [NC] +
-  RewriteCond %{ENV:​GEOIP_COUNTRY_CODE} ^US$ +
-  RewriteRule ^(.*)$ https://​www.example.com/​us/​$1 [R,L] +
-  RewriteCond %{REQUEST_URI} !^/sg [NC] +
-  RewriteCond %{ENV:​GEOIP_COUNTRY_CODE} ^SG$ +
-  RewriteRule ^(.*)$ https://​www.example.com/​sg/​$1 [R,L] +
-  RewriteCond %{REQUEST_URI} !^/my [NC] +
-  RewriteCond %{ENV:​GEOIP_COUNTRY_CODE} ^MY$ +
-  RewriteRule ^(.*)$ https://​www.example.com/​my/​$1 [R,L] +
-   +
-==== Be more specific than "GeoIP not working"​==== +
-Quite often we receive a report claiming that "GeoIP is not working""​. This is too vague. Is the GeoIP module note working? Or are the GeoIP rewrite rules not working as expected? It's best to clarify before logging any ticket. +
- +
-Whether the GeoIP module is working can be easily verified through the following (change the country code ''​US''​ to your country code accordingly):​ +
- +
-<​code>​ +
-  <​IfModule mod_geoip.c>​ +
-  RewriteEngine on +
-  RewriteCond %{ENV:​GEOIP_COUNTRY_CODE} ^US$ +
-  RewriteRule ^(.*)$ - [F,L] +
-  </​IfModule>​ +
-</​code>​ +
-   +
-If it returns ''​403 forbidden'',​ then it means the GeoIP module is actually working.  +
-   +
-GeoIP rewrite rules that do not work as expected may be more complicated. You will need to check the rules to look for issues such as a redirect loop. When needed, you can log a ticket with us. Let us know the rules set is not working as expected, and provide a more detailed test example for us to take a further look.  +
- +
-==== IP Not Blocked Due to Out-of-date Database ==== +
-A user set up the following at ''/​etc/​apache2/​conf.d/​userdata/​geoip.conf'':​  +
- +
-  <​IfModule mod_geoip.c>​ +
-  RewriteEngine on +
-  RewriteCond %{ENV:​GEOIP_COUNTRY_CODE} !^(GB|DK|US|IN)$ +
-  RewriteRule (wp-login|xmlrpc)\.php$ - [F,L] +
-  </​IfModule>​ +
- +
-Testing from an IP in NG/​Nigeria/​- ''​x.x.x.x'',​ it should be blocked but it is not. +
- +
-Further analysis shows the above IP belongs to North Carolina, US in the downloaded MaxMind database. It looks like the record on that old database is incorrrect. If the database is not kept up to date, it will result in incorrect information. +
- +
-You can keep the database up to date from time to time manually by doing a direct download, or you can use the [[https://​dev.maxmind.com/​geoip/​geoipupdate/​|geoipupdate tool]], so your system automatically keeps the file up to date whenever MaxMind publishes an update.+
  • Admin
  • Last modified: 2020/11/14 15:24
  • by Lisa Clarke