GeoFirewall Module Documentation
Table of Contents
- Module Overview (Technical)
- Module Overview (Commercial/Business)
- Module Overview (End User/Administrator)
- Configuration Sections
- Settings Reference
- Common Scenarios & Examples
- Limitations & Important Notes
- Troubleshooting Tips
- Glossary
---
1. Module Overview (Technical)
What Is GeoFirewall?
GeoFirewall is a country-based firewall module that creates rules based on geographic IP ranges. It provides an interactive world map for country selection and supports both blocking and allowing traffic by country.
Architecture
┌─────────────────────────────────────────────────────────────────┐
│ GeoFirewall Architecture │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Interactive World Map │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │ │
│ │ │ 🟢 │ │ 🔴 │ │ 🔴 │ │ ⚪ │ │ 🟢 │ │ │
│ │ │ USA │ │ CN │ │ RU │ │ BR │ │ UK │ │ │
│ │ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ │ │
│ │ │ │
│ │ 🟢 Allowed 🔴 Blocked ⚪ Unselected │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ Generates rules │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ GeoFirewall Rules │ │
│ │ │ │
│ │ ┌────────────────┐ ┌────────────────┐ │ │
│ │ │ Block China │ │ Block Russia │ │ │
│ │ │ Country: CN │ │ Country: RU │ │ │
│ │ │ Action: Block │ │ Action: Block │ │ │
│ │ │ Priority: 100 │ │ Priority: 110 │ │ │
│ │ └────────────────┘ └────────────────┘ │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ Applied to nftables with GeoIP │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Linux Firewall (nftables + GeoIP) │ │
│ │ │ │
│ │ table inet geo_filter { │ │
│ │ chain input { │ │
│ │ # Block China │ │
│ │ ip saddr @geoip_cn drop │ │
│ │ # Block Russia │ │
│ │ ip saddr @geoip_ru drop │ │
│ │ } │ │
│ │ } │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Key Tables
| Table | Purpose |
|---|
public.geo_firewall_rules | Country rules |
Key Files
| File | Description |
|---|
modules/geoFirewall/ | Frontend module | |
| GeoIP database | Country IP ranges |
2. Module Overview (Commercial/Business)
Business Value
GeoFirewall provides geographic access control:
| Without GeoFirewall | With GeoFirewall |
|---|
| No geo blocking | Block by country | |
| IP range research | Visual map selection | |
| Manual ranges | Auto GeoIP updates | |
| Complex setup | Click to block |
Use Cases
- Block Attack Origins
- Block high-risk countries
- Reduce SIP scanning
- Regional Service
- Allow only service region
- Restrict global access
- Compliance
- Geographic restrictions
- Data sovereignty
- Cost Control
- Block toll fraud countries
- Limit international access
Feature Highlights
| Feature | Benefit |
|---|
| Interactive Map | Visual selection | |
| Block/Allow | Flexible actions | |
| Bulk Operations | Select/deselect all | |
| Enable/Disable | Quick toggle | |
| Priority Order | Controlled evaluation | |
| GeoIP Database | Accurate IP mapping |
3. Module Overview (End User/Administrator)
What Can You Do?
- Block countries by clicking on map
- Allow only specific countries
- Search for countries
- Select/deselect all countries
- Enable/disable all rules
- Set rule priority
- Apply rules to firewall
GeoFirewall Interface - Map View
┌─────────────────────────────────────────────────────────────────┐
│ GeoFirewall │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Manage firewall rules by country │
│ │
│ [🔍 Search country...] [GeoFirewall: ● Enabled] │
│ │
│ [Map] [Form] │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ WORLD MAP │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────┐ │ │
│ │ │ │ │ │
│ │ │ 🟢 USA 🔴 CN ⚪ IN │ │ │
│ │ │ │ │ │
│ │ │ 🟢 UK 🔴 RU ⚪ BR │ │ │
│ │ │ │ │ │
│ │ │ 🟢 CA 🔴 KP ⚪ AU │ │ │
│ │ │ │ │ │
│ │ └─────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ [+ Zoom] [- Zoom] [Reset] [Select All] [Unselect All] │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
│ Legend: 🟢 Allowed 🔴 Blocked ⚪ Unselected │
│ │
│ Selected: 6 countries (3 blocked, 3 allowed) │
│ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ GeoFirewall │
├─────────────────────────────────────────────────────────────────┤
│ │
│ [Map] [Form] │
│ │
│ [+ Add Rule] [Enable All] [Disable All] [Apply Rules] │
│ │
│ [🔍 Search rules...] │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Name │ Country │ Action│ Direction│ Pri │ St │ │
│ ├──────────────┼────────────┼───────┼──────────┼─────┼────┤ │
│ │ Block China │ 🇨🇳 China │ Block │ Input │ 100 │ ● │ │
│ │ Block Russia │ 🇷🇺 Russia │ Block │ Input │ 110 │ ● │ │
│ │ Block N.Korea│ 🇰🇵 N. Korea│ Block │ Input │ 120 │ ● │ │
│ │ Allow USA │ 🇺🇸 USA │ Allow │ Input │ 200 │ ● │ │
│ │ Allow UK │ 🇬🇧 UK │ Allow │ Input │ 210 │ ● │ │
│ │ Allow Canada │ 🇨🇦 Canada │ Allow │ Input │ 220 │ ● │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Add/Edit Rule
┌─────────────────────────────────────────────────────────────────┐
│ Add GeoFirewall Rule │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Rule Name: [Block China ] │
│ Descriptive name (e.g., Block China, Allow USA) │
│ │
│ Country: [🇨🇳 China (CN) ▼] │
│ Selected from map or dropdown │
│ Rule applies to all traffic from/to this country │
│ │
│ Action: [Block ▼] │
│ Block (discard traffic) | Allow (permit traffic) │
│ │
│ Direction: [Input ▼] │
│ Input (to server) | Output (from server) | Forward │
│ │
│ Priority: [100 ] │
│ Rule priority (0-9999). Lower numbers evaluated first │
│ │
│ Enabled: ✓ │
│ │
│ [Save] [Cancel] │
│ │
└─────────────────────────────────────────────────────────────────┘
Quick Tips
TIP
Map Click: Click any country on the map to block/allow.
TIP
Search: Use search to quickly find countries.
WARNING
Don't Block Your Country: Ensure your access isn't blocked!
---
4. Configuration Sections
Rule Fields
| Field | Description |
|---|
| Rule Name | Unique identifier | |
| Country | Selected country | |
| Action | Block or Allow | |
| Direction | Input, Output, Forward | |
| Priority | Order (0-9999) | |
| Enabled | Active/Inactive |
Map Controls
| Control | Description |
|---|
| Zoom In | Enlarge map | |
| Zoom Out | Shrink map | |
| Reset | Default view | |
| Select All | Block/allow all | |
| Unselect All | Remove all rules |
5. Settings Reference
Actions
| Action | Behavior | Use Case |
|---|
| Block | Drop all traffic | High-risk countries | |
| Allow | Permit traffic | Service regions |
Common Blocked Countries (High SIP Attacks)
| Country | Code | Risk Level |
|---|
| China | CN | High | |
| Russia | RU | High | |
| North Korea | KP | High | |
| Iran | IR | Medium | |
| Vietnam | VN | Medium | |
| Indonesia | ID | Medium |
Regional Allow Lists
| Region | Countries |
|---|
| North America | US, CA, MX | |
| Western Europe | UK, DE, FR, ES, IT | |
| APAC Business | JP, AU, SG, KR |
6. Common Scenarios & Examples
Scenario 1: Block High-Risk Countries
- Open GeoFirewall
- Click on China → Block
- Click on Russia → Block
- Click on North Korea → Block
- Apply Rules
Scenario 2: Allow Only USA
- Click "Select All" → Block All
- Click on USA → Allow
- Set priority (Allow lower than Block)
- Apply Rules
Scenario 3: Block Toll Fraud Origins
- Identify high-risk countries for toll fraud
- Block: Cuba, Somalia, Guinea-Bissau
- Block: Mauritania, Sierra Leone
- Apply Rules
- Monitor CDR for anomalies
Scenario 4: Regional Service
Allow Rules (Priority 10-100):
├─ USA (10)
├─ Canada (20)
├─ UK (30)
├─ Germany (40)
└─ France (50)
Block Rule (Priority 9999):
└─ All others (catch-all)
---
7. Limitations & Important Notes
Technical Notes
NOTE
GeoIP Database: Accuracy depends on database updates.
NOTE
VPN/Proxy: Users can bypass with VPNs.
WARNING
Self-Block: Don't block your own country!
Best Practices
- Know Your Users: Don't block legitimate users
- Allow First: Create allow rules with lower priority
- Test Access: Verify after applying rules
- Update Database: Keep GeoIP current
- Monitor Logs: Watch for blocked traffic
GeoIP Limitations
| Limitation | Impact |
|---|
| VPN bypass | Users appear from VPN country | |
| CDN/Cloud | IP may show as different country | |
| Accuracy | ~95-99% for countries | |
| Updates | Need periodic database refresh |
8. Troubleshooting Tips
Common Issues
| Symptom | Possible Cause | Solution |
|---|
| Blocked unexpectedly | Wrong country blocked | Check rules | |
| Can't connect | Own country blocked | Console access | |
| Still getting attacks | VPN/proxy | Add IP blacklist | |
| Map not loading | Library missing | Check npm install |
Check Rules
SELECT
name,
country_code,
action,
direction,
priority,
is_enabled
FROM public.geo_firewall_rules
ORDER BY priority;
GeoIP Lookup
# Check IP country
geoiplookup 8.8.8.8
# View GeoIP database info
geoiplookup -v
Emergency Recovery
# If blocked yourself:
# 1. Access server console
# 2. Disable GeoFirewall
systemctl stop nftables
# 3. Fix rules via admin panel
# 4. Re-enable
systemctl start nftables
---
9. Glossary
| Term | Definition |
|---|
| GeoIP | IP to country mapping | |
| GeoFirewall | Country-based firewall | |
| Block | Deny traffic | |
| Allow | Permit traffic | |
| Country Code | ISO 3166-1 alpha-2 |
Lua Script Status ℹ️
Security Module
| Component | Status |
|---|
| GeoFirewall | ℹ️ Country-based firewall - no Lua handler required |
---
Documentation last updated: January 2026
