hoborg/homelab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
64a43c8a961e61e14e3fa30fb1d3e0910ea82049
homelab/docs/geoip-blocking.md
Arpad Krejczinger 43cfd25798 docs: Update cron schedules to match actual configuration 
- Correct permanent ban script cron schedule: 2:00 AM daily (not every 6 hours)
- Correct geoip-shell update cron schedule: 4:08 AM daily (not 4:18 AM)
- Add geoip-shell persistence cron job that runs on reboot
2025-09-17 01:08:51 +02:00

6.0 KiB
Raw Blame History

GeoIP Blocking with geoip-shell

Overview

Tool: geoip-shell v0.7.5 Repository: https://github.com/friendly-bits/geoip-shell Installation Method: Manual from GitHub repository Purpose: Geographic IP blocking for enhanced security

Installation

# Clone the repository
git clone https://github.com/friendly-bits/geoip-shell.git
cd geoip-shell

# Install the tool
sudo make install

Current Configuration

Core Settings

  • Firewall Backend: iptables
  • IP Lists Source: RIPE (Réseaux IP Européens)
  • Network Interfaces: All interfaces protected
  • LAN Detection: Automatic subnet detection enabled

Update Mechanism

  • Cron Service: ✅ Enabled
  • Update Schedule: Daily at 4:08 AM (8 4 * * *)
  • Last Update: September 17, 2025 at 00:57:41
  • Persistence: ✅ Enabled (survives reboots)
  • Backup: ✅ Automatic IP lists backup enabled

Persistence Cron Job

  • Schedule: On reboot (@reboot)
  • Command: /usr/bin/geoip-shell-run.sh restore -a
  • Purpose: Restores geoip-shell firewall rules after system reboot

Inbound Geoblocking Configuration

Blocking Mode

  • Type: Whitelist (only specified countries allowed)
  • IP Families: IPv4 and IPv6 supported

Whitelisted Countries

AL (Albania), AD (Andorra), AM (Armenia), AT (Austria), AZ (Azerbaijan)
BY (Belarus), BE (Belgium), BA (Bosnia and Herzegovina), BG (Bulgaria)
HR (Croatia), CY (Cyprus), CZ (Czech Republic), DK (Denmark)
EE (Estonia), FO (Faroe Islands), FI (Finland), FR (France)
GE (Georgia), DE (Germany), GI (Gibraltar), GR (Greece)
GG (Guernsey), HU (Hungary), IS (Iceland), IE (Ireland)
IM (Isle of Man), IT (Italy), JE (Jersey), KZ (Kazakhstan)
LV (Latvia), LI (Liechtenstein), LT (Lithuania), LU (Luxembourg)
MT (Malta), MD (Moldova), MC (Monaco), ME (Montenegro)
NL (Netherlands), MK (North Macedonia), NO (Norway), PL (Poland)
PT (Portugal), RO (Romania), RU (Russia), SM (San Marino)
RS (Serbia), SK (Slovakia), SI (Slovenia), ES (Spain)
SE (Sweden), CH (Switzerland), TR (Turkey), UA (Ukraine)
GB (United Kingdom), VA (Vatican City)

Network Exceptions (Always Allowed)

IPv4 Networks:

  • 172.18.0.0/16 - Docker network
  • 172.17.0.0/16 - Docker network
  • 169.254.0.0/16 - Link-local addresses
  • 192.168.0.0/24 - Local LAN
  • 172.20.0.0/16 - Docker network
  • 172.19.0.0/16 - Docker network

IPv6 Networks:

  • fdaa:bbcc:ddee::/64 - Custom network
  • fe80::/10 - Link-local addresses

Protocol Coverage

  • TCP: All destination ports blocked for non-whitelisted countries
  • UDP: All destination ports blocked for non-whitelisted countries

Firewall Status

  • IPv4 Chain: ✅ Enabled and active
  • IPv6 Chain: ✅ Enabled and active
  • Whitelist Rules: ✅ Properly configured

Outbound Geoblocking

  • Status: Disabled (no outbound restrictions)

System Health

  • Overall Status: ✅ No problems detected
  • Firewall Integration: ✅ Working correctly
  • Update Process: ✅ Functioning properly

Security Impact

Protection Provided

  1. Geographic Blocking: Blocks all traffic from countries not in whitelist
  2. Comprehensive Coverage: Both IPv4 and IPv6 protection
  3. Full Protocol Coverage: TCP and UDP traffic controlled
  4. Network Awareness: Automatically detects and allows local networks
  5. Persistence: Rules survive system reboots
  6. Automatic Updates: IP lists updated daily

Integration with Existing Security

  • Complements fail2ban: Provides geographic layer above intrusion detection
  • Works with UFW: Uses iptables backend compatible with UFW
  • Docker Compatible: Automatically allows Docker networks
  • LAN Friendly: Preserves local network access

Monitoring and Maintenance

Status Checking

geoip-shell status

Log Locations

  • Main logs: /var/log/geoip-shell.log
  • System logs: journalctl -u geoip-shell

Update Verification

  • Automatic daily updates at 4:18 AM
  • Last update timestamp visible in status
  • Backup of IP lists maintained

Configuration Philosophy

This setup follows a whitelist approach focusing on:

  • Trusted Regions: European countries plus select others
  • Local Access: Full LAN and Docker network access preserved
  • Minimal Disruption: Automatic detection of local networks
  • Comprehensive Protection: Both inbound directions covered

Manual Setup Process

The tool was installed manually with interactive prompts rather than scripted installation due to security considerations. Key decisions made during setup:

  1. Whitelist Mode: Chosen over blacklist for better control
  2. European Focus: Primary whitelist consists of European countries
  3. Network Exceptions: Docker and LAN networks automatically detected
  4. Dual Stack: Both IPv4 and IPv6 protection enabled
  5. Full Protocol Coverage: TCP and UDP both protected

Troubleshooting

Common Issues

  • Service Not Starting: Check systemctl status geoip-shell
  • Rules Not Applied: Verify iptables chains with iptables -L
  • Update Failures: Check /var/log/geoip-shell.log

Recovery Commands

# Restart service
sudo systemctl restart geoip-shell

# Reload configuration
sudo geoip-shell reload

# Check for issues
sudo geoip-shell status

Future Considerations

Potential Enhancements

  • Custom Country Lists: Add/remove countries based on threat intelligence
  • Time-based Rules: Different rules for different times of day
  • Integration with Monitoring: Alert on blocked country attempts
  • Backup Configurations: Document alternative configurations

Monitoring Improvements

  • Log Analysis: Regular review of blocked attempts by country
  • Performance Impact: Monitor system resource usage
  • False Positives: Track legitimate traffic being blocked

References