Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
ipdbtools(1)		FreeBSD	General	Commands Manual		  ipdbtools(1)

     ipup - ipdb - -- Tools for generating IP based Geo-block-
     ing and Geo-routing tables	in order to configure the system's firewall
     and/or routing facilities

     ipup [-h] [-r bstfiles] <IP_address>

     ipup [-h] -t CC:DD:.. | CC=nnnnn:DD=mmmmm:.. | "" [-n table_number]
	  [-v table_value] [-x offset] [-p] [-4] [-6] [-r bstfiles]

     ipup [-h] -q CC

     ipdb <outnamebase>	<datafile1> <datafile2>	<datafile3> ... [<>]

     In	general, access	control	by the firewall	is established by selectors
     that can be attributed to incoming	and outgoing IP	packets, like physical
     interfaces	on which the packets are going,	source and destination IP ad-
     dresses, protocol types, port numbers, content types and content, etc.,
     and routing is determined by destination IP addresses. The	Geo-location
     would be just another selector, but this information is not carried ex-
     plicitly with IP packets, however,	it can be obtained using the IP	ad-
     dress as a	key for	looking-up the location	in an IP database. For exam-
     ple, the country to which a given IP address is delegated,	can be ob-
     tained with the common Unix tool whois(1).

     whois does	an online look-up in the IP databases of the 5 Regional	Inter-
     net Registries (AFRINIC, APNIC, ARIN, LACNIC, RIPENCC), and this is the
     most reliable way to obtain the country code for a	given IP address, be-
     cause the RIR's are the authorities for internet number delegations. Un-
     fortunately, online database look-up is by	far too	slow for even thinking
     about being utilized on the firewall level, where IP packets need to be
     processed in a microsecond	time scale. Therefore, a locally maintained IP
     Geo-location database is indispensable in the given respect. The System's
     own routing and filtering tables can be configured	to do these tasks if
     there is a	source of the appropriate data.	The ipdbtools(1) are designed
     to	provide	this data and to assist	managing and using it.

     The three tools in	the package are:

       ipup	       A tool to utilize the IP	Geo-location tables to look-up
		       the country code	belonging to an	IP address or generate
		       sorted lists of CIDR compatible IP address/masklen
		       pairs per country code, formatted as raw	CIDR ranges or
		       ipfw(8) table construction directives.

       ipdb	       A tool for consolidating	the IP address ranges from the
		       RIR delegation statistics files into binary sorted ta-
		       bles of IP ranges + country codes, suitable for direct
		       utilization by the ipup look-up tool. IPv4 and IPv6
		       ranges are stored in separate files.  A shell script to update	the IP Geo-location tables by
		       downloading the 5 RIR delegation	statistics files from
		       a Regional Internet Registry mirror, and	invoking ipdb
		       to generate the binary sorted tables. It	is suitable
		       for invocation by cron.

Setting	up the local IP	Geo-location tables
     The authoritative IP Geo-location information must	be obtained from the 5
     RIR's, and	compiled into an optimized format, suitable for	quickly	look-
     ing-up the	country	codes of given IP addresses. This information is
     present in	so called delegation statistics	files on the ftp servers of
     each RIR, and APNIC, LACNIC and RIPENCC mirror the	files of the other
     RIR's on their servers - as of the	date of	this writing, ARIN and AFRINIC
     do	not mirror current delegation statistics of the	other RIR's.

     1)	Choose one of the three	useful mirror sites, depending on where	you
     are located:	RIPENCC	-- Europe and Eurasia [default mirror]	APNIC -- Asia Pacific	LACNIC -- Latin	America	and Caribbean

     2)	As user	root execute the shell script with the chosen
     mirror as the parameter, for example

      /usr/local/etc/ipdb/IPRanges/afrinic.md5	100% of	  74  B	 277 kBps 0s
      /usr/local/etc/ipdb/IPRanges/afrinic.dat	100% of	 397 kB	1330 kBps 0s
      /usr/local/etc/ipdb/IPRanges/apnic.md5	100% of	  73  B	 264 kBps 0s
      /usr/local/etc/ipdb/IPRanges/apnic.dat	100% of	4045 kB	1259 kBps 4s
      /usr/local/etc/ipdb/IPRanges/arin.md5	100% of	  67  B	 246 kBps 0s
      /usr/local/etc/ipdb/IPRanges/arin.dat	100% of	8160 kB	1270 kBps 7s
      /usr/local/etc/ipdb/IPRanges/lacnic.md5	100% of	  74  B	 274 kBps 0s
      /usr/local/etc/ipdb/IPRanges/lacnic.dat	100% of	1870 kB	1271 kBps 2s
      /usr/local/etc/ipdb/IPRanges/ripencc.md5	100% of	  74  B	 270 kBps 0s
      /usr/local/etc/ipdb/IPRanges/ripencc.dat	100% of	  10 MB	1258 kBps 9s
      ipdb v1.1.2 (128), Copyright (C) 2016-2018 Dr. Rolf Jansen
      Processing RIR data files	...

       afrinic.dat  apnic.dat  arin.dat	 lacnic.dat  ripencc.dat

      Number of	processed IP-Ranges = 113267

     As	shown above, this will download	the delegation statistics data to-
     gether with MD5 hashes for	integrity checking into	the directory
     /usr/local/etc/ipdb/IPRanges/.  Then the ipdb tool	will process the data
     files and generate	two binary sorted table	(.bst) files, one for the IPv4
     ranges /usr/local/etc/IPRanges/ipcc.bst.v4	and another one	for the	IPv6
     ranges /usr/local/etc/IPRanges/ipcc.bst.v6.

     Quering the local IP Geo-location tables

     Use the ipup tool for the various queries:

     -h	      Show the usage instructions.

     [-r bstfiles]
	      Base path	to the binary sorted tables (.v4 and .v6) with the
	      consolidated IP ranges which were	generated by the ipdb tool
	      [default:	/usr/local/etc/ipdb/IPRanges/ipcc.bst].

     First usage form -- CC query:

	      IPv4 or IPv6 address for which the country code should be

     Second usage form -- firewall and routing table generation:

     -t	CC:DD:.. | CC=nnnnn:DD=mmmmm:..	| CC:DD=ooooo:EE;.. | ""
	      Output all IP address/masklen pairs belonging to the listed
	      countries, given by 2 letter capital country codes, separated by
	      colon. An	empty CC list (denoted by "") means any	country	code.
	      A	table value can	be assigned per	country	code in	the following
		-t BR=10000:DE=10100:US:CA:AU=10200.
	      In the case of no	assignment, no value [0] or the	global value
	      defined by either	the -v or the -x option	is utilized.

     [-n table_number]
	      The ipfw table number between 0 and 65534	[default: 0].

     [-v table_value]
	      A	global 32-bit unsigned value for all ipfw table	entries	[de-
	      fault: no	value -> 0].

     [-x offset]
	      Decimal encode the given CC and add it to	the offset for comput-
	      ing the table value:
	      value = offset + ((C1 - 'A')*26 +	(C2 - 'A'))*10.

     [-p]     Plain IP table generation, i.e. without ipfw table construction
	      directives, and any -n, -v and -x	flags are ignored in this

     [-4]     Process only the IPv4 address ranges.

     [-6]     Process only the IPv6 address ranges.

     Third usage form -- compute the encoded value of a	country	code:

     -q	CC    The country code to be encoded (see -x flag above).

     Check whether the IP Geo-location tables are ready	by looking-up some ad-
     dresses using the ipup tool:

     $ ipup in - in	ES

     $ ipup in - in DE

     $ ipup in - in US

     $ ipup not	found

     $ ipup 2001:0618:85a3:08d3:1319:8a2e:0370:7344
	2001:0618:85a3:08d3:1319:8a2e:0370:7344	in 2001:618:0:0:0:0:0:0	-
     2001:618:ffff:ffff:ffff:ffff:ffff:ffff in CH

Firewall Examples
     ipup can be used for Geo-blocking together	with ipfw(8). For this pur-
     pose, ipup	would generate tables of CIDR ranges for the selected country
     codes, and	these tables can be directly piped into	ipfw(8). The respec-
     tive configuration	script may contain something like:

     # Allow only web access from DE, BR, US:
     /usr/local/bin/ipup -t DE:BR:US -n	7 | /sbin/ipfw -q /dev/stdin
     /sbin/ipfw	-q add 70 deny tcp from	not table\(7\) to any 80,443 in	recv
     em0 setup

     OR	vice versa:

     # Deny web	access from certain countries we don't like this week:
     /usr/local/bin/ipup -t TR:SA:RU:GB	-n 66 |	/sbin/ipfw -q /dev/stdin
     /sbin/ipfw	-q add 70 allow	tcp from not table\(66\) to any	80,443 in recv
     em0 setup

     In	the case of a different	firewall facility, a plain table (without ipfw
     directives) can be	generated using	ipup by	specifying the -p flag.	The
     table may be piped	into a pre-processing command before being passed to
     the firewall utility:

     # Output data in the format of some other fictional firewall:
     /usr/local/bin/ipup -t FR:ES:PT -x0 | awk '{print "add-filter", $4, $5}'


     /usr/local/bin/ipup -p -t US:CA | while read TABLE	NUM ADD	ADDR VAL; do
     myfirewall	add filter $ADDR value $VAL; done

Routing	Example
     ipup is well suited for manipulating the system's routing table by	the
     way of the	route(8) utility:
     # Force packets to	Austria	to take	a different route:
     /usr/local/bin/ipup -p -t AT | while read LINE; do	/sbin/route add	$LINE
     $SOMEROUTER; done

Cronjob	for keeping the	IP Geo-location	tables updated may	be executed by a weekly	(perhaps daily)	cronjob, for
     this you might want to add	the following entry to /etc/crontab:

     # Weekly update of	the IP Geo-location tables
       5    4	 *    *	   6	root	/usr/local/bin/ ftp.ap- > /dev/null 2>&1 && /fullpath/to/fw_or_router_reinit_script

       directory for maintaining the IP	Geo-location tables

       binary (uint32_t) sorted	table of IPv4 ranges and its country codes

       binary (uint128t) sorted	table of IPv6 ranges and its country codes

     whois(1), ipfw(8),	route(8)

     in	Ports: ip2cc(1), IP::Country(3)

     Dr. Rolf Jansen - Copyright (c) 2016 - all	rights reserved.

     Improper use of the ipdb tools may	result in erroneous IP tables, and
     firewalls or routers may be rendered non-functional once configured with
     incorrect tables.

     In	NO event shall the author and/or copyright owner be liable for ANY
     damages resulting from ANY	use of this software. Use the ipdb tools at
     your own risk!

     The ipdb tools have been carefully	developed and tested. Anyway, the
     tools are provided	without	any expressed or implied warrantee of being
     100 % bug free.

FreeBSD, Darwin		       October 18, 2021		       FreeBSD,	Darwin

NAME | SYNOPSIS | DESCRIPTION | Setting up the local IP Geo-location tables | USAGE AND OPTIONS | EXAMPLES | Firewall Examples | Routing Example | Cronjob for keeping the IP Geo-location tables updated | FILES | SEE ALSO | AUTHOR | IMPORTANT NOTE | BUGS

Want to link to this manual page? Use this URL:

home | help