Installation

Quick Start

After installing the package properly:

1. install the database (using the database dashboard page)
2. set-up a rule for the redirection
3. Add the MaxMind IP-GeoLoc attribute, or the block to a page you want to activate the redirection

More details after:

Package installation

The recommended method to install MaxMind IP-GeoLoc, is simply using your target website marketplace page. However, if you wish not to use concrete5 internal feature, you can follow the next instructions:

1. Download the zip archive
2. Uncompress the zip archive into your packages/ directory
3. Ensure the directory packages/gnt_maxmind/data is writable by the server
4. Visit your Add Functionality page (located at http://yoursite.com/index.php/dashboard/extend/install )
5. Click on the MaxMind IP-GeoLoc Install button
6. Follow the onscreen instructions

During the installation, you will be prompted a few options first:

Before you install the addon, you can already set a few settings parameter:

• Database storage: the location used to store Maxmind database
• Uninstallation behavior: delete databases on uninstall or not

Those settings will be freely modifiable after installation from the Settings page.

At the end of the installation, the addon will check if any database is provided, and will suggest you to go the database page if you don't have any installed.

After installing MaxMind IP-GeoLoc (either through downloading or preferably directly through your concrete5 website interface), you will be provided with the Maxmind GeoIP Redirect and Message block and the Maxmind IP GeoLoc Redirect page attribute.

MaxMind IP-GeoLoc also installs a few dashboard pages under its own Maxmind GeoIP sub menu.

Upload Maxmind GeoLite database

MaxMind IP-GeoLoc needs the Maxmind GeoLite2 or GeoIP2 database installed on the server. You can install this in different ways: different methods from the Dashboard>Maxmind GeoIP>Databases Page:

Following your initial installation, no database will be installed (this addon does not ship a MaxMind GeoLite2 database), so the list of database will be empty. In order to use the IP geolocalisation features, you will need to download the MaxMind GeoLite2 database using one of the following method:

MaxMind IP-GeoLoc can automatically download the latest version of MaxMind GeoLite database. To do this, go to the Dashboard>Maxmind GeoIP>Databases page, and then click on the Download Latest MaxMind GeoLite Free button. Maxmind GeoIP will then automatically download and install the latest MaxMind GeoLite database.

You can also download the MaxMind GeoLite database from the automated Jobs page of your website :

If you can't use the automatic downloader for some reason, you can still upload the Maxmind GeoLite2 database directly through the dashboald page. First, go to the Dashboard>Maxmind GeoIP>Databases page, and use the provided upload form.

In case everything fails, you can still upload the MaxMind GeoLite2 City database or the commercial version of GeoIP database into the packages/gnt_maxmind/data directory. The uploaded file must be named according to the following scheme : YYYYMMDD-HHMMSS-maxmind-geoip2-city.mmdb for example 20131205-230640-maxmind-geoip2-city.mmdb.

You can download the free version of MaxMind GeoLite2 database here : http://dev.maxmind.com/geoip/geoip2/geolite2/.

You will need to download the "GeoLite2 City" archive and uncompress it first before you upload it to your server. To find the correct storage path, go to the Maxmind Settings page:

Average Users

Adding a Customized Message

To add a customized message into a page, add an instance of the Maxmind GeoIP Redirect and Message block on that page, and fill in the message in the add/edit interface.

The Known location message will be outputted for visitors whose IP can be matched to a country. In this message the following patterns will be replaced :

%COUNTRY% :the country name (in the current locale)%COUNTRY_CODE%:the country ISO code%COUNTRY_XX% :the country name in the XX locale, (eg: en for English)%STATE_XX% :the state name%STATE_CODE% :the state ISO code (eg: WA or 75 for Paris-France)%STATE_XX% :the state name in the XX locale, (eg: Washington State)%CITY% :the city name (in the current locale)%CITY_XX% :the city name in the XX locale, (eg: 'en' for English)%IP% :The visitor IP address

for instance the following message :

Hello visitor from %COUNTRY%, did you know in Chinese your country name is written %COUNTRY_zh-CN%?

will be seen as

Hello visitor from United States, did you know in Chinese your country name is written 美国?

by a visitor from the US, and :

Hello visitor from France, did you know in Chinese your country name is written 法国?

by a visitor from France.

The Unknown location message will be outputted for visitors whose IP can not be matched to a country. In this message you can use the same patterns, as the preceding, but for obvious reasons only the %IP% pattern will be replaced by by a meaningful value. All other patterns will be replaced by an empty string.

Lookup an IP

If you want to lookup a specific IP address, you can go to the Dashboard>Maxmind GeoIP>IP GeoLoc Lookup page :

By default the IP address filled in the IP text field is your public IP address (more precisely your IP address visible from the server). The preceding screenshot shows a randomly picked IP address.

Several information will be printed

• Country: including all localized names available
• State (Province): including all localized names available
• City: including all localized names available
• Latitude/Longitude: including a google map display for location

Creating Redirection Rules

One of the most powerful feature this addon will give you is the ability to create various type of redirections for visitors based on their country/city or simply their IP address. To do so, you must process as follow:

1. Create a redirection rule set (in Dashboard>>Maxmind GeoIP>Redirection)
2. Add redirection rules to it
3. Save the redirection rule set (and activate it)
4. Use the redirection rule set from a message block or from a page attribute

Lets detail each step:

To create a new redirection rule set (or to modify an existing ruleset) go to the Dashboard>>Maxmind GeoIP>Redirection page.

From that page, click on the Create New Rule Set button.

Each redirection rule set contains two parts :

• The General options (applicable to each rules)
• The redirection rules themselves

The General options of a rule set will let you enable or disable the rule set, set a specific name for this rule set (used to select the rule set from the message block or from the page attribute), and set the default message used in case of suggested redirection.

The message entered can contain the same patterns as the block message:

• %COUNTRY% the country name (in the current locale)
• %COUNTRY_CODE% the country ISO code
• %COUNTRY_XX% the country name in the XX locale, (eg: 'en' for English)
• %CITY% the city name (in the current locale)
• %CITY_XX% the city name in the XX locale, (eg: 'en' for English)
• %IP% The visitor IP address

as well as the following rule specific pattern:

• %TARGET_URL% the redirection target URL
• %TARGET_A_OPEN% the redirection target a open tag (to create a link)
• %TARGET_A_CLOSE% the redirection target a close tag (to create a link)

the %TARGET_A_OPEN% and %TARGET_A_CLOSE% can be used to create a link to the redirection target inside a redirection message.

By default, the redirection rule set is empty :

Click on the Add a redirect Rule to create a new rule.

You can create multiple rules. Rules are applied from top to bottom. Rules can be be reordered by dragging a rule.

Each rule can be activated or deactivated individually using the activation switch. When a rule is activated (through the activation switch), a rule need to match all the conditions set in the Matching section on the rule.

Currently, 3 match types are available :

• Match the visitor Country Code (no match, equal/in, not equal/not in, or using a regexp)
• Match the visitor State Code (no match, equal/in, not equal/not in, or using a regexp)
• Match the visitor City Name (no match, equal/in, not equal/not in, or using a regexp)
• Match the visitor IP address (no match, equal/in, not equal/not in, or using a regexp)

Each matching (except no match) accepts a parameter against the visitor corresponding data (country/city/state/ip) is checked. The parameter input becomes visible when the corresponding match type is selected. The input accepts the following format:

• equal/in or not equal:Simple text:the data will be checked for equality (ignoring case)Comma separated list:check if data is the list, ex: WA,NY,NJRange:check if the data is between the boundaries of the range, ex: AA-EE, or 192.168.0.1-192.168.0.10 (in case of IPs, the IP is treated decoded, in case of a text, the compared in aIP CIDR network:only available for IP matching, in the format of IP/bits notation, ex: 192.168.0.1/24, please see the Wikipedia Classless Inter-Domain Routing page for more information.
• regex: PRCE compatible regular expression, please refer to the PRCE Patterns manual for more information.

If your application needs a specific matching, or if you are unsure if those matching types will, let you achieve your goals, please contact us.

If a rule is activated, the redirection is then executed (the following rules are then ignored). If a rule is not activated, MaxMind IP-GeoLoc will then check the next rule in the list.

Each rule have a Redirect type, and a target. Redirect types can be one of the following choices :

• No redirection
• Forced HTTP Redirection
• Suggest Redirect

The Suggest Redirect target type will display a message on the page (this message can be positioned and configured, see bellow). The message shown is either the rule set global message or the specific message of the rule (if selected). This type of redirection will let you show the message for a specific amount of time (timeout). The user will be redirected to the target at the end of the timeout if the hide on timeout is not selected.

The redirection will redirect to a target. Currently the available targets include :

• No target (therefore, no redirection)
• To a specific page of the website
• To an external url

Finally, each rule can be configured through the following options:

• exclude users  if enabled, this rule will not affect logged in users
• exclude admins  if enabled, this rule will not affect logged in admins
• hide on timeout  if enabled, do not redirect the user, just hide the message
• modal message  if enabled, make the message modal (the user must click on it)
• type  message type (alert, info, success, error)
• position  position of the message on the screen (top/bottom left/middle/right)

To apply a redirection rule set to a page, the easiest way is to add the Maxmind IP GeoLoc Redirectattribute to the selected page :

The page attribute can be activated for the page, or for the page and all its sub-pages (child pages). Beware, activating the attribute on the home page will activate it on all pages on the website (since the home page is the parent of all pages.

Using this method, you can easily create page trees accessible by only a specific IP/country/city etc…

You can also use the Maxmind GeoIP Redirect and Message block. Using block to perform redirection will also allow you to perform that redirection on multiple page (for instance through Stacks).

Advanced Users

Globally Deactivating all Redirect Rules

In case you want to disable all redirection rules temporary, you can do so by disabling the redirection in the Dashboard>Maxmind GeoIP>Settings page :

Schedule automatic db updates

MaxMind IP-GeoLoc comes with 2 jobs :

• Download Maxmind db which will automatically download the latest Maxmind GeoLite 2
• Delete unused Maxmind dbs which will delete all databases but the currently selected

It is advised to update at least once a month the database either using the Databases page or by running the Download Maxmind db job. If you automate the download job, then you may want to automate the delete job as well so that your data folder does not grow too big.

Debugging rules

Sometimes you need to trace a little how rules are really applied and what happens for what IP. MaxMind IP-GeoLoc provides several tools to help you:

You can activate debug traces in different places:

• Globally, directly in the rule set definition, by activating the Activate debug log for this ruleset checkbox
• Locally on each page, by activating the Activate debug log checkbox in the attribute

When logs are activated on a specific rule (and the page where the rule had been placed is viewed by any visitors), a complete log of actions is added to concrete5 logs, accessible at http://yoursite.com/index.php/dashboard/reports/logs.

If you want to check what would be displayed for a specific IP address, and know which field are avaiable, use the lookup page and enter the address in it.

In order to know exactly where a specific user would be taken, you can simulate that visitor IP. You can either set a fixed IP for all visitors in the Settings page, or set a simulated IP by adding a parameter to the URL query. The name of the variable is customizable in the Settings page.

In the settings page, simulation can be set to several option, using the Allow IP simulation (debug), select box:

• No simulation, use REMOTE_IP (default), the actual visitor IP will be used
• Take IP from a GET VARIABLE, lets you define a variable to read the IP (default MAXMIND_IP
• Fixed IP for all visitors lets you enter the IP all visitors will be assigned (simulated)

For example, if you selected the GET VARIABLE method, and used MAXMIND_IP, to simulate a visitor coming from the IP 1.2.3.4, you could visit the url: http://yoursite.com/path/to/my/page?MAXMIND_IP=1.2.3.4.

Managing database path and uninstall behavior

By default MaxMind IP-GeoLoc stores the databases files under the application/files/gnt_maxmind directory. This directory will be created if non existing. That way, updates won't delete downloaded databases. If you wish to change this, go to the Settings page:

Activate the checkbox left to the storage path to access to the move location options:

Enter a new location in the text field, the new directory must be writable if existing, or its parent must be existing and writable if not. If the target directory does not exist, MaxMind IP-GeoLoc will attempt to create it. Options are given to know what to do about existing databases (either copy them, move them, or leave them).

The default behavior upon un-installation is to leave the databases where they are. If you wish to remove the databases upon uninstallation, change the corresponding setting in the Settings page.

For Developers

Installing new message themes/layouts

MaxMind IP-GeoLoc uses noty js to create the messages shown on suggested redirections. To install other themes for your messages, you can install those themes in one of the following locations:

• js/3rdparty/noty/themes
• gnt_maxmind/js/3rdparty/noty/themes
• application/js/3rdparty/noty/themes
• application/gnt_maxmind/js/3rdparty/noty/themes

layouts can be installed in the following locations:

• js/3rdparty/noty/layouts
• gnt_maxmind/js/3rdparty/noty/layouts
• application/js/3rdparty/noty/layouts
• application/gnt_maxmind/js/3rdparty/noty/layouts

Additionally, one can package new themes or layouts by placing them into a gnt_maxmind/js/3rdparty/noty/themes  or gnt_maxmind/js/3rdparty/noty/layouts directory respectively.

Your themes or layout must be named after the name of your js file suffixed with "Theme". For instance if your theme is named beautiful.js then your theme must be named beautifulTheme.

Incidentally, you can overwrite the default theme by copying the default.js file shipped with the package into your site override and respectively for layouts).

You can also create or redefine the provided layouts by adding a file (or copying it) in your site override application/js/3rdparty/noty/layouts directory (or any place listed above).

More information on noty can be found here http://needim.github.io/noty.

Speed up with Maxmind C extension

If you need better lookup performances, Maxmind built a C extension that can be installed to speed up the IP lookup process. To install the extension, please follow their instructions here and there.

Although this addon had been tested with and without the maxminddb C extension installed, the author does not provide free installation or support service for this C extension. If you need support concerning this point, please contact us for a quotation.

Support

If you need any assistance regarding this addon, please use the support forum directly.

In case you need a new feature, or anything else, feel free to contact me through concrete5 PM system, or contact us  directly.