==========
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