no2key / telize Goto Github PK

                           t  e  l  i  z  e
                       _______________________
                 ______\                     /_______
                \\     \\           ___     //      /
           __    \ ____  \   __    /   \   _____/\ / ____
       ___/  \____/  _//____/  \___\___/___\__   /__/  _//____
      \\__    ____  __/  __     __      ____    ____  __/  __///
        /      \_   |/    \_     /       \/     /_/   |/    \_
      \\\   ___/\___       /____/\_______/\   ___/\___       /
  <0(--- \__/ -h7- \______/   \       .    \__/ ---- \______/ --(0>
                       \      .\     /.      .
                        \      .\   //      /
                         \______\\ //______/ 
                                  Y

Description

Telize is a REST API built on Nginx and Lua allowing to get a visitor IP address and to query location information from any IP address. It outputs JSON-encoded IP geolocation data, and supports both JSON and JSONP.

Requirements

Nginx modules

Telize requires Nginx compiled with the following modules :

• GeoIP (Optional HTTP modules : --with-http_geoip_module)
• HttpRealipModule (Optional HTTP module : --with-http_realip_module)
• HttpEchoModule (Third party module (ngx_echo) : http://wiki.nginx.org/HttpEchoModule)
• HttpLuaModule (Third party module (ngx_lua) : http://wiki.nginx.org/HttpLuaModule)

If you are using Debian stable, the nginx-extras package have these modules compiled-in.

Lua modules

Telize requires the following Lua module :

• Lua CJSON
• Lua iconv

Installing via LuaRocks :

luarocks install lua-cjson
luarocks install lua-iconv

GeoIP databases

Telize requires the free GeoLite databases : http://dev.maxmind.com/geoip/legacy/geolite/

For IPv4 support only :

mkdir -p /usr/share/GeoIP
cd /usr/share/GeoIP
wget http://geolite.maxmind.com/download/geoip/database/GeoLiteCountry/GeoIP.dat.gz
wget http://geolite.maxmind.com/download/geoip/database/GeoLiteCity.dat.gz
wget http://download.maxmind.com/download/geoip/database/asnum/GeoIPASNum.dat.gz
gunzip *gz

For IPv4 and IPv6 support :

mkdir -p /usr/share/GeoIP
cd /usr/share/GeoIP
wget http://geolite.maxmind.com/download/geoip/database/GeoIPv6.dat.gz
wget http://geolite.maxmind.com/download/geoip/database/GeoLiteCityv6-beta/GeoLiteCityv6.dat.gz
wget http://download.maxmind.com/download/geoip/database/asnum/GeoIPASNumv6.dat.gz
gunzip *gz

Installation

Copy timezone.conf and timezone-offset.conf in the Nginx configuration files directory.

Edit nginx.conf to include timezone.conf, timezone-offset.conf and to add directives specifying the path to the GeoIP database files, within the http block.

For IPv4 support only :

http {

	...

	include        /etc/nginx/timezone.conf;
	include        /etc/nginx/timezone-offset.conf;

	geoip_country  /usr/share/GeoIP/GeoIP.dat;
	geoip_city     /usr/share/GeoIP/GeoLiteCity.dat;
	geoip_org      /usr/share/GeoIP/GeoIPASNum.dat;
}

For IPv4 and IPv6 support (requires at least Nginx 1.3.12) :

http {

	...

	include        /etc/nginx/timezone.conf;
	include        /etc/nginx/timezone-offset.conf;

	geoip_country  /usr/share/GeoIP/GeoIPv6.dat;
	geoip_city     /usr/share/GeoIP/GeoLiteCityv6.dat;
	geoip_org      /usr/share/GeoIP/GeoIPASNumv6.dat;
}

Then deploy the API configuration file telize to the appropriate location on your system, and reload Nginx configuration. If you are behind a load balancer, read the next section.

Depending on existing configuration, the map_hash_max_size and map_hash_bucket_size sizes might be set too low and Nginx will refuse to start. If this happens, please add the following directives in the http block.

map_hash_max_size 8192;
map_hash_bucket_size 64;

There is an automatic install script for Debian :

sh install/debian.sh

Lastly, if your Telize instance produces lots of logs, this might be of interest : Log rotation directly within Nginx configuration file.

Telize and Load Balancers

When using Telize behind a load balancer, uncomment the following directives in the server block and set the load balancer IP range accordingly :

# set_real_ip_from 10.0.0.0/8; # Put your load balancer IP range here
# real_ip_header X-Forwarded-For;

In the /geoip location, replace this directive :

proxy_set_header X-Real-IP $ip;

By the following directive :

proxy_set_header X-Forwarded-For $ip;

CORS Support (Cross-origin resource sharing)

Telize has CORS enabled by default since version 1.02. The following variables defines CORS behavior, within the telize configuration file.

set $cors "true";
set $cors_origin "*";

Usage

For complete API documentation and JavaScript API usage examples, please check the project site : http://www.telize.com

Get IP address in Plain text format :

• Example : http://www.telize.com/ip

Get IP address in JSON format :

• Example (JSON) : http://www.telize.com/jsonip
• Example (JSONP) : http://www.telize.com/jsonip?callback=getip

Get IP address location in JSON format :

Calling the API endpoint without any parameter will return the visitor IP address :

• Example (JSON) : http://www.telize.com/geoip
• Example (JSONP) : http://www.telize.com/geoip?callback=getgeoip

Appending an IP address as parameter will return location information for this IP address :

• Example (JSON) : http://www.telize.com/geoip/46.19.37.108
• Example (JSONP) : http://www.telize.com/geoip/46.19.37.108?callback=getgeoip

License

Telize is released under the BSD 3-Clause license. See LICENSE file for details.

Author

Telize is developed by Frederic Cambus

• Site : http://www.cambus.net
• Twitter: http://twitter.com/fcambus

Resources

Project Homepage : http://www.telize.com

Latest tarball release : http://www.statdns.com/telize/telize-1.02.tar.gz

GitHub : https://github.com/fcambus/telize