Currently geoip-shell fully supports OpenWrt, both with firewall3 + iptables and with firewall4 + nftables, while providing the same user interface and features as on any other Linux system. So usage is the same as described in the main README.md file, while some parts of the backend (namely persistence implementation), some defaults and the location of the data directory are different.
Installation is possible either via the -install script (as described in the main README), or via an ipk package. ipk packages are a new feature and are not yet included in the OpenWrt repository but you can get them from the Releases. They come in 2 flavors: geoip-shell-[...].ipk and geoip-shell-iptables[...].ipk. The geoip-shell-iptables package is for firewall3+iptables OpenWrt systems, while the geoip-shell package is for firewall4+nftables OpenWrt systems.
To download the latest ipk via the command line (using curl):
- For firewall4 + nftables:
curl -LO "$(curl -s https://api.github.com/repos/friendly-bits/geoip-shell/releases | grep -m1 -o 'https://github.com/friendly-bits/geoip-shell/releases/.*geoip-shell_.*\.ipk')"
- For firewall3 + iptables:
curl -LO "$(curl -s https://api.github.com/repos/friendly-bits/geoip-shell/releases | grep -m1 -o 'https://github.com/friendly-bits/geoip-shell/releases/.*geoip-shell-iptables_.*\.ipk')"
A LuCi interface has not been implemented (yet). As on any other Linux system, all user interface is via a command line (but my goal is to make this an easy experience).
After installing the ipk package, geoip-shell will be inactive until you configure it. To do so, run geoip-shell configure and follow the interactive setup. You can also run geoip-shell -h before that to find out about configuration options and then append certain options after the configure action, for example: geoip-shell configure -c "de nl" -m whitelist to configure geoip-shell in whitelist mode for countries Germany and Netherlands. The interactive setup will ask you about all the important options but some niche options are only available non-interactively (for example if you want to configure geoblocking for certain selection of ports). You can always change these settings after initial configuration via the same geoip-shell configure command.
- For nftables-based systems:
opkg remove geoip-shell - For iptables-based systems:
opkg remove geoip-shell-iptables
Because OpenWrt typically runs on embedded devices with limited memory and very small flash storage, geoip-shell implements some techniques to conserve these resources as much as possible:
- During installation on OpenWrt via the install script, comments and the debug code are stripped from the scripts to reduce their size. The ipk packages already come with comments and debug removed.
- Only the required modules are installed, depending on the system (iptables- or nftables- based).
- I've researched the most memory-efficient way for loading ip lists into nftables sets. Currently, nftables has some bugs related to this process which may cause unnecessarily high memory consumption. geoip-shell works around these bugs as much as possible.
- To avoid unnecessary flash storage wear, all filesystem-related tasks geoip-shell does which do not require permanent storage are done in the /tmp directory which in the typical OpenWrt installation is mounted on the ramdisk. Besides the scripts, by default geoip-shell only stores a tiny config file in permanent storage and that config file gets overwritten only when you change the config.
- Some defaults on OpenWrt are different to further minimize flash storage wear (read below).
Typical geoip-shell installation on an OpenWrt system currently consumes around 120kB. The distribution folder itself weighs quite a bit more (mainly because of documentation) but you can install via an ipk which doesn't remain in storage after installation, or if installing via the -install script, delete the distribution folder and free up space taken by it. geoip-shell does not install its documentation into the system. I have some plans to reduce that size by compressing certain scripts which provide user interface and implementing automatic extraction to /tmp when the user wants to access them, but this is not yet implemented.
To view all installed geoip-shell scripts in your system and their sizes, run ls -lh /usr/bin/geoip-shell-* /usr/lib/geoip-shell/*.
- Persistence of geoip firewall rules and ip sets works differenetly on OpenWrt than on other Linuxes, since geoip-shell has an OpenWrt-specific procd init script.
- The cron job which implements persistence on other Linuxes and runs at reboot is not created on OpenWrt.
- geoip-shell integrates into firewall3 or firewall4 via what's called a "firewall include". On OpenWrt, a firewall include is a setting which tells firewall3 or firewall4 to do something specific in response to certain events.
- The only task of the init script for geoip-shell is to call the geoip-shell-mk-fw-include.sh script, which makes sure that the firewall include exists and is correct, if not then creates the include.
- The firewall include is what does the actual persistence work. geoip-shell firewall include triggers on firewall reload (which happens either at reboot or when the system decides that a reload of the firewall is necessary, or when initiated by the user).
- When triggered, the include script calls the -run script with the "restore" action.
- The -run script verifies that geoip nftables/iptables rules and ip sets exist, and if not then it restores them from backup, or (if backup doesn't exist) initiates re-fetch of the ip lists and then re-creates the rules and the ip sets.
- By default, geoip-shell does not create backups on OpenWrt because typically the permanent storage is very small and prone to wear.
- Automatic updates of ip lists on OpenWrt are triggered from a cron job like on other Linuxes.
Generally the defaults are the same as for other systems, except:
- the data directory which geoip-shell uses to store the status file and the backups is by default in
/tmp/geoip-shell-data, rather than in/var/lib/geoip-shellas on other Linux systems. This is to avoid flash wear. You can change this by running the install script with the-a <path>option, or after installation via the commandgeoip-shell configure -a <path>. - the 'nobackup' option is set to 'true', which configures geoip-shell to not create backups of the ip lists. With this option, geoip-shell will work as usual, except after reboot (and for iptables-based systems, after firewall restart) it will re-fetch the ip lists, rather than loading them from backup. You can change this by running the -install script with the
-o falseoption (-ostands for nobackup), or after installation via the commandgeoip-shell configure -o false. To have persistent ip list backups, you will also need to change the data directory path as explained above. - if using geoip-shell on a router with just a few MB of embedded flash storage, consider either leaving the nobackup and datadir path defaults as is, or connecting an external storage device to your router (preferably formatted to ext4) and configuring a directory on it as your geoip-shell data directory, then enabling automatic backups. For example, if your external storage device is mounted on /mnt/somedevice, you can do all this via this command:
geoip-shell configure -a /mnt/somedevice/geoip-shell-data -o false. - the default ip lists source for OpenWrt is ipdeny (rather than ripe). While ipdeny is a 3rd party, they provide aggregated lists which consume less memory (on nftables-based systems the ip lists are automatically optimized after loading into memory, so there the source does not matter, but a smaller initial ip lists size will cause a smaller memory consumption spike while loading the ip list).
The repository includes the mk-owrt-package.sh and prep-owrt-package scripts which automate creation of geoip-shell ipk packages. The makefile.tpl file is used as the base template for the Makefile. If you want to build the ipk package by yourself, read the comments inside the mk- script for instructions.
This is about it for this document. Much more information is available in the main README.md and in the extra .md files inside the Documentation directory. If you have any questions, go ahead and use the Discussions tab, or contact me in this thread: https://forum.openwrt.org/t/geoip-shell-flexible-geoip-blocker-for-linux/189611
If you use this project, I will be happy to hear about your experience in the above thread or via the Discussions tab on Github. If for some reason geoip-shell is not working for you, I will want to know that as well so I can improve it.
Also, please consider giving this repository a star on Github - this helps other people to find it.