You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: Documentation/DETAILS.md
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -100,7 +100,7 @@ These options apply to geoblocking direction (inbound or outbound) which you can
100
100
101
101
`-c <"country codes">`: Change which country codes are included in the whitelist/blacklist (this command replaces all country codes with newly specified ones).
102
102
103
-
`-p <[tcp|udp]:[allow|block]:[all|<ports>]>`: Specify ports geoblocking 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](/Documentation/NOTES.md), sections 9-11.
103
+
`-p <[tcp|udp]:[allow|block]:[all|<ports>]>`: Specify ports geoblocking 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](/Documentation/NOTES.md), sections 10-12.
Copy file name to clipboardExpand all lines: Documentation/NOTES.md
+22-22Lines changed: 22 additions & 22 deletions
Original file line number
Diff line number
Diff line change
@@ -13,7 +13,7 @@ Depending on the options you specified during interactive setup or via the comma
13
13
- geoip-shell combines the trusted addresses, the LAN addresses and the link-local addresses in one ipset and creates one rule for each ip family and enabled geoblocking direction.
14
14
- If both geoblocking directions need the same set of allowed addresses, geoip-shell creates only one ipset per ip family and reuses it for both directions. Otherwise geoip-shell creates separate ipsets for each direction.
15
15
16
-
2) Firewall rules structure created by geoip-shell:
16
+
3) Firewall rules structure created by geoip-shell:
17
17
<details> <summary>Read more:</summary>
18
18
19
19
### **iptables**
@@ -37,21 +37,21 @@ Depending on the options you specified during interactive setup or via the comma
37
37
38
38
</details>
39
39
40
-
3) How to manually check firewall rules created by geoip-shell:
40
+
4) How to manually check firewall rules created by geoip-shell:
41
41
- With nftables: `nft -t list table inet geoip-shell`. This will display all geoip-shell rules and sets.
42
42
- With iptables: `iptables -vL -t mangle` and `ip6tables -vL -t mangle`. This will report all geoip-shell rules. To check ipsets created by geoip-shell, use `ipset list -n | grep geoip-shell`. For a more detailed view, use this command: `ipset list -t`.
43
43
44
-
4) geoip-shell uses RIPE as the default source for ip lists, except on OpenWrt. 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 geoblocking. With iptables, the machine which these lists are loaded on has to do less work when processing incoming connection requests. With nftables, this does not affect the load on the CPU because nftables automatically optimizes loaded ip lists, so ip lists from RIPE perform identically to ip lists from ipdeny. The downloaded lists from ipdeny are still smaller, so even with nftables, there is still a benefit of lower transient memory consumption while loading the lists (which mostly matters for embedded hardware with very limited memory capacity).
44
+
5) geoip-shell uses RIPE as the default source for ip lists, except on OpenWrt. 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 geoblocking. With iptables, the machine which these lists are loaded on has to do less work when processing incoming connection requests. With nftables, this does not affect the load on the CPU because nftables automatically optimizes loaded ip lists, so ip lists from RIPE perform identically to ip lists from ipdeny. The downloaded lists from ipdeny are still smaller, so even with nftables, there is still a benefit of lower transient memory consumption while loading the lists (which mostly matters for embedded hardware with very limited memory capacity).
45
45
46
-
5) Scripts intended as user interface are: **-install**, **-uninstall**, **-manage** (also called by running '**geoip-shell**' after installation) and **check-ip-in-source.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.
46
+
6) Scripts intended as user interface are: **-install**, **-uninstall**, **-manage** (also called by running '**geoip-shell**' after installation) and **check-ip-in-source.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.
47
47
48
-
6) The run, fetch and apply scripts write to syslog in case an error occurs. The run and fetch scripts also write to syslog upon success. To verify that cron jobs ran successfully, on Debian and derivatives run `cat /var/log/syslog | grep geoip-shell`. On other distributions, you may need to figure out how to access the syslog.
48
+
7) The run, fetch and apply scripts write to syslog in case an error occurs. The run and fetch scripts also write to syslog upon success. To verify that cron jobs ran successfully, on Debian and derivatives run `cat /var/log/syslog | grep geoip-shell`. On other distributions, you may need to figure out how to access the syslog.
49
49
50
-
7) geoip-shell will not run in the background consuming resources (except for a short time when triggered by the cron jobs). All the actual blocking is done by the netfilter component in the kernel. geoip-shell offers an easy and relatively fool-proof interface with netfilter, config persistence, automated ip lists fetching and update.
50
+
8) geoip-shell will not run in the background consuming resources (except for a short time when triggered by the cron jobs). All the actual blocking is done by the netfilter component in the kernel. geoip-shell offers an easy and relatively fool-proof interface with netfilter, config persistence, automated ip lists fetching and update.
51
51
52
-
8) Sometimes ip list source servers are temporarily unavailable and if you're unlucky enough to attempt installing geoip-shell during that time frame, the fetch script will fail which will cause the initial setup to fail as well. Try again after some time or use another source. Once the initial setup succeeds, an occasional fetch failure during automatic update won't cause any issues as last successfully fetched ip list will be used until the next update cycle succeeds.
52
+
9) Sometimes ip list source servers are temporarily unavailable and if you're unlucky enough to attempt installing geoip-shell during that time frame, the fetch script will fail which will cause the initial setup to fail as well. Try again after some time or use another source. Once the initial setup succeeds, an occasional fetch failure during automatic update won't cause any issues as last successfully fetched ip list will be used until the next update cycle succeeds.
53
53
54
-
9) How to geoblock or allow specific ports.
54
+
10) How to geoblock or allow specific ports.
55
55
geoip-shell allows to limit geoblocking to certain **destination** ports.
56
56
57
57
The general syntax is: `geoip-shell configure [-D <inbound|outbound>] -p <[tcp|udp]:[allow|block]:[all|<ports>]>`
@@ -83,49 +83,49 @@ Depending on the options you specified during interactive setup or via the comma
83
83
84
84
`geoip-shell configure -D inbound -p tcp:block:125-135,7` - for inbound tcp traffic, only geoblock packets which have destination ports 125-135 and 7, do not geoblock inbound traffic on all other tcp ports
85
85
86
-
10) How to remove specific ports assignment:
86
+
11) How to remove specific ports assignment:
87
87
88
88
use `geoip-shell configure [-D <inbound|outbound>] -p [tcp|udp]:block:all`.
89
89
90
90
Example: `geoip-shell configure -p tcp:block:all` will remove prior port-specific rules for the tcp protocol, inbound direction. All inbound tcp packets with all destination ports will now go through geoip filter.
91
91
92
92
Example: `geoip-shell configure -D outbound -p udp:block:all` will remove prior port-specific rules for the udp protocol, outbound direction. All outbound udp packets with all destination ports will now go through geoip filter.
93
93
94
-
11) How to make all packets for a specific protocol bypass geoip blocking:
94
+
12) How to make all packets for a specific protocol bypass geoip blocking:
95
95
96
96
use `geoip-shell configure [-D <inbound|outbound>] -p [tcp|udp]:allow:all`
97
97
98
98
Example: `geoip-shell configure -p udp:allow:all` will allow all inbound udp packets with all destination ports to bypass the geoip filter.
99
99
100
-
12) geoip-shell creates both 'accept' and 'drop' firewall rules, depending on your config. The 'drop' verdict is final: once a packet encounters the 'drop' rule, it is dropped. The 'accept' verdict is not final: a packet accepted by geoip-shell rules may still get dropped by other rules you may have in your firewall. So essentially geoip-shell acts as a filter which is only capable of narrowing down machine's exposure to the Internet but not overriding other blocking rules which you may have.
100
+
13) geoip-shell creates both 'accept' and 'drop' firewall rules, depending on your config. The 'drop' verdict is final: once a packet encounters the 'drop' rule, it is dropped. The 'accept' verdict is not final: a packet accepted by geoip-shell rules may still get dropped by other rules you may have in your firewall. So essentially geoip-shell acts as a filter which is only capable of narrowing down machine's exposure to the Internet but not overriding other blocking rules which you may have.
101
101
102
-
13) Firewall rules persistence, as well as automatic ip list updates, is implemented via cron jobs: a periodic job running by default on a daily schedule, and a job that runs at system reboot (after 30 seconds delay). Either or both cron jobs can be disabled (run `geoip-shell -h` to find out how, or read [DETAILS.md](/Documentation/DETAILS.md)). On OpenWrt, persistence is implemented via an init script and a firewall include rather than via a cron job.
102
+
14) Firewall rules persistence, as well as automatic ip list updates, is implemented via cron jobs: a periodic job running by default on a daily schedule, and a job that runs at system reboot (after 30 seconds delay). Either or both cron jobs can be disabled (run `geoip-shell -h` to find out how, or read [DETAILS.md](/Documentation/DETAILS.md)). On OpenWrt, persistence is implemented via an init script and a firewall include rather than via a cron job.
103
103
104
-
14) You can specify a custom schedule for the periodic cron job this way: `geoip-shell configure -s <your_cron_schedule>`.
104
+
15) You can specify a custom schedule for the periodic cron job this way: `geoip-shell configure -s <your_cron_schedule>`.
105
105
106
-
15) If you want to change the autoumatic update schedule but you don't know the crontab expression syntax, check out https://crontab.guru/ (no affiliation). geoip-shell includes a script which validates cron expressions you request, so don't worry about making a mistake.
106
+
16) If you want to change the autoumatic update schedule but you don't know the crontab expression syntax, check out https://crontab.guru/ (no affiliation). geoip-shell includes a script which validates cron expressions you request, so don't worry about making a mistake.
107
107
108
-
16) Note that cron jobs will be run as root.
108
+
17) Note that cron jobs will be run as root.
109
109
110
-
17) When geoip-shell detects both iptables and nftables during the initial setup, it will default to using nftables. If you have nftables installed but for some reason you are using iptables rules (via the nft_compat kernel module which is provided by packages like nft-iptables etc), you can and probably should configure geoip-shell with the option `-w ipt` which will force it to use iptables+ipset. For example: `geoip-shell configure -w ipt`.
110
+
18) When geoip-shell detects both iptables and nftables during the initial setup, it will default to using nftables. If you have nftables installed but for some reason you are using iptables rules (via the nft_compat kernel module which is provided by packages like nft-iptables etc), you can and probably should configure geoip-shell with the option `-w ipt` which will force it to use iptables+ipset. For example: `geoip-shell configure -w ipt`.
111
111
112
-
18) If you upgrade your system from iptables to nftables, you can use this command: `geoip-shell configure -w nft`, which will remove all iptables rules and ipsets and re-create nftables rules and sets based on your existing config. If for some reason you prefer to switch from nftables to iptables, you can use this command: `geoip-shell configure -w ipt`. If you are on OpenWrt and installed via an ipk package, this does not apply: instead, you will need to uninstall geoip-shell-iptables package and install the geoip-shell package for nftables-based OpenWrt (or the other way around).
112
+
19) If you upgrade your system from iptables to nftables, you can use this command: `geoip-shell configure -w nft`, which will remove all iptables rules and ipsets and re-create nftables rules and sets based on your existing config. If for some reason you prefer to switch from nftables to iptables, you can use this command: `geoip-shell configure -w ipt`. If you are on OpenWrt and installed via an ipk package, this does not apply: instead, you will need to uninstall geoip-shell-iptables package and install the geoip-shell package for nftables-based OpenWrt (or the other way around).
113
113
114
-
19) 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.
114
+
20) 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.
115
115
116
-
20) 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.
116
+
21) 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.
117
117
118
-
21) If for some reason you need to install or configure geoip-shell in strictly non-interactive mode, you can call the -install or the -manage script with the `-z` option which will avoid asking the user any questions. In non-interactive mode, commands will fail if required config is incomplete or invalid.
118
+
22) If for some reason you need to install or configure geoip-shell in strictly non-interactive mode, you can call the -install or the -manage script with the `-z` option which will avoid asking the user any questions. In non-interactive mode, commands will fail if required config is incomplete or invalid.
119
119
120
-
22) To test before deployment:
120
+
23) To test before deployment:
121
121
<details> <summary>Read more:</summary>
122
122
123
123
- If you prefer to check geoip-shell rules before committing to actual geoblocking, you can install geoip-shell with the `-z` option which will prevent geoip-shell from starting automated setup when installation completes: `sh geoip-shell-install.sh -z`. Then call the -manage script with the `-N true` option (N stands for noblock) to apply all actions and create all firewall rules except the geoblocking enable rule: `geoip-shell configure -N true`.
124
124
- You can configure geoip-shell with the `-n true` option (n stands for nopersistence) to skip creating the reboot cron job which implements persistence (or the init script on OpenWrt) and with the '-s disable' option to skip creating the autoupdate cron job: `geoip-shell configure -n true -s disable`. This way, a simple machine restart should undo all changes made to the firewall (unless you have some software which restores firewall settings after reboot). To enable persistence and automatic updates later, use the command `geoip-shell configure -n false -s <"your_cron_schedule_expression">` (default cron schedule expression is `15 4 * * *`).
125
125
126
126
</details>
127
127
128
-
23) How to get yourself locked out of your remote server and how to prevent this:
128
+
24) How to get yourself locked out of your remote server and how to prevent this:
129
129
<details> <summary>Read more:</summary>
130
130
131
131
There are 4 scenarios where you can lock yourself out of your remote server with geoip-shell:
_(for detailed description of this feature, read [NOTES.md](/Documentation/NOTES.md), sections 9-11)_
169
+
_(for detailed description of this feature, read [NOTES.md](/Documentation/NOTES.md), sections 10-12)_
170
170
171
171
**To enable or disable geoblocking** (only adds or removes the geoblocking enable rules, leaving all other firewall geoblocking rules and ip sets in place):
172
172
@@ -276,11 +276,3 @@ If you are using the ipdeny source then note that they are a 3rd party which has
276
276
277
277
- I would appreciate a report of whether it works or doesn't work on your system (please specify which). You can use the Github Discussions tab for that.
278
278
- If you find a bug or want to request a feature, please let me know by opening an issue.
0 commit comments