## **Overview**
### Main Scripts
-- geoip-shell-install.sh
-- geoip-shell-uninstall.sh
- geoip-shell-manage.sh
- geoip-shell-run.sh
- geoip-shell-fetch.sh
**geoip-shell-detect-lan.sh**
This script is only used under specific conditions:
-- During initial setup, with whitelist mode, and only if wan interfaces were set to 'all', and LAN subnets were not specified via command line args. geoip-shell then assumes that it is being installed on a machine belonging to a LAN, uses this script to detect the LAN subnets and offers the user to add them to the whitelist, and to enable automatic detection of LAN subnets in the future.
+- During initial setup, with whitelist mode, and only if wan interfaces were set to 'all', and LAN subnets were not specified via command line args. geoip-shell then assumes that it is being configured on a host behind a router and firewall, uses this script to detect the LAN subnets and offers the user to add them to the whitelist, and to enable automatic detection of LAN subnets in the future.
- At the time of creating/updating firewall rules, and only if LAN subnets automatic detection is enabled. geoip-shell then re-detects LAN subnets automatically.
### Library Scripts
For more information about integration with OpenWrt, read [OpenWrt-README.md](OpenWrt-README.md)
### User interface
-The scripts intended as user interface are **geoip-shell-install.sh**, **geoip-shell-uninstall.sh**, **geoip-shell-manage.sh** and **check-ip-in-source.sh**. All the other scripts are intended as a back-end. If you just want to install and move on, you only need to run the -install script.
After installation, the user interface is provided by running "geoip-shell", which is a symlink to the -manage script.
## **Main scripts in detail**
**geoip-shell-manage.sh**: serves as the main user interface to configure geoip after installation. You can also call it by simply typing `geoip-shell`. As most scripts in this suite, it requires root privileges because it needs to interact with the netfilter kernel component and access the data folder which is only readable and writable by root. Since it serves as the main user interface, it contains a lot of logic to generate a report, parse, validate and initiate actions requested by the user (by calling other scripts as required), check for possible remote machine lockout and warn the user about it, check actions result, update the config and take corrective actions in case of an error. Describing all this is beyond the scope of this document but you can read the code. Sources the lib-status script when generating a status report. Sources lib-setup for some of the arguments parsing logic and interactive dialogs implementation.
-`geoip-shell <on|off> [-c <"country_codes">]` : Enable or disable the geoip blocking chain (via a rule in the base geoip chain)
+`geoip-shell <on|off>` : Enable or disable the geoip blocking chain (via a rule in the base geoip chain)
`geoip-shell <add|remove> [-c <"country_codes">]` :
* Adds or removes the specified country codes to/from the config file.
`geoip-shell restore` : re-fetches and re-applies geoip firewall rules and ip lists as per the config.
-`geoip-shell configure [options]` : changes geoip-shell configuration
+`geoip-shell showconfig` : prints the contents of the config file.
+
+`geoip-shell configure [options]` : changes geoip-shell configuration.
+
+Initial configuration is possible either fully interactively (the -manage script gathers all important config via dialog with the user), partially interactively (you provide some command line arguments, the -manage script processes them and if needed, asks you additional questions), or completely non-interactively by calling the -manage script with the `-z` option which will force setup to fail if any required options are missing or invalid. Any sensible combination of the following options is allowed in one command.
**Options for the `geoip-shell configure` command:**
`-u [ripe|ipdeny]`: Change ip lists source.
-`-i <[ifaces]|auto|all>`: Change which network interfaces geoip firewall rules are applied to. `auto` will attempt to automatically detect WAN network interfaces. `auto` works correctly in **most** cases but not in **every** case. Don't use `auto` if the machine has no direct connection to WAN. The automatic detection occurs only when manually triggered by the user via this command.
+`-i <[ifaces]|auto|all>`: Change which network interfaces geoip firewall rules are applied to. `auto` will attempt to automatically detect WAN network interfaces. `auto` works correctly in **most** cases but not in **every** case. Don't use `auto` if the machine has no dedicated WAN network interfaces. The automatic detection occurs only when manually triggered by the user via this command.
`-l <"[lan_ips]"|auto|none>`: Specify LAN ip's or subnets to exclude from blocking (both ipv4 and ipv6). `auto` will trigger LAN subnets re-detection at every update of the ip lists. When specifying custom ip's or subnets, automatic detection is disabled. This option is only avaiable when using geoip-shell in whitelist mode.
`-t <"[trusted_ips]|none">`: Specify trusted ip's or subnets (anywhere on the Internet) to exclude from geoip blocking (both ipv4 and ipv6).
-`-p <[tcp|udp]:[allow|block]:[all|<ports>]>`: specify ports geoip blocking will apply (or not apply) to, for tcp or udp. To specify ports for both tcp and udp, use the `-p` option twice. For more details, read [NOTES.md](NOTES.md), sections 9-11.
+`-p <[tcp|udp]:[allow|block]:[all|<ports>]>`: Specify ports geoip blocking will apply (or not apply) to, for tcp or udp. To specify ports for both tcp and udp, use the `-p` option twice. For more details, read [NOTES.md](NOTES.md), sections 9-11.
`-r <[user_country_code]|none>` : Specify user's country code. Used to prevent accidental lockout of a remote machine. `none` disables this feature.
-`-s <"schedule_expression"|disable>` : enables automatic ip lists updates and configures the schedule for the periodic cron job which implements this feature. `disable` disables automatic ip lists updates.
+`-s <"schedule_expression"|disable>` : Enables automatic ip lists updates and configures the schedule for the periodic cron job which implements this feature. `disable` disables automatic ip lists updates.
`-o <true|false>` : No backup. If set to 'true', geoip-shell will not create a backup of ip lists and firewall rules after applying changes, and will automatically re-fetch ip lists after each reboot. Default is 'true' for OpenWrt, 'false' for all other systems.
`-a <path>` : Set custom path to directory where backups and the status file will be stored. Default is '/tmp/geoip-shell-data' for OpenWrt, '/var/lib/geoip-shell' for all other systems.
-`-O <memory|performance>`: specify optimization policy for nftables sets. By default optimizes for low memory consumption if system RAM is less than 2GiB, otherwise optimizes for performance. This option doesn't work with iptables.
+`-O <memory|performance>`: Specify optimization policy for nftables sets. By default optimizes for low memory consumption if system RAM is less than 2GiB, otherwise optimizes for performance. This option doesn't work with iptables.
-`geoip-shell showconfig` : prints the contents of the config file.
+`-z`: Non-interactive setup.
-**geoip-shell-run.sh**: Serves as a proxy to call the -fetch, -apply and -backup scripts with arguments required for each action. Executes the requested actions, depending on the config set by the -install and -manage scripts, and the command line options, and writes to system log when starting and on action completion (or if any errors encountered). If persistence or autoupdates are enabled, the cron jobs (or on OpenWrt, the firewall include script) call this script with the necessary options. If a non-fatal error is encountered during an automatic update function, the script enters sort of a temporary daemon mode where it will re-try the action (up to a certain number of retries) with increasing time intervals. It also implements some logic to account for unexpected issues encountered during the 'restore' action which runs after system reboot to impelement persistnece, such as a missing backup, and in this situation will automatically change its action from 'restore' to 'update' and try to re-fetch and re-apply the ip lists.
+**geoip-shell-run.sh**: Serves as a proxy to call the -fetch, -apply and -backup scripts with arguments required for each action. Executes the requested actions, depending on the config and the command line options, and writes to system log when starting and on action completion (or if any errors encountered). If persistence or autoupdates are enabled, the cron jobs (or on OpenWrt, the firewall include script) call this script with the necessary options. If a non-fatal error is encountered during an automatic update function, the script enters sort of a temporary daemon mode where it will re-try the action (up to a certain number of retries) with increasing time intervals. It also implements some logic to account for unexpected issues encountered during the 'restore' action which runs after system reboot to impelement persistnece, such as a missing backup, and in this situation will automatically change its action from 'restore' to 'update' and try to re-fetch and re-apply the ip lists.
-`geoip-shell-run add -l <"list_id [list_id] ... [list_id]">` : Fetches ip lists, loads them into ip sets and applies firewall rules for specified list id's.
-A list id has the format of `<country_code>_<family>`. For example, ****US_ipv4** and **GB_ipv6** are valid list id's.
+`geoip-shell-run.sh add -l <"list_id [list_id] ... [list_id]">` : Fetches ip lists, loads them into ip sets and applies firewall rules for specified list id's.
+A list id has the format of `<country_code>_<family>`. For example, **US_ipv4** and **GB_ipv6** are valid list id's.
-`geoip-shell-run remove -l <"list_ids">` : Removes iplists and firewall rules for specified list id's.
+`geoip-shell-run.sh remove -l <"list_ids">` : Removes iplists and firewall rules for specified list id's.
-`geoip-shell-run update` : Updates the ip sets for list id's that had been previously configured. Intended for triggering from periodic cron jobs.
+`geoip-shell-run.sh update` : Updates the ip sets for list id's that had been previously configured. Intended for triggering from periodic cron jobs.
-`geoip-shell-run restore` : Restore previously downloaded lists from backup (skip fetching). Used by the reboot cron job (or by the firewall include on OpenWrt) to implement persistence.
+`geoip-shell-run.sh restore` : Restore previously downloaded lists from backup (skip fetching). Used by the reboot cron job (or by the firewall include on OpenWrt) to implement persistence.
**geoip-shell-fetch.sh**
-- Fetches ip lists for given list id's from RIPE or from ipdeny. The source is selected during installation. If you want to change the default which is RIPE, install with the `-u ipdeny` option.
+- Fetches ip lists for given list id's from RIPE or from ipdeny.
- Parses, validates, compiles the downloaded lists, and saves each one to a separate file.
- Implements extensive sanity checks at each stage (fetching, parsing, validating and saving) and handles errors if they occur.
-(for specifics on how to use the script, run it with the -h option)
+Options:
+
+`-l <"list_ids">` : ip list id's in the format <country_code>_<family> (if specifying multiple list id's, use double quotes)
+
+`-p <path>` : Path to directory where downloaded and compiled subnet lists will be stored.
+
+`-o <output_file>` : Path to output file where fetched list will be stored.
+
+`-s <status_file>` : Path to a status file to register fetch results in.
+
+`-u <ripe|ipdeny>` : Use this ip list source for download. Supported sources: ripe, ipdeny.
+
+Extra options:
+
+`-r` : Raw mode (outputs newline-delimited ip lists rather than nftables-ready ones).
+
+`-f` : Force using fetched lists even if list timestamp didn't change compared to existing list.
+
-**geoip-shell-apply.sh**: directly interfaces with the firewall. Creates or removes ip sets and firewall rules for specified list id's. Sources the lib-apply-ipt or lib-apply-nft script which does most of the actual work.
+**geoip-shell-apply.sh**: directly interfaces with the firewall. Creates or removes ip sets and firewall rules for specified list id's. Sources the lib-ipt or lib-nft library script.
-`geoip-shell-apply add -l <"list_ids">` :
+`geoip-shell-apply.sh add -l <"list_ids">` :
- Loads ip list files for specified list id's into ip sets and applies firewall rules required for geoip blocking.
List id has the format of `<country_code>_<family>`. For example, **US_ipv4** and **GB_ipv6** are valid list id's.
-`geoip-shell-apply remove -l <"list_ids">` :
+`geoip-shell-apply.sh remove -l <"list_ids">` :
- removes ip sets and geoip firewall rules for specified list id's.
-**geoip-shell-cronsetup.sh** manages all the cron-related logic and actions. Called by the -manage script. Cron jobs are created based on the settings stored in the config file. Also used to validate cron schedule provided by the user at the time of installation or later.
+**geoip-shell-cronsetup.sh** manages all the cron-related logic and actions. Called by the -manage script. Cron jobs are created based on the settings stored in the config file. Also used to validate cron schedule specified by the user.
-**geoip-shell-backup.sh**: Creates a backup of current geoip-shell firewall rules and ip sets and current geoip-shell config, or restores them from backup. By default (if you didn't run the installation with the '-o' option), backup will be created after every change to ip sets in the firewall. Backups are automatically compressed and de-compressed with the best utility available to the system, in this order "bzip2, xz, gzip", or simply "cat" as a fallback if neither is available (which generally should never happen on Linux). Only one backup copy is kept. Sources the lib-backup-ipt or the lib-backup-nft script which does most of the actual work.
+**geoip-shell-backup.sh**: Creates backup of current geoip-shell firewall rules and ip sets and current geoip-shell config, or restores them from backup. By default (if you didn't configure geoip-shell with the '-o' option), backup will be created after every change to ip sets in the firewall. Backups are automatically compressed and de-compressed with the best utility available to the system, in this order "bzip2, xz, gzip", or simply "cat" as a fallback if neither is available (which generally should never happen on Linux). Only one backup copy is kept. Sources the lib-ipt or the lib-nft library script.
-`geoip-shell-backup create-backup` : Creates a backup of the current firewall state and geoip blocking config.
+`geoip-shell-backup.sh create-backup` : Creates backup of geoip-shell ip sets and config.
-`geoip-shell-backup restore` : Restores the firewall state and the config from backup. Used by the *run script to implement persistence. Can be manually used for recovery from fault conditions.
+`geoip-shell-backup.sh restore` : Restores geoip-shell state and config from backup. Used by the *run script to implement persistence. Can be manually used for recovery from fault conditions. If run with option `-n`, does not restore the config and the status files.
### **nftables**
- With **nftables**, all firewall rules created by geoip-shell are in the table named `geoip-shell`, family "inet", which is a term nftables uses for tables applying to both ip families. The `geoip-shell` table includes rules for both ip families and any nftables sets geoip-shell creates. geoip-shell creates 2 chains in that table: `GEOIP-BASE` and `GEOIP-SHELL`. The base chain attaches to netfilter's `prerouting` hook and has a rule which directs traffic to the `GEOIP-SHELL` chain. That rule is the geoip-shell "enable" rule for nftables-based systems which acts exactly like the "enable" rule in the iptables-based systems, except it applies to both ip families.
- - **nftables** allows for more control over which network interfaces each rule applies to, so when certain network interfaces are specified during installation, geoip-shell specifies these interfaces directly in the rules inside the `GEOIP-SHELL` chain, and so (contrary to iptables-based systems) there is no need in an additional chain.
+ - **nftables** allows for more control over which network interfaces each rule applies to, so when certain network interfaces are specified during initial setup, geoip-shell specifies these interfaces directly in the rules inside the `GEOIP-SHELL` chain, and so (contrary to iptables-based systems) there is no need in an additional chain.
- **nftables** features atomic rules updates, meaning that when issuing multiple nftables commands at once, if any command fails, all changes get cancelled and the system remains in the same state as before. geoip-shell utilizes this feature for fault-tolerance and to completely eliminate time when geoip blocking is disabled during an update of the sets or rules.
- **nftables** current version (up to 1.0.8 and probably 1.0.9) has some bugs related to unnecessarily high transient memory consumption when performing certain actions, including adding new sets. These bugs are known and for the most part, already have patches implemented which should eventually roll out to the distributions. This mostly matters for embedded hardware with less than 512MB of memory. geoip-shell works around these bugs as much as possible. One of the workarounds is to avoid using the atomic replacement feature for nftables sets. Instead, when updating sets, geoip-shell first adds new sets one by one, then atomically applies all other changes, including rules changes and removing the old sets. In case of an error during any stage of this process, all changes get cancelled, old rules and sets remain in place and geoip-shell then destroys the new sets. This is less efficient but with current versions of nftables, this actually lowers the minimum memory bar for the embedded devices. Once a new version of nftables will be rolled out to the distros, geoip-shell will adapt the algorithm accordingly.
3) geoip-shell uses RIPE as the default source for ip lists. RIPE is a regional registry, and as such, is expected to stay online and free for the foreseeable future. However, RIPE may be fairly slow in some regions. For that reason, I implemented support for fetching ip lists from ipdeny. ipdeny provides aggregated ip lists, meaning in short that there are less entries for same effective geoip blocking, so the machine which these lists are installed on has to do less work when processing incoming connection requests. All ip lists the suite fetches from ipdeny are aggregated lists.
-4) The scripts intended as user interface are: **-install**, **-uninstall**, **-manage** (also called by running '**geoip-shell**' after installation) and **check-ip-in-registry.sh**. The -manage script saves the config to a file and implements coherence checks between that file and the actual firewall state. While you can run the other scripts individually, if you make changes to firewall geoip rules, next time you run the -manage script it may insist on reverting those changes since they are not reflected in the config file. The **-backup** script can be used individually. By default, it creates a backup of geoip-shell state after every successful action involving changes to or updates of the ip lists. If you encounter issues, you can use it with the 'restore' command to restore geoip-shell to its previous state. It also restores the config, so the -manage script will not mind.
+4) The script intended as user interface is **geoip-shell-manage.sh** (also called by running **geoip-shell**).
5) How to manually check firewall rules created by geoip-shell:
- With nftables: `nft -t list table inet geoip-shell`. This will display all geoip-shell rules and sets.
-# Notes about questions asked during the initial setup
+## Notes about questions asked during the initial setup
-## **'Your shell 'A' is supported by geoip-shell but a faster shell 'B' is available in this system, using it instead is recommended. Would you like to use 'B' with geoip-shell?'**
-geoip-shell will work with the shell A you ran it from, but it will work faster with a shell B which is also installed in your system. Your call - type in `y` or `n`. The recommendation is clear. If you type in `y`, geoip-shell installer will launch itself using shell B and configure geoip-shell to always use shell B.
-
-## **'I'm running under an unsupported/unknown shell shell 'A' but a supported shell 'B' is available in this system, using it instead is recommended. Would you like to use 'B' with geoip-shell?'**
-
-Whether geoip-shell will work correctly or at all with the shell A you ran it from is unknown, but a supported shell B is available in your system. You can try to run geoip-shell with A but the recommendation is clear. Generally, geoip-shell works best with shells `ash` and `dash`. If you type in `y`, geoip-shell installer will launch itself using shell B and configure geoip-shell to always use shell B.
-
-## **'Please enter your country code':**
+### **'Please enter your country code':**
If you answer this question, the _-manage_ script will check that changes in ip lists which you request to make will not block your own country and warn you if they will. This applies both to the initial setup, and to any subsequent changes to the ip lists which you may want to make in the future. The idea behind this is to make this tool as fool-proof as possible. This information is written to the geoip-shell config file (only readable by root) on your device and geoip-shell does not send it anywhere. You can remove this config entry any time via the command `geoip-shell configure -r none`. You can skip the question by pressing Enter if you wish.
-## **'Does this machine have dedicated WAN interface(s)? [y|n]':**
+### **'Does this machine have dedicated WAN interface(s)? [y|n]':**
Answering this question is mandatory because the firewall is configured differently, depending on the answer. Answering it incorrectly may cause unexpected results, including having no geoip blocking or losing remote access to your machine.
Otherwise, geoip rules are applied to traffic arriving from all network interfaces, except the loopback interface. Besides that, when geoip-shell is installed in whitelist mode and you picked `n` in this question, additional firewall rules may be created which add LAN subnets or ip's to the whitelist in order to avoid blocking them (you can approve or configure that on the next step of the installation). This does not guarantee that your LAN subnets will not be blocked by another rule in another table, and in fact, if you prefer to block some of them then having them in whitelist will not matter. This is because while the 'drop' verdict is final, the 'accept' verdict is not.
-## **'Autodetected ipvX LAN subnets: ... [c]onfirm, c[h]ange, [s]kip or [a]bort installation?'**
+### **'Autodetected ipvX LAN subnets: ... [c]onfirm, c[h]ange, [s]kip or [a]bort?'**
You will see this question if installing the suite in whitelist mode and you chose `n` in the previous question. The reason why under these conditions this question is asked is to avoid blocking your LAN from accessing your machine.
If you find out that the subnets were detected incorrectly, you can type in 'h' and manually enter the correct subnets or ip addresses which you want to allow connections from.
-## **'A[u]to-detect LAN subnets when updating ip lists or keep this config c[o]nstant?'**
+### **'A[u]to-detect LAN subnets when updating ip lists or keep this config c[o]nstant?'**
As the above question, you will see this one if installing the suite in whitelist mode and you answered `n` to the question about WAN interfaces. You will not see this question if you specified custom subnets or ips in the previous question.
Generally if automatic detection worked as expected during initial setup, most likely it will work correctly every time, so it is a good idea to allow auto-detection with each update. If not then, well, not.
-## **Extra options**
+### **Extra options**
- geoip-shell supports an additional setting: trusted ip's or subnets. Currently this is only configurable by running the -install script with the option `-t <"[trusted_ips]">` (or after installation via the `geoip-shell configure -t <"[trusted_ips]">` command). You can specify trusted ip addresses or subnets anywhere on the LAN or on the Internet. To remove this setting later, run `geoip-shell configure -t none`.
-- geoip-shell supports lots of additional command-line options. You can find out more by running `sh geoip-shell-install.sh -h`, or after installation `geoip-shell -h`, or by reading [NOTES.md](NOTES.md) and [DETAILS.md](DETAILS.md).
\ No newline at end of file
+- geoip-shell supports lots of additional command-line options. You can find out more by running `geoip-shell -h`, or by reading [NOTES.md](NOTES.md) and [DETAILS.md](DETAILS.md).
\ No newline at end of file
projects / feed / packages.git / commitdiff