---
title: "Hash Tables (HTables)"
description: "Documentation for Hash Tables (HTables)"
---

## Table of Contents
1. [Overview & In-Memory Key-Value Architecture](#1-overview--in-memory-key-value-architecture)
2. [Business & Operational Significance](#2-business--operational-significance)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Layout](#4-visual-interface--layout)
5. [Field Reference & Entry Parameters](#5-field-reference--entry-parameters)
6. [Kamailio `htable` Script Mechanics & Syntax](#6-kamailio-htable-script-mechanics--syntax)
7. [Security & Rate Limiting Integration](#7-security--rate-limiting-integration)
8. [Troubleshooting & Verification](#8-troubleshooting--verification)
9. [Model Context Protocol (MCP) AI Integration](#9-model-context-protocol-mcp-ai-integration)
10. [Glossary](#10-glossary)

---

## 1. Overview & In-Memory Key-Value Architecture

In **Ring2All SBC**, the **Hash Tables (HTables)** module provides high-speed, in-memory key-value data structures held directly inside Kamailio shared memory (`shm`). Powered by the native `htable` module, HTables enable real-time state caching, atomic counter increments, dynamic time-to-live (TTL) expiration, and perimeter security tracking without querying persistent disk storage or external databases.

```
Incoming SIP Request (e.g. 192.168.11.199)
                  │
                  ▼
┌────────────────────────────────────────────────────────┐
│               Kamailio Shared Memory (shm)             │
│                                                        │
│   ┌────────────────────────────────────────────────┐   │
│   │ Table: ipban (Auto-expire TTL: 3600s)          │   │
│   │ • 192.168.11.199 => "pike_flood" (TTL: 1420s)  │   │─── Matched -> Drop Immediately (403)
│   │ • 10.200.5.88    => "failed_auth" (TTL: 280s)   │   │
│   └────────────────────────────────────────────────┘   │
│                                                        │
│   ┌────────────────────────────────────────────────┐   │
│   │ Table: reg_throttle (Rate Limiting)            │   │
│   │ • 2000@domain    => 12 attempts (Counter)      │   │─── Exceeded -> Reject (429)
│   └────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────┘
```

When coupled with the **DMQ (Distributed Message Queue)** cluster module, HTables automatically synchronize security bans and registration counters across all SBC nodes in real time.

---

## 2. Business & Operational Significance

* **Sub-Millisecond Anti-Flood Drops**: Intercepts abusive IP addresses at the earliest possible routing phase, terminating malicious floods before packet processing burdens the CPU.
* **Brute-Force & Password Spray Mitigation**: Tracks failed SIP `REGISTER` and `INVITE` authentication attempts in real time, automatically imposing temporary or permanent bans.
* **Per-Subscriber Rate Limiting**: Maintains atomic transaction counters for call setup attempts, registration frequencies, and concurrent channels without database lock contention.
* **Cluster-Wide Threat Defense**: Immediately synchronizes detected attackers across all active SBC cluster nodes via DMQ, ensuring that an attacker blocked on Node 1 cannot probe Node 2.

---

## 3. 🎯 User Roles & Key Capabilities

| Role | Primary Use Case | Key Capabilities |
| :--- | :--- | :--- |
| **SBC Security Engineer** | Threat Remediation & Perimeter Defense | Inspect active IP bans, manually revoke or impose blacklists, and adjust table auto-expiration TTLs. |
| **High-Throughput Dialplan Developer** | Stateful Routing Logic | Utilize in-memory hash table pseudovariables (`$sht`) for atomic counters, quotas, and state caching. |
| **Anti-Fraud Specialist** | Registration Abuse Investigation | Audit registration throttle tables, track abnormal credential probe spikes, and analyze attack vectors. |
| **Systems Administrator** | Shared Memory Allocation Governance | Monitor hash table bucket sizing, slot utilization, and memory fragmentation via the RPC Console. |
| **AI Security Analyst / SOC Automation Agent** | Perimeter Threat Mitigation | Query active IP ban hash tables, inject emergency perimeter blocks, revoke false-positive bans, and reload memory tables via MCP. |

---

## 4. Visual Interface & Layout

The HTables interface displays all active hash tables, key-value mappings, associated expiration timestamps, and cluster replication indicators.

![Hash Tables (HTables) List View](/screenshots/sbc/settings/logic/htables/htables-list.png)

---

## 5. Field Reference & Entry Parameters

| Field Name | Data Type | Default | Description |
| :--- | :--- | :--- | :--- |
| **Table Name** | String | `ipban` | Name of the defined hash table (e.g., `ipban`, `reg_throttle`, `active_calls`). |
| **Key Identifier** | String | `192.168.11.199` | The unique lookup key (e.g., IP address, username, Call-ID, or domain string). |
| **Value / Payload** | String / Integer | `1` | Stored data associated with the key (e.g., ban reason, integer counter, or timestamp). |
| **TTL Remaining** | Seconds / Time | `3420s` | Seconds remaining before the key is automatically purged from memory by Kamailio's garbage collector. |
| **Auto-Expire Flag** | Boolean | `true` | Indicates whether keys in this table expire automatically according to their configured lifetime. |
| **DMQ Replicate** | Boolean | `true` | Specifies whether updates, additions, or deletions to this entry are broadcast across the DMQ mesh cluster. |

---

## 6. Kamailio `htable` Script Mechanics & Syntax

In the Kamailio routing script, hash tables are accessed using the `$sht(table=>key)` pseudovariable family:

```text
# Configuration Definition in kamailio.cfg
modparam("htable", "htable", "ipban=>size=12;autoexpire=3600;dmqreplicate=1")
modparam("htable", "htable", "reg_throttle=>size=10;autoexpire=60")

route[CHECK_PERIMETER_IPBAN] {
    # Check if the source IP address ($si) exists in the ipban table
    if ($sht(ipban=>$si) != $null) {
        xlog("L_WARN", "[HTABLE] Dropping packet from banned IP: $si (Reason: $sht(ipban=>$si))\n");
        sl_send_reply("403", "Forbidden - IP Banned");
        exit;
    }
}

route[RECORD_FAILED_AUTH] {
    # Increment failed attempts counter
    $shtinc(reg_throttle=>$si);
    if ($sht(reg_throttle=>$si) > 5) {
        # Ban IP for 1 hour
        $sht(ipban=>$si) = "Brute Force Threshold Exceeded";
        $shtex(ipban=>$si) = 3600;
        xlog("L_ALERT", "[SECURITY] IP $si banned for 3600s due to failed authentications\n");
    }
}
```

---

## 7. Security & Rate Limiting Integration

HTables serve as the real-time cache for multiple perimeter protection modules:

1. **Pike Anti-Flood Integration**: When Pike detects a packet rate exceeding the threshold (e.g., > 30 requests within 2 seconds), it sets an entry in `$sht(ipban=>$si)`.
2. **APIBAN Threat Feed Ingestion**: Blacklisted IP addresses ingested from APIBAN are populated directly into HTables for instant, zero-latency rejection.
3. **Session Concurrency Guard**: Tracks active calls per domain or subscriber, immediately returning `SIP 486 Busy Here` if a customer exceeds their contracted channel limit.

---

## 8. Troubleshooting & Verification

### Inspecting Table Contents via RPC Console
Dump all keys from the `ipban` table in the **RPC Console**:
```bash
htable.dump ipban
```
Output:
```json
{
  "jsonrpc": "2.0",
  "result": [
    {
      "name": "ipban",
      "size": 4096,
      "entries": [
        {
          "key": "192.168.11.199",
          "value": "pike_flood",
          "type": "str",
          "expires": 3412
        }
      ]
    }
  ],
  "id": 1
}
```

### Manually Removing an IP Ban Entry
To unblock a legitimate customer IP address immediately:
```bash
htable.delete ipban 192.168.11.199
```

---

## 9. Model Context Protocol (MCP) AI Integration

The Hash Tables (HTables) subsystem connects with the Model Context Protocol (MCP) to allow diagnostic and incident-response agents to inspect in-memory tables, dump security ban records, inject temporary blocks, unban whitelisted addresses, and reload memory structures.

### Available MCP Tools

| Tool Name | Operation Type | Risk Level | Description |
| :--- | :--- | :--- | :--- |
| `list_htables` | Status Query | `read` | List all defined hash tables in Kamailio shared memory with size and auto-expire policies. |
| `get_htable_entries` | Content Dump | `read` | Dump all active key-value entries from a specific hash table (e.g. `ipban`, `reg_throttle`). |
| `set_htable_entry` | Security Mutation | `operational` | Set or update a key-value entry in a Kamailio hash table with optional type definition. |
| `delete_htable_entry` | Threat Revocation | `operational` | Remove an entry or unban an IP from a Kamailio hash table immediately. |
| `reload_htables` | Operational Reload | `operational` | Reload a database-backed hash table into Kamailio shared memory via JSON-RPC. |

### Tool Schemas & Payloads

#### 1. `list_htables`

##### Input Schema
```json
{
  "type": "object",
  "properties": {}
}
```

##### Output Payload Example
```json
{
  "success": true,
  "data": {
    "totalTables": 3,
    "tables": [
      { "name": "ipban", "size": 4096, "autoexpire": 3600, "dmqreplicate": true },
      { "name": "reg_throttle", "size": 1024, "autoexpire": 60, "dmqreplicate": false },
      { "name": "auth_cache", "size": 2048, "autoexpire": 300, "dmqreplicate": false }
    ]
  }
}
```

#### 2. `get_htable_entries`

##### Input Schema
```json
{
  "type": "object",
  "properties": {
    "table_name": {
      "type": "string",
      "description": "Name of the hash table to dump (e.g. 'ipban')."
    }
  },
  "required": ["table_name"]
}
```

##### Output Payload Example
```json
{
  "success": true,
  "data": {
    "tableName": "ipban",
    "totalEntries": 1,
    "entries": [
      {
        "key": "192.168.11.199",
        "value": "pike_flood",
        "type": "str",
        "expires": 3412
      }
    ]
  }
}
```

#### 3. `delete_htable_entry`

##### Input Schema
```json
{
  "type": "object",
  "properties": {
    "table_name": {
      "type": "string",
      "description": "Target hash table (e.g. 'ipban')."
    },
    "key": {
      "type": "string",
      "description": "Key or IP to remove from the table (e.g. '192.168.11.199')."
    }
  },
  "required": ["table_name", "key"]
}
```

##### Output Payload Example
```json
{
  "success": true,
  "data": {
    "message": "Key '192.168.11.199' deleted successfully from table 'ipban'.",
    "rpc_response": "OK"
  }
}
```

### Natural Language AI Prompts

#### English Examples
* *"Dump all banned IP addresses currently stored in the 'ipban' hash table."*
* *"Unban IP address '192.168.11.199' by deleting its entry from the 'ipban' table."*
* *"List all Kamailio in-memory hash tables and their bucket configurations."*

#### Spanish Examples (Español)
* *"Vuelca todas las direcciones IP bloqueadas actualmente en la tabla hash 'ipban'."*
* *"Desbloquea la dirección IP '192.168.11.199' eliminando su entrada de la tabla 'ipban'."*
* *"Lista todas las tablas hash en memoria de Kamailio y sus configuraciones de buckets."*

### Enterprise Safeguards & Access Governance
1. **Immediate Cluster Propagation**: Entry deletions in DMQ-enabled tables are propagated across the cluster to avoid inconsistent state between SBC nodes.
2. **Type Safety Clamping**: Entry value types (`str` or `int`) are explicitly validated prior to JSON-RPC dispatch.
3. **Role Segregation**: Unbanning IPs or mutating security tables requires `noc_network_engineer` or `sbc_system_admin` privileges.

---

## 10. Glossary

* **HTable (Hash Table)**: An associative array data structure that stores key-value pairs in memory for $O(1)$ constant-time lookup performance.
* **TTL (Time-To-Live)**: A timer mechanism that automatically deletes an entry from memory after a predetermined duration.
* **Atomic Increment (`$shtinc`)**: A thread-safe operation that increases an integer counter without risk of race conditions between worker processes.
* **DMQ Replication**: Automatic synchronization of hash table keys, values, and expiration timers across multiple SBC nodes.