IntroductionThe geo template
is the first in a series of 'contributed' or non-core templates that are shipped as part
of the Whitebeam application server. Contributed templates tend to provide a specialist service applicable to a small subset
of potential Whitebeam applications. In the case of the 'geo' template - the service provided is to take an IP address and to
return geographical data about the owner of that address. This information has a number
of potential uses including targeted advertising, content selection or simply
blocking certain geographies from access in localised service. Whitebeam's service based architecture and template model make implementation of
functionality like this both simple and efficient. The Geo template loads a geographical
database of IP blocks into memory. As a single process the amount of memory used is
negligible. The application then receives XML mapping requests, consults the database and
returns the results to the caller. The overhead of loading the database happens once when the template application is started
(but can be re-started to load a newer version of the database with no loss of service). Contrast this model with alternatives where the data must either be loaded into each process
and each time a page wants information, or must be stored in an external database such as
mySql or Postgres and endure the overhead of a database request for each lookup. This template has been contributed by YellowHawk - where it was developed to enable
geographical based advertising in their
GadgetSpeak web-site. A single template method takes an IP address and returns a structure containing the bounds
of the containing block of IP addresses, a two letter, three letter abbreviations for the
country and a human readable name for the country. Simple example to display the source of an HTTP request :
var ipAddr = rb.page.env.RemoteAddr();
var info = rb.geo.iplookup(ipAddr);
rb.page.write("<p>You're currently in : '"+info.country+"'</p>");
Configuring the Geo templateThe template needs an IP address database to run. Ip address allocations are continually
changing so Whitebeam does not ship with this information. There are a number of source
of this data freely available on the Internet. The one we'd recommend downloading (which
is in the correct format) is available on the following address : http://software77.net/cgi-bin/ip-country/geo-ip.pl Download the CSV (comma separated value) format file and store it on your server. The default
location will be in /var/whitebeam/conf/IpToCountry.csv, although you can store it
anywhere and specify the path when you start the Geo template. As stated - the database does change regularly. To avoid having to stop and start the template
to reload a more recent database simply send a SIGHUP signal to the geo process. The new
database will be reloaded at the end of the next client request. |