Home
Please see the sidebar to the right (bottom of page for mobile) for links to all available documentation.
The project was created for people looking to do firewall GeoIP filtering on a variety of different systems with nftables. It provides a full featured program that's easy to set up and use. The following is an outline of the feature set that the project was designed to provide. It offers some background on the various program features and design decisions.
- Written for the popular Bash Shell. Since GeoIP scripts affect the function of the firewall, it's important to understand what the script is doing without having to install or learn a higher level programming language. The source code is heavily commented to make it easier to understand and customize. Bash also has a small memory footprint which is beneficial to systems with limited RAM.
- Use a "EULA free" GeoIP database. A large number of GeoIP firewall installations have no need to agree to a GeoIP database EULA, so it makes sense to use a database without one.
- Automatic GeoIP database updates. Once this is set up it should "just work" without the need for user intervention.
- Soft links to the GeoIP script and systemd service files in system directories. This allows updated versions of the GeoIP script and project files to be used automatically, without having to remember to copy multiple files to different system directories after updating.
-
Definitions of GeoIP set elements all in one file. By using the same definition file
refill-sets.nftto fill sets at boot time as well as refilling sets after a database update, it eliminates the possibility of having one list of country codes loading at system boot and a different list loading after a database update. The User Guide has detailed information on how to set this up. - Generate the list of valid country codes from the GeoIP database itself. If a GeoIP program uses a third-party location file to generate the country code list then it can make scores of valid IP address ranges in the database unavailable to the end user. This would include any new country codes that db-ip.com may add to their database that don't exist in the third-party location file. GeoIP for nftables creates the country code list directly from the database itself, making all of the latest valid country codes available to the end user.
- Determine the installed version of nftables from the nft program to accommodate limitations in older versions. Since distribution repositories tend to lag behind the latest version of nftables, it's useful to have a version check so the program can proceed accordingly.
- Create "include-all" files to allow including all GeoIP sets on older versions of nftables <= 0.9.3. Many users want the convenience of including all GeoIP sets in their ruleset so they don't have to remember to include each country code that they reference with a firewall rule. The generated include-all files allow all GeoIP sets within a given Internet Protocol version to be included in a ruleset with a single reference on older versions of nftables <= 0.9.3.
-
Store user settings in a standard configuration file. It's no fun trying to remember the correct command line string months after installing a program. With settings in a standard configuration file the GeoIP for nftables script can be launched in a terminal simply with:
sudo geoip-nft - Save the current GeoIP database locally and use the local copy instead of downloading a new copy each time. This allows the user to run the GeoIP script over and over during testing without being a burden to db-ip.com. They generously make their database available for free, so minimizing downloads respects their bandwidth. The GeoIP script will check the date of the locally stored database and only download a new version if it's out-of-date.
- Generate GeoIP sets with starting and ending IP address ranges directly from the database. It's preferable to pass the IP address ranges directly from the GeoIP database to nftables (without converting to CIDR notation first) since they will be automatically converted by nftables when loaded. This results in GeoIP sets with far fewer elements to represent the same address ranges since nftables will only convert an address range to CIDR notation if the end result is a single address range. Passing the address ranges straight from the database to nftables also makes it easier to verify that GeoIP sets contain the correct data. You can directly match starting and ending IP addresses between the GeoIP set files and the database file.
- GeoIP filtering for servers, workstations and embedded systems like the Raspberry Pi. The code has been tested on Ubuntu Server, Fedora Server and Raspberry Pi OS. It should run on many systemd-based distributions with little or no modifications.
- Avoid non-inclusive language in the source code and documentation.
- Combine Geo and IP to form a unique name for the GeoIP for nftables project.
GeoIP for nftables documentation is licensed under the GNU GPLv2 (or at your option, any later version).