OmniEPDG Operations Guide
OmniEPDG is an evolved Packet Data Gateway (ePDG) that enables Voice over WiFi (VoWiFi) calling. It authenticates mobile subscribers over untrusted WiFi networks using EAP-AKA, and connects them to the mobile core network through Diameter signaling to the HSS and GTP tunnels to a Packet Gateway (PGW).
The OmniEPDG control panel showing an active subscriber session with real-time traffic statistics.
OmniEPDG supports two operational modes:
- GTP Mode (default) - Full 3GPP-compliant tunneling through a PGW via GTPv2-C and GTP-U
- Simple VPN Mode - Local breakout with a built-in IP pool and Linux TUN interface, no PGW required
Documentation
Configuration & Operations
- Architecture & Call Flows - System architecture, protocol interfaces, UE state machines, and message sequence diagrams for both modes
- Configuration Reference - Complete parameter documentation for Diameter, GTPv2-C, GTP-U, Simple VPN, and logging
- Control Panel - Web-based monitoring UI for sessions, Diameter peers, and logs
Security
- Security Guide - Authentication rate limiting and GeoIP country blocking
Monitoring & Troubleshooting
- Metrics Reference - Prometheus metrics for monitoring authentication, sessions, Diameter signaling, and system health
- Troubleshooting - Common issues, diagnostic procedures, and resolution steps
Operational Modes
GTP Mode
The default mode. OmniEPDG tunnels all subscriber traffic through a PGW using GTPv2-C for session control and GTP-U (via Linux kernel module) for the user plane. This is fully 3GPP compliant and suitable for carrier deployments with existing EPC infrastructure.
Traffic path: UE → IPSec → OmniEPDG → GTPv2-C Create Session → GTP-U tunnel → PGW → Internet
Required infrastructure: HSS, PGW
Simple VPN Mode
OmniEPDG allocates IP addresses from a local pool and routes subscriber traffic directly through a Linux TUN interface (tun_epdg) using standard kernel routing. No PGW or GTP infrastructure is needed. Authentication still happens via Diameter SWx to the HSS.
Traffic path: UE → IPSec → OmniEPDG → Local IP allocation → TUN interface → Linux routing → Internet
Required infrastructure: HSS only (PGW not needed)
Optional optimization: The skip_sar flag bypasses HSS Server-Assignment-Request/Answer, reducing connection setup time. This means the HSS will not track which ePDG serves the subscriber and HSS-initiated procedures (deregistration, profile push) will not function. Suitable for private deployments without roaming requirements.
Mode Comparison
| Capability | GTP Mode | Simple VPN Mode |
|---|---|---|
| 3GPP compliant | Yes | No (with skip_sar), Partial (without) |
| PGW required | Yes | No |
| HSS required | Yes | Yes (authentication only) |
| IP allocation | From PGW | Local pool (CIDR) |
| User plane | GTP-U kernel module | Linux TUN + routing |
| HSS profile push | Yes (PPR/PPA) | No |
| HSS deregistration | Yes (RTR/RTA) | No (with skip_sar) |
| PGW-initiated teardown | Yes | N/A |
| Roaming support | Yes | No |
| IPv6 / Dual-stack | Yes | IPv4 only |
Protocol Interfaces
| Interface | Protocol | Transport | Mode | Peer | Purpose | Reference |
|---|---|---|---|---|---|---|
| SWu | IKEv2 / IPSec | UDP | Both | UE | Secure tunnel and EAP-AKA authentication | 3GPP TS 33.402 |
| SWx | Diameter | SCTP | Both | HSS | Authentication vectors and server assignment | 3GPP TS 29.273 Section 8 |
| S6b | Diameter | SCTP | GTP only | PGW | Session authorization and policy | 3GPP TS 29.273 Section 9 |
| S2b | GTPv2-C / GTP-U | UDP | GTP only | PGW | Control and user plane tunnel | 3GPP TS 29.274 |
Features
Core Functionality
- EAP-AKA Authentication - Full 3GPP EAP-AKA subscriber authentication via HSS
- IPSec Tunnel Management - IKEv2-based secure tunnel between UE and ePDG
- Dual Operational Modes - GTP tunneling to PGW or local breakout with Simple VPN
- Per-UE State Machines - Independent Erlang FSM per subscriber for session lifecycle management
- Dual-Stack Support - IPv4, IPv6, and IPv4v6 PDP address types (GTP mode)
GTP Mode Features
- GTP Tunnel Establishment - GTPv2-C session creation and GTP-U user plane via Linux kernel module
- PGW-Initiated Teardown - PGW sends Delete Bearer Request, ePDG cascades teardown to UE
- Network-Initiated Teardown - HSS triggers deregistration via SWx RTR, ePDG tears down all sessions
- Re-Authentication - HSS-triggered profile push and re-authorization per 3GPP TS 29.273 Section 7.1.2.5.1
Simple VPN Mode Features
- Local IP Pool - CIDR-based IPv4 address allocation with per-IMSI tracking
- TUN Interface Routing - Standard Linux TUN device (
tun_epdg) with per-UE host routes - DNS Configuration - Configurable DNS servers provided to UEs via PCO
- Optional SAR Skip - Bypass HSS registration for faster connection setup
Security Features
- Authentication Rate Limiting - Per-IP and per-IMSI brute-force protection with configurable thresholds
- GeoIP Country Blocking - Whitelist or blacklist based country access control using MaxMind GeoLite2
- Dead Peer Detection - Active liveness monitoring with configurable probes
- ESP Anti-Replay Protection - RFC 4303 compliant 64-bit sliding window
HSS Integration (SWx Diameter)
- Multimedia-Auth-Request/Answer (MAR/MAA) - Retrieve EAP-AKA authentication vectors (both modes)
- Server-Assignment-Request/Answer (SAR/SAA) - Download subscriber profile and APN configuration (skippable in Simple mode)
- Push-Profile-Request/Answer (PPR/PPA) - Receive updated subscriber profiles from HSS (GTP mode)
- Registration-Termination-Request/Answer (RTR/RTA) - HSS-initiated subscriber deregistration (GTP mode)
PGW Integration (GTP Mode Only)
S6b Diameter:
- AA-Request/Answer (AAR/AAA) - Authorize PGW sessions
- Session-Termination-Request/Answer (STR/STA) - Terminate PGW sessions
- Re-Auth-Request/Answer (RAR/RAA) - Re-authorize active sessions
- Abort-Session-Request/Answer (ASR/ASA) - Forcefully terminate sessions
S2b GTPv2-C:
- Create Session Request/Response - Establish GTP tunnels with TEID allocation
- Delete Session Request/Response - Tear down GTP tunnels
- Delete Bearer Request/Response - PGW-initiated bearer management
Quick Start
Configuration Structure
Configuration is done in config/runtime.exs or via environment variables. The vpn_mode parameter selects between GTP and Simple VPN modes. See the Configuration Reference for complete parameter documentation.
Typical Network Addressing (GTP Mode)
| Component | IP Address | Port | Notes |
|---|---|---|---|
| OmniEPDG (GTP-U) | 10.74.0.11 | - | GTP-U tunnel endpoint |
| OmniEPDG (Diameter S6b) | 10.74.0.12 | 3868 | S6b Diameter listener |
| HSS | 10.74.0.21 | 3868 | SWx Diameter peer |
| PGW | 10.74.0.23 | 2123 | GTPv2-C and S6b peer |
Typical Network Addressing (Simple VPN Mode)
| Component | IP Address | Notes |
|---|---|---|
| OmniEPDG (TUN gateway) | 10.44.0.1 | Gateway IP on the tun_epdg interface |
| UE IP pool | 10.45.0.0/16 | Configurable CIDR pool for subscriber IPs |
| HSS | 10.74.0.21:3868 | SWx Diameter peer (authentication only) |
3GPP Specifications
| Specification | Title | Relevance |
|---|---|---|
| TS 29.273 | EPS AAA interfaces (SWx, S6b, SWm) | Primary specification for ePDG Diameter interfaces |
| TS 29.274 | GTPv2-C and GTP-U | S2b tunnel control and user plane (GTP mode) |
| TS 33.402 | Security for non-3GPP accesses | EAP-AKA authentication for untrusted WiFi |
| TS 23.402 | Architecture enhancements for non-3GPP accesses | Overall ePDG architecture and procedures |
| TS 23.003 | Numbering, addressing and identification | NAI format, IMSI structure |
| TS 29.229 | Cx/Dx Diameter (common definitions) | Server-Assignment-Type values used by SWx |
| RFC 6733 | Diameter Base Protocol | Diameter transport, peer management, watchdog |
| RFC 4187 | EAP-AKA | Authentication method used over IKEv2 |
Documentation By Role
Network Operators:
- Start with the Architecture & Call Flows to understand the system and both operational modes
- Review the Configuration Reference for deployment parameters
- Review the Security Guide to configure rate limiting and GeoIP blocking
- Set up monitoring using the Metrics Reference for Prometheus integration
- Keep the Troubleshooting guide available for operations
System Integrators:
- Review the Architecture & Call Flows for interface details and state machines
- Use the Configuration Reference for peer connectivity setup
- Configure alerting using the Metrics Reference
- Reference the 3GPP specifications table above for protocol compliance