geoip-shell turns country based IP blocking into a scripted firewall setup

What the project actually does

geoip-shell is described as a user-friendly and versatile geoblocker for Linux supporting both nftables and iptables firewall management utilities. The stated idea is to make geoblocking, meaning restricting access from or to Internet addresses based on geolocation, easy on almost any Linux system regardless of hardware, including desktop, server, container, VPS or router, while staying reliable and offering flexible configuration options for advanced users. The core functionality is creating either a whitelist or a blacklist in the firewall using automatically downloaded IP lists for user-specified countries. All firewall rules and IP sets required for geoblocking are created automatically during the initial setup, and the suite supports automated interactive setup for configuration. The primary language of the repository is Shell, and the project is GPL-3.0 licensed with the default branch main. The last push was on 2026-10-04, and the release history is steady, with v0.8.6 on 2026-10-04, v0.8.5 in August 2026 and v0.8.4 in May 2026. The repository tree shows the shape of the thing: separate scripts for install, apply, fetch, backup, cron setup, geo initialisation, management, run and uninstall, plus a lib/ directory, a Documentation/ directory, an OpenWrt/ directory, a check-ip-in-source.sh utility and a cca2.list file.

Where the IP lists come from

The source choice is the most consequential decision, and the README is unusually clear about it. Lists are fetched either from RIPE, the regional Internet registry for Europe, the Middle East and parts of Central Asia, with additional supported sources of ipdeny, MaxMind and IPinfo, and all supported sources provide updated IP lists for all regions. The reliability section explains the trade-off in one sentence: the default source is RIPE, which allows the project to avoid dependency on non-official third parties, while the MaxMind and IPinfo sources are commercial and provide more accurate IP lists. For MaxMind both the free GeoLite2 database and the paid GeoIP2 database are supported, and for IPinfo any type of license is supported, though using either of these requires an account with the respective provider. There is a fourth source, ipdeny, which provides aggregated IP lists and is described as useful for embedded devices with limited memory. So the choice is between a registry feed that is free and self-sufficient, a commercial database that is more precise but needs credentials, and an aggregated feed that is cheap to store on small hardware.

How the rules land in the firewall

The mechanism differs by backend, and the difference explains the design. With nftables the project uses the native nftables sets, which allow creating efficient firewall rules with thousands of IP ranges, and it relies on nftables atomic rules replacement to make the interaction with the system firewall fault tolerant and to completely eliminate the time when geoblocking is disabled during an automatic update. That last property is the important one: a naive implementation tears down the old rules and builds the new ones, and for the duration of that window the firewall is open. With iptables the same job is done through the ipset utility instead, where automatic optimization is implemented. On the inbound side the project uses the prerouting hook in the kernel's netfilter component, which shortens the path unwanted packets travel in the system and may reduce CPU load if additional firewall rules process incoming traffic further down the line. The IP list parsing and validation are implemented through efficient regex processing, which the README says is very quick even on slow embedded CPUs, and the whole design assumes the shell suite is only active for a short time when invoked either directly by the user or by the init script, reboot cron job or update cron job.

Reliability work that most scripts skip

Several behaviours here are the difference between a script and a tool you can put on a router. Downloaded IP lists go through validation, which safeguards against applying corrupted or incomplete lists to the firewall. All scripts perform extensive error detection and handling, all user input is validated to reduce the chance of accidental mistakes, and the firewall rules coherence is verified after each action. State is backed up automatically, optional but enabled by default except on OpenWrt, and the firewall rules are recovered automatically after a reboot or in case of unexpected errors. Downloads are smart, using data timestamp checks to avoid unnecessary downloads and reconfiguration. There is also a safety valve for the failure mode that matters most in a remote setting: the project supports specifying trusted IP addresses anywhere on the Internet which bypass geoblocking, to make it easier to regain access to the machine if something goes wrong. Persistence of geoblocking across system reboots and automatic updates of the IP lists are optional but enabled by default.

The installer, the checkers and the utilities

The user-facing surface is unusually wide for a shell suite, and the README enumerates it. Before installation there is a utility, check-ip-in-source.sh, to check whether specific IP addresses you might want to block or allow are indeed included in the IP lists fetched from the source, which is the sensible first command to run because it answers the question the installer cannot: will the list you are about to load actually contain the ranges you expect. After installation there is a utility symlinked to geoip-shell for changing configuration, covering turning geoblocking on or off, configuring outbound geoblocking, changing country codes, changing the geoblocking mode, changing the IP lists source and changing the cron schedule. There is a geoip-shell status command to check geoblocking status, which also reports if there are any issues, and it is described as a way to check the firewall rules as well as the configuration. Installation and initial setup are said to take a very short time, there is a good command line interface and useful console messages, all main scripts display detailed usage information when executed with the -h option, and the project ships an uninstall script which completely removes the suite and the geoblocking firewall rules with no restart required.

Outbound blocking, allowlists and OpenWrt

Beyond the basic inbound case, the feature list includes outbound geoblocking, so a host can be prevented from reaching addresses in other countries as well as being protected from them. Local allowlists and blocklists are listed as their own section of the documentation, and the setup automates auxiliary firewall rule creation based on the user's preferences, with the example that when configuring on a host in whitelist mode, geoip-shell will detect LAN IP ranges and suggest adding them to the whitelist, which is the step that otherwise locks a server out of itself. The project supports running on OpenWrt, and it is written in POSIX-compliant shell code so it is compatible with virtually every Linux system as long as the pre-requisites are met. Two behaviours differ on OpenWrt, since automatic backup of the geoip-shell state is enabled by default except on OpenWrt, and the repository carries a dedicated OpenWrt/ directory for that target. A note on privacy completes the picture: the README has a privacy section, which for a tool that fetches country lists and applies them to your firewall is the section a careful reader should read before installing.

Where geoip-shell is the wrong choice

Four limits are worth naming. The first is the level at which the decision is made. Country IP lists describe where an address is registered, so a corporate exit, a VPN endpoint or a cloud provider's range is attributed to the country of that provider, and a person using a VPN appears wherever the VPN is. The project also cannot distinguish a residential subscriber from a data centre, so a whitelist that is supposed to admit a country can admit a large hosting range with it. If your requirement is to block abusive traffic rather than to apply policy by country, address list reputation or application level rate limiting is the right mechanism. The second is that geoip-shell manages your firewall, which means it sits on the critical path of your network's connectivity. A misconfigured whitelist mode on a remote host is a self-inflicted lockout, which is why the trusted IP bypass and the pre-installation source checker exist, and why you should test on a console you can reach before applying it to a production gateway. The third is the shell dependency chain. The project's compatibility claim rests on POSIX shell plus the pre-requisites, and while that is a genuinely wide reach, it also means behaviour can differ across distributions and BusyBox based systems in ways the README does not enumerate. The fourth is the scale of the rules. Thousands of ranges in a firewall is normal for this approach, but it is still thousands, and on a small router under memory pressure the optimisation the README describes for nftables, choosing between low memory consumption and performance based on the machine's RAM and user preference, is the knob you will need. The realistic alternative for a static rule set is to maintain the ranges yourself with a small script and ipset, which you will then own, and the alternative for a managed commercial requirement is a provider of geofenced CDN or WAF rules, which costs money but comes with updates and support.

Editorial conclusion

Adopt geoip-shell if you want country based blocking on a Linux firewall, whether that is a home router, a VPS or a container host, because the installer builds the rules and the list sets for you and keeps the lists current without a rebuild. Do not adopt it if you need application level geolocation, because the decision is made at the packet level from a country IP list and a hosting provider's address range says nothing about where a person actually is. Verify two things before you lock the firewall down: that the source you choose matches the accuracy you need, since the README names RIPE as the default precisely to avoid depending on non-official third parties while MaxMind and IPinfo are the more accurate commercial options, and that your mode choice is right, since whitelist mode on a remote machine can cut you out of it and the project offers trusted IP addresses as the escape hatch. The practical first step is to run check-ip-in-source.sh with a few addresses you care about, before installation, to confirm the chosen source's lists actually contain them.

Frequently asked questions

Official sources

1. friendly-bits/geoip-shell on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases