GeoIP Database Guide

GeoIP Database Guide

How NFTBan uses GeoIP databases for geographic blocking and threat analysis.

---

What is GeoIP?

GeoIP (Geographic IP) is a database that maps IP addresses to physical locations. When NFTBan receives network traffic, it can look up where that IP address is located in the world.

Why Does NFTBan Need GeoIP?

NFTBan uses GeoIP databases for several security features:

• Geographic blocking - Block entire countries (e.g., nftban geoban block CN)
• Geographic allowing - Only allow specific countries (whitelist mode)
• Threat analysis - See where attacks are coming from
• Statistics - Geographic distribution of banned IPs
• IP lookup - Investigate suspicious IPs (nftban geoip lookup 8.8.8.8)

Example:

# Block all traffic from China and Russia
nftban geoban block CN
nftban geoban block RU

# Lookup where an IP is from
nftban geoip lookup 1.2.3.4
# Output: CN/China

---

Database Providers

NFTBan supports two GeoIP database providers. Choose the one that best fits your needs.

DB-IP Lite (Default)

Property	Value
Database	dbip-country-lite.mmdb
Size	~7 MB
Location	/var/lib/nftban/geoip/dbip-country-lite.mmdb
Data included	Country code + Country name
Accuracy	~99% country-level
Cost	FREE (no registration required)
License	CC BY 4.0
Updates	Monthly

Advantages:

• No registration or license key required
• Works out of the box
• Smaller download size
• High country-level accuracy

Attribution: IP Geolocation by DB-IP

---

MaxMind GeoLite2 (Optional)

Property	Value
Database	GeoLite2-Country.mmdb or GeoLite2-City.mmdb
Size	~6 MB (Country) or ~61 MB (City)
Location	/var/lib/nftban/geoip/GeoLite2-*.mmdb
Data included	Country + City + Coordinates + Timezone (City edition)
Accuracy	~99% country, ~70% city
Cost	FREE (requires license key)
Updates	Weekly

Advantages:

• City-level geolocation available
• Official source from MaxMind
• More frequent updates

Requirement: Free license key from MaxMind

---

Quick Start

Using DB-IP (Default - No Configuration Needed)

# Download database
sudo nftban-core geoip update

# Test lookup
nftban-core geoip lookup 8.8.8.8
# Output: US/United States

That's it! No registration or license key required.

---

Using MaxMind (Optional)

Step 1: Get free license key from MaxMind GeoLite2 Signup

Step 2: Configure NFTBan to use MaxMind

# Set MaxMind as source
nftban geoip config set-source maxmind

# Set your license key
nftban geoip config set-key YOUR_LICENSE_KEY_HERE

# Download database
sudo nftban-core geoip update

Step 3: Verify it works

nftban-core geoip lookup 8.8.8.8
# Output: US/United States

---

Configuration

View Current Configuration

nftban geoip config show

Output:

Database Source:
  Current: dbip

DB-IP Lite Settings (DEFAULT):
  URL: https://download.db-ip.com/free/
  License: CC BY 4.0 (Free, no registration)
  Updates: Monthly (automatic)

Database Location:
  Path: /var/lib/nftban/geoip/dbip-country-lite.mmdb
  Size: 7.0M
  Date: 2026-01-04

Configuration Commands

Command	Description
nftban geoip config show	Show current configuration
nftban geoip config set-source dbip	Use DB-IP Lite (default)
nftban geoip config set-source maxmind	Use MaxMind GeoLite2
nftban geoip config set-key KEY	Set MaxMind license key
nftban geoip config test-download	Test database download

Configuration Files

# System configuration
/etc/nftban/conf.d/nftban-go.conf

# User overrides (created by config commands)
/etc/nftban/conf.d/nftban-go.conf.local

Example /etc/nftban/conf.d/nftban-go.conf.local:

GEOIP_DB_SOURCE="maxmind"
GEOIP_MAXMIND_LICENSE_KEY="your_key_here"

---

Database Management

Check Database Status

nftban-core geoip status

Output:

GeoIP Database Status
======================================================================

Database: FOUND
   Path: /var/lib/nftban/geoip/dbip-country-lite.mmdb
   Size: 7.0 MB
   Modified: 2026-01-04 20:02:37

Database Information:
  Type: DBIP-Country-Lite
  Build Date: 2026-01-01
  Description: DB-IP.com - IP to Country
  IP Version: 6
  Node Count: 1214986

Performance Test (10 lookups):
  Average lookup time: 2 microseconds
  Performance: EXCELLENT (<1ms)

Update Database

# Download latest database
sudo nftban-core geoip update

IP Lookup

# Basic lookup
nftban-core geoip lookup 8.8.8.8
# Output: US/United States

# JSON format (for scripts)
nftban-core geoip lookup 8.8.8.8 --json
# Output: {"ip":"8.8.8.8","country_code":"US","country_name":"United States","database":"dbip-country-lite.mmdb"}

---

Automatic Updates

NFTBan keeps your GeoIP database fresh automatically using a systemd timer.

Update Schedule

• Weekly: Every Sunday at 2:00 AM
• On boot: 30 minutes after system startup
• Randomization: Random delay (0-60 minutes) to avoid server overload

Check Timer Status

# See when next update will run
systemctl list-timers nftban-core-geoip.timer

# Check if timer is active
systemctl status nftban-core-geoip.timer

# View update logs
sudo journalctl -u nftban-core-geoip.service -n 50

---

Database Compatibility

NFTBan automatically detects and uses whichever database is available, checking in this order:

1. dbip-country-lite.mmdb (DB-IP Lite - default)
2. GeoLite2-City.mmdb (MaxMind City - with city data)
3. GeoLite2-Country.mmdb (MaxMind Country)

This means:

• You can switch providers anytime
• Both databases can coexist
• Lookups use the first available database

---

Troubleshooting

Database File Missing

# Check if database exists
ls -l /var/lib/nftban/geoip/

# If missing, download it
sudo nftban-core geoip update

Download Fails

# Test download connectivity
nftban geoip config test-download

# Check network
ping download.db-ip.com

# For MaxMind, verify license key is correct
nftban geoip config show

Wrong Country Returned

GeoIP accuracy varies:

• Country-level: ~99% accurate
• City-level: ~70% accurate (MaxMind City only)

Solutions:

• Update database: sudo nftban-core geoip update
• VPN/proxy IPs show VPN server location, not user location

Permission Denied

# Fix directory permissions
sudo chown -R nftban:nftban /var/lib/nftban/geoip/
sudo chmod 750 /var/lib/nftban/geoip/

---

Quick Reference

Common Commands

# Check database status
nftban-core geoip status

# Update database
sudo nftban-core geoip update

# Lookup IP address
nftban-core geoip lookup <IP>

# Lookup with JSON output
nftban-core geoip lookup <IP> --json

# Show configuration
nftban geoip config show

# Switch to MaxMind
nftban geoip config set-source maxmind
nftban geoip config set-key YOUR_KEY

# Switch back to DB-IP
nftban geoip config set-source dbip

File Locations

File	Description
/var/lib/nftban/geoip/dbip-country-lite.mmdb	DB-IP database
/var/lib/nftban/geoip/GeoLite2-Country.mmdb	MaxMind Country database
/var/lib/nftban/geoip/GeoLite2-City.mmdb	MaxMind City database
/etc/nftban/conf.d/nftban-go.conf.local	User configuration

---

Provider Comparison

Feature	DB-IP Lite	MaxMind GeoLite2
Registration	Not required	Required (free)
License Key	Not required	Required
Database Size	~7 MB	~6 MB (Country) / ~61 MB (City)
Country Data	Yes	Yes
City Data	No	Yes (City edition)
Coordinates	No	Yes (City edition)
Timezone	No	Yes (City edition)
Update Frequency	Monthly	Weekly
License	CC BY 4.0	GeoLite2 EULA

---

Related Documentation

• CLI Commands Reference - Full command list
• Configuration Reference - Central config options
• Security Architecture - System security design

---

Last updated: March 2026 | NFTBan v1.19.10