OmniEPDG Operations Guide

OmniEPDG is a 3GPP-compliant ePDG (evolved Packet Data Gateway) that enables WiFi calling by bridging untrusted WiFi access to the mobile core network. It supports two operational modes: GTP mode for PGW tunneling and Simple VPN mode for local IP breakout.

Quick Links

Configuration & Deployment

• Network Requirements - Firewall ports and DNS entries required for deployment
• Configuration Reference - Complete parameter documentation for IKEv2, Diameter, VPN modes, and all runtime settings
• Architecture Overview - System architecture, call flows, state machines, and protocol references

Operations & Monitoring

• Control Panel - Web-based monitoring interface for sessions, Diameter peers, and logs
• Metrics Reference - Prometheus metrics, example queries, and alerting rules
• Troubleshooting - Common issues, diagnostic procedures, and resolution steps

Security

• Authentication Security - Rate limiting and GeoIP country blocking

Architecture Overview

Operational Modes

OmniEPDG supports two operational modes selected via the vpn_mode configuration parameter.

GTP Mode

Full 3GPP tunneling through a PGW. Subscriber traffic is encapsulated in GTP-U and routed through the mobile core.

Use when:

• Integration with existing mobile core infrastructure
• Policy and charging through PCRF/PCEF
• Roaming and inter-operator handoff required

Components:

• Diameter S6b for PGW session authorization
• GTPv2-C for session management (Create/Delete/Modify Session)
• Linux kernel GTP-U module for user plane

Simple VPN Mode

Local IP breakout via TUN interface. Subscriber traffic is routed directly through the OmniEPDG host without PGW involvement.

Use when:

• Standalone deployment without PGW
• Testing and development
• Local breakout scenarios

Components:

• Local IP pool management (IPv4/IPv6)
• TUN interface (omniepdg0) with per-subscriber host routes
• Optional NAT/masquerade for internet access

Authentication Security

OmniEPDG includes built-in security features to protect against brute-force attacks and restrict access by geographic location. See the Authentication Security guide for details.

Rate Limiting

Protects against brute-force attacks by tracking failed authentication attempts:

• Per-IP limiting - Blocks IPs after 10 failures in 1 minute (5 minute block)
• Per-IMSI limiting - Blocks IMSIs after 5 failures in 1 minute (10 minute block)
• Sliding window algorithm with automatic expiration
• Successful authentication clears failure history

GeoIP Country Blocking

Optional geographic access control using MaxMind GeoLite2 database:

• Whitelist mode - Only allow connections from specified countries
• Blacklist mode - Block connections from specified countries
• Configurable handling of unknown/private IPs
• Fail-open or fail-closed behavior when database unavailable

Key Configuration

Minimal Configuration (Simple VPN Mode)

config :omniepdg,
  vpn_mode: :simple,
  simple_vpn: [
    pool_ipv4: "10.45.0.0/16",
    dns_servers_ipv4: ["8.8.8.8", "8.8.4.4"]
  ]

config :diameter_ex,
  diameter: %{
    host: "epdg",
    realm: "epc.mnc001.mcc001.3gppnetwork.org",
    peers: [
      %{host: "hss", ip: "10.74.0.21", port: 3868, transport: :tcp}
    ]
  }

Enable Authentication Security

config :omniepdg,
  # Rate limiting (enabled by default with these values)
  auth_rate_limit_per_ip: 10,
  auth_rate_limit_ip_block_ms: 300_000,
  auth_rate_limit_per_imsi: 5,
  auth_rate_limit_imsi_block_ms: 600_000,

  # GeoIP blocking (disabled by default)
  geoip_enabled: true,
  geoip_mode: :whitelist,
  geoip_countries: ["AU", "NZ"]

See the Configuration Reference for complete parameter documentation.

Monitoring

Control Panel

Access the web control panel at http://<host>:4000/dashboard for:

• Real-time session monitoring
• Diameter peer status
• Live log streaming
• System configuration

See the Control Panel guide for details.

Prometheus Metrics

Scrape metrics from http://<host>:9568/metrics for:

• Authentication success/failure rates
• Session lifecycle events
• Diameter signaling latency
• Security events (rate limiting, GeoIP blocks)
• IP pool utilization
• ESP data plane statistics

See the Metrics Reference for queries and alerting rules.

Troubleshooting

Common issues and resolution steps:

Issue	Quick Check	Guide Section
Authentication failures	Check SWx MAR/MAA in logs	Authentication Failures
Diameter connection issues	Check peer status in control panel	Diameter Connectivity
GTP tunnel failures	Check GTPv2-C cause codes	GTP Tunnel Failures
Simple VPN issues	Check TUN interface and routes	Simple VPN Failures
Rate limiting false positives	Adjust thresholds	Rate Limiting Issues
GeoIP blocking issues	Check database and country codes	GeoIP Issues

See the Troubleshooting guide for detailed diagnostic procedures.

Documentation Index

Document	Description
Architecture	System design, state machines, call flows, protocol references
Configuration	Complete configuration reference with examples
Control Panel	Web interface guide with screenshots
Metrics	Prometheus metrics, queries, and alerting
Network Requirements	Firewall ports and DNS entries for deployment
Security	Rate limiting and GeoIP country blocking
Troubleshooting	Common issues and diagnostic procedures