![]() |
Fixing The Web |
Home Contact Country Blocking: For Dedicated Servers For Shared Servers Country Lookup Tool Rules Generator |
A site for both the WebMaster and the WebUser
Country Blocking Documentation
****************************************************************** Documentation for the ipcountryblock package consisting of countryiptsetup.php, countryiptables.php, and iptocountry.php. ****************************************************************** Copyright (C) 2006 Click Here Software Co. Written by: Maurice Randall Distributed by: FixingTheWeb.com Email: support@fixingtheweb.com Version 1.2 : November 17, 2006 ****************************************************************** This product can use either one of the following two country database files: The IP-to-Country Database provided by WebHosting.Info (http://www.webhosting.info), available from http://ip-to-country.webhosting.info or: The GeoIP Database provided by MaxMind.com (http://www.maxmind.com), available from http://www.maxmind.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 (at your option) 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. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc. 51 Franklin Street, Fifth Floor Boston, MA 02110-1301, USA. ****************************************************************** === Introduction ======== The purpose of this package of programs is to assist the webmaster in blocking out entire countries from having access to his/her computer. Even small time webmasters, someone running a website on a single computer connected to a dsl or cable modem while using the same computer for online access will find this package useful. If your website runs on a remote host, you might have limited use of this package. It all depends on the type of hosting package you have. For a 'dedicated' server, you should have all the functionality provided here. For a VPS (Virtual Private Server) setup, you might also have full functionality, provided your host allows access to the 'iptables' command on your server. If you're on a 'shared' server, then you will have limited use of this package. In that case, you will only be able to use the "iptocountry.php' utility for looking up the countries that ip addresses belong to. The core of this package makes use of the iptables functionality in the Linux kernel. The included countryiptables.php program will generate a file containing a list of iptables rulesets that may be loaded into the kernel. Every possible range of addresses identified as belonging to each country that you select will be in this file. To do this manually would be a daunting task. That's why we have programs such as this to do the work for us. This package also includes a handy utility called iptocountry.php that lets you look up an IP address and identify the country it belongs to as well as the entire range of addresses it falls within. === Requirements ======== Your system must be running a web server such as Apache on a Linux server for the iptables functionality of this package. It also must have php4 (or higher) installed. If you use another operating system that uses the same iptables functionality as Linux, then this might work for you as well. I've found that the 2.6.x Linux kernel is needed for this package because it uses the iprange module with iptables. If you've been able to get iprange to work with iptables on a 2.4.x kernel, then you are in luck. I personally gave up and upgraded to the 2.6.x kernel. I think some of the newer 2.4 kernels can use the iprange module. Without iptables running or if you use another type of operating system that doesn't use iptables, you can still use part of this package as long as you have php running on your system. The iptocountry.php program will be very useful in helping you to determine the country an ip address belongs to as well as the countries that are immediately before and after the ip range of the particular country. === File requirements ======== If you've downloaded the complete countryip.tar.gz package, then you have this documentation and the 3 php files needed. You will also need one more file which contains all of the country and ip address info. You have your choice of two different databases. One can be downloaded from http://ip-to-country.webhosting.info. This file is called ip-to-country.csv and can be found in the downloads section of their website. On the website, the downloadable file is called ip-to-country.csv.zip. The other one can be found at http://www.maxmind.com. This file is called GeoIPCountryWhois.csv once it is unzipped. In it's zipped format when you download it, it is called GeoIPCountryCSV.zip. It's also found as GeoIP-lite on the site. This is the free download. You can also use their more accurate GeoIP file from their paid service. Be sure to get the .csv version and not the binary version. Whichever file you choose, be sure to unzip it and copy it to the directory you will be using for this package. The file you download from one of these two souces is used just one time during the initial setup. The information database is built from the file and is used for the operation of the programs in this package. However, once you begin using this package, you will want to check periodically for new updates to the database file that you choose to use. Both database files are updated approximately every month or so. NOTE: For the rest of this documentation, the country database file you have chosen to use will be referred as the ".csv database file". === Summary ======== Here's a brief summary of what you need to do to get this entire package running: 1. Download and unpack or unzip this package into its own directory. 2. Download either the IP-TO-COUNTRY or the MaxMind database file and unpack it in the same directory as this package. 3. Run the countryiptsetup.php program from this package to set up all the database files that are used by countryiptables.php and iptocountry.php 4. Run countryiptables.php to select the countries you wish to block. 5. Use iptables to install your newly selected countries into the kernel so that Linux can block them for you. 6. Configure Linux so that your settings will be preserved if the computer gets rebooted. Optionally (or instead): Run iptocountry.php to look up countries according to their IP address. For a much more detailed installation description, keep reading... === Setting up ======== Now that you have the 3 php files and the .csv database file, it's time to do the setup. You need to either create a new directory on your system or use an existing one. The directory must be accessible to your web server just like any other file that is used on your website. I personally prefer a new directory just to help prevent clutter and to keep organized. So, from a command line prompt, I cd to a location somewhere on my system that is part of the web site and do: mkdir country Whatever suits you is fine, the programs themselves don't care where the directory is or what you name it. Just be sure to put all of the files included in this package and the .csv database file in the same directory. Note: If you are only going to use the "iptocountry.php" program, you can do the installation from a web-based admin utility such as CPanel or VDeck, etc. You can also install the entire package from a web-based admin utility as well, however, the part where you will configure the kernel's iptables functionality will have to be done from a command line prompt. If you're doing this on a computer where you have direct physical contact, then you will have no problem at all with the installation since you have full control over your computer. === Check permissions ======== You proably already know about this stuff, but some people still have trouble with it. This example is how I had to do it on my system. After creating the directory I wanted to use I assigned the correct permissions to it so that the Apache web server could have access to it and be able to write files within the directory. This example assumes the directory is called 'country'. From a command line prompt, 'cd' to the parent directory where 'country' resides. Since I just created the new directory, I'm already where I need to be and issue the following command: chmod 775 country On some systems, 755 might work and some might be OK with 744. But 775 should always work, provided the directory is also 'owned' by the web server or belongs to a group that is assigned to it. Just to make sure things will work, I always assign the directory with the web server as the owner and the group. On my Debian system, the Apache server is known as "www-data". So, I do the following: chown www-data.www-data country Now, the web server has full read and write access to the 'country' directory. If your web server uses a different name than 'www-data', just change the above command accordingly. Maybe on your system, your own username will work. You'll find out later when it comes time to create some files. === Copy the files ======== Next, use whatever method you normally use for copying files. Copy all of the files included with this package plus the .csv database file into your 'country' directory. === Initial testing ======== At this point, only one of the three php files will work, countryiptsetup.php. Don't even try to run countryiptables.php or iptocountry.php yet. From a web browser, type in the path in the url address bar to point to your country directory and the countryiptsetup.php program. Here's an example: http://yourwebsite.com/country/countryiptsetup.php Naturally, you will substitute "yourwebsite.com" with the real name of the web site you are using along with the actual path to the countryiptsetup.php file. A page will display in your browser that says at the top: "Generate Database Files for countryiptables.php and iptocountry.php" If the page appears with no error messages, then your combination of web server and php functionality is working at this point. You should see a web page with some text and a single button that can be clicked on. If any error messages were displayed from either your browser, your web server, or php building a page with error messages, then something is wrong and needs to be fixed. The most likely problem at this point is php isn't working for you. However, if you've downloaded this package with the intentions of using it, I have to assume you already have a functional php system running. If not, check the internet for help on getting it working for you. Getting php working is not the subject of this documentation. If you received no apparent errors, move on... === Build the database ======== The work of creating the database files is all handled by the countryiptsetup.php program. It will do all the work for you while you sit back and wait for it to finish. If you think you're ready, go ahead and click on "Generate Database". Go to the refrigerator and get a Coke or something. Don't be alarmed, on a slow server, this can take several minutes. It might appear as though your web browser is stalling, but it's just waiting for the page to come back after all the new files are created. Be patient. If you'd like you can monitor the progress by periodically looking at the 'country' directory. There are 256 files being created, all beginning with a number and ending with .php. Also, one additional file called countries.php will be created at the end. Don't interrupt the process - don't hit the stop button in your browser. Give it time to complete the task of building the files. A modern-day fast server will probably get the job done quite rapidly, but some of us are still using some older equipment. NOTE: If something goes wrong or the process gets interrupted, don't panic. Just do it again. Any existing files that were created will be deleted and replaced by new ones. This would be no different than the actual process of updating each month when an updated .csv database file is installed. When your browser comes back to life, the setup job should be all finished. However, if something went wrong, you'll likely see an error message of some sort, most likely from php complaining that it can't create the files. Check the permissions applied to the directory you are using. That should be the only problem you are likely to encounter. I doubt the problem would be a lack of disk space. Most users nowadays have gigs and gigs of storage space. In any case, the php files only take up about 27K of space, the .csv file eats up about 3MB-6MB and the newly created database files use about another 3MB-5MB. So, less than 7MB-12MB of free space will do the job. If you don't have that much available, then just turn your computer off and forget it. You probably can't do much with it anyway. Get a Commodore 64, it doesn't need much in the way of resources. (You can tell what my bread and butter is). === Updating the database ======== Now that the database files are built, we are all done with both the .csv database file and the countryiptsetup.php file. However, the .csv database file gets updated periodically, maybe every couple of months or so. Whenever that happens, just go download a new version of it, copy it in place of the existing .csv database file and then rerun the countryiptsetup.php program. It will upgrade all the existing database files for you. It's as simple as clicking on "Generate Database". Whenever you recreate new updated database files, the countries.php file is also recreated. This file stores your country selections. Your existing settings will be preserved and restored when the new countries.php file is created. NOTE: If you decide to switch from one database to the other (IP-to-Country vs. MaxMind), be sure to either delete the countries.php file or rename it to something else if you'd like to preserve it. The reason for this is due to the slightly different names each database gives to some of the countries. When you switch, your default settings are not preserved. This need not be done if you stick with the same database provider. === Using the software ======== We now have two php programs that can be used, one is countryiptables.php and the other is iptocountry.php. Let's check out iptocountry.php first and get familiar with it. This will help to understand what takes place when we run the countryiptables.php program. Just as with the setup program, point your browser to iptocountry.php: http://yourwebsite.com/country/iptocountry.php You'll get a page showing a brief help message along with a text box and a clickable button. Enter an IP address into the text box and then click on "Get IP Info". A page will appear that will display the address you entered along with a version of the address in a long decimal format. The long decimal format is basically the four ip address bytes multiplied out to the full 32-bit number they represent. For most purposes, you can ignore the long decimal results, but they are included in case you have a need for them. I use them for manually looking through the database files and comparing ranges of addresses. Also displayed is the range of ip addresses that your request matches up with along with the country that this range belongs to. Then below this are two columns of info. In the left column are 6 ranges of ip addresses listed that appear numerically ahead of your request. Likewise, in the column to the right are 6 ranges of ip addresses listed that appear numerically after your request. You can use this information when you wish to find larger blocks of ip addresses than just the one that matches your request. When you use this program, you'll notice that sometimes it provides a response quite rapidly while other times, it seems to take longer. The difference is due to the ip address you are requesting info on. Some ranges are broken up real badly with very small chunks distributed here and there. When the program encounters those ranges, there is a tremendous amount of data to search through and calculate. But even on a fairly slow server, the wait isn't bad, it's just that you will notice a difference depending on the address you enter. Play with this program and get used to it. You'll find it's very handy and really helps when you want to find the info you need. === Block those countries ======== Now it's time to move on and get our system so it can block the countries we don't want or don't need. There's nothing personal intended here, but there comes a time when we just can't take it anymore and must take some drastic action. It's just too bad that there are some bad people out there spoiling the internet for everyone else. Some will say, "a few bad apples spoils it for everyone". Well, it's not a few bad apples. There are thousands if not millions of bad apples in this case. What do we do about them? BLOCK 'EM! === Get IPTABLES running ======== Now, before going any further, you must make sure that iptables is working on your Linux system, or other Unix type of system. For this discussion, I'll make reference to Linux because that's what I'm using. If you use something different and it still has iptables, then you can adapt to what I will talk about. The first thing to do is see if you get any kind of response from iptables. Simply typing the command all by itself will reveal if it's available on your system. From a command prompt type: iptables You should get a message saying something like 'type iptables -h for more information'. If you get a message that says "command not found", it might be that you will need to be logged in as 'root' rather than a normal user. Knowing that iptables is working, you must also make sure that the iprange module is supported by your version of the kernel and iptables. Enter an iptables command that uses iprange and see if it either accepts it or responds with an error message. From a command prompt do: iptables -t nat -I PREROUTING -m iprange --src-range 218.0.0.0-218.31.255.255 -j DROP If you get a command prompt back with no error message, then you are in luck. Plus, you have just blocked out over 2 million IP addresses in China. (Sorry China, but I figured this was a good example to use since I'm blocking China on my system) If you want to undo this block, just issue the same command but replace the -I part with -D. This stuff is really quite simple once you understand how to do it and provided someone explains it in an easy to understand manner. Hopefully, I'm doing just that. If you get an error message when entering the iptables command example above, it most likely means that your kernel doesn't support the iprange module or maybe the module just isn't loaded in. At this point, you will have to figure out how to get Linux to accept iprange in the iptables command. Generally, the error message when it isn't working is something like "no chain/target/match by that name" or something like that. The error might be something different if iprange is in the kernel but just not working right. This was my case. It didn't work for me initially and I had to upgrade to the 2.6.x kernel. From what I could tell, iprange was installed on my system, but for some reason the coding wasn't right and it didn't work. I found out it also didn't work for many other people. A newer kernel is what was needed. Trust me, it's worth the effort to upgrade your system to be able to use this functionality. For the rest of this documentation, we will assume that iptables is working for you and it is also accepting the iprange match in the command. === Setup for IPTABLES ======== The next thing to do is to get iptables to generate a default ruleset file for us. This is needed because it will get included into the new file you will be creating. This allows you to keep all of your existing iptables rules while adding the additional country blocking rules to it. We don't want the standard rules file that can be launched as a script. We want the one that iptables can create for us. This will match the same format as the one that countryiptables.php generates and is able to be loaded into the running kernel much faster. So, the next step is to do the following from a command prompt: iptables-save > defaultrules Note: you must name it exactly as "defaultrules" or the program won't find it. You'll have to know if it was found or not. That's explained later on. A new file named 'defaultrules' will be created in the current directory. It's easiest if you issued this command right from your country directory. If not, be sure to copy the file to the directory. This file contains all of your current rules that iptables is now using. Actually, it's OK to skip this part and not create the defaultrules file. If you skip it, then there is just a slightly different command to use later on when we install the country blocking rules into the kernel. But, it's best to do this part so you have a complete new rules file with your old rules and the new rules. It's your choice. === Pick your countries ======== Now you get to decide who you like and who you don't like. So, point your browser to the countryiptables.php file: http://yourwebsite.com/country/countryiptables.php You'll get a page displayed showing some buttons and all the available countries you can pick from. The first time you run this program, none of the countries will be selected. This means that you are not choosing to block any country yet. Go through the list and pick the countries you want to block. There is a checkbox next to each country name. You'll notice 4 buttons displayed in a row. Here's the description of each one: Clear All - clicking on this button will clear all the country selections. Use this button to clear all of your existing selections when you want to pick just one or two countries. Select All - clicking on this button will select all of the countries. Use this and then deselect a country or two. You might want to block out the whole entire world all except for a few select countries. Save As Defaults - when you are happy with your selections, click on this button to save your settings. Everytime you load this program, you'll have the same countries selected for further work. Load Default Selections - click on this if you change your mind or need to revert back to your default country selections. By default, this program will create iptables rules that will block the countries coming in on the "eth0" ethernet interface. You can keep this selection or select a different one such as "eth1" if that is the interface that is connected to the internet where all the incoming packets are arriving. Near the top, you'll see where you can select eth0, eth1, or eth2. You can also type in something different if your Linux distrubution uses a different naming convention. Whichever interface you choose is the one where incoming packets will be blocked. After all, if this is a firewall machine, it will have at least two ethernet interfaces and there's no point in blocking countries coming in from your local network. On the other hand, you might have one interface connected to your local network and two connected to the internet. In that case, you can click on the checkbox that says "All except above interface". In that case, you will be blocking all the interfaces except for the one that you have selected. If you're not sure what the name is of your interface, enter the following command from a command prompt: ifconfig If the information scrolls by and off the screen, send the info to the 'more' or the 'less' command like this: ifconfig | less Now you can read the info and find out what names are given for your ethernet interfaces (cards). You'll also see other helpful info such as the local IP address assigned to the card, the number of ingoing and outgoing packets, etc. === Build the IPTABLES file ======== Now that you have all of the countries selected that you want to block, it's time to build a file that will be installed into the Linux kernel. It's as simple as typing in a filename and clicking a button. In the text box near the top of the page, enter a filename to use for this file that is about to be created. You'll notice that a default filename has already been entered for you. You can change it if you'd like. Maybe you want to create several different country blocking files or maybe different files for different server machines. Once you've chosen the filename, click on "Create File" and go get another Coke. Or get a Vernors or whatever you like. Actually, this process will go quite quickly on a fast server. A slow server might take 3-6 minutes. But it also depends on how many countries you have chosen and which countries they are. If you want to watch the progress of this file being created, go to a command prompt and get into the directory where your files are located and enter the following: tail -f badiptlist.txt ...or whatever you entered for the filename to be created. You'll be able to see the big list of iptables rules being created. You will be amazed at how big this list can be. On my system it contains over 10,000 lines of rules. My system created a file that is about 1MB in size. You can load this file into a text editor and manually edit it if you'd like. This is where you can remove a block on a particular region and not actually block an entire country. Use the iptocountry.php program to help you pick and choose. Anyway, once the file is finished being created, we have to go and install it into the Linux kernel. But this is easy, I'll show you how. You can do it right from the same directory unless your intentions are to use it on a different machine. In that case, copy it over to the intended computer. Now, there are two versions of the command that we will use. It all depends on if you used a defaultrules file as described earlier or if you omitted that part. Let's assume you created a defaultrules file. If you failed to enter the correct name when the file was created, countryiptables.php didn't find it when it created the badiptlist.txt file. We need to know if it found it or not. The easiest way to find out is by looking at the beginning and/or ending of the badiptlist.txt file. Do this: less badiptlist.txt (or "more badiptlist.txt" or just load the file into a text editor of your choice) Look for the line of text that says "*nat" at the beginning of the line. Most likely it will be the very first line. If it is followed by three lines that each begin with a colon ':', then your defaultrules file was found OK. === Load the kernel with the new rules ======== Now, let's load the new rule sets into the kernal. You will probably have to be logged in with root privileges to do this operation. If you can't do that, you'll have to get someone who can. With the defaultrules file in use, do the following at a command prompt: iptables-restore < badiptlist.txt If you did not use the defaultrules file, do this instead: iptables-restore -n < badiptlist.txt The -n parameter tells iptables not to flush the existing rules. This will keep the rules that are already in the kernel and install the additional ones from our newly created badiptlist.txt file. You can also do this later on if you want to add one or two countries to the blocking rules that you are installing now. If so, just make sure the defaultrules file isn't accessible. Or go ahead and create a whole new complete file and install the whole thing without the -n parameter. Either way works. On the other hand, with the defaultrules file included, then it's OK to have the existing rules flushed because we will be reinstalling them from the badiptlist.txt file. On a fast server with some memory, this process of installing the badiptlist.txt file into the kernel will only take a few seconds, even if the file is huge. However, on a slow server or one that has very little memory, it will take much longer. My firewall machine is a 166mhz system with 256K of ram. It takes in the 10000+ lines in about 5 seconds. But my DNS server is a 486-66 with only 36MB of memory. The first time I installed the 10000+ lines of rules, I thought something went wrong. It took over 15 minutes. So... be patient depending on your individual setup. I suspect the big difference is the amount of memory in the machine and not the processor speed. Amazingly, the old 486 took it all in and is handling it nicely. I had to install this on the DNS machine because that machine doesn't sit behind the firewall machine. As for the rest of the machines on my local network, they didn't need this installed because they all sit behind the firewall machine. The firewall machine does all the work of blocking for those machines. === Save for the next reboot ======== Now you think that maybe you have to write a script or something so that these new rules get installed into the kernal each time your machine reboots. Not so. You can have iptables save the newly installed rules for you and automatically use them at every reboot. Your system might vary from how I'll describe mine, and if so, you'll have to do a little digging to figure it out. But I'm sure it's similar. On my Debian system, I just do the following from a command prompt as root: /etc/init.d/iptables save active Iptables will then save the rules from the kernel to a file that will be loaded during bootup. This part goes quickly, even on the slow (and low memory) 486. And it pulls the data in during bootup quickly as well, even on the slow 486. If you're Linux distribution also uses the /etc/init.d/ method during bootup, then you can probably do the above, however, your system might be different. If so, read on. (otherwise, skip to the next section) As an example, on a recent SUSE Linux system, I've done the following: First create a directory where the 'active' file should reside. A good place might be in the /var/lib/iptables/ if that exists on your system. If not, you can create that directory. You'll have to be logged in as 'root' to do this. Do the following two commands from a command prompt (actually don't do the first one if the /var/lib/iptables/ directory already exists): mkdir /var/lib/iptables iptables-save > /var/lib/iptables/active You have now saved the entire set of rules from the kernel into a file called 'active' in the /var/lib/iptables/ directory. Next, we need a way for this to be loaded in by default whenever the machine has to be rebooted. There is a file you can edit to add anything you'd like performed during bootup. It's called 'boot.local' and can be found in the /etc/rc.d/ directory. Using a text editor, add the following line in this file: iptables-restore /var/lib/iptables/active Check your particular Linux distribution to find out where you can add something like the above to be performed during bootup. They don't all do things the same exact way. I've described how you can do this with Debian and SUSE. Other systems might use one of these two methods, while others will use something different. Do a little digging, I'm sure you can figure it out. === Performance ======== When I first installed my 10000+ lines of iptables rules, I was afraid that it would really bog things down. I was worried that incoming connections would be real slow. After all, before the kernel can allow a legitimate connection to be made, it must search through the whole list of rules to see if the incoming IP address should be accepted. I figured I'd probably have to just undo it all and put up with the constant hacking attempts. Was I relieved when I discovered no real difference in performance. Even the 486 is handling 10000+ rules without any noticeable lag. It's a Linux text only machine with 36MB of memory and it doesn't even touch the swap partition. It's obvious that the iptables functionality in the Linux kernel is very efficient. If it wasn't, my 486 powered DNS server wouldn't be running right now. The only holdup with that machine is the initial installation of the code into the kernel. From that point on, it's as smooth as can be. My firewall machine is more powerful and has more memory. It does the initial loading very quickly and handles the incoming connections very efficiently. It appears that only the very first packet coming in is slowed down by about 8-10 milleseconds. That's absolutely nothing to worry about. Any user accessing my web site can't possibly notice that initial delay. The best part is the whole setup runs smoother because a lot of bandwidth isn't getting unnecessarily used up by unwanted bad guys. If someone is trying to access my website from a country that is being blocked, their first packet arrives and is completely ignored by the kernel. No response is returned at all. To the person at the other end, it looks as if my IP address either isn't in use or the power is off causing no response. That one packet arriving adds very little to the bandwidth usage. It's much better having several thousand bad guys sending in one useless packet than those several thousand bad guys scouring my website for email addresses and making hacking attempts. For the countries I don't block, everything appears normal to these people. I think that's about it for getting everything going. I probably wrote a lot more stuff here than I needed to, but it never hurts to have clear instructions, and with examples! Have fun... -Maurice http://fixingtheweb.com http://cmdrkey.com http://cbmfiles.com http://wellscargosales.com email: maurice@fixingtheweb.com email: support@fixingthweb.com Maurice Randall % Click Here Software P.O. Box 606 Charlotte MI 48813 PH: (517) 543-5202 |