Geoip blocker for Linux. Supports both nftables and iptables firewall management utilities.
The idea of this project is making geoip blocking easy on (almost) any Linux system, no matter which hardware, including desktop, server, VPS or router, while also being reliable and providing flexible configuration options for the advanced users.
Supports running on OpenWrt. Supports ipv4 and ipv6.
Core functionality is creating either a whitelist or a blacklist in the firewall using automatically downloaded ip lists for user-specified countries.
ip lists are fetched either from RIPE (regional Internet registry for Europe, the Middle East and parts of Central Asia) or from ipdeny. Both sources provide updated ip lists for all regions.
All firewall rules and ip sets required for geoip blocking to work are created automatically during installation or setup.
Implements optional (enabled by default) persistence of geoip blocking across system reboots and automatic updates of the ip lists.
After installation, a utility is provided to check geoip status and firewall rules or change country codes and geoip-related config.
NOTE: Installation can be run interactively, which does not require any command line arguments and gathers the important config via dialog with the user. Alternatively, config may be provided via command-line arguments.
Some features are only accessible via command-line arguments.
To find out more, use sh geoip-shell-install.sh -h
or read NOTES.md and DETAILS.md
(Note that some commands require root privileges, so you will likely need to run them with sudo
)
1) If your system doesn't have curl
, wget
or (OpenWRT utility) uclient-fetch
, install one of them using your distribution's package manager (for Debian and derivatives: apt-get install curl
). Systems which only have iptables
also require the ipset
utility (apt-get install ipset
).
2) Download the latest realease: https://github.com/friendly-bits/geoip-shell/releases. Unless you are installing on OpenWrt, download Source code (zip or tar.gz). For installation on OpenWrt, read the OpenWrt README.
Or download using the command line:
either run git clone https://github.com/friendly-bits/geoip-shell
- this will include all the latest changes but may not always be stable
or to download the latest release (requires curl):
curl -L "$(curl -s https://api.github.com/repos/friendly-bits/geoip-shell/releases | grep -m1 -o 'https://api.github.com/repos/friendly-bits/geoip-shell/tarball/[^"]*')" > geoip-shell.tar.gz
to extract, run: tar -xvf geoip-shell.tar.gz
3) Extract all files included in the release into the same folder somewhere in your home directory and cd
into that directory in your terminal.
4) For interactive installation, run sh geoip-shell-install.sh
.
NOTE: If the install script says that your shell is incompatible but you have another compatible shell installed, use it instead of sh
to call the -install script. For example: dash geoip-shell-install.sh
. Check out Pre-Requisites for a list of compatible shells. If you don't have one of these installed, use your package manager to install one (you don't need to make it your default shell).
Examples for non-interactive installation options:
installing on a server located in Germany, which has nftables and is behind a firewall (no direct WAN connection), whitelist Germany and Italy and block all other countries:
sh geoip-shell-install.sh -m whitelist -c "DE IT" -r DE -i all -l auto -O performance
installing on a router located in the US, blacklist Germany and Netherlands and allow all other countries:
sh geoip-shell-install.sh -m blacklist -c "DE NL" -r US -i pppoe-wan
if you prefer to fetch the ip lists from a specific source, add -u <source>
to the arguments, where <source>
is ripe
or ipdeny
.
to block or allow specific ports or ports ranges, use <[tcp|udp]:[allow|block]:[ports]>
. This option may be used twice in one command to specify ports for both tcp and udp (for examples, read NOTES.md, sections 9-11).
to exclude certain trusted ip addresses or subnets on the internet from geoip blocking, add -t <"[trusted_ips]">
to the arguments
if your machine uses nftables, depending on the RAM capacity of the machine and the number and size of the ip lists, consider installing with the -O performance
or -O memory
option. This will create nft sets optimized either for performance or for low memory consumption. By default, when the machine has more than 2GiB of memory, the performance
option is used, otherwise the memory
option is used.
if your distro (or you) have enabled automatic nftables/iptables rules persistence, you can disable the built-in cron-based persistence feature by adding the -n
(for no-persistence) option when running the -install script.
if your system has nftables installed and also a package like xtables-compat (utilizing the nft_compat module) which allows to manage the nftables backend using iptables rules, you can override the geoip-shell default to directly utilize the nftables backend with option -w ipt
. This will create iptables rules and ipsets for geoip-shell rather than nftables rules and sets. You will need the ipset
utility installed for this.
if for some reason you need to install geoip-shell in strictly non-interactive mode, you can call the install script with the -z
option which will avoid asking the user any questions. geoip-shell will get installed but initial setup will fail if required config is incomplete or invalid.
5) The install script will ask you several questions to configure the installation, then initiate download and application of the ip lists. If you are not sure how to answer some of the questions, read SETUP.md.
6) That's it! By default, ip lists will be updated daily around 4:15am local time (to avoid everyone loading the servers at the same time, the default minute is randomized to +-5 precision at the time of initial setup and the seconds are randomized at the time of automatic update).
(Note that all commands require root privileges, so you will likely need to run them with sudo
)
Generally, once the installation completes, you don't have to do anything else for geoip blocking to work (if you installed via an OpenWrt ipk package, read the OpenWrt README).
If you want to change geoip blocking config or check geoip blocking status, you can do that via the provided utilities.
A selection of options is given here, for additional options run geoip-shell -h
or read NOTES.mdand DETAILS.md.
To check current geoip blocking status: geoip-shell status
. For a list of all firewall rules in the geoip chain and for a detailed count of ip ranges in each ip list: geoip-shell status -v
.
To add or remove ip lists for countries: geoip-shell <add|remove> -c <"country_codes">
Examples:
geoip-shell add -c "DE NL"
geoip-shell remove -c DE
To enable or disable geoip blocking: geoip-shell <on|off>
To change ip lists source: geoip-shell configure -u <ripe|ipdeny>
To change geoip blocking mode: geoip-shell configure -m <whitelist|blacklist>
To have certain trusted ip addresses or subnets bypass geoip blocking: geoip-shell configure -t <["ip_addresses"]|none>
. none
removes previously set trusted ip addresses.
To have certain LAN ip addresses or subnets bypass geoip blocking: geoip-shell configure -l <["ip_addresses"]|auto|none>
. auto
will automatically detect LAN subnets (only use this if the machine has no dedicated WAN interfaces). none
removes previously set LAN ip addresses. This is only needed when using geoip-shell in whitelist mode, and typically only if the machine has no dedicated WAN network interfaces. Otherwise you should apply geoip blocking only to those WAN interfaces, so traffic from your LAN to the machine will bypass the geoip filter.
To change protocols and ports geoblocking applies to: geoip-shell configure -p <[tcp|udp]:[allow|block]:[all|<ports>]>
(for detailed description of this feature, read NOTES.md, sections 9-11)
To enable or change the automatic update schedule: geoip-shell configure -s <"schedule_expression">
Example
geoip-shell configure -s "1 4 * * *"
To disable automatic updates of ip lists: geoip-shell configure -s disable
To update or re-install geoip-shell: run the -install script from the (updated) distribution directory. It will first run the -uninstall script of the older/existing version, then install the new version.
To uninstall: geoip-shell-uninstall.sh
On OpenWrt, if installed via an ipk package: opkg uninstall <geoip-shell|geoip-shell-iptables>
(if a pre-requisite is missing, the -install.sh script will tell you which)
POSIX-compliant shell. Works on most relatively modern shells, including bash, dash, ksh93, yash and ash (including Busybox ash). Likely works on mksh and lksh. Other flavors of ksh may or may not work (please let me know if you try them). Does not work on tcsh and zsh.
NOTE: If the install script says that your shell is incompatible but you have another compatible shell installed, use it instead of sh
to call the -install script. For example: dash geoip-shell-install.sh
The shell you use to install geoip-shell will be the shell it runs in after installation. Generally prefer the simpler shells (like dash or ash) over complex shells (like bash and mksh) due to better performance.
Optional: the check-ip-in-source.sh optional script requires grepcidr. install it with apt install grepcidr
on Debian and derivatives. For other distros, use their built-in package manager.
For some helpful notes about using this suite, read NOTES.md.
For specifics about each script, read DETAILS.md.
For information about OpenWrt support, read the OpenWrt README.
geoip-shell does not share your data with anyone. If you are using the ipdeny source then note that they are a 3rd party which has its own data privacy policy.