A few weeks ago, a guide explaining how to install AWStats on FreeBSD was released here in adminbyaccident.com. On that piece a basic install of AWStats is shown, however, a nice and important functionality of AWStats is missing. Knowing the location of visitors is a matter of interest, for the sake of it or because you need to know who prefers whatever you’re selling on your site for example. To accomplish that enabling geolocation in AWStats is the way to go.
This same setup can be built in DigitalOcean. Use this link to get 100 $ credit at DigitalOcean and support Adminbyaccident.com hosting costs.
Pre-requisites
A FreeBSD box with AWStats installed on it. You can use this tutorial from this very site.
Step1. Installing Geolocation databases
MaxMind is a company that sells databases containing information relative to IPs and how those are related to specific geographical locations. Countries, cities and even ASN (autonomous systems). To get that information one must pay a fee for accurate, very reliable data. However, there’s still a free edition anyone can download with a registration to their site. Those free access databases are called GeoLite2. Because of this the very first thing we need to do is to register to MaxMind and get a user ID as well as license number.
Once we’ve acquired those two elements, we can start with the installation of the software to pull those databases and configuring the system and AWStats to make use of them.
The first piece of software to install is the ‘geoipupdate’ package.
root@awstats:~ # pkg install geoipupdate-4.7.1
Updating FreeBSD repository catalogue...
FreeBSD repository is up to date.
All repositories are up to date.
The following 1 package(s) will be affected (of 0 checked):
New packages to be INSTALLED:
geoipupdate: 4.7.1
Number of packages to be installed: 1
The process will require 6 MiB more space.
3 MiB to be downloaded.
Proceed with this action? [y/N]: y
[awstats] [1/1] Fetching geoipupdate-4.7.1.txz: 100% 3 MiB 1.6MB/s 00:02
Checking integrity... done (0 conflicting)
[awstats] [1/1] Installing geoipupdate-4.7.1...
[awstats] [1/1] Extracting geoipupdate-4.7.1: 100%
=====
Message from geoipupdate-4.7.1:
--
You must register for a (free) MaxMind account
to download the free GeoIP2 databases.
Register for an account: https://www.maxmind.com/en/geolite2/signup
Get a license key: https://www.maxmind.com/en/accounts/155743/license-key
Place the generated account key and license key
into /usr/local/share/geoipupdate/GeoIP.conf
root@awstats:~ #
The exact location of this configuration file for the geolocation in AWStats to work is sitting in the following path:
root@awstats:~ # ls -al /usr/local/etc/GeoIP.conf
-rw-r--r-- 1 root wheel 1817 28 juny 21:53 /usr/local/etc/GeoIP.conf
root@awstats:~ #
Once this geoipupdate software is installed we need to configure it so we can use or user ID and license to pull those databases we want to use for AWStats.
root@awstats:~ # grep -n 'AccountID' /usr/local/etc/GeoIP.conf
8:AccountID YOUR_ACCOUNT_ID_HERE
root@awstats:~ #
As it can be seen the Account ID sits on line 8 in the GeoIP.conf file and just below of it the license entry.
root@awstats:~ # grep -n 'LicenseKey' /usr/local/etc/GeoIP.conf
9:LicenseKey YOUR_LICENSE_KEY_HERE
root@awstats:~ #
Grab your favorite editor and edit both lines, 8 and 9, and replace the capital string with the real information relative to your MaxMind’s account.
Once that’s done it’s time to pull the databases from MaxMind. We’ll do this with the following command.
root@awstats:~ # /usr/local/bin/geoipupdate
root@awstats:~ #
Where have they gone? Down to /usr/local/share/GeoIP.
root@awstats:/usr/local/share/GeoIP # ll
total 48118
-rw------- 1 root wheel 0 28 juny 21:57 .geoipupdate.lock
-rw-r--r-- 1 root wheel 64454306 28 juny 21:58 GeoLite2-City.mmdb
-rw-r--r-- 1 root wheel 4206286 28 juny 21:58 GeoLite2-Country.mmdb
root@awstats:/usr/local/share/GeoIP #
With the databases in place it’s time to move on to the next step and install the necessary dependencies to enable geolocation in AWStats.
Step 2. Install the Perl packages for AWStats understand GeoIP
For AWStats to interact with the databases we’ve just pulled from MaxMind we need to install some Perl software. If we install the following package, all the dependencies will also be downloaded.
root@awstats:/usr/local/share/GeoIP # pkg install p5-GeoIP2-2.006002
Updating FreeBSD repository catalogue...
FreeBSD repository is up to date.
All repositories are up to date.
The following 81 package(s) will be affected (of 0 checked):
……..
Proceed with this action? [y/N]: y
……..
root@awstats:/usr/local/share/GeoIP #
Disclaimer. MaxMind doesn’t seem to be maintaining this package since middle 2019. More information on this link. https://metacpan.org/dist/GeoIP2
Don’t feel bad, many Linux distributions are still relying on a package that the producer has deprecated for some time. Evidences:
https://pkgs.org/search/?q=Geo-IP
https://metacpan.org/dist/Geo-IP-PurePerl
However, this is, with these Perl dependencies installed we now have to configure AWStats to make use of the downloaded databases.
Step 3. Configure AWStats geolocation plugin
In order to enable geolocation in AWStats we need to configure the main configuration file for the site we are monitoring. The steps are simple.
Enable the correct plugin for geolocation.
Point the database location.
To enable the plugin let’s look for its location in the file.
root@awstats:~ # grep -n 'geo' /usr/local/etc/awstats/awstats.awstatsdemo.com.conf
187:# it is highly recommanded to enable the plugin 'geoip', 'geoipfree', or 'geoip2'
1454:#LoadPlugin="geoipfree"
1460:# PARAMETERS: [GEOIP_STANDARD | GEOIP_MEMORY_CACHE] [/pathto/geoip.dat[+/pathto/override.txt]]
1463:# Replace spaces in the path of geoip data file with string "%20".
1465:#LoadPlugin="geoip GEOIP_STANDARD /pathto/GeoIP.dat"
1473:# Replace spaces in the path of geoip data file with string "%20".
1475:#LoadPlugin="geoip2_country /pathto/GeoLite2-Country.mmdb"
1479:# PARAMETERS: [GEOIP_STANDARD | GEOIP_MEMORY_CACHE] [/pathto/geoipv6.dat[+/pathto/override.txt]]
1483:# Replace spaces in the path of geoip data file with string "%20".
1485:#LoadPlugin="geoip6 GEOIP_STANDARD /pathto/GeoIPv6.dat"
1492:# Replace spaces in the path of geoip data file with string "%20".
1494:#LoadPlugin="geoip_city_maxmind GEOIP_STANDARD /pathto/GeoIPCity.dat"
1501:# Replace spaces in the path of geoip data file with string "%20".
1503:#LoadPlugin="geoip2_city /pathto/GeoLite2-City.mmdb"
1504:#LoadPlugin="geoip2_city /usr/local/share/GeoIP/GeoLite2-City.mmdb"
1513:# Replace spaces in the path of geoip data file with string "%20".
1515:#LoadPlugin="geoip_asn_maxmind GEOIP_STANDARD /usr/local/geoip.dat+http://enc.com.au/itools/autnum.php?asn="
1522:# Replace spaces in the path of geoip data file with string "%20".
1524:#LoadPlugin="geoip_region_maxmind GEOIP_STANDARD /pathto/GeoIPRegion.dat"
1530:# Replace spaces in the path of geoip data file with string "%20".
1532:#LoadPlugin="geoip_isp_maxmind GEOIP_STANDARD /pathto/GeoIPISP.dat"
1538:# Replace spaces in the path of geoip data file with string "%20".
1540:#LoadPlugin="geoip_org_maxmind GEOIP_STANDARD /pathto/GeoIPOrg.dat"
root@awstats:~ #
There are a few geolocation plugins that can be enabled. In my case I’m interested to know about the country of origin of my visitors. And I’m using the GeoLite2 free database. So that already tells me I should enable the plugin ‘geoip2_country’ sitting on the line 1475.
With your favorite editor edit such line and remove the ‘#’ (hashtag) symbol in the beginning of the line so the plugin is activated and do also point the database path correctly.
Before:
#LoadPlugin="geoip2_country /pathto/GeoLite2-Country.mmdb"
After:
LoadPlugin="geoip2_country /usr/local/share/GeoIP/GeoLite2-Country.mmdb"
After this change has been applied, just wait for visitors to come to your site and update the statistics automatically with the cronjob routine or just do it manually.
root@awstats:/usr/local/share/GeoIP # /usr/local/www/awstats/tools/awstats_updateall.pl now
Running '"/usr/local/www/awstats/cgi-bin/awstats.pl" -update -config=awstatsdemo.com -configdir="/usr/local/etc/awstats"' to update config awstatsdemo.com
Create/Update database for config "/usr/local/etc/awstats/awstats.awstatsdemo.com.conf" by AWStats version 7.8 (build 20200416)
From data in log file "/var/log/httpd-access.log"...
Phase 1 : First bypass old records, searching new record...
Direct access after last parsed record (after line 8058)
Jumped lines in file: 8058
Found 8058 already parsed records.
Parsed lines in file: 3
Found 0 dropped records,
Found 0 comments,
Found 0 blank records,
Found 0 corrupted records,
Found 0 old records,
Found 3 new qualified records.
root@awstats:/usr/local/share/GeoIP #
With this in place you should be able to see what country are your visitors coming from. Note IPs change from time to time and the information you downloaded today in the databases may change with time. To get updates just follow the next and last step of this how to enable geolocation in AWStats on FreeBSD.
Step 4. Automatically receive geolocation database updates
To get regular updated geolocation database information we do only need to add a cronjob in our server. This way we’ll receive automated updates without the hassle to manually perform them.
After issuing the following command add the data below it.
root@awstats:~ # crontab -e
Data:
SHELL=/bin/sh
PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin
# Order of crontab fields
# minute hour mday month wday command
0 0,12 * * * /usr/local/www/awstats/cgi-bin/awstats.pl -update -config=awstatsdemo.com
1 0 * * 1,3 /usr/local/bin/geoipupdate
With this in place we’ll get updates every Monday and Wednesday at 00:01 hours.
Conclusion
Enabling geolocation in AWStats on FreeBSD is quite a simple task. Open an account on MaxMind’s site, install the software to download the databases with the geolocation information, configure AWStats to make use of it and add a cron job not to miss any future updates.
If you find the articles in Adminbyaccident.com useful to you, please consider making a donation.