GeoBlocker

Joomla Plugin + Unlimited GeoIP Data Look-ups

Documentation Frequently Asked Questions Many web developers are looking for an easy way to block certain countries, states / provinces, regions, zip codes / postal codes, and/or area codes from accessing their Joomla website or specific pages / areas on their website (such as login or registration) while still allowing IP address / IP range exclusions (such as search engine bots). With our Joomla plugin, you are now able to block access to your website based on Geo-location information. Simply install the plugin, enter the areas you would like to block, and you're done. Blocked visitors will either see a basic textual block message or they will be redirected to another URL; both of which are configured in the settings. On the other hand, if you have a list of only approved countries, states / provinces, regions, zip codes / postal codes, and/or area codes, you may enter those to specifically allow them and block all other areas (new in version 1.1). Features: Apply to the entire website or to a specified subset of pages (new in version 1.4) Block website access by country Block website access by US States or provinces Block website access by Zip Codes or Postal Code (including the ability to enter an entire range) Block website access by Telephone Area Codes (including the ability to enter an entire range) Alternatively, allow only a list of pre-approved areas and block all others Exclude IP addresses or range of IP addresses from being blocked using comma separated values, dash separated ranges, CIDR ranges, and wildcards (new in version 1.2) Check visitor's IP address once every 15 minutes instead on every page load to improve speed and lessen server loads (new in version 1.1) Display blocked message to website visitor or redirect blocked website visitor to another internal or external URL. NOTE: If you've setup the plugin to block the 'Entire Joomla Website' and you want to redirect to an internal URL, make sure you exclude this particular URL from blocking by placing it in the 'Pages to Exclude Restrictions' text box. (new in version 1.6) External server look-ups mean you get the most up-to-date information without any manual updating or subscription fees By default, the plugin uses an external server to look-up geographic IP address location data which is updated once a month. The database is over 99.5% accurate on a country level and 79% accurate on a city level for the US within a 25 mile radius. This requires that your web server supports cURL on port 80 (most web servers do). The plugin also gives you the option of manually downloading the geographic IP location database periodically and uploading to your own server. This allows you to use a more accurate version of the GeoIP database. However, the external server look-up is very fast, very accurate, and is adequate for most users. Exclude specific Joomla user group(s) from being blocked. 'User Groups to Exclude Restrictions': If the visitor is authenticated and they are part of the selected user group(s), then no blocking will be performed for the visitor. This is useful if you want to allow registered users to browse the site even if they are in a blocked area. (NOTE: You will need to change the plugin scope and exclude the login page so the user can access the login URL.) (new in version 1.9.3; Joomla v1.6 and later) Works with CloudFlare and Rackspace Cloud Sites Compatibility: The plugin has been programmed and tested with Joomla 1.5, 1.6, 1.7, 2.5, 3.1, 3.2, 3.3, and 3.4. Feel free to test in other versions of Joomla and report back to us so we can update our information. Feel free to test in other versions of Joomla and report back to us so we can update our information. If you have problems with the plugin in other versions of Joomla and would like us to update the plugin for your version of Joomla, contact us.   Database Cost: Optional access to the external server which looks up the geographic IP address location data requires a monthly payment of $5 per month (or $48 per year) per domain to cover bandwidth and server resources. If you choose to run the plugin using the local server option, you will need to obtain a copy of the GeoIP database (paid and free versions available) from MaxMind and periodically manually update it yourself. Download: Sign-up today to gain access to the plugin (v1.9.9 released June 2017) and begin your subscription to the external server data feed. Also listed on The Joomla! Extensions Directory (JED).

Query IP Address Data:

*For testing purposes only!
TIP: When testing parameters on your Joomla website, clear your browser's cookies after each configuration change before refreshing the frontend of your website.

Change Log:

2012/01/03 - v1.0. Initial Release.
2012/02/05 - v1.1. Modified plugin to only check visitor's IP address once every 15 minutes instead on every page load to improve speed and lessen server loads. Also added option to allow OR block specific codes.
2012/02/06 - v1.2. Added ability to exclude IP addresses or IP address ranges from being checked.
2012/02/07 - v1.3. Bug fixes. Also released Joomla 1.6, 1.7, and 2.5 compatible version.
2013/01/01 - v1.4. Bug fixes. Added ability to block or allow access to certain URLs rather than the entire website.
2013/02/20 - v1.5. Bug fix related to the local server option when used with a GeoIP Country or GeoIP Region database file.
2013/03/10 - v1.6. Feature enhancement; added 'Pages to Exclude Restrictions' text box which can be used to exclude blocking on certain pages when the plug-in scope is set to 'Apply to Entire Joomla Website'.
2013/03/13 - v1.7. Bug fixes. Updated to allow for the integration with CloudFlare.
2013/05/04 - v1.8. Verified compatibility with Joomla 3.1.1. Updated external server feed URL. Bug fixes related to timeouts and subscription expired error messages when plugin is unable to connect to external server feed URL.
2013/06/25 - v1.9. Added ability for API subscribed users to manually setup CRON job to periodically automatically download database locally. CRON job should run the plugins/system/GeoBlocker/cron.php file and plug-in parameters should be set as follows: Data Location: Local Server; Local Server – File Name: GeoIPCity.dat; Local Server – File Type: GeoIP City DB.
2013/11/05 - v1.9.1. Bug fixes to prevent warning messages from being displayed when PHP server configuration is set to verbose for both errors and warnings.
2013/11/29 - v1.9.2. Bug fixes related to Joomla 3.x and the functionality of applying the plugin to specific pages and excluding the plugin from specific pages.
2015/05/23 - v1.9.3. Added feature to exclude specific Joomla user group(s) from being blocked.
2015/07/22 - v1.9.4. Updated plugin to work with Rackspace Cloud Sites (they use a load balancer that does not pass the visitor IP via standard HTTP headers).
2015/08/06 - v1.9.5. Bug fix that caused PHP Warning message to be displayed on some websites when the 'User Groups to Exclude Restrictions' field was left blank.
2015/09/15 - v1.9.6. Bug fix that may cause 'Undefined variable' PHP notice message when visitor's IP address does not have geolocation data associated with it.
2015/09/22 - v1.9.7. Bug fix that may cause 'Trying to get property of non-object' PHP notice message in the event of connectivity issues to the external server data feed.
2016/04/01 - v1.9.8. Bug fix that may cause 'Strict Standards: Only variables should be assigned by reference' PHP notice message when running PHP version 5 or later with Strict Mode enabled.
2017/06/01 - v1.9.9. Bug fix that may cause PHP Notice to appear in rare cases that PHP is configured to display Notice messages.

1) How do I configure the GeoBlocker plugin to block or allow specific areas?

It is very easy to configure the plugin. First, you need to decide how you'd like the plugin to operate. Would you like it to block visitors from specific areas or would you rather have a pre-approved / whitelist of only the areas that you'd like to allow?

For example, Company A sells a product and due to trademark restrictions, they are not allowed to advertise or sell this product in the United States. In this instance, the plugin would be configured to 'Block all the following codes' and the country 'US' would be typed in the 'Country Codes' textbox.

Another example, Company B located in the United States only sells products to local residents within the United States and Canada and they are not interested in allowing other visitors outside of the United States and Canada to view their website. In this instance, the plugin would be configured to 'Allow only the following codes' and the counties 'US,CA' would be typed in the 'Country Codes' textbox.

To assist you in entering the correct country codes, we have also published a list of ISO 3166-2 country codes.

2) Can I apply the rules to specific pages on the website rather than the entire website?

The first drop down box allows you to select 'Apply to Entire Joomla Website' or 'Apply to Specific Pages Only'. For a detailed explanation of both, keep reading.

If you choose to apply the rules to the entire Joomla website, then you have the option (it is not required) to fill in a list of pages that you'd like to exclude. These pages should be listed in the 'Pages to Exclude Restrictions' textbox and if you enter multiple pages, you should separate them with a comma. The format should include all characters that appear in the browser's address bar AFTER the domain name. For example, to block http://www.example.com/products/widget you should enter this: /products/widget.

If you choose to apply the rules to specific pages, then you will also need to fill in the 'Pages to Apply Restrictions' textbox and if you enter multiple pages, you should separate them with a comma. The format should include all characters that appear in the browser's address bar AFTER the domain name. For example, to block http://www.example.com/products/widget you should enter this: /products/widget.

3) How do I exclude Joomla user groups from being blocked?

The input box labeled '' allows you to exclude Joomla user groups from being blocked. Listed below are some example scenarios where this feature might be useful:

Scenario A: Only allow registered users to use the Joomla website: Sometimes is may be useful to only allow registered users the ability to access the website. Here is how you'd configure the plugin for this:

Scenario B: Allow white-listed locations to access the site and force all others to register/sign-in: Since no geolocation database is 100% accurate (due to the constant assignment and reassignment of IP addresses by ARIN), some web developers would prefer to only allow visitors access to the site which are verified to be within the accepted areas. However, to take into account the small percentage of users who might arrive with an IP address does not have geolocation information associated with it, the web developer would like to ask those visitors to register / sign-in first (the message instructing the user to register/sign-in could be in a module which is assigned to the sign-in page menu item). Here is how you'd configure the plugin for this:

4) How do I exclude an IP address or a range of IP addresses from being blocked?

The textbox labeled 'Excluded IP addresses' allows you to exclude single IP addresses or ranges of IP addresses. This may be useful to exclude bots/spiders such as Google or to exclude the developer's IP address from being blocked (when his/her area is blocked based on the plugin parameters). To enter multiple values, separate each IP address or range with a comma. You may enter the IP address range using any of the following formats:

Specific Range: 64.223.160.0-64.223.192.255

CIDR Notation: 66.249.64.0/24

Wildcards: 72.14.192.*

5) What are the two 'Data Location' options?

The GeoBlocker plugin allows you to pull the database from either a local file or the external feed. Most users will select the 'External Feed' option, as this provides a "set it and forget" functionality. With the External Feed, the web developer does not need to manually update the database and you're guaranteed to always be using the most up-to-date geographic information. However, the plugin also allows the database to reside locally. This may be useful on servers which do not reside on the internet and do not have the ability to contact the external feed via the internet. Here is how you'd configure the plugin for both data locations:

External Feed: This is the default option. When you purchased the plugin, you were given the option of subscribing to the 'IP Look-ups Subscription'. If you selected this, then there is nothing further you need to do. Just configure and enable the plug-in and you're done! If you declined this option but later changed your mind and would like to use it, you may subscribe to geographic IP lookup subscription by clicking the green button to the right.

Local Server: If you prefer to manually download and install the database to your server (and manually update it as updates are released), then you may choose this option and specify the database file name AND the database file type in two parameters following. The database file should be uploaded to: /plugins/system/GeoBlocker/lib/

NOTE: If you have the need to use the Local Server option due to incompatibilities with your web server and the External Feed, we do offer a third option which will automatically download the database to your local server. Please contact us regarding this option, as it take some special configuration on our end to enable this.

6) What is the difference between the two 'Message or Redirect' options?

When GeoBlocker determines a visitor should be blocked, you may display a simple message with black text on a white background (such as 'Sorry, access to our website has been blocked for your region.') OR you may redirect the visitor to another URL (such as http://www.example.com). NOTE: If you redirect the visitor to another URL on the same website, you must exclude that page from GeoBlocker (refer to item #2 above for more details), otherwise the user will enter an infinite redirect loop.