---
title: "Firewall Services Module Documentation"
description: "Documentation for Services"
---

## Table of Contents
1. [Module Overview (Technical)](#1-module-overview-technical)
2. [Module Overview (Commercial & Business Value)](#2-module-overview-commercial--business-value)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Form Structure](#4-visual-interface--form-structure)
5. [Architectural Flow & Security Governance](#5-architectural-flow--security-governance)
6. [Common Scenarios & Operational Playbooks](#6-common-scenarios--operational-playbooks)
7. [Troubleshooting & Diagnostic Commands](#7-troubleshooting--diagnostic-commands)
8. [Model Context Protocol (MCP) AI Integration](#8-model-context-protocol-mcp-ai-integration)
9. [Glossary](#9-glossary)

---

## 1. Module Overview (Technical)

The **Firewall Services** module (`public.firewall_services`) defines standard named network services, protocols, and port definitions utilized across **Ring2All Billing**. In high-availability telecommunications and billing environments, exposing explicit TCP/UDP ports for web interfaces, REST APIs, database clustering, and caching must be governed through reusable service abstractions rather than hardcoded firewall port numbers.

Services created in this module can be directly referenced by higher-level firewall rules and access control policies. Each service maintains a protocol definition (`TCP`, `UDP`, or `TCP/UDP`), single or ranged port allocations (e.g., `80`, `8443`, `8000-8010`), and an operational toggle that can disable access across all dependent firewall chains simultaneously.

### Data Model & System Linkage

```
 ┌────────────────────────────────────────────────────────────────────────┐
 │               Firewall Service Entity (public.firewall_services)       │
 │  • id: bigint (Canonical Primary Key)                                  │
 │  • name: VARCHAR(100) (e.g., 'HTTPS Portal Web', 'Fastify Billing API')│
 │  • protocol: 'TCP' | 'UDP' | 'BOTH'                                    │
 │  • port: VARCHAR(50) (Single '8443' or Port Range '8000-8010')         │
 │  • description: text (Functional Scope & Service Purpose)              │
 │  • is_system: boolean (Protects Core OS Services from Deletion)        │
 │  • enabled: boolean (State Toggle)                                     │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
           ┌─────────────────────────┴─────────────────────────┐
           ▼                                                   ▼
 ┌───────────────────────────────────┐               ┌───────────────────────────────────┐
 │       Firewall Rules Linkage      │               │       Linux Kernel Netfilter      │
 │ • Referenced by custom rules      │               │ • Translates into nftables sets   │
 │ • Reusable across multiple subnets│               │ • Opens/closes ports in INPUT     │
 └───────────────────────────────────┘               └───────────────────────────────────┘
```

### PostgreSQL Schema Architecture

* **`public.firewall_services`**:
  * `id`: Numeric primary key (`bigserial`).
  * `name`: Unique human-readable service identifier.
  * `protocol`: Transport layer protocol (`'TCP'`, `'UDP'`, `'BOTH'`).
  * `port`: Comma-separated list or port range string (e.g., `'80'`, `'8443'`, `'3003'`, `'5060-5080'`).
  * `description`: Explanatory context for operations and NOC teams.
  * `is_system`: Boolean flag protecting critical services (SSH, HTTP redirect, Web Portal) from accidental deletion.
  * `enabled`: Master switch controlling whether the port set is included in the active packet filter.

---

## 2. Module Overview (Commercial & Business Value)

* **Simplified Security Governance:** Reusable service definitions eliminate human error caused by mistyping port numbers when provisioning firewall policies across multiple environments.
* **Rapid Emergency Isolation:** If a specific microservice (e.g., a legacy API listener or unencrypted testing port) exhibits a vulnerability, disabling the service definition immediately closes the port across all firewall rules.
* **Audit Transparency:** Provides compliance auditors and telecommunications regulators with a clear, readable inventory of every listening port and its documented business justification.

---

## 3. 🎯 User Roles & Key Capabilities

| User Role | Key Permissions | Core Responsibilities & Workflows |
| :--- | :--- | :--- |
| **Super Administrator** | Full Control (`CRUD` on Services) | Configures core platform services, binds custom microservice ports, and toggles system service availability. |
| **Security Officer / SecOps** | Audit & Port Compliance | Audits listening service inventories, ensures non-TLS cleartext services remain disabled, and verifies port ranges. |
| **DevOps / SysAdmin** | Read & Create (Application Ports) | Registers new application endpoints, webhook ingress ports, and metrics exporters (e.g., Prometheus node exporter on port 9100). |

---

## 4. Visual Interface & Form Structure

### Level 1 — Firewall Services List View
The services inventory displays all configured network definitions, transport protocols, port assignments, descriptions, active status indicators, and action triggers.

![Firewall Services List View](/screenshots/billing/admin/firewall/services/services-list.png)

### Level 2 — Add Firewall Service Modal
The modal dialog provides a clean, validated form to create named network service definitions.

![Add Firewall Service Modal](/screenshots/billing/admin/firewall/services/services-modal.png)

#### Fields & Parameters Reference
* **Service Name:** Alphanumeric identifier (e.g., `HTTPS Portal Web`, `Fastify Billing API`, `Prometheus Exporter`).
* **Protocol:** Transport layer selection (`TCP`, `UDP`, or `Both`).
* **Port:** Target port number (e.g., `8443`) or port span (e.g., `8000-8010`).
* **Description:** Detailed explanation of the service purpose and underlying software daemon.
* **Enabled:** Operational toggle. When set to `Yes`, the service is eligible for inclusion in active firewall chains.

---

## 5. Architectural Flow & Security Governance

```
  ┌──────────────┐         1. POST /api/firewall/services         ┌────────────────────────┐
  │ System Admin ├───────────────────────────────────────────────►│  Fastify 5 API Route   │
  └──────────────┘                                                └───────────┬────────────┘
                                                                              │
                                                                 2. Validate  │ 3. Store in
                                                                    Port/Proto│    ss_billing
                                                                              ▼
  ┌──────────────┐         4. nftables / iptables Reload          ┌────────────────────────┐
  │ Linux Kernel ◄────────────────────────────────────────────────┤  Firewall Service Sync │
  │    Filter    │                                                └────────────────────────┘
  └──────────────┘
```

1. **Service Registration:** The administrator inputs service parameters into the modal and clicks **Create**.
2. **Validation:** The Fastify backend validates port ranges (1-65535) and prevents port collisions with reserved operating system processes.
3. **Storage:** The record is inserted into `public.firewall_services`.
4. **Kernel Application:** If the firewall is active, the service definition updates the kernel packet filtering sets to immediately open or close the specified port.

---

## 6. Common Scenarios & Operational Playbooks

### Playbook 1: Registering a Metrics Monitoring Service (Prometheus)
1. Navigate to **ADMIN > Firewall > Services**.
2. Click **+ Add** in the top-right toolbar.
3. Enter **Service Name:** `Prometheus Node Exporter`.
4. Select **Protocol:** `TCP`.
5. Enter **Port:** `9100`.
6. Enter **Description:** `Telemetry metrics endpoint for internal Prometheus scrapers`.
7. Set **Enabled** to `Yes`.
8. Click **Create**.
9. The service is now ready to be restricted to the monitoring subnet under **Access Control** or **Rules**.

### Playbook 2: Deactivating an Unused Service Port
1. Navigate to **ADMIN > Firewall > Services**.
2. Locate the row for the service you wish to decommission (e.g., `HTTP Web Redirect` on port 80).
3. Click the **Edit** icon.
4. Toggle **Enabled** to `No`.
5. Click **Save**.
6. The firewall immediately ceases accepting traffic on port 80, enforcing exclusive HTTPS on port 8443.

---

## 7. Troubleshooting & Diagnostic Commands

### Inspecting Configured Services in PostgreSQL
```bash
sudo -u postgres psql -d ss_billing -c \
  "SELECT id, name, protocol, port, description, enabled FROM firewall_services ORDER BY id ASC;"
```

### Checking Listening Ports with Linux Utilities
```bash
# Verify which applications are actively listening on the configured ports
ss -tulnp | grep -E ':(80|8443|3003|22|5432|6379)'

# Test socket reachability locally
nc -zv 127.0.0.1 3003
```

---

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

The **Firewall Services** module connects directly to the **Ring2All BSS MCP Server**, enabling infrastructure management copilots to inspect named service abstractions and verify port bindings safely.

### Available MCP Tools

| Tool Name | Access Role | Description & Primary Function | Example Arguments |
| :--- | :--- | :--- | :--- |
| `list_firewall_services` | `Super Administrator` | Lists defined firewall network services with port definitions, transport protocols, and enabled status. | `{}` |

### Sample MCP Tool Execution: `list_firewall_services`

#### Request Payload
```json
{
  "name": "list_firewall_services",
  "arguments": {}
}
```

#### Response Payload
```json
[
  {
    "id": 1,
    "name": "Billing HTTP/HTTPS",
    "protocol": "tcp",
    "port": "80,443",
    "description": "Public web portal and REST API",
    "enabled": true,
    "isSystem": true
  },
  {
    "id": 2,
    "name": "SSH Management",
    "protocol": "tcp",
    "port": "22",
    "description": "Encrypted system shell management",
    "enabled": true,
    "isSystem": true
  }
]
```

### Conversational AI Prompts for Copilot
* *"List all defined network services and their port assignments."*
* *"Is SSH management enabled as a recognized firewall service?"*
* *"Show which ports are opened for the Billing API."*

---

## 9. Glossary

* **Transport Protocol:** The layer 4 communications protocol (typically TCP for reliable streams or UDP for low-latency datagrams) used by network packets.
* **Port Range:** A continuous block of sequential port numbers (e.g., `10000-20000` for RTP media relay) managed as a single logical entity.
* **System Service:** A protected service entry marked `is_system = true` that cannot be deleted to prevent accidental administrative isolation.
* **Model Context Protocol (MCP):** Open protocol standard that enables secure, controlled integration between Large Language Models and external tools, databases, and telecom rating engines.