homelab/docs/geoip-blocking.md

# 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

```bash
# 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
```bash
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
```bash
# 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

- **Official Repository:** https://github.com/friendly-bits/geoip-shell
- **Documentation:** Available in repository wiki
- **Issue Tracking:** GitHub issues for bug reports and feature requests