OmniPGW Operations Guide

OmniPGW - Packet Gateway Control Plane (PGW-C)

by Omnitouch Network Services

Overview
Architecture
Network Interfaces
Key Concepts
Getting Started
Configuration
Real-Time Operations Monitoring (OAM API)
Monitoring & Metrics
Detailed Documentation
Additional Resources

Overview

OmniPGW is a high-performance Packet Gateway Control Plane (PGW-C) implementation for 3GPP LTE Evolved Packet Core (EPC) networks, developed by Omnitouch Network Services. It manages the control plane functions for data sessions, including:

Session Management - Creating, modifying, and terminating UE (User Equipment) data sessions
IP Address Allocation - Assigning IP addresses to mobile devices from configured pools
Policy & Charging Control - Interfacing with PCRF for policy enforcement and charging
User Plane Coordination - Controlling the PGW-U (User Plane) for packet forwarding

What PGW-C Does

Accepts session requests from SGW-C via S5/S8 interface (GTP-C)
Allocates UE IP addresses from configured subnet pools
Requests policy decisions from PCRF via Gx interface (Diameter)
Programs forwarding rules in PGW-U via Sxb interface (PFCP)
Manages QoS enforcement through bearer contexts and QoS rules
Tracks charging information for billing systems

Architecture

Component Overview

Process Architecture

PGW-C is built on Elixir/OTP and uses a supervised process architecture:

Application Supervisor - Top-level supervisor managing all components
Protocol Brokers - Handle incoming/outgoing protocol messages
Session Processes - One GenServer per active PDN connection
Registries - Track allocated resources (IPs, TEIDs, SEIDs, etc.)
PFCP Node Manager - Maintains PFCP associations with PGW-U peers

Each component is supervised and will automatically restart on failure, ensuring system reliability.

Network Interfaces

PGW-C implements three primary 3GPP interfaces:

S5/S8 Interface (GTP-C v2)

Purpose: Control plane signaling between SGW-C and PGW-C

Protocol: GTP-C Version 2 over UDP

Key Messages:

Create Session Request/Response
Delete Session Request/Response
Create Bearer Request/Response
Delete Bearer Request/Response

Configuration: See S5/S8 Configuration

Sxb Interface (PFCP)

Purpose: Control plane signaling between PGW-C and PGW-U

Protocol: PFCP (Packet Forwarding Control Protocol) over UDP

Key Messages:

Association Setup Request/Response
Session Establishment Request/Response
Session Modification Request/Response
Session Deletion Request/Response
Heartbeat Request/Response

Configuration: See PFCP/Sxb Interface Documentation

Gx Interface (Diameter)

Purpose: Policy and Charging Rules Function (PCRF) interface

Protocol: Diameter (IETF RFC 6733)

Key Messages:

Credit Control Initial Request/Answer (CCR-I/CCA-I)
Credit Control Termination Request/Answer (CCR-T/CCA-T)

Configuration: See Diameter Gx Interface Documentation

Key Concepts

PDN Session

A PDN (Packet Data Network) Session represents a UE's data connection to an external network (like the Internet). Each session has:

UE IP Address - Allocated from a configured subnet pool
APN (Access Point Name) - Identifies the external network
Bearer Context - Contains QoS parameters and tunnel information
Charging ID - Unique identifier for billing
TEID (Tunnel Endpoint ID) - S5/S8 interface tunnel identifier
SEID (Session Endpoint ID) - Sxb interface session identifier

Bearer Context

A bearer represents a traffic flow with specific QoS characteristics:

Default Bearer - Created with every PDN session
Dedicated Bearers - Additional bearers for specific QoS needs
EBI (EPS Bearer ID) - Unique identifier for each bearer
QoS Parameters - QCI, ARP, bitrates (MBR, GBR)

PFCP Rules

The PGW-C programs the PGW-U with packet processing rules:

PDR (Packet Detection Rule) - Matches packets (uplink/downlink)
FAR (Forwarding Action Rule) - Specifies forwarding behavior
QER (QoS Enforcement Rule) - Enforces bitrate limits
BAR (Buffering Action Rule) - Controls packet buffering

See PFCP Interface Documentation for details.

IP Address Allocation

UE IP addresses are allocated from configured subnet pools:

APN-based selection - Different APNs can use different subnets
Dynamic allocation - Random IP selection from available range
Static allocation - Support for UE-requested IP addresses
Collision detection - Ensures unique IP assignment

See UE IP Pool Allocation for configuration, and IPv6 / Dual-Stack for IPv6 and IPv4v6 PDN operation.

Getting Started

Prerequisites

Elixir ~1.16
Erlang/OTP 26+
Network connectivity to SGW-C, PGW-U, and PCRF
Understanding of LTE EPC architecture

Starting OmniPGW

Configure runtime settings in config/runtime.exs
Compile the application:
```
mix deps.get
mix compile
```
Start the application:
```
mix run --no-halt
```

Verifying Operation

Check the logs for successful startup:

[info] Starting OmniPGW...
[info] Starting Metrics Exporter on 127.0.0.42:42069
[info] Starting S5/S8 Broker on 127.0.0.10
[info] Starting Sxb Broker on 127.0.0.20
[info] Starting Gx Broker
[info] Starting PFCP Node Manager
[info] OmniPGW successfully started

Access metrics at http://127.0.0.42:42069/metrics (configured address).

Configuration

All runtime configuration is defined in config/runtime.exs. The configuration is structured into several sections:

Configuration Overview

Quick Configuration Reference

Section	Purpose	Documentation
metrics	Prometheus metrics exporter	Monitoring Guide
diameter	Gx interface to PCRF	Diameter Gx Config
s5s8	GTP-C interface to SGW-C	S5/S8 Config
sxb	PFCP interface to PGW-U	PFCP Config
ue	UE IP address pools	IP Pool Config
pco	Protocol Configuration Options	PCO Config
CDR	Offline charging & usage reporting	CDR Format

See the Complete Configuration Guide for detailed information.

Real-Time Operations Monitoring (OAM API)

OmniPGW exposes an OAM REST API for real-time monitoring and operations, providing instant visibility into system status. Query these read endpoints on demand (or on a polling interval / from a script) for a live operational view - no command-line access to the host or raw metrics queries required.

Accessing the OAM API

The API is served over HTTPS/TLS. All routes are served under the /api prefix.

https://<omnipgw-ip>:8443/

Interactive API documentation (Swagger UI) is available at:

https://<omnipgw-ip>:8443/api/docs

Example health check (use -k for a self-signed lab certificate):

curl -k https://localhost:8443/api/status
{"result":"ok"}

Available Endpoints:

Purpose	Endpoint	Replaces (old page)
Deep dive into a specific subscriber (IMSI/MSISDN/IP)	`POST /api/ue_search`	UE Search
List / search active PDN sessions	`GET /api/sessions[?search=<imsi\|msisdn\|ip>]`	PGW Sessions
One session by IMSI	`GET /api/sessions/<imsi>`	PGW Sessions (detail)
Session history / audit events	`GET /api/session_history[?type=&search=&page=&page_size=]`	Session History
Network topology overview	`GET /api/topology`	Network Topology
UE IP address pool utilization	`GET /api/ip_pools`, `GET /api/ip_pools/<name>`	IP Pools
UPF / PFCP peer status	`GET /api/upf`, `GET /api/upf/<ip>`	PFCP Sessions / UPF Status
UPF selection rules, health, PCO config	`GET /api/upf_selection`	UPF Selection
Diameter (Gx/Gy) peer connectivity	`GET /api/diameter[?status=connected\|disconnected]`, `GET /api/diameter/<origin-host>`	Diameter Peers
Online-charging (Gy) status per session	`GET /api/charging[?search=<imsi>]`, `GET /api/charging/<imsi>`	Gy status
P-CSCF DNS discovery status	`GET /api/pcscf_monitor`	P-CSCF Monitor
Health check	`GET /api/status`	-

For a live dashboard-style view, poll the collection endpoints on an interval, for example:

watch -n 2 'curl -sk https://localhost:8443/api/sessions'
watch -n 1 'curl -sk https://localhost:8443/api/diameter?status=disconnected'

Note: the former Logs page (live log streaming) and the Gy Simulator page have no OAM API equivalent. Stream logs from the host / your log aggregator, and use GET /api/charging to inspect live Gy/online-charging state.

Key Features

On-Demand and Polled Data:

Every endpoint returns current live state from OmniPGW processes
Poll on an interval with watch/cron/a script for an auto-refreshing view
Status fields (e.g. peer connected/associated) are returned explicitly in the JSON

Search & Filter:

Search sessions by IMSI, IP, MSISDN, or APN via GET /api/sessions?search=...
Filter Diameter peers by ?status=connected|disconnected
Filter charging state by ?search=<imsi>

Full Detail Records:

Per-entity endpoints (/api/sessions/<imsi>, /api/upf/<ip>, /api/diameter/<origin-host>, /api/charging/<imsi>) return complete state as JSON
Inspect full session, peer configuration, and capabilities

Access Control:

Served over HTTPS/TLS on port 8443
Bind to the management IP only and front with your access controls
Intended for NOC/operations team and automation use

Operational Workflows

Session Troubleshooting (Deep Dive):

1. User reports connection issue
2. POST /api/ue_search with a JSON body containing the IMSI, MSISDN, or IP
3. Review the comprehensive session details in the response:
   a) Active Sessions - Verify session exists with correct parameters
   b) Current Location - Check TAC, Cell ID, serving network
   c) Bearer Information - Verify default and dedicated bearers
      - QCI, MBR/GBR, Charging Rule Names
      - APN-AMBR limits
   d) Charging Information - Gy session ID, quota status (also GET /api/charging/<imsi>)
   e) Policy Information - Gx session, installed PCC rules
   f) Recent Events - GET /api/session_history?search=<imsi>
4. If session not found → GET /api/diameter?status=disconnected for PCRF connectivity

Quick Session Lookup:

1. User reports issue
2. GET /api/sessions?search=<imsi|msisdn> (or GET /api/sessions/<imsi>)
3. Verify session exists with basic details:
   - UE IP address allocated
   - QoS parameters
   - Tunnel endpoints established
4. For detailed analysis → POST /api/ue_search

System Health Check:

GET /api/upf              → Verify all PGW-U peers "Associated"
GET /api/diameter?status=connected → Verify all PCRF peers "Connected"
GET /api/sessions         → Check active session count vs. capacity
GET /api/status           → Overall health check ({"result":"ok"})

Capacity Monitoring:

Count entries returned by GET /api/sessions
Compare to licensed/expected capacity
Identify peak usage times
Monitor distribution across APNs; use GET /api/ip_pools for per-pool utilization

API vs. Metrics

Use the OAM API for:

Deep-dive subscriber troubleshooting (POST /api/ue_search)
Individual session details and state inspection (GET /api/sessions/<imsi>)
Real-time peer status (GET /api/upf, GET /api/diameter)
Quick health checks across all interfaces (GET /api/status)
Troubleshooting specific users by IMSI/MSISDN/IP
Bearer QoS analysis (MBR, GBR, QCI)
Policy and charging rule inspection (GET /api/charging)
Session history and audit trails (GET /api/session_history)
IP pool capacity monitoring (GET /api/ip_pools)
Verifying configuration and rules (GET /api/upf_selection)

Use Prometheus Metrics for:

Historical trends
Alerting and notifications
Capacity planning graphs
Performance analysis
Long-term monitoring

Best Practice: Use both together - the OAM API for immediate operations, Prometheus for trends and alerts.

Monitoring & Metrics

In addition to the OAM API, OmniPGW exposes Prometheus-compatible metrics for monitoring:

Available Metrics

Session Metrics
- teid_registry_count - Active S5/S8 sessions
- seid_registry_count - Active PFCP sessions
- session_id_registry_count - Active Gx sessions
- address_registry_count - Allocated UE IP addresses
- charging_id_registry_count - Active charging IDs
Message Metrics
- s5s8_inbound_messages_total - GTP-C messages received
- sxb_inbound_messages_total - PFCP messages received
- gx_inbound_messages_total - Diameter messages received
- Message handling duration distributions
Error Metrics
- s5s8_inbound_errors_total - S5/S8 protocol errors
- sxb_inbound_errors_total - PFCP protocol errors
- gx_inbound_errors_total - Diameter errors
Session Lifecycle Metrics
- pgw_session_create_total{result,cause,pdn_type,rat_type} - PDN session creation attempts, broken down by result (success/failure), the GTP cause returned, PDN type (ipv4/ipv6/ipv4v6) and RAT type
- pgw_session_delete_total{pdn_type} - PDN session deletions by PDN type
- pgw_session_modify_total - Modify Bearer Requests handled
UE IP Pool Metrics
- ue_pool_addresses_allocated{pool,ip_version} - Allocated UE addresses per pool (APN pattern) and IP version
- ue_pool_addresses_total{pool,ip_version} - Total pool capacity
- ue_pool_addresses_utilization_ratio{pool,ip_version} - Fraction allocated (0.0-1.0); useful for pool-exhaustion alerting. Note pools that share an address range each count the shared allocations
- ue_ip_allocation_failures_total{ip_version,reason} - Allocation failures (pool_exhausted, already_registered)
Per-Peer UPF / PFCP Metrics
- upf_peer_associated{peer_ip} - 1/0 PFCP association state per peer
- upf_peer_healthy{peer_ip} - 1/0 health per peer
- upf_peer_missed_heartbeats{peer_ip} - Consecutive missed heartbeats per peer
- upf_heartbeat_rtt - PFCP heartbeat round-trip time distribution, by peer_ip
Bearer & QoS Metrics
- pgw_bearer_create_total{type,qci} - Bearers created by type (default/dedicated) and QCI
- pgw_bearer_delete_total{type} - Bearers deleted by type
Diameter Peer Metrics
- diameter_peers_connected{application} - Connected Diameter peers by application (gx/gy/all)

Accessing Metrics

Metrics are exposed via HTTP at the configured endpoint:

curl http://127.0.0.42:42069/metrics

See Monitoring & Metrics Guide for dashboard setup and alerting.

Detailed Documentation

This section provides a comprehensive overview of all OmniPGW documentation. Documents are organized by topic and use case.

Documentation Structure

OmniPGW Documentation
├── OPERATIONS.md (This Guide)
│
└── docs/
    ├── Configuration & Setup
    │   ├── configuration.md          Complete runtime.exs reference
    │   ├── ue-ip-allocation.md       IP pool configuration
    │   └── pco-configuration.md      DNS, P-CSCF, MTU settings
    │
    ├── Network Interfaces
    │   ├── pfcp-interface.md         Sxb/PFCP (PGW-U communication)
    │   ├── diameter-gx.md            Gx (PCRF communication)
    │   ├── diameter-gy.md            Gy/Ro (OCS communication)
    │   └── s5s8-interface.md         S5/S8 (SGW-C communication)
    │
    └── Operations
        ├── session-management.md     PDN session lifecycle
        └── monitoring.md             Prometheus metrics & alerting

Documentation by Topic

🚀 Getting Started

Document	Description	Purpose
OPERATIONS.md	Main operations guide (this document)	Overview and quick start

⚙️ Configuration

Document	Description	Lines
configuration.md	Complete runtime.exs configuration reference	1,600+
ue-ip-allocation.md	UE IP pool management and allocation	943
ipv6-dual-stack.md	IPv6 / IPv4v6 PDN operation across PGW-C and UPF	-
pco-configuration.md	Protocol Configuration Options (DNS, P-CSCF, MTU)	344

🔌 Network Interfaces

Document	Description	Lines
pfcp-interface.md	PFCP/Sxb interface to PGW-U	1,355
diameter-gx.md	Diameter Gx interface to PCRF (Policy Control)	941
diameter-gy.md	Diameter Gy/Ro interface to OCS (Online Charging)	1,100+
s5s8-interface.md	GTP-C S5/S8 interface to SGW-C	456

📊 Operations & Monitoring

Document	Description	Lines
session-management.md	PDN session lifecycle and operations	435
monitoring.md	Prometheus metrics, Grafana dashboards, alerting	807
data-cdr-format.md	CDR file format, URR configuration, offline charging	847
qos-bearers.md	QoS & bearer management, policy control	448
troubleshooting.md	Troubleshooting procedures and common issues	687

🔧 Advanced Features

Document	Description	Lines
pcscf-monitoring.md	P-CSCF discovery and health monitoring	894

Documentation Features

📈 Mermaid Diagrams

All documents include Mermaid charts for visual understanding:

Architecture diagrams
Sequence diagrams (message flows)
State machines
Network topology

💡 Practical Examples

Every document includes:

Real-world configuration examples
Copy-paste ready configs
Common use cases

🔍 Troubleshooting

Each interface document includes:

Common issues and solutions
Debug commands
Metrics for diagnosis

🔗 Cross-References

Documents are extensively cross-linked for easy navigation.

Reading Paths

For Network Operators

OPERATIONS.md - Overview (this document)
configuration.md - Setup
monitoring.md - Monitoring
session-management.md - Day-to-day operations

For Network Engineers

OPERATIONS.md - Architecture overview (this document)
pfcp-interface.md - User plane control
diameter-gx.md - Policy control
diameter-gy.md - Online charging
s5s8-interface.md - Session management
ue-ip-allocation.md - IP management

For Configuration & Deployment

configuration.md - Complete reference
ue-ip-allocation.md - IP pools
pco-configuration.md - Network parameters
monitoring.md - Set up monitoring

Document Statistics

Total Documents: 14
Total Lines: ~10,900+
Total Size: ~265 KB
Mermaid Diagrams: 75+
Code Examples: 150+

Key Concepts Covered

Architecture

✅ Control/User plane separation
✅ OTP/Elixir architecture
✅ Process supervision
✅ GenServer-based sessions

Protocols

✅ PFCP (Packet Forwarding Control Protocol)
✅ GTP-C v2 (GPRS Tunnelling Protocol)
✅ Diameter (RFC 6733)

3GPP Interfaces

✅ Sxb (PGW-C ↔ PGW-U)
✅ Gx (PGW-C ↔ PCRF)
✅ Gy/Ro (PGW-C ↔ OCS)
✅ S5/S8 (SGW-C ↔ PGW-C)

Operations

✅ Session management
✅ IP allocation strategies
✅ QoS enforcement
✅ Charging integration
✅ Monitoring & alerting

Additional Resources

3GPP Specifications

Spec	Title
TS 29.274	GTP-C v2 (S5/S8 interface)
TS 29.244	PFCP (Sxb interface)
TS 29.212	Diameter Gx interface (Policy Control)
TS 32.299	Diameter Charging Applications (Gy/Ro)
TS 32.251	Packet Switched domain charging
TS 23.401	EPC architecture

Configuration file: config/runtime.exs

Table of Contents​

Overview​

What PGW-C Does​

Architecture​

Component Overview​

Process Architecture​

Network Interfaces​

S5/S8 Interface (GTP-C v2)​

Sxb Interface (PFCP)​

Gx Interface (Diameter)​

Key Concepts​

PDN Session​

Bearer Context​

PFCP Rules​

IP Address Allocation​

Getting Started​

Prerequisites​

Starting OmniPGW​

Verifying Operation​

Configuration​

Configuration Overview​

Quick Configuration Reference​

Real-Time Operations Monitoring (OAM API)​

Accessing the OAM API​

Key Features​

Operational Workflows​

API vs. Metrics​

Monitoring & Metrics​

Available Metrics​

Accessing Metrics​

Detailed Documentation​

Documentation Structure​

Documentation by Topic​

🚀 Getting Started​

⚙️ Configuration​

🔌 Network Interfaces​

📊 Operations & Monitoring​

🔧 Advanced Features​

Documentation Features​

📈 Mermaid Diagrams​

💡 Practical Examples​

🔍 Troubleshooting​

🔗 Cross-References​

Reading Paths​

For Network Operators​

For Network Engineers​

For Configuration & Deployment​

Document Statistics​

Key Concepts Covered​

Architecture​

Protocols​

3GPP Interfaces​

Operations​

Additional Resources​

3GPP Specifications​

Related Documentation​

Table of Contents

Overview

What PGW-C Does

Architecture

Component Overview

Process Architecture

Network Interfaces

S5/S8 Interface (GTP-C v2)

Sxb Interface (PFCP)

Gx Interface (Diameter)

Key Concepts

PDN Session

Bearer Context

PFCP Rules

IP Address Allocation

Getting Started

Prerequisites

Starting OmniPGW

Verifying Operation

Configuration

Configuration Overview

Quick Configuration Reference

Real-Time Operations Monitoring (OAM API)

Accessing the OAM API

Key Features

Operational Workflows

API vs. Metrics

Monitoring & Metrics

Available Metrics

Accessing Metrics

Detailed Documentation

Documentation Structure

Documentation by Topic

🚀 Getting Started

⚙️ Configuration

🔌 Network Interfaces

📊 Operations & Monitoring

🔧 Advanced Features

Documentation Features

📈 Mermaid Diagrams

💡 Practical Examples

🔍 Troubleshooting

🔗 Cross-References

Reading Paths

For Network Operators

For Network Engineers

For Configuration & Deployment

Document Statistics

Key Concepts Covered

Architecture

Protocols

3GPP Interfaces

Operations

Additional Resources

3GPP Specifications

Related Documentation