Skip to main content

Use MonoPbx as the IMS for a private 5G network running free5GC

This guide connects a private 5G standalone network built on free5GC to MonoPbx. free5GC carries the radio and data side (registration, PDU sessions, IP addresses). MonoPbx is the IMS: it is the P-CSCF the phones register with, checks the SIM (IMS-AKA), and gives each SIM an ordinary MonoPbx extension for voice and SMS.

free5GC is a 5G-only core. There is no LTE attach and no PCRF, so phones use voice over NR (VoNR) on the ims data network, and optional QoS for calls goes through the PCF (N5), not Diameter Rx.

:::info Reference page This guide is a walkthrough. Every IMS setting is described in IMS mode (VoLTE and VoWiFi). Running Open5GS instead? See IMS for a private network with Open5GS. :::

What you will build​

data (internet DNN)
Phone ──NR── gNB ──┬──────────────────────────────────────▶ internet
(SIM) │
┌─────────▼────────────── free5GC ────────────────┐
│ AMF UPF (gtp5g) SMF UDM / UDR PCF │
└───────┬──────────────────────────────┬──────────┘
│ "ims" DNN │ N5 (HTTPS)
│ (own subnet) │ Npcf_PolicyAuthorization
┌───────▼──────────────────────────────▼──────────┐
│ MonoPbx │
│ P-CSCF + S-CSCF + registrar │
│ SIP 5060, built-in subscriber data (HSS/UDM │
│ role), rtpengine for media, extensions, SMS │
└───────▲─────────────────────────────────────────┘
│ IKEv2 / ESP, UDP 500 and 4500 (optional)
Phone ──Wi-Fi── internet ePDG (VoWiFi)

How it fits together:

  • The phone registers on the 5G core and opens a second PDU session on the ims DNN. free5GC gives that session its own address range and, when the phone asks for it, the P-CSCF address. That address is MonoPbx.
  • The phone sends SIP REGISTER to MonoPbx over the ims session. MonoPbx challenges it with IMS-AKA and verifies the answer with the SIM's key, so MonoPbx needs the same IMSI, K and OPc as the free5GC subscriber. MonoPbx does not talk to the free5GC UDM for this.
  • N5 (optional): for each call MonoPbx asks the free5GC PCF for a QoS flow for the voice stream. Without it calls run on the default QoS flow of the ims session.
  • VoWiFi (optional): the phone builds an IKEv2 tunnel to the MonoPbx ePDG over any Wi-Fi. free5GC is not involved.

Before you start​

You needNotes
free5GCA working 5G SA network where a phone already registers and has internet on the internet DNN. The configuration keys below were checked against the free5GC v4.3.0 sample files and the current SMF, PCF and WebConsole sources. See the free5GC installation guide.
SIMs you can programYou must know each SIM's IMSI, K and OPc (or OP). free5GC and MonoPbx must hold the same values. This guide uses free5GC's sample PLMN 208/93; replace it with yours everywhere.
HandsetsPhones that support voice over NR (VoNR) on your PLMN. This is the hard requirement of a 5G-only core: if the phone cannot do VoNR, it cannot make IMS calls on this network (see step 6).
A MonoPbx hostLinux, reachable from the free5GC UPF at a fixed IP address. Step 1 links to the install guides.
NetworkA route from the ims UE subnet to the MonoPbx host and back (see step 3), and no NAT between the UPF and MonoPbx.
Your namesThe IMS realm is derived from the PLMN: ims.mnc<MNC>.mcc<MCC>.3gppnetwork.org, with the MNC padded to three digits. For PLMN 208/93: ims.mnc093.mcc208.3gppnetwork.org. Phones build it from the SIM; you do not need to register it in public DNS.

The examples use addresses from the documentation ranges. Replace them with yours.

NameExample
MonoPbx host (P-CSCF)192.0.2.10
free5GC host (SMF, UPF, PCF)192.0.2.20
internet UE subnet10.60.0.0/16
ims UE subnet10.62.0.0/16
ePDG address (VoWiFi)192.0.2.30
PCF, as MonoPbx reaches it (through the HTTPS front of step 5)https://pcf.example.net:8443

Step 1. Install MonoPbx​

Install MonoPbx with the VM installer, Docker Compose, packages or Kubernetes, and finish the first run. Then create at least one user with an extension for each SIM, as in Add users, extensions and phones. A SIM registers only against an enabled extension of an active user.

Open these ports to the free5GC user plane (the ims UE subnet): UDP and TCP 5060 (SIP) and the RTP range of rtpengine. The full list is in Network requirements.

:::tip Where phones send SIP Phones send SIP to the P-CSCF address free5GC hands them. Use the host's real address (192.0.2.10) as the SIP listen address and sip.advertise. With the Linux Compose bundle the SIP edge (mpbx-sip) already listens on port 5060 on the host. :::

Step 2. Switch on IMS mode and set the realm​

IMS is off by default. A system administrator switches it on in the install configuration, then restarts MonoPbx.

On a package or VM install, add this to the configuration file (mpbx.toml):

[ims]
enabled = true

The same setting as an environment variable is MPBX__IMS__ENABLED=true. In the Linux Docker Compose bundle, set it on the services that run the API and the SIP engine with an extra override file next to the bundle (compose.ims.yaml), and add it to the docker compose ... up -d command from the install guide. start.sh does not include the extra file, so use this command for starts and restarts:

services:
mpbx:
environment:
MPBX__IMS__ENABLED: "true"
mpbx-sip-engine:
environment:
MPBX__IMS__ENABLED: "true"
docker compose -f compose.yaml -f compose.linux.yaml -f compose.ims.yaml up -d --wait

After the restart, open Numbers and trunks, Private 4/5G, Network in the admin console (/admin/ims, system administrators; the entry joins the sidebar once the network is connected) and set:

Console fieldValue for this guideWhy
Mobile country code (MCC)208Your PLMN
Mobile network code (MNC)93Your PLMN. 2 or 3 digits
IMS home domainims.mnc093.mcc208.3gppnetwork.orgThe realm phones derive from the SIM
Subscriber data fromThis install (built-in)See step 4
Default algorithm for new subscribersMilenageWhat free5GC uses (the WebConsole offers OPc and OP)
Protect registrations with IPsecOff for this first testSee the note below
Allow voice over Wi-FiOff until the optional VoWiFi section

Save. The default IMPI of a new SIM then becomes <IMSI>@ims.mnc093.mcc208.3gppnetwork.org.

:::note IPsec (TS 33.203) With IPsec off, registrations run over plain SIP on the ims PDU session, which is a private network of your own. This is the simplest way to get a first call. To protect registrations with IPsec, run the P-CSCF role and point the engines at it as described in IMS mode, VoLTE. A SIM whose IPsec policy is required is refused until that is in place. :::

Step 3. free5GC: the ims DNN and the P-CSCF address​

Phones need a second PDU session on the DNN ims, with its own address range and the P-CSCF address in the session setup. The same DNN name must appear in the AMF, SMF and UPF configuration and in the subscriber. The snippets show only what you add; keep the rest of each sample file.

AMF: allow the DNN and announce voice over PS​

In config/amfcfg.yaml:

configuration:
supportDnnList:
- internet
- ims
nasIE:
networkFeatureSupport5GS:
enable: true
imsVoPS: 1 # IMS voice over PS session supported; the sample file has 0

imsVoPS is the "IMS voice over PS session indicator" of the 5GS network feature support IE (TS 24.501). It is 0 in the sample file. A phone only starts voice over NR when the network says IMS voice over PS is supported, so set it to 1.

SMF: DNN, address pool and P-CSCF​

In config/smfcfg.yaml, add ims to each S-NSSAI that carries voice, with its DNS and the P-CSCF (the pcscf key sits next to dns), and give the UPF a pool and an interface for it. This is the sample file's structure; the new parts are the ims entries:

configuration:
snssaiInfos:
- sNssai:
sst: 1
sd: 010203
dnnInfos:
- dnn: internet
dns:
ipv4: 8.8.8.8
ipv6: 2001:4860:4860::8888
- dnn: ims
dns:
ipv4: 8.8.8.8
ipv6: 2001:4860:4860::8888
pcscf:
ipv4: 192.0.2.10

userplaneInformation:
upNodes:
UPF:
type: UPF
nodeID: 127.0.0.8
addr: 127.0.0.8
sNssaiUpfInfos:
- sNssai:
sst: 1
sd: 010203
dnnUpfInfoList:
- dnn: internet
pools:
- cidr: 10.60.0.0/16
- dnn: ims
pools:
- cidr: 10.62.0.0/16
interfaces:
- interfaceType: N3
endpoints:
- 127.0.0.8
networkInstances:
- internet
- ims

pcscf: ipv4: is read by the SMF for each DNN and returned to a phone that asks for a P-CSCF address in its PDU session request (the extended protocol configuration options). It is IPv4 only. Repeat the ims entries for every S-NSSAI your SIMs use (the sample file has a second one, 112233, with its own pool).

UPF: the address pool​

In config/upfcfg.yaml, add the pool next to the internet one:

dnnList:
- dnn: internet
cidr: 10.60.0.0/16
ipForwardEnable: true
- dnn: ims
cidr: 10.62.0.0/16
ipForwardEnable: true

The cidr values must match the SMF pools.

Routing and firewall​

The ims subnet must reach MonoPbx and MonoPbx must reach it back:

  • If MonoPbx is on another host, add a return route on it (or on the router it uses): sudo ip route add 10.62.0.0/16 via 192.0.2.20
  • Do not NAT the ims subnet towards MonoPbx. The free5GC installation guide masquerades traffic leaving the data-network interface (iptables -t nat -A POSTROUTING -o <dn_interface> -j MASQUERADE). If MonoPbx is reached through that interface, limit the rule to the internet pool, for example -s 10.60.0.0/16, so SIP and media from 10.62.0.0/16 keep their real address. The PCF finds the phone's session by that address.
  • Keep forwarding on (sudo sysctl -w net.ipv4.ip_forward=1) and allow 10.62.0.0/16 to 192.0.2.10 on UDP/TCP 5060 and on the rtpengine range in any firewall between them.

Restart free5GC so all network functions read the new files.

Step 4. Subscribers​

Each SIM exists in two places: in free5GC (so the phone can register on the 5G core) and in MonoPbx (so the phone can register for voice). Both must hold the same IMSI, K, OPc and AMF.

In the free5GC WebConsole​

Open the WebConsole at http://<WebConsole host>:5000 (the default login in the WebConsole readme is admin / free5gc; change it), then Subscribers, and create the subscriber:

WebConsole fieldValue
SUPI (IMSI)imsi-208930000000001, the SIM's IMSI
PLMN ID20893
GPSI (MSISDN)optional, the phone number
Authentication Management Field (AMF)8000 (the default)
Operator Code Type / ValueOPc (or OP) and its value
Permanent Authentication Keythe SIM's K
SQNleave the default

For the slice (SST 1, SD 010203), configure two data networks:

Data Network NameDefault 5QINotes
internet9Session AMBR as you need
ims5The standard 5QI for IMS signalling; give it a Session AMBR, for example 1 Mbps both ways

Save. The subscriber's S-NSSAI must be one your AMF and SMF support (step 3).

In MonoPbx​

  1. Go to Numbers and trunks, Private 4/5G, IMS subscribers, Add a subscriber.
  2. Enter the IMSI (208930000000001, without the imsi- prefix), the subscriber key K and the operator key (OPc, or OP, which MonoPbx converts once and does not store). Keep Allowed access at VoLTE and VoWiFi and IPsec at Follow the install setting.
  3. Pick the Extension this SIM belongs to. A SIM registers only against an enabled extension of an active user.
  4. MonoPbx adds the public identity (IMPU) a SIM without an ISIM application registers with, sip:208930000000001@ims.mnc093.mcc208.3gppnetwork.org, and the default IMPI 208930000000001@ims.mnc093.mcc208.3gppnetwork.org on its own. Under Public identities (IMPU) add only more identities, for example tel:+15551230001 (the phone's number, optional but needed to reach the phone by number). For many SIMs use the bulk import described in IMS mode, subscribers. To change the extension of a SIM you already added, open it with Manage and pick another Extension.

K and OPc are write-only: after saving, MonoPbx never shows them again, so keep your own record.

A SIM registers only when it is active, linked to an enabled extension of an active user, and its access policy allows the access. Anything else gets a bare 403.

:::info Where the keys live You enter the keys twice because free5GC authenticates the 5G registration (its UDM) and MonoPbx authenticates the IMS registration. They never need to talk to each other for this. MonoPbx keeps its own sequence number for each SIM, so the first registration can take one extra round trip while the SIM and MonoPbx agree on it. That is normal.

MonoPbx can also take subscriber data from an external HSS over Cx or from a 5G UDM over Nudm, for cores that serve IMS authentication that way; see IMS mode. This guide does not use either. :::

Step 5. Policy control over N5 (optional)​

This step is optional. It asks the PCF for a QoS flow for each call's voice stream. Skip it and calls use the default QoS flow of the ims session, which is fine for a first test. Registration, calls and SMS do not depend on it.

What free5GC supports​

The free5GC PCF lists npcf-policyauthorization in its serviceList. In the current PCF source it accepts an application-session create request from an AF, finds the PDU session by the phone's IPv4 or IPv6 address, turns each audio media component into a PCC rule with 5QI 1, and tells the SMF, which then sets up the QoS flow. It also supports the QoS notification event. MonoPbx sends the phone's address, the audio flows and the events it wants, so the two fit on paper. Whether the QoS flow is carried end to end on your UPF depends on your free5GC and gtp5g version; test it as the checklist says.

Reach the PCF over HTTPS​

MonoPbx's N5 client accepts an https:// PCF address (plain http:// only for localhost and 127.0.0.1). The sample free5GC SBI uses scheme: http. Either:

  • put a TLS-terminating reverse proxy in front of the PCF (on the MonoPbx host or the free5GC host) that listens on https://pcf.example.net:8443 and forwards to the PCF's bindingIPv4:port from pcfcfg.yaml (127.0.0.7:8000 in the sample), speaking HTTP/2 over cleartext to it as the free5GC network functions do; or
  • switch the free5GC SBI to HTTPS as described in the free5GC configuration documentation.

Use a certificate that MonoPbx trusts (a public CA, or provide your CA in the settings). Do not expose the PCF to anything but MonoPbx.

MonoPbx settings​

In Numbers and trunks, Private 4/5G, Diameter and policy, under Policy control (dedicated bearers):

Console fieldValue
Policy serverPCF over HTTP (N5)
PCF base URLhttps://pcf.example.net:8443
PCF authenticationNone (the sample PCF has no OAuth2 on the SBI), or Static bearer token if your front requires one
PCF source networks (optional)the address the PCF or your proxy posts notifications from, as a CIDR block
NRF URL (optional)leave empty

Save, then restart the MonoPbx engine so it reads the policy settings (they are read when the engines start): docker compose -f compose.yaml -f compose.linux.yaml -f compose.ims.yaml restart mpbx-sip-engine on the Linux Compose bundle, or restart the mpbx service on a single-process install. Client-certificate (mTLS) authentication to the PCF is not available; use None or a bearer token.

MonoPbx puts a notification address in each request, https://<base domain>/api/v1/ims/n5/notify/<token>, where <base domain> is the PBX's http.base_domain. The PCF posts QoS events there, so the PCF host must be able to reach that HTTPS address and trust its certificate. If it cannot, calls still work, but MonoPbx is not told when a QoS flow is lost.

Step 6. Handsets​

free5GC offers only 5G, so a phone makes IMS calls with voice over NR.

  1. Insert the programmed SIM. The phone must register on your PLMN (208/93) in 5G standalone mode and have data on the internet DNN.
  2. Add the IMS APN: name ims, APN ims, type ims. The name must match the DNN you created in free5GC.
  3. Turn on VoNR and VoLTE/IMS calling.
    • Phones only use VoNR where their carrier configuration allows it for the SIM's PLMN, and a lab PLMN has none. If the phone cannot do VoNR on your PLMN, it cannot make IMS calls here. Check what your handset supports.
    • Android: the carrier configuration decides. The relevant keys in CarrierConfigManager are KEY_CARRIER_VOLTE_AVAILABLE_BOOL (carrier_volte_available_bool) for IMS calling, KEY_VONR_ENABLED_BOOL (vonr_enabled_bool) and KEY_VONR_SETTING_VISIBILITY_BOOL (vonr_setting_visibility_bool) for voice over NR, KEY_VONR_ON_BY_DEFAULT_BOOL (vonr_on_by_default_bool) to turn it on by default, KEY_CARRIER_NR_AVAILABILITIES_INT_ARRAY (carrier_nr_availabilities_int_array) for the 5G modes the carrier supports, and KEY_CARRIER_WFC_IMS_AVAILABLE_BOOL (carrier_wfc_ims_available_bool) for Wi-Fi Calling. They can be set by a carrier-privileged app (a SIM with carrier-privilege rules) or by a device's engineering tools. See the Android reference.
    • iPhone: voice over NR, VoLTE and Wi-Fi Calling are enabled by the carrier profile installed for the SIM, so a lab SIM needs a profile that allows them. Ask your SIM vendor which handsets they have verified.
  4. Set the phone's SMSC address to the one you set in MonoPbx (step 7) if it asks for one.
  5. Toggle airplane mode so the phone registers again and builds the ims PDU session.

The phone should use the P-CSCF address the SMF returned (pcscf: ipv4:, here 192.0.2.10). On many phones you can read it from the modem or IMS log. If a phone does not request a P-CSCF address in its PDU session request, the SMF does not send one: some handsets then need a static P-CSCF in their carrier configuration.

Step 7. First call and SMS​

Calls.

  1. In the console, open IMS subscribers and check that the SIM's subscriber is Active.
  2. After the phone registers (see the checklist), call the SIM's extension from a desk phone or softphone registered to MonoPbx. The phone rings.
  3. Call another extension from the handset.
  4. Dial an external number from the handset to test your trunk and outbound rules, the same as for any extension.

Media passes through rtpengine, so the rtpengine address MonoPbx advertises must be reachable from the ims subnet.

:::info Calls to other kinds of phone An IMS handset speaks AMR-WB or AMR; desk phones and trunks speak G.711. Handset to handset calls need no conversion. For calls between a handset and anything else, switch on Mobile codecs for VoLTE and VoWiFi (AMR-WB, AMR) in the settings and use an rtpengine that can encode AMR. Read the licence note on that setting first; the AMR and EVS codec licences are your responsibility. See IMS mode. :::

SMS.

  1. In the IMS settings, set the SMSC address (an E.164 number, a host or a SIP URI, for example +10000000000), and make sure the company has an SMS service with a number for the user.
  2. Send a text from the handset. MonoPbx accepts it, sends it through the company's SMS service from one of the user's numbers, and returns the delivery report to the phone.
  3. A text the company receives for a number routed to the SIM's user or extension is also delivered to the handset.

Verification checklist​

Work through these in order. Stop at the first one that fails and use the troubleshooting table.

  • The phone registered on the 5G core and has internet on the internet DNN (the AMF and SMF logs show the registration and the session).
  • A second PDU session exists for the ims DNN, with an address from 10.62.0.0/16.
  • From the phone's ims address, MonoPbx's SIP port answers: check on the MonoPbx host that SIP from 10.62.x.x arrives (sudo tcpdump -ni any udp port 5060).
  • The phone's REGISTER is answered with 401 and then 200 OK. With the engine log at debug, MonoPbx names the refusal reason for a 403 (never the keys).
  • In the console, the SIM's extension shows as registered.
  • N5 only: place a call, then look in the PCF log for the application-session request ("App Session Id ... Create") and in the SMF log for the QoS flow. After the call the session is deleted.
  • A call in each direction has audio both ways.
  • A text from the handset reaches its destination and a text to the SIM's number reaches the handset.

Troubleshooting​

SymptomLikely causeWhat to check
The phone registers but has no ims PDU sessionThe DNN is missing in the phone, the subscriber, the AMF supportDnnList, the SMF or the UPFThe ims APN on the phone matches exactly; the subscriber has an ims data network; ims is in supportDnnList, in the SMF dnnInfos, dnnUpfInfoList and networkInstances, and in the UPF dnnList; free5GC was restarted
The phone never starts voice over NRThe network does not announce IMS voice over PS, or the phone has no VoNR for this PLMNimsVoPS: 1 in amfcfg.yaml; the carrier configuration of the phone (step 6)
The phone has the ims session but never registersNo P-CSCF address was givenpcscf: ipv4: is set for the ims DNN in every S-NSSAI the SIM uses and the SMF was restarted; the phone asks for a P-CSCF address in its PDU session request
REGISTER never arrives at MonoPbxRouting, firewall or NATThe return route to 10.62.0.0/16; ports 5060 UDP/TCP open; the masquerade rule does not cover the ims subnet
REGISTER gets 401 again and againThe K or OPc differs between free5GC and MonoPbx, or the phone rejects the networkRe-enter K and OPc in MonoPbx with Replace keys; check the AMF is 8000 on both sides. If the SIM's sequence number is ahead, MonoPbx resynchronises on its own; a 401 that never ends is a key mismatch
REGISTER gets 403The subscriber is suspended or not linked to an enabled extension of an active user; the access policy does not allow the access; the To identity is not one of the SIM's public identities; IPsec is required but not set upThe subscriber page; for a SIM added with an older version, add sip:<IMSI>@ims.mnc093.mcc208.3gppnetwork.org as an IMPU; IPsec setting
REGISTER gets 500 with Retry-AfterThe subscriber back end is not availableThe mode is This install (built-in) in this guide; a different back end must be reachable
The phone registers but a call never rings the extensionThe SIM is linked to a different extension, or the extension is disabledThe link of the subscriber; the extension's status
Calls connect with one-way or no audioThe UPF cannot reach rtpengine, or rtpengine advertises an address the ims subnet cannot reachRouting from 10.62.0.0/16 to the rtpengine address and the RTP range; RTPE_ADVERTISE; the firewall; then check Mobile codecs if a handset-to-trunk call is silent
N5 requests failThe PCF is not reachable over HTTPS, the certificate is not trusted, or the PCF has no session for the phone's addressThe PCF base URL and certificate; the phone's address as MonoPbx sees it is not translated; the PCF log for "Session Binding failed"; the call continues on the default QoS flow
N5 works but MonoPbx is not told about a lost QoS flowThe PCF cannot reach https://<base domain>/api/v1/ims/n5/notify/...http.base_domain, the certificate, and PCF source networks

Optional: VoWiFi (Wi-Fi Calling) with the ePDG​

With VoWiFi the phone builds an IKEv2 tunnel to the MonoPbx ePDG over any Wi-Fi network and registers through it. The ePDG authenticates the phone with EAP-AKA' using the same SIM key as step 4 and gives it an address inside the tunnel, the P-CSCF address and a DNS server. free5GC does not take part: the tunnel carries only the phone's IMS signalling and media to MonoPbx, and there is no connection to the free5GC core.

Run the ePDG​

The ePDG is the mpbx-epdg process on a Linux host with a public or routable address, a certificate for its name, and permission to bind UDP 500 and 4500. Settings, from IMS mode, VoWiFi:

On the engines:

[ims.epdg]
link_listen = "0.0.0.0:7444" # where the ePDG connects to the engine
pool = "10.9.0.0/22" # the same pool the ePDG uses

The link secret is the environment variable MPBX_IMS_EPDG_LINK_SECRET (32 random bytes, openssl rand -base64 32), the same value on the engine and the ePDG.

On the ePDG host:

[ims]
enabled = true

[ims.epdg]
address = "192.0.2.30"
id = "epdg.epc.mnc093.mcc208.pub.3gppnetwork.org"
cert_file = "/etc/mpbx/epdg.crt"
key_file = "/etc/mpbx/epdg.key"
link_connect = "192.0.2.10:7444"
pool = "10.9.0.0/22"
pcscf = ["192.0.2.10"]
dns = ["192.0.2.53"]

The certificate's name must match id, and its chain must be one the phone trusts. Phones validate the ePDG's certificate against their own trust store, so for a private network use a certificate from a public CA, or install your CA on the test phones. Then turn on Allow voice over Wi-Fi in the IMS settings. The SIM's Allowed access must be VoLTE and VoWiFi or VoWiFi only. Drop packets from the pool that do not arrive through the tunnel, as described in IMS mode, Good to know.

How the phone finds the ePDG​

The phone looks the ePDG up by name in DNS. The name is built from the SIM's PLMN:

epdg.epc.mnc<MNC>.mcc<MCC>.pub.3gppnetwork.org (MNC padded to three digits)
epdg.epc.mnc093.mcc208.pub.3gppnetwork.org (PLMN 208/93)
  • On an iPhone the name is derived from the SIM's MCC and MNC and cannot be changed.
  • The public pub.3gppnetwork.org zone is managed through the GSMA and answers only for networks provisioned through GSMA membership and IPX. A private or lab network is not in it, so you must answer this name yourself: run a DNS resolver with a local zone for it and make the handsets use that resolver.
  • Set id in the ePDG configuration to this same name, and point the name at the ePDG's address (192.0.2.30).

Pick the resolver you already run. Each example answers epdg.epc.mnc093.mcc208.pub.3gppnetwork.org with 192.0.2.30:

dnsmasq

address=/epdg.epc.mnc093.mcc208.pub.3gppnetwork.org/192.0.2.30

Unbound

server:
local-zone: "epdg.epc.mnc093.mcc208.pub.3gppnetwork.org." redirect
local-data: "epdg.epc.mnc093.mcc208.pub.3gppnetwork.org. 300 IN A 192.0.2.30"

BIND (named.conf, then a zone file)

zone "epdg.epc.mnc093.mcc208.pub.3gppnetwork.org" {
type master;
file "/etc/bind/db.epdg.mnc093.mcc208";
};
$TTL 300
@ IN SOA ns.example.net. admin.example.net. ( 1 3600 600 86400 300 )
IN NS ns.example.net.
IN A 192.0.2.30

Then make the handsets use that resolver. The Wi-Fi network's DHCP server hands out DNS servers to phones that join it; set the resolver's address there (for dnsmasq on the same box, dhcp-option=option:dns-server,192.0.2.53), and check that the phone does not use a private DNS service, a VPN or a cellular resolver for this lookup. Check from a laptop on the same Wi-Fi: dig epdg.epc.mnc093.mcc208.pub.3gppnetwork.org must return 192.0.2.30.

On Android you have two further options for test devices:

  • Use the same DNS override. This works without changing the phone.
  • Set the ePDG address in the carrier configuration, with the CarrierConfigManager.Iwlan keys (Android 12, API level 31 and later):
    • KEY_EPDG_STATIC_ADDRESS_STRING (iwlan.epdg_static_address_string): the ePDG's IP address or FQDN.
    • KEY_EPDG_ADDRESS_PRIORITY_INT_ARRAY (iwlan.epdg_address_priority_int_array): the order in which address sources are tried. EPDG_ADDRESS_STATIC is 0 and EPDG_ADDRESS_PLMN is 1; put 0 first to use the static address.
    • Wi-Fi Calling itself is enabled with KEY_CARRIER_WFC_IMS_AVAILABLE_BOOL.
    • These are carrier configuration keys; a normal app cannot change them. See the Android reference.

How the phone finds the P-CSCF​

  • Over 5G the phone learns the P-CSCF address from the network when it sets up the ims PDU session: the free5GC SMF puts the pcscf address of smfcfg.yaml into the session setup (step 3). It does not use DNS for this.
  • Over Wi-Fi the P-CSCF comes from the ePDG: it sends the addresses from [ims.epdg] pcscf to the phone in the IKEv2 configuration payload, together with the inner address and DNS servers.

If you use the IMS domain (ims.mnc093.mcc208.3gppnetwork.org) as the SIP domain, phones only use it inside SIP messages sent to the P-CSCF address they were given; it does not have to resolve in DNS for this setup.

Check VoWiFi​

  1. Turn Wi-Fi Calling on and join the Wi-Fi network that uses your resolver.
  2. In the console, the Status card lists the ePDG with its tunnels and the leased inner addresses.
  3. The handset registers as for VoLTE and the extension shows as registered.

If the N5 policy server is on, a Wi-Fi call asks the free5GC PCF for a QoS flow using the phone's tunnel address, which the PCF does not know. The request is refused and the call continues without a dedicated QoS flow.

The usual causes when the tunnel does not come up: the DNS name does not resolve to the ePDG, UDP 500 or 4500 is filtered, the certificate name does not match id, or the SIM's access policy is VoLTE only. The IMS mode page describes the Status card.

Where to go next​