One Hat Cyber Team

View File Name : _readme.txt


  PHP COUNTRY DETECTOR/REDIRECTOR BY IP (RESTRICT VISITS) - VERSION 4.2 
	- advanced redirection  - for MySql and Plain text databases 
	- Copyright (C) 2004 Ionita Dragos Alexandru - http://dragos.web-heaven.com

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or any later version. 

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

CONTACT:
	http://ipdb.web-heaven.com
	ipdb@web-heaven.com

DOWNLOAD UPDATES AND IP DATABASES AT:
	http://ipdb.web-heaven.com

WHAT DOES IT DO?

- This is a script designed to fit into your web site and redirect/restrict access to visitors based on their country, or just to get the visitor`s country and country details, like population, currency and flag image path.
- The script should be included in a set of pages on your web site so it could redirect visitors to those pages accordingly to the redirection rules. - In this distribution it is included a free IP2Country database (75% accurate) for 179 countries, with 16934 record, which is very inaccurate... 
- The country code of the visitor is saved in a cookie or a session variable in order to avoid searching the IP database repeatedly. 
- With this script you can create as many "Redirection Nodes" as you want. On the same web site, some pages could have different redirection rules than the others, by including them in different Redirection Nodes.
- For each Redirection Node, each country (or IP database) has a Redirection Rule (a link associated with it). If the visitor`s IP is in an IP database, he is redirected to the redirection link associated with it, or if this one is blank, to the default redirection link. If this default redirection link is blank too, the page is loaded. If the visitor`s country has no Redirection Rule specified, he is redirected to the default 'reject' link or if this one is blank, the page is loaded.
- It features an IP exception list, where you can place your trusted IPs, and a passwords/codes list for exceptions.  
- The IP databases supported are MySql full, MySql split, Plain text full, Plain text split - all available at http://ipdb.web-heaven.com
- The Plain text databases can have both IP numbers (3240323434) and IP addresses (192.168.0.1).
- If you consider country IP databases just as "Redirection IP databases", you`ll be able to redirect/restrict access to your web site based on a list of IP addresses, not necessarily from the same country. That`s why the script can also read IP databases with IP addresses (192.168.0.1), so you could easily create your custom IP database. 
- It also creates an array with visitor`s country information, and the path to it`s flag GIF file, than you could use in your own scripts;

REQUIREMENTS:
	Web server with PHP minimum version 4.1.x, optionally MySql;

FILES:
	rv/rv.php - main script file; Edit this file for configuration.
	rv/rv_****.php - additional functions
	rv/.htaccess - Apache restriction file, to deny access to rv/ folder, to
		avoid abuse. 
	rv/exceptions_ips.dat - A list of IPs who will be excluded from
		the redirection. It can only have IP addresses (192.168.0.1) or IP address
		ranges; Edit this file to add exceptions; Example: 213.120.148.65
		213.120.148.70;213.120.148.123
	rv/exceptions_codes.dat - A list of codes that could be send to your RV-protected
		pages in order to skip the redirection. 
		Example: http://yoursite.com/bla/yourRV-protected_file.php?rv_ex=[CODE]
		where [CODE] has to be in exceptions_CODE.dat
	rv_database/_rv_free.dat - a free IP2Country database - type: Plain text with IP numbers;
	rv_database/_rv_free.sql - Sql Dump of the same free database - type: MySql full 
	rv_database/Countries.* - Country information files 
	rv_cflags/* - GIF country flags

IP NUMBERS AND IP ADDRESSES:
  An IP numbers range look like 3268209248;3268209250; In HEXA it is C2CCEA60;C2CCEA62.
  Let`s take groups of 2 : C2.CC.EA.60;C2.CC.EA.62 and make each group DECIMAL
  again: 194.204.234.96;194.204.234.98. This is an IP addresses range.

INSTALL:
 - If you use MySql, load rv_database/_rv_free.sql into your mysql server:
	mysql -u [username] -p
	mysql>use [your database]
	mysql>source [path to/]_rv_free.sql
 - Edit rv/rv.php and modify it as described there.
 - Add the next line at the beginning of EVERY PAGE YOU NEED TO REDIRECT VISITORS:

	<?PHP $rv_path="rv/"; include($rv_path."rv.php"); ?>

		or (if rv/ directory is a level up)

	<?PHP rv_path="../rv/"; include($rv_path."rv.php"); ?> 

	 Be careful! The script is setting cookies so it`s a MUST that no character (not even space or new line) should be in front of <?PHP $ip_path=".....
 - If you want a different set of redirection rules (Another Redirection Node) 
 in other pages of your website, all you have to do is to m
 ake a copy of rv/rv.php -> rv2/rv.php, copy all other files from rv -> rv2, edit rv2/rv.php, 
 just change the _NODE_ID and the REDIRECTION RULES. Then include it in your
  files with <?PHP $rv_path="rv2/"; include($rv_path."rv.php"); ?>
 - Please read TIPS section for configuration and optimization advices.

THE IP DATABASE
 - The free IP -> Country database included in this distribution originates is highly unacurate.
	It has data for 179 countries and the csv file size is 429 Kb.
	The number of records is 16934 and the number of IP addresses covered is 2,757,057,835 . Our opinion is that this database it`s 75% accurate.
 - You can get an updated and optimized IP database from http://ipdb.web-heaven.com with data from RIPE, ARIN, APNIC and LARNIC public databases. The database is updated daily and you`ll have 6 months of free access to updates! Used with this script it is 99% accurate.

TESTING AND DEBUG-ING
 To test and debug you need to set in rv/rv.php the constant _DEBUG_MODE to 1: define("_DEBUG_MODE","1") then point your browser to http://yoursite.com/etc/exemple.php. Now play with the configuration, modify redirection rules. When you are satisfied, set _DEBUG_MODE to 2 in order to test how cookies / session vars are saved. When it`s ok set _DEBUG_MODE to 0.


CONFIGURATION TIPS
 - If you want to use PHP COUNTRY DETECTOR BY IP just to detect the country of your visitor
  and to register the country details in an array, in rv/rv.php comment 
  out all REDIRECTION RULES and make blank the default redirect and reject links ( =""; ). 
 Then define("_LOAD_COUNTRY_ARRAY","1") and that`s it! edit exemple.php to see how you can use the country details of your visitor. This fields can be used in your scripts: $rv_cinfo["code"] $rv_cinfo["name"] $rv_cinfo["region"] $rv_cinfo["capital"] $rv_cinfo["currency"] $rv_cinfo["currency_code"] $rv_cinfo["population"] $rv_cinfo["flag_path"] ; 
 The flag image can be generated like this: <img src="<?php echo $rv_cinfo["flag_path"]; ?>" alt="" width="36" height="24" border="0">

 - If you want PHP COUNTRY DETECTOR BY IP to safely reject all visitors from country XX and YY and to accept all the other visitors you have to set : $rv_default_reject_link=""; $rv_default_redirect_link=""; , $rv_url_save_method="session";
 In the Redirection Rules section, for country XX uncomment the line and place an invalid url for it ($rv_rr["XX"]="index.asphp") . Do the same for YY; Also uncomment the line for "PX" to reject proxy servers as well and add an invalid url there too.
 
 - If you need to display language specific pages for German and French : $rv_default_reject_link=""; $rv_default_redirect_link=""; as redirection rule set $rv_rr["DE"]="yourpage_german.htm"; Do the same for FR;

 - If you want to restrict access to visitors from your country too, you have to add your IP address or your network`s IP range in the rv/exceptions_ips.dat file in order for you to be able to visit your website. Also you could add a code like "foo" in rv/exceptions_codes.dat and access your website once with http://yoursite.com/bla/yourRV-protected_file.php?rv_ex=foo

 - If you want to deny access to your website to a certain group of people, or if you want to show them a fake version of your website, you have to get the IP ranges of this people, from their ISP. Then create a file rv_OUT.dat in rv_database with the IP address ranges of this people (192.168.0.2;193.0.0.0). Then make this script use a plain text split database as source ($rv_db_type="text";$rv_db_format="split") Tell the script that it has to read IP addresses not numbers : $rv_text_db_ip_type="addresses";
 Set as blank the default reject and redirect links, comment or erase all other redirection rules and add a new redirection rule: $rv_rr["OUT"]="fake_website.php"; Do not forget to add this script to all your website`s files: <?PHP $rv_path="rv/"; include($rv_path."rv.php"); ?>

 - Finally, if you want to be 99% sure that the IP -> Country conversion is realistic, you have to use the best database on the market, database provided by us at http://ipdb.web-heaven.com . It is updated daily and you`ll have 6 months of free access to updates.

QUESTIONS, BUG REPORTS AND CUSTOMIZATION REQUESTS
 - We can customize the script for your specific needs. 
 - If you have a static web site and you do not want to modify your files, or if you just want this solution, we can customize our script for MOD_REWRITE and we can configure your web server for it, or we could reconfigure your web server to parse static pages trough the PHP processor.
 - Prices depend on the number of hours needed for the job. 
	Email us at ipdb@web-heaven.com