========== geoip-vmod

Varnish GeoIP Module

:Author: Lee Doolan

SYNOPSIS

import geoip;

DESCRIPTION

This Varnish module lets you add VCL that sets the request header X-GeoIP based on the geolocalization of the given IP address.

Requires GeoIP library (on Debian install libgeoip-dev).

INSTALLATION

The source tree is based on autotools to configure the building, and does also have the necessary bits in place to do functional unit tests using the varnishtest tool.

Install the GeoIP library headers::

apt-get install libgeoip-dev pkg-config

To check out the current development source::

git clone git://github.com/leed25d/geoip-vmod.git cd geoip-vmod; ./autogen.sh

Usage:

./configure VARNISHSRC=DIR

VARNISHSRC is the directory of the Varnish source tree for which to compile your vmod. Both the VARNISHSRC and VARNISHSRC/include will be added to the include search paths for your module.

Make targets: make - builds the vmod make install - installs your vmod in VMODDIR make check - runs the unit tests in src/tests/*.vtc

In your VCL you could then use this vmod like the following. This sets the request header X-GeoIP to the requestor's geo (or Unknown). ,---- | import geoip; | | sub vcl_recv { | set req.http.X-Forwarded-For = client.ip; | set req.http.X-GeoIP = geoip.country_code(req.http.X-Forwarded-For); | } `----

,----
| import geoip;
|
| sub vcl_recv {
|     set req.http.X-GeoIP = geoip.country_code_from_ip(client.ip);
| }
`----

If the given IP is invalid, or cannot be found in the database, the returned country code is "AA", which is an invalid country code used in this module to indicate an error.

FUNCTIONS

country_code

Prototype STRING country_code(STRING)

Returns the country code (or "AA", if the given IP is invalid, a country code can not be found).

country_code_from_ip

Prototype STRING country_code_from_ip(IP)

Just like country_code, but takes an IP as argument instead of a string.

organization

STRING organization(STRING)

Returns the organization (or "Unknown organization" if the given IP is invalid, an organization can not be found or the organization database could not be found).

organization_from_ip

STRING organization_from_ip(IP]

Just like organization, but takes an IP as argument instead of a string.

region

STRING region(STRING)

Returns the region (or "Unknown region" if the given IP is invalid, an region can not be found or the region database could not be found).

region_from_ip

STRING region_from_ip(STRING)

Just like region, but takes an IP as argument instead of a string.

HISTORY

Manpage based on the libvmod-example by Varnish Software and tHauke Lampe's own GeoIP Vmod on https://github.com/lampeh/libvmod-geoip

CREDITS

The idea for this varnish module and the proof of concept and the initial implementation are all due to David Newhall II

Lee Doolan, the maintainer, added libtool configuration details, added thread safety, added SCM (git). Stability patch provided by Varnish Software.

COPYRIGHT

This document is licensed under the same license as the libvmod-example project. See LICENSE for details.

• Copyright (c) 2011 Livejounal
• Copyright (c) 2012 Varnish Software