---
title: "GeoFirewall Module Documentation"
description: "Documentation for Geo Firewall"
---

## Table of Contents
1. [Navigation & Access](#navigation--access)
2. [Screenshots & Visual Interface](#screenshots--visual-interface)
3. [Module Overview (Technical)](#1-module-overview-technical)
4. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness)
5. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator)
6. [User Roles & Key Capabilities](#-user-roles--key-capabilities)
7. [Configuration Sections](#4-configuration-sections)
8. [Settings Reference](#5-settings-reference)
9. [Common Scenarios & Examples](#6-common-scenarios--examples)
10. [Model Context Protocol (MCP) AI Integration](#model-context-protocol-mcp-ai-integration)
11. [Limitations & Important Notes](#7-limitations--important-notes)
12. [Troubleshooting Tips](#8-troubleshooting-tips)
13. [Glossary](#9-glossary)
---

## Navigation & Access

To access the Geo Firewall module:
1. Log in to the Ring2All Web Portal (`https://<domain-or-ip>/login`) with administrative credentials.
2. In the left navigation sidebar, locate and expand **Admin**.
3. Under the **Firewall** section, click **Geo Firewall** (`/admin/firewall/geo`).
4. Interact directly with the SVG world map by clicking countries to toggle between **Allowed** (green) and **Blocked** (red), or use the country search selector at the top right.
5. Use the map zoom (`+` / `-`) and reset controls at the bottom left to navigate regions.
6. Click **Save** in the bottom action bar to apply geographic IP filtering rules into the system firewall.

---

## Screenshots & Visual Interface

### Geo Firewall Interactive World Map
The Geo Firewall module renders a high-performance interactive vector world map where countries are color-coded in real time according to their traffic admission status. Blocked high-risk jurisdictions are highlighted in red, allowed traffic origins in green, and changes can be inspected and committed dynamically.
![Geo Firewall Interactive Map](/screenshots/admin/firewall/geofirewall-list.png)

---

## 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                            │   │
│  │    }                                                     │   │
│  │  }                                                       │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

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

1. **Block Attack Origins**
   - Block high-risk countries
   - Reduce SIP scanning

2. **Regional Service**
   - Allow only service region
   - Restrict global access

3. **Compliance**
   - Geographic restrictions
   - Data sovereignty

4. **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 Interface - Form/List View

```
┌─────────────────────────────────────────────────────────────────┐
│              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!

---

## 🎯 User Roles & Key Capabilities

The GeoFirewall module allocates country-level filtering controls across platform operational roles:

| User Role | Key Permissions & Responsibilities | Common Tasks & Workflows |
|:---|:---|:---|
| **System Super Administrator / Security Officer** | Full authority to manage global country block/allow lists, interactive map toggles, and kernel ipset bindings. | Block entire high-risk geographical zones (e.g. regions with zero legitimate business), commit rules to nftables, safeguard host country access. |
| **Tenant Administrator** | Scoped review of allowed countries to ensure international branches and teleworkers are reachable. | Verify country access status for employees traveling abroad, request targeted country exemptions from the security operations team. |
| **Fraud Prevention Analyst / NOC** | Rapid response to international toll fraud campaigns and distributed brute-force attacks. | Identify spike origins in real time, toggle targeted nations to `BLOCK` during live volumetric SIP sweeps, analyze geographic traffic telemetry. |
| **Regulatory & Compliance Auditor** | Auditing geographic network boundaries to satisfy cross-border telecommunication mandates. | Verify that sanctioned jurisdictions are systematically blocked at layer 3/4, inspect changes to geographic access permissions. |

---

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

1. Open GeoFirewall
2. Click on China → Block
3. Click on Russia → Block
4. Click on North Korea → Block
5. Apply Rules

### Scenario 2: Allow Only USA

1. Click "Select All" → Block All
2. Click on USA → Allow
3. Set priority (Allow lower than Block)
4. Apply Rules

### Scenario 3: Block Toll Fraud Origins

1. Identify high-risk countries for toll fraud
2. Block: Cuba, Somalia, Guinea-Bissau
3. Block: Mauritania, Sierra Leone
4. Apply Rules
5. 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

1. **Know Your Users**: Don't block legitimate users
2. **Allow First**: Create allow rules with lower priority
3. **Test Access**: Verify after applying rules
4. **Update Database**: Keep GeoIP current
5. **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 |

---

## Model Context Protocol (MCP) AI Integration

The GeoFirewall module connects directly to the **Ring2All Platform Copilot MCP Server**, enabling natural language geographic IP policy inspection and management:

### 🛠️ Available MCP Tools

| Tool Name | Operation | Access Level | Description | Key Parameters |
|:---|:---|:---|:---|:---|
| `list_geofirewall_rules` | Read | SuperAdmin / Auditor | Lists country-level GeoFirewall rules, displaying country code, country name, action (`block` or `allow`), direction, and enabled state. | `search` (string), `action` (`accept`, `drop`, `allow`, `block`), `direction` (`input`, `output`), `countryCode` (string), `enabled` (boolean) |
| `list_firewall_rules` | Read | SuperAdmin / Auditor | Inspects general packet filtering rules that interact with geographic sets. | `search` (string, optional) |
| `get_voipbl_status` | Read | SuperAdmin / Auditor | Returns status of threat intelligence blocklists working alongside GeoIP filtering. | None |

### 📋 JSON Tool Schemas & Sample Executions

#### `list_geofirewall_rules`

```json
{
  "name": "list_geofirewall_rules",
  "arguments": {
    "action": "block"
  }
}
```

*Sample Successful Response:*
```json
{
  "success": true,
  "data": {
    "total": 2,
    "rules": [
      {
        "id": 1,
        "name": "Block High-Risk Eastern Europe",
        "countryCode": "RU",
        "countryName": "Russian Federation",
        "action": "block",
        "direction": "input",
        "priority": 50,
        "enabled": true
      },
      {
        "id": 2,
        "name": "Block High-Risk Asia Scanners",
        "countryCode": "CN",
        "countryName": "China",
        "action": "block",
        "direction": "input",
        "priority": 50,
        "enabled": true
      }
    ]
  }
}
```

### 💬 Natural Language Prompt Examples

#### English Prompts
- *"List all countries currently blocked by the PBX GeoFirewall."*
- *"Check if traffic from Mexico (country code MX) is allowed or blocked."*
- *"Show all active GeoFirewall rules with high priority (priority <= 50)."*
- *"Verify whether any inbound GeoFirewall rule blocks the United States (US)."*

#### Ejemplos en Español (Spanish Prompts)
- *"Lista todos los países actualmente bloqueados por el GeoFirewall de la centralita."*
- *"Verifica si el tráfico procedente de México (código MX) está permitido o bloqueado."*
- *"Muestra todas las reglas de GeoFirewall activas con prioridad alta (prioridad <= 50)."*
- *"Comprueba si alguna regla entrante de GeoFirewall bloquea a Estados Unidos (US)."*

### 🛡️ Enterprise Safeguards & Best Practices
1. **Home Country Lockout Safeguard**: System initialization verifies that the host server's local country and primary operating jurisdiction are not set to `block`, preventing accidental administrative lockout.
2. **Kernel ipset Efficiency**: Country IP blocks are aggregated into high-performance kernel sets (`nftables set`), allowing millions of IPv4/IPv6 subnets to be evaluated in O(1) CPU lookup time.
3. **Database Freshness**: GeoIP subnet mappings are continuously updated against verified MaxMind GeoLite2 databases to prevent stale ISP classification errors.

---

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

```sql
SELECT 
  name,
  country_code,
  action,
  direction,
  priority,
  is_enabled
FROM public.geo_firewall_rules
ORDER BY priority;
```

### GeoIP Lookup

```bash
# Check IP country
geoiplookup 8.8.8.8

# View GeoIP database info
geoiplookup -v
```

### Emergency Recovery

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

---

*Documentation last updated: January 2026*