Skip to main content

OmniEPDG Configuration Reference

OmniEPDG is configured via config/runtime.exs and environment variables. All customer-facing configuration is performed at runtime - compile-time defaults are built into the release and not exposed.

For containerized deployments, use environment variables as documented in the Environment Variables Reference section.

Table of Contents​

Configuration Structure​

Configuration File​

All configuration is done in config/runtime.exs. This file is read when OmniEPDG starts and supports environment variable substitution for containerized deployments.

Configuration Example​

# config/runtime.exs
config :omniepdg,
  # IKEv2 server settings
  listen_ip: {0, 0, 0, 0},
  port_500: 500,
  port_4500: 4500,

  # VPN mode: :simple (local breakout) or :gtp (PGW via GTP-C)
  vpn_mode: :simple,

  # Simple VPN mode settings
  simple_vpn: [
    pool_ipv4: "10.45.0.0/16",
    pool_ipv6: "2001:db8::/32",
    dns_servers_ipv4: ["8.8.8.8", "8.8.4.4"],
    dns_servers_ipv6: ["2001:4860:4860::8888", "2001:4860:4860::8844"]
  ]

# Control panel configuration
config :control_panel,
  parent_application: :omniepdg,
  parent_application_readable_name: "OmniEPDG",
  use_additional_pages: [
    {OmniEpdg.Web.DashboardLive, "/", "Dashboard"},
    {OmniEpdg.Web.SessionsLive, "/sessions", "Sessions"},
    {OmniEpdg.Web.DiameterLive, "/diameter", "Diameter"}
  ]

# Diameter configuration (runtime.exs)
config :diameter_ex,
  diameter: %{
    service_name: :omniepdg,
    listen_ip: "0.0.0.0",
    listen_port: 3868,
    host: "epdg",
    realm: "epc.mnc001.mcc001.3gppnetwork.org",
    product_name: "OmniEPDG",
    vendor_id: 10415,
    applications: [
      %{application_name: :swx, application_id: 16_777_265, vendor_id: 10415},
      %{application_name: :s6b, application_id: 16_777_272, vendor_id: 10415}
    ],
    peers: [
      %{host: "hss", ip: "127.0.0.1", port: 3868, transport: :tcp}
    ]
  }

# License client configuration (runtime.exs)
config :license_client,
  server_url: "https://license.example.com/api",
  product: "omniepdg"

IKEv2 Server Parameters​

The IKEv2 server handles the SWu interface between UEs and OmniEPDG. It terminates IPSec tunnels and performs EAP-AKA authentication.

ParameterTypeRequiredDefaultEnv VarDescription
listen_ipTupleNo{0, 0, 0, 0}EPDG_LISTEN_IPIP address to bind the IKEv2 server. Use {0, 0, 0, 0} for all interfaces. Format: Erlang tuple {A, B, C, D}.
port_500IntegerNo500EPDG_PORT_500UDP port for IKE protocol (pre-NAT). Standard IKE port per RFC 7296.
port_4500IntegerNo4500EPDG_PORT_4500UDP port for IKE NAT-Traversal. Standard NAT-T port per RFC 7296.
cert_fileStringYes/etc/omniepdg/certs/epdg.crtEPDG_CERT_FILEPath to the X.509 certificate file (PEM format) for IKEv2 server authentication.
key_fileStringYes/etc/omniepdg/certs/epdg.keyEPDG_KEY_FILEPath to the private key file (PEM format) corresponding to the certificate.
session_inactivity_timeout_msIntegerNo300000EPDG_SESSION_TIMEOUTSession inactivity timeout in milliseconds. Sessions are terminated if no IKE or ESP traffic is received within this period. Default is 5 minutes.

Authentication Security Parameters​

OmniEPDG includes built-in protection against brute-force attacks and geographic access control. See the Security Guide for detailed documentation.

Rate Limiting Parameters​

config :omniepdg,
  # Per-IP rate limiting
  auth_rate_limit_per_ip: 10,
  auth_rate_limit_ip_window_ms: 60_000,
  auth_rate_limit_ip_block_ms: 300_000,

  # Per-IMSI rate limiting
  auth_rate_limit_per_imsi: 5,
  auth_rate_limit_imsi_window_ms: 60_000,
  auth_rate_limit_imsi_block_ms: 600_000
ParameterTypeRequiredDefaultDescription
auth_rate_limit_per_ipIntegerNo10Maximum failed auth attempts per IP before blocking.
auth_rate_limit_ip_window_msIntegerNo60000Sliding window for counting IP failures (milliseconds).
auth_rate_limit_ip_block_msIntegerNo300000Block duration for IPs exceeding threshold (5 minutes).
auth_rate_limit_per_imsiIntegerNo5Maximum failed auth attempts per IMSI before blocking.
auth_rate_limit_imsi_window_msIntegerNo60000Sliding window for counting IMSI failures (milliseconds).
auth_rate_limit_imsi_block_msIntegerNo600000Block duration for IMSIs exceeding threshold (10 minutes).

GeoIP Parameters​

config :omniepdg,
  geoip_enabled: false,
  geoip_database_path: "/etc/omniepdg/GeoLite2-Country.mmdb",
  geoip_mode: :whitelist,
  geoip_countries: ["AU", "NZ"],
  geoip_allow_unknown: false,
  geoip_fail_open: true
ParameterTypeRequiredDefaultDescription
geoip_enabledBooleanNofalseEnable GeoIP-based country blocking. Requires MaxMind GeoLite2 database.
geoip_database_pathStringNo"/etc/omniepdg/GeoLite2-Country.mmdb"Path to MaxMind GeoLite2 Country database (MMDB format).
geoip_modeAtomNo:whitelist:whitelist (only allow listed countries) or :blacklist (block listed countries).
geoip_countriesListNo[]ISO 3166-1 alpha-2 country codes (e.g., ["AU", "NZ", "US"]).
geoip_allow_unknownBooleanNomode-dependentAllow IPs that cannot be geolocated. Default: false for whitelist, true for blacklist.
geoip_fail_openBooleanNotrueAllow all connections if GeoIP database fails to load.

VPN Mode Selection​

ParameterTypeRequiredDefaultEnv VarDescription
vpn_modeAtomNo:simpleEPDG_VPN_MODEOperational mode: :simple for local IP breakout via TUN interface, :gtp for tunneling through a PGW via GTPv2-C/GTP-U. See the Operations Guide for a detailed comparison.

Simple VPN Parameters​

The simple_vpn configuration block controls IP allocation and DNS for Simple VPN mode. OmniEPDG supports both IPv4 and IPv6 address pools.

config :omniepdg,
  simple_vpn: [
    pool_ipv4: "10.45.0.0/16",
    pool_ipv6: "2001:db8::/32",
    dns_servers_ipv4: ["8.8.8.8", "8.8.4.4"],
    dns_servers_ipv6: ["2001:4860:4860::8888", "2001:4860:4860::8844"],
    p_cscf_ipv4: ["10.4.12.165"],
    p_cscf_ipv6: [],
    mtu: 1400,
    nat_enabled: true
  ]
ParameterTypeRequiredDefaultDescription
pool_ipv4StringYes"10.45.0.0/16"IPv4 address pool in CIDR notation. One IP is allocated per subscriber.
pool_ipv6StringNo"2001:db8::/32"IPv6 address pool in CIDR notation for dual-stack subscribers.
dns_servers_ipv4ListNo["8.8.8.8", "8.8.4.4"]IPv4 DNS servers provided to UEs via PCO (Protocol Configuration Options).
dns_servers_ipv6ListNo["2001:4860:4860::8888", "2001:4860:4860::8844"]IPv6 DNS servers provided to UEs via PCO.
p_cscf_ipv4ListNo[]IPv4 P-CSCF (IMS Proxy) addresses for VoWiFi. Provided to UEs to enable IMS registration.
p_cscf_ipv6ListNo[]IPv6 P-CSCF (IMS Proxy) addresses for VoWiFi.
mtuIntegerNo1400MTU value for the tunnel interface. Lower values reduce fragmentation.
nat_enabledBooleanNotrueEnable NAT for subscriber traffic. When true, masquerade rules are applied for outbound traffic.

Diameter Parameters​

The Diameter configuration controls the SWx (HSS) and S6b (PGW) interfaces. When diameter_enabled is true, OmniEPDG starts the Diameter stack and connects to configured peers.

config :diameter_ex,
  diameter: %{
    service_name: :omniepdg,
    listen_ip: "0.0.0.0",
    listen_port: 3868,
    host: "epdg",
    realm: "epc.mnc001.mcc001.3gppnetwork.org",
    product_name: "OmniEPDG",
    vendor_id: 10415,
    applications: [
      %{application_name: :swx, application_id: 16_777_265, vendor_id: 10415},
      %{application_name: :s6b, application_id: 16_777_272, vendor_id: 10415}
    ],
    peers: [
      %{host: "hss", ip: "10.74.0.21", port: 3868, transport: :tcp}
    ]
  }

Service Parameters​

ParameterTypeRequiredDefaultEnv VarDescription
service_nameAtomNo:omniepdg-Internal Diameter service identifier.
listen_ipStringNo"0.0.0.0"DIA_LISTEN_IPIP address to bind the Diameter listener for incoming connections.
listen_portIntegerNo3868DIA_LISTEN_PORTDiameter listener port. Standard port is 3868 per RFC 6733.
hostStringYes"epdg"DIA_HOSTDiameter Origin-Host (without realm). Combined with realm to form the full Diameter identity.
realmStringYes"epc.mnc001.mcc001.3gppnetwork.org"DIA_REALMDiameter Origin-Realm per RFC 6733. Must match the operator's network domain.
product_nameStringNo"OmniEPDG"-Product-Name AVP value in Diameter CER.
vendor_idIntegerNo10415-Vendor-Id AVP value. 10415 is the 3GPP vendor ID.

Peer Parameters​

Each entry in the peers list defines a Diameter peer connection (typically to the HSS).

ParameterTypeRequiredDefaultEnv VarDescription
hostStringYes-HSS_HOSTPeer's Diameter identity (Origin-Host). Must match the peer's configured identity.
ipStringYes-HSS_IPPeer's IP address for TCP/SCTP connection.
portIntegerNo3868HSS_PORTPeer's Diameter port.
transportAtomNo:tcp-Transport protocol: :tcp or :sctp.

Application IDs​

ApplicationIDVendor IDInterfaceReference
SWx1677726510415ePDG ↔ HSS3GPP TS 29.273
S6b1677727210415AAA ↔ PGW3GPP TS 29.273

License Client Configuration​

The license client validates OmniEPDG against a license server.

config :license_client,
  server_url: "https://license.example.com/api",
  product: "omniepdg"
ParameterTypeRequiredDefaultEnv VarDescription
server_urlStringYes-LICENSE_SERVER_URLURL of the license server API endpoint.
productStringNo"omniepdg"-Product identifier for license validation.

Control Panel Configuration​

The web control panel provides monitoring and management capabilities.

config :control_panel,
  port: 4000
ParameterTypeRequiredDefaultEnv VarDescription
portIntegerNo4000CONTROL_PANEL_PORTHTTP port for the control panel web interface.

Prometheus Metrics Configuration​

OmniEPDG exposes Prometheus metrics via HTTP for monitoring and alerting.

config :omniepdg,
  prometheus: %{
    port: 9568
  }
ParameterTypeRequiredDefaultEnv VarDescription
portIntegerNo9568PROMETHEUS_PORTHTTP port for Prometheus metrics endpoint (/metrics).

Exposed Metrics​

Counter Metrics (Event-driven):

  • epdg_ikev2_session_initiated_count - IKE_SA_INIT exchanges started
  • epdg_ikev2_session_established_count - IKE SAs successfully established
  • epdg_ikev2_session_failed_count - IKE SA establishment failures (by reason)
  • epdg_eap_identity_count - EAP Identity requests
  • epdg_eap_aka_challenge_count - EAP-AKA Challenges sent
  • epdg_eap_aka_success_count - EAP-AKA authentications succeeded
  • epdg_eap_aka_failure_count - EAP-AKA authentications failed (by reason)
  • epdg_eap_aka_sync_failure_count - EAP-AKA SQN sync failures
  • epdg_diameter_swx_mar_count - Multimedia-Auth-Requests (by result)
  • epdg_diameter_swx_sar_count - Server-Assignment-Requests (by result)
  • epdg_diameter_s6b_aar_count - AA-Requests handled (by result)
  • epdg_diameter_s6b_str_count - Session-Termination-Requests
  • epdg_session_created_count - Sessions created (by vpn_mode)
  • epdg_session_terminated_count - Sessions terminated (by reason)
  • epdg_esp_packets_in_count - ESP packets decrypted
  • epdg_esp_packets_out_count - ESP packets encrypted
  • epdg_ip_allocated_count - IP addresses allocated (by type)
  • epdg_ip_released_count - IP addresses released (by type)

Gauge Metrics (Polled every 5s):

  • epdg_sessions_active_count - Total active sessions
  • epdg_sessions_by_state_count - Sessions by FSM state
  • epdg_ip_pool_allocated_count - IPs currently allocated
  • epdg_ip_pool_available_count - IPs available in pool
  • epdg_ip_pool_utilization_ratio - Pool utilization (0.0-1.0)
  • epdg_diameter_swx_pending_count - Pending SWx requests
  • epdg_diameter_s6b_active_sessions_count - Active S6b sessions

Histogram Metrics (Latency tracking):

  • epdg_auth_duration_ms - Full auth flow duration
  • epdg_diameter_swx_mar_latency_ms - MAR response time
  • epdg_diameter_swx_sar_latency_ms - SAR response time
  • epdg_session_duration_seconds - Session lifetime

VM Metrics:

  • vm_memory_total - Total VM memory
  • vm_memory_processes - Process memory
  • vm_memory_binary - Binary memory
  • vm_memory_ets - ETS table memory
  • vm_system_info_process_count - Running processes
  • vm_system_info_port_count - Open ports
  • vm_statistics_run_queue - Scheduler run queue

Prometheus Scrape Configuration​

scrape_configs:
  - job_name: 'omniepdg'
    static_configs:
      - targets: ['localhost:9568']

Timeout Reference​

All internal FSM timeouts are hardcoded. These govern how long state machines wait for responses before considering them failed.

TimeoutValueModeContextDescription
GTP answer10,000 msGTPePDG UE FSMMaximum wait for GTPv2-C Create/Delete Session Response from PGW.
SWm answer10,000 msBothePDG UE FSMMaximum wait for internal Diameter SWm response (DER/DEA, STR/STA).
S6b answer10,000 msGTPAAA UE FSMMaximum wait for Diameter S6b response (ASR/ASA).

Environment Variables Reference​

Environment variables are read in config/runtime.exs and override compile-time defaults.

IKEv2 Server​

VariableDefaultDescription
EPDG_LISTEN_IP"0.0.0.0"IKEv2 server bind address (dotted decimal format, e.g., "10.0.0.1").
EPDG_PORT_500"500"IKE protocol port.
EPDG_PORT_4500"4500"IKE NAT-Traversal port.
EPDG_CERT_FILE"/etc/omniepdg/certs/epdg.crt"Path to IKEv2 server certificate (PEM).
EPDG_KEY_FILE"/etc/omniepdg/certs/epdg.key"Path to IKEv2 server private key (PEM).
EPDG_SESSION_TIMEOUT"300000"Session inactivity timeout in milliseconds.

VPN Mode​

VariableDefaultDescription
EPDG_VPN_MODE"simple"VPN mode: "simple" or "gtp".

Diameter​

VariableDefaultDescription
DIA_LISTEN_IP"0.0.0.0"Diameter listener bind address.
DIA_LISTEN_PORT"3868"Diameter listener port.
DIA_HOST"epdg"Diameter Origin-Host (without realm).
DIA_REALM"epc.mnc001.mcc001.3gppnetwork.org"Diameter Origin-Realm.

HSS Peer​

VariableDefaultDescription
HSS_HOST"hss"HSS Diameter identity (Origin-Host).
HSS_IP"127.0.0.1"HSS IP address.
HSS_PORT"3868"HSS Diameter port.

License, Control Panel, and Metrics​

VariableDefaultDescription
LICENSE_SERVER_URL-License server API URL (required).
CONTROL_PANEL_PORT"4000"Control panel HTTP port.
PROMETHEUS_PORT"9568"Prometheus metrics HTTP port (/metrics endpoint).

Example: Docker Compose​

services:
  omniepdg:
    image: omniepdg:latest
    environment:
      # IKEv2
      EPDG_LISTEN_IP: "0.0.0.0"
      EPDG_CERT_FILE: "/certs/epdg.crt"
      EPDG_KEY_FILE: "/certs/epdg.key"

      # VPN mode
      EPDG_VPN_MODE: "simple"

      # Diameter
      DIA_HOST: "epdg"
      DIA_REALM: "epc.mnc001.mcc001.3gppnetwork.org"
      HSS_HOST: "hss"
      HSS_IP: "10.74.0.21"
      HSS_PORT: "3868"

      # License
      LICENSE_SERVER_URL: "https://license.example.com/api"

      # Control panel
      CONTROL_PANEL_PORT: "4000"

      # Prometheus metrics
      PROMETHEUS_PORT: "9568"
    ports:
      - "500:500/udp"
      - "4500:4500/udp"
      - "4000:4000"
      - "9568:9568"
    volumes:
      - ./certs:/certs:ro
    cap_add:
      - NET_ADMIN
Last updated on