---
title: "Engine Settings"
description: "Documentation for Engine Settings"
---

## Table of Contents
1. [Overview & Core Architecture](#1-overview--core-architecture)
2. [Business & Operational Significance](#2-business--operational-significance)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Form Layout](#4-visual-interface--form-layout)
5. [Configuration Parameters Reference](#5-configuration-parameters-reference)
6. [Kamailio Core Engine Mechanics](#6-kamailio-core-engine-mechanics)
7. [High-Capacity Tuning & Best Practices](#7-high-capacity-tuning--best-practices)
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 & Core Architecture

In **Ring2All SBC**, the **Engine Settings** module governs the low-level runtime configuration and operational parameters of the underlying Kamailio SIP core engine. It allows platform administrators to tune worker process concurrency, inter-process communication, memory allocation monitoring, system logging facilities, and perimeter protocol identity headers directly from the web interface without manual file editing.

```
       ┌───────────────────────────────────────────────────────────┐
       │                   Incoming SIP Traffic                    │
       │                   (UDP / TCP / TLS / WSS)                 │
       └─────────────────────────────┬─────────────────────────────┘
                                     │
                    ┌────────────────▼────────────────┐
                    │     Ring2All SBC Core Engine     │
                    │        (Kamailio 6.1.x)         │
                    └────────────────┬────────────────┘
                                     │
          ┌──────────────────────────┼──────────────────────────┐
          │                          │                          │
┌─────────▼───────────┐    ┌─────────▼───────────┐    ┌─────────▼───────────┐
│ Worker Concurrency  │    │  Logging & Debug    │    │ Protocol Identity   │
│ • UDP Children (8)  │    │ • Log Level (INFO)  │    │ • Server Signature  │
│ • TCP Children (8)  │    │ • Facility (LOCAL0) │    │ • Custom User-Agent │
│ • Max Conns (16384) │    │ • Memory Debug Flag │    │ • Banner Obscurity  │
└─────────────────────┘    └─────────────────────┘    └─────────────────────┘
```

The SBC engine operates as a multi-process asynchronous SIP proxy. Proper tuning of worker children and connection pools ensures optimal packet throughput, sub-millisecond transaction dispatching, and deterministic performance under high call attempt rates (Calls Per Second - CPS).

---

## 2. Business & Operational Significance

* **System Stability Under Peak CPS**: Accurately provisioning UDP and TCP worker children prevents packet queue saturation during severe traffic spikes or flash crowds.
* **Perimeter Security & Information Obscurity**: Controlling or suppressing the `Server` and `User-Agent` SIP headers prevents external scanners and malicious adversaries from fingerprinting platform versions.
* **Diagnostic Observability**: Centralizing syslog level and facility controls ensures that audit trails, SIP transaction warnings, and memory debug metrics flow reliably to SIEM and log aggregation clusters (e.g., OpenSearch, Graylog, ELK).
* **Memory Leak Prevention**: Enabling memory debugging capabilities allows engineering teams to track shared (`shm`) and private (`pkg`) memory allocations in real time.

---

## 3. 🎯 User Roles & Key Capabilities

| Role | Primary Use Case | Key Capabilities |
| :--- | :--- | :--- |
| **SBC Core Engineer** | Performance Tuning & Concurrency Optimization | Adjust UDP/TCP worker child counts, configure TCP maximum connections, and align engine parameters with host CPU topology. |
| **Security Auditor** | Perimeter Footprint Hardening | Enforce custom User-Agent and Server signatures to mask software versions from unauthenticated reconnaissance probes. |
| **Systems Administrator** | Log Routing & Syslog Governance | Configure log verbosity levels and map logging output to dedicated syslog facilities for automated retention. |
| **NOC Support Specialist** | Real-Time Engine Verification | Verify running daemon parameters and validate engine synchronization status via RPC telemetry. |
| **AI Platform Copilot / NOC Diagnostic Agent** | Autonomous Engine Governance & Tuning | Interrogate core Kamailio engine parameters, inspect Max-Forwards and registration expires limits, verify worker process health, and update perimeter identity settings. |

---

## 4. Visual Interface & Form Layout

The Engine Settings view presents a centralized configuration form divided into logical groups: **Logging & Diagnostics**, **Process Concurrency**, and **Perimeter Identity**.

![Engine Settings Configuration View](/screenshots/sbc/settings/technology/engine-settings/engine-settings.png)

---

## 5. Configuration Parameters Reference

| Field Name | Type | Kamailio Core Directive | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| **Core Log Level** | Select | `debug` / `log_stderror` | `INFO (2)` | Verbosity level for Kamailio engine logging (`L_ERR`, `L_WARN`, `L_INFO`, `L_DBG`). Higher levels increase disk I/O. |
| **Syslog Facility** | Select | `log_facility` | `LOG_LOCAL0` | Dedicated POSIX syslog facility used for routing SIP engine messages to log aggregation daemons. |
| **Memory Debug Level** | Select | `memdbg` | `0 (Disabled)` | Shared and private memory debugging flag. Used during engineering diagnostic sessions to trace memory allocations. |
| **UDP Children Processes** | Integer | `children` | `8` | Number of dedicated worker processes spawned per UDP network interface socket. Recommended: 1 to 2 workers per physical CPU core. |
| **TCP Children Processes** | Integer | `tcp_children` | `8` | Dedicated processes handling inbound TCP/TLS connections and framing. Should match or exceed UDP children in WebRTC/TLS deployments. |
| **TCP Max Connections** | Integer | `tcp_max_connections` | `16384` | Upper bound of concurrent open TCP sockets accepted by the SBC before dropping new handshakes. |
| **Server Signature** | Switch / Text | `server_signature` | `Ring2All SBC` | Header string injected into outbound SIP responses (`Server: ...`). Can be masked or customized for security obscurity. |
| **User-Agent Header** | Text | `user_agent_header` | `Ring2All-SBC/6.1` | Default User-Agent string stamped on locally generated SIP requests (e.g., `OPTIONS` keepalives, `NOTIFY`, `REGISTER`). |

---

## 6. Kamailio Core Engine Mechanics

When changes are saved in the Engine Settings module, the values are written to the `sbc_engine_settings` database table and synchronized with the underlying `/etc/kamailio/sbc-engine-settings.cfg` runtime directives:

```text
# Global Configuration Directives generated by Ring2All SBC Engine Settings
debug = 2
log_facility = LOG_LOCAL0
memdbg = 0
children = 8
tcp_children = 8
tcp_max_connections = 16384
server_signature = no
user_agent_header = "User-Agent: Ring2All-SBC"
```

> [!NOTE]
> Fundamental concurrency changes (such as adjusting `children`, `tcp_children`, or socket listeners) require an engine daemon restart to reallocate shared memory and spawn POSIX worker processes. Dynamic parameters (such as `debug` level) can be reloaded live via the RPC Console.

---

## 7. High-Capacity Tuning & Best Practices

1. **Calculate Children by CPU Cores**:
   $$\text{UDP Children} = \min(\text{Physical CPU Cores} \times 2, 32)$$
   Assigning more worker processes than available hardware threads introduces context switching overhead without increasing packet throughput.
2. **OS Socket Buffers Alignment**:
   Ensure Linux kernel socket receive buffers are aligned with Kamailio process counts:
   ```bash
   sysctl -w net.core.rmem_max=67108864
   sysctl -w net.core.wmem_max=67108864
   ```
3. **Suppress Version Fingerprints in Production**:
   Disable verbose server signatures or replace them with generic labels to comply with PCI-DSS and CIS Security Benchmarks.

---

## 8. Troubleshooting & Verification

### Inspecting Engine Status via RPC
Open the **RPC Console** tool and execute core diagnostic commands:
```bash
core.version
core.shmmem
```
Sample output:
```json
{
  "jsonrpc": "2.0",
  "result": {
    "total": 134217728,
    "free": 118492160,
    "used": 15725568,
    "real_used": 15728640,
    "max_used": 18942100,
    "fragments": 142
  },
  "id": 1
}
```

### Validating Syslog Stream
Verify that log output is routed to `/var/log/kamailio.log` under the configured facility:
```bash
tail -n 20 /var/log/kamailio.log
```

---

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

The Engine Settings module is natively integrated with the Ring2All SBC Model Context Protocol (MCP) server. Autonomous diagnostic agents, platform tuning copilots, and security compliance bots utilize these tools to inspect low-level SIP proxy parameters and apply perimeter identity adjustments.

### Available MCP Tools

| Tool Name | Operation Type | Risk Level | Description |
| :--- | :--- | :--- | :--- |
| `get_engine_settings` | Status Query | `read` | Retrieve active Kamailio core parameters (User-Agent, server signature, max-forwards limit, registration expires boundaries). |
| `update_engine_settings` | Configuration Mutation | `operational` | Update core SIP parameters and synchronize directives to `/etc/kamailio/sbc-engine-settings.cfg`. |

---

### Tool Schemas & Payloads

#### 1. `get_engine_settings`

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

##### Output Payload Example
```json
{
  "success": true,
  "data": {
    "id": 1,
    "user_agent": "Ring2All-SBC-Carrier",
    "server_signature": false,
    "max_forwards": 70,
    "default_expires": 3600,
    "min_expires": 60,
    "max_expires": 7200,
    "updated_at": "2026-09-08T14:30:00.000Z"
  }
}
```

---

#### 2. `update_engine_settings`

##### Input Schema
```json
{
  "type": "object",
  "properties": {
    "user_agent": {
      "type": "string",
      "description": "Custom User-Agent header string (e.g. 'Ring2All-SBC-Enterprise')."
    },
    "server_signature": {
      "type": "boolean",
      "description": "Whether to include Server header signature in SIP responses."
    },
    "max_forwards": {
      "type": "number",
      "description": "SIP Max-Forwards limit (default: 70, range: 10-255)."
    },
    "default_expires": {
      "type": "number",
      "description": "Default SIP registration expiration in seconds (default: 3600)."
    },
    "min_expires": {
      "type": "number",
      "description": "Minimum acceptable SIP registration expiration in seconds (default: 60)."
    },
    "max_expires": {
      "type": "number",
      "description": "Maximum allowable SIP registration expiration in seconds (default: 7200)."
    }
  }
}
```

##### Output Payload Example
```json
{
  "success": true,
  "data": {
    "message": "Engine settings updated successfully."
  }
}
```

---

### Natural Language AI Prompts

#### English Examples
* *"What are our current Kamailio SIP engine parameters and User-Agent signature?"*
* *"Update our SBC engine settings to mask the server signature and set max-forwards to 65."*
* *"Inspect the registration expiry boundaries configured on the SBC engine."*

#### Spanish Examples (Español)
* *"¿Cuáles son los parámetros actuales del motor SIP de Kamailio y la firma de User-Agent?"*
* *"Actualiza los ajustes del motor SBC para ocultar la firma del servidor y fijar max-forwards en 65."*
* *"Inspecciona los límites de expiración de registro configurados en el motor del SBC."*

---

### Enterprise Safeguards & Access Governance
1. **Parameter Sanitization**: The `max_forwards` parameter is strictly clamped between 10 and 255 to prevent forwarding loops or RFC violations.
2. **Cluster Broadcast**: Modifications trigger drop-in configuration regeneration across all active cluster nodes without overwriting core SIP routing logic.
3. **Role-Based Isolation**: Mutations require the `sbc_system_admin` or `noc_network_engineer` profile; read-only operators can inspect settings via `get_engine_settings`.

---

## 10. Glossary

* **CPS (Calls Per Second)**: The number of new SIP `INVITE` transactions established per second.
* **POSIX Children**: Independent OS processes spawned by the core engine to process incoming network frames in parallel.
* **Shared Memory (`shm`)**: Centralized memory pool accessible by all Kamailio worker children for dialogs, transactions, and routing tables.
* **Syslog Facility**: A POSIX standard identifier (e.g., `LOG_LOCAL0`) used by the system logger to categorize log origins and destinations.