Home

Awesome

geoip-shell

Powerful geoblocker for Linux. Supports both nftables and iptables firewall management utilities.

The idea of this project is making geoblocking (i.e. restricting access from or to Internet addresses based on geolocation) easy on (almost) any Linux system, no matter which hardware, including desktop, server, container, VPS or router, while also being reliable and providing flexible configuration options for the advanced users.

If you find this project useful, please take a second to give it a star on Github. This helps other people to find it.

image image

Table of contents

Main Features

Reliability:

<details> <summary>Read more:</summary> </details>

Efficiency:

<details><summary>Read more:</summary> </details>

User-friendliness:

<details><summary>Read more:</summary> </details>

Compatibility:

<details><summary>Read more:</summary> </details>

Installation

(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. <details><summary>Or download using the command line:</summary>

</details>

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 installation followed by interactive setup, run sh geoip-shell-install.sh. For non-interactive installation, run sh geoip-shell-install.sh -z.

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).

5) Unless you installed in non-interactive mode, the install script will suggest you to configure geoip-shell. If you type in y, geoip-shell will ask you several questions, then initiate download and application of the ip lists.

Initial setup

Once the installation completes, the installer will suggest to automatically start the interactive setup. If you ran the install script non-interactively or interrupted the setup at some point, you can manually (re)start interactive setup by running geoip-shell configure.

Interactive setup gathers the important config via dialog with the user and does not require any command line arguments. If you are not sure how to answer some of the questions, read SETUP.md.

Alternatively, some or all of the config options may be provided via command-line arguments.

NOTE: Some features are only accessible via command-line arguments. In particular, by default, initial setup only configures inbound geoblocking and leaves outbound geoblocking in disabled state. If you want to configure outbound geoblocking, read the section Outbound geoblocking.

To find out more, run geoip-shell -h or read NOTES.md and DETAILS.md

Usage

(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 inbound geoblocking to work (if you installed via an OpenWrt ipk package, read the OpenWrt README).

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).

If you want to change geoblocking config or check geoblocking 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.md and DETAILS.md.

Note that when using the geoip-shell configure command, if direction is not specified, direction-specific options apply to inbound geoblocking. Direction-specific options are -m <whitelist|blacklist|disable>, -c <country_codes>, -p <ports>. To specify direction, add -D <inbound|outbound> before specifying options for that direction (for more details, read the section Outbound geoblocking).

To check current geoip blocking status: geoip-shell status. For a list of all firewall rules in the main geoblocking chains and for a detailed count of ip ranges in each ip list: geoip-shell status -v.

To configure geoblocking mode:

geoip-shell configure -m <whitelist|blacklist|disable>

(disable unloads all ip lists and removes firewall geoblocking rules for both directions)

To change countries in the geoblocking whitelist/blacklist:

geoip-shell configure -c <"country_codes">

<details><summary>Example:</summary>

</details>

To geoblock or allow specific ports or ports ranges:

geoip-shell configure -p <[tcp|udp]:[allow|block]:[all|<ports>]>

(for detailed description of this feature, read NOTES.md, sections 10-12)

To enable or disable geoblocking (only adds or removes the geoblocking enable rules, leaving all other firewall geoblocking rules and ip sets in place):

geoip-shell <on|off>

To change ip lists source: geoip-shell configure -u <ripe|ipdeny>

To have certain trusted ip addresses or subnets, either in your LAN or anywhere on the Internet, bypass geoblocking:

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>

LAN addresses can only be configured when geoblocking mode for at least one direction is set to whitelist. Otherwise there is no need to whitelist LAN addresses. Also whitelisting LAN addresses is typically only needed if the machine has no dedicated WAN network interfaces. Otherwise you should apply geoblocking only to those WAN interfaces, so traffic from your LAN to the machine will bypass the geoblocking filter without any special rules for that.

auto will automatically detect LAN subnets (only use this if the machine has no dedicated WAN interfaces). none removes previously set LAN ip addresses.

To enable or change the automatic update schedule: geoip-shell configure -s <"schedule_expression">

<details><summary>Example</summary>

geoip-shell configure -s "1 4 * * *"

</details>

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.

To temporarily stop geoip-shell: geoip-shell stop. This will kill any running geoip-shell processes, remove geoip-shell firewall rules and unload ip sets.

To uninstall: geoip-shell-uninstall.sh

On OpenWrt, if installed via an ipk package: opkg remove <geoip-shell|geoip-shell-iptables>

<details><summary>Examples of using the configure command:</summary>

geoip-shell configure -r DE -i all -l auto -m whitelist -c "DE IT"

geoip-shell configure -m blacklist -c "DE NL" -r US -i pppoe-wan

</details>

Outbound geoblocking

When using the geoip-shell configure command, if direction is not specified, direction-specific options apply to the inbound geoblocking direction.

Direction-specific options are -m <whitelist|blacklist|disable>, -c <country_codes>, -p <ports>. To specify direction, add -D <inbound|outbound> before specifying options for that direction.

So to configure outbound geoblocking, use same commands as described in the Usage section above, except add the -D outbound option before any direction-specific options.

Examples:

To enable and configure outbound geoblocking:

geoip-shell configure -D outbound -m <whitelist|blacklist>.

To configure geoblocking mode for both inbound and outbound directions:

geoip-shell configure -D inbound -m <whitelist|blacklist> -D outbound -m <whitelist|blacklist>

**To configure inbound and outbound geoblocking, whitelisting Germany and Italy and blocking all other countries for incoming traffic, blacklisting France for outgoing traffic:

geoip-shell configure -D inbound -m whitelist -c "DE IT" -D outbound -m blacklist -c FR

To change protocols and ports outbound geoblocking applies to:

geoip-shell configure -D outbound -p <[tcp|udp]:[allow|block]:[all|<ports>]>

Pre-requisites

(if a pre-requisite is missing, the -install.sh script will tell you which)

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.

Notes

For some helpful notes about using this suite, read NOTES.md.

In detail

For specifics about each script, read DETAILS.md.

OpenWrt

For information about OpenWrt support, read the OpenWrt README.

Privacy

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.

P.s.