telize

High performance JSON IP and GeoIP REST API (IP Geolocation)
Log | Files | Refs | README | LICENSE

commit e65fd607aa770fc5caa6c51fa1c00f4f0961d453
parent 3fee9e367b8616fd7df8a4ccaec0795c389fd59b
Author: Frederic Cambus <fred@statdns.com>
Date:   Mon, 21 Nov 2016 19:38:03 +0100

Reformat README file to wrap long lines, remove whitespace before colons, and use Markdown link format

Diffstat:
MAUTHORS | 6+++---
MCONTRIBUTORS | 2+-
MREADME.md | 87++++++++++++++++++++++++++++++++++++++++++++++++-------------------------------
3 files changed, 57 insertions(+), 38 deletions(-)

diff --git a/AUTHORS b/AUTHORS @@ -1,6 +1,6 @@ -Telize is developed by : +Telize is developed by: Frederic Cambus <fred AT statdns DOT com> -Site : http://www.cambus.net -Twitter : @fcambus +Site: http://www.cambus.net +Twitter: @fcambus diff --git a/CONTRIBUTORS b/CONTRIBUTORS @@ -1,4 +1,4 @@ -The following people have contributed to Telize : +The following people have contributed to Telize: - Jon Nalley - Yann Verry diff --git a/README.md b/README.md @@ -20,7 +20,9 @@ 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. -Geolocation operations are performed using Nginx GeoIP module which caches the database in RAM. Therefore, Telize has very minimal overhead and should be blazing fast. +Geolocation operations are performed using Nginx GeoIP module which caches +the database in RAM. Therefore, Telize has very minimal overhead and should +be blazing fast. ## Requirements @@ -30,15 +32,16 @@ Telize requires Nginx 1.7.4+ compiled with the following modules : - GeoIP (Optional HTTP module : --with-http_geoip_module) - HttpRealipModule (Optional HTTP module : --with-http_realip_module) -- HttpLuaModule 0.9.17+ (Third party module (ngx_lua) : http://wiki.nginx.org/HttpLuaModule) +- HttpLuaModule 0.9.17+ (Third party module [ngx_lua][1]) -For maximum performance, please make sure the HttpLuaModule is compiled against LuaJIT : +For maximum performance, please make sure the HttpLuaModule is compiled +against LuaJIT: ldd $(which nginx) | grep lua ### Lua modules -Telize requires the following Lua modules : +Telize requires the following Lua modules: - Lua CJSON - Lua iconv @@ -52,9 +55,9 @@ Alternatively, those modules can be installed directly using binary packages. ### GeoIP databases -Telize requires the free GeoLite databases : http://dev.maxmind.com/geoip/legacy/geolite/ +Telize requires the free [GeoLite databases] from MaxMind. -#### For IPv4 support only : +#### For IPv4 support only mkdir -p /var/db/GeoIP cd /var/db/GeoIP @@ -63,7 +66,7 @@ Telize requires the free GeoLite databases : http://dev.maxmind.com/geoip/legacy wget http://download.maxmind.com/download/geoip/database/asnum/GeoIPASNum.dat.gz gunzip *gz -#### For IPv4 and IPv6 support : +#### For IPv4 and IPv6 support mkdir -p /var/db/GeoIP cd /var/db/GeoIP @@ -74,9 +77,12 @@ Telize requires the free GeoLite databases : http://dev.maxmind.com/geoip/legacy ## Installation -Copy `timezone.conf` and `timezone-offset.conf` in the Nginx configuration files directory. +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. +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 @@ -106,40 +112,49 @@ Edit `nginx.conf` to include `timezone.conf`, `timezone-offset.conf` and to add geoip_org /var/db/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. +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. +Depending on existing configuration, default values of `map_hash_max_size` +and `map_hash_bucket_size` variables might be too low and Nginx will refuse +to start. If this happens, please add the following in the `http` block. map_hash_max_size 8192; map_hash_bucket_size 64; -On busy instances, the maximum number of open files limit must be increased using the `worker_rlimit_nofile` directive in order to avoid running out of available file descriptors. +On busy instances, the maximum number of open files limit must be increased +using the `worker_rlimit_nofile` directive in order to avoid running out of +available file descriptors. ## Access and Error logs -The default Telize configuration does not have logging enabled, it must be configured manually. +The default Telize configuration does not have logging enabled, it must be +configured manually. -If your Telize instance produces lots of logs, this might be of interest : [Log rotation directly within Nginx configuration file](http://www.cambus.net/log-rotation-directly-within-nginx-configuration-file/). +If your Telize instance produces lots of logs, this might be of interest: +[Log rotation directly within Nginx configuration file][3]. ## 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 : +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 : +In the `/geoip` location, replace this directive: proxy_set_header X-Real-IP $ip; -By the following directive : +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. +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 "*"; @@ -147,30 +162,30 @@ Telize has CORS enabled by default since version 1.02. The following variables d ## Usage For complete API documentation and JavaScript API usage examples, please check -the project site : http://www.telize.com +the project site: http://www.telize.com ### Get IP address in Plain text format -- Example : http://127.0.0.1/ip +- Example: http://127.0.0.1/ip ### Get IP address in JSON format -- Example (JSON) : http://127.0.0.1/jsonip -- Example (JSONP) : http://127.0.0.1/jsonip?callback=getip +- Example (JSON): http://127.0.0.1/jsonip +- Example (JSONP): http://127.0.0.1/jsonip?callback=getip ### Get IP address location in JSON format Calling the API endpoint without any parameter will return the visitor -IP address : +IP address: -- Example (JSON) : http://127.0.0.1/geoip -- Example (JSONP) : http://127.0.0.1/geoip?callback=getgeoip +- Example (JSON): http://127.0.0.1/geoip +- Example (JSONP): http://127.0.0.1/geoip?callback=getgeoip Appending an IP address as parameter will return location information for -this IP address : +this IP address: -- Example (JSON) : http://127.0.0.1/geoip/46.19.37.108 -- Example (JSONP) : http://127.0.0.1/geoip/46.19.37.108?callback=getgeoip +- Example (JSON): http://127.0.0.1/geoip/46.19.37.108 +- Example (JSONP): http://127.0.0.1/geoip/46.19.37.108?callback=getgeoip ## License @@ -179,15 +194,19 @@ for details. ## Author -Telize is developed by Frederic Cambus +Telize is developed by Frederic Cambus. -- Site : http://www.cambus.net +- Site: http://www.cambus.net - Twitter: http://twitter.com/fcambus ## Resources -Project Homepage : http://www.telize.com +Project Homepage: http://www.telize.com + +Latest tarball release: http://www.statdns.com/telize/telize-1.06.tar.gz -Latest tarball release : http://www.statdns.com/telize/telize-1.06.tar.gz +GitHub: https://github.com/fcambus/telize -GitHub : https://github.com/fcambus/telize +[1]: http://wiki.nginx.org/HttpLuaModule +[2]: http://dev.maxmind.com/geoip/legacy/geolite/ +[3]: http://www.cambus.net/log-rotation-directly-within-nginx-configuration-file/