Use MonoPbx as the IMS for a private 4G/5G network running Open5GS
This guide connects a private LTE or 5G network built on Open5GS to MonoPbx. Open5GS carries the radio and data side (attach, bearers, 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.
When you finish, a phone on your network can register for VoLTE, call an extension, and receive a call from one.
:::info Reference page This guide is a walkthrough. Every IMS setting is described in IMS mode (VoLTE and VoWiFi). Running a 5G-only core on free5GC instead? See IMS for a private network with free5GC. :::
What you will build
data (internet APN)
Phone ──radio── eNB / gNB ──┬──────────────────────────────▶ internet
(SIM) │
┌─────────▼───────────── Open5GS ─────────────┐
│ MME / AMF SGW-U/UPF SMF HSS / UDM │
│ │ PCRF (4G) / PCF (5G)
└──────────┬───────────────┼─────────┬────────┘
│ "ims" APN/DNN │ │ Diameter Rx (4G)
│ (own subnet) │ │ TCP 3868
┌──────────▼───────────────┘ │
│ MonoPbx │
│ P-CSCF + S-CSCF + registrar ◀────┘
│ SIP 5060, built-in subscriber data (HSS 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 attaches to the default APN (
internet) and then opens a second PDN connection on theimsAPN (DNN in 5G). Open5GS gives that session its own address range and tells the phone the P-CSCF address during session setup. That address is MonoPbx. - The phone sends SIP
REGISTERto MonoPbx over theimssession. MonoPbx challenges it with IMS-AKA and verifies the answer with the SIM's key, so MonoPbx needs the same K and OPc as the Open5GS subscriber. - Rx (4G): for each call MonoPbx asks the Open5GS PCRF for a dedicated bearer for the voice stream. This is optional; without it calls run on the
imsdefault bearer. - VoWiFi (optional): the phone builds an IKEv2 tunnel to the MonoPbx ePDG over any Wi-Fi. Open5GS is not involved.
Before you start
| You need | Notes |
|---|---|
| Open5GS | A working network where a phone already attaches and has internet through the internet APN. The configuration keys below were checked against the Open5GS 2.8.0 files. See the Open5GS quickstart. |
| SIMs you can program | You must know each SIM's IMSI, K and OPc (or OP). Open5GS and MonoPbx must hold the same values. Test PLMN 001/01 is used in this guide. Open5GS also ships 999/70 as its default; if you use it, replace mnc001.mcc001 with mnc070.mcc999 everywhere. |
| Handsets | Phones that support VoLTE and can be told to use it on your PLMN (see step 6). |
| A MonoPbx host | Linux, reachable from the Open5GS user plane (UPF) at a fixed IP address. Step 1 links to the install guides. |
| Network | A route from the ims UE subnet to the MonoPbx host and back (see step 3), and no NAT between the UPF and MonoPbx. |
| Your names | The IMS realm is derived from the PLMN: ims.mnc<MNC>.mcc<MCC>.3gppnetwork.org, with the MNC padded to three digits. For PLMN 001/01: ims.mnc001.mcc001.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.
| Name | Example |
|---|---|
| MonoPbx host (P-CSCF) | 192.0.2.10 |
| Open5GS core host (SMF, PCRF, UPF) | 192.0.2.20 |
internet UE subnet | 10.45.0.0/16 |
ims UE subnet | 10.46.0.0/16 |
| ePDG address (VoWiFi) | 192.0.2.30 |
| MonoPbx Diameter identity | mpbx.ims.mnc001.mcc001.3gppnetwork.org, realm ims.mnc001.mcc001.3gppnetwork.org |
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 Open5GS user plane (the ims UE subnet): UDP and TCP 5060 (SIP) and the RTP range of rtpengine. MonoPbx connects out to the PCRF on TCP 3868, so nothing listens for Diameter. The full list is in Network requirements.
:::tip Where phones send SIP
Phones send SIP to the P-CSCF address Open5GS 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 field | Value for this guide | Why |
|---|---|---|
| Mobile country code (MCC) | 001 | Your PLMN |
| Mobile network code (MNC) | 01 | Your PLMN. 2 or 3 digits |
| IMS home domain | ims.mnc001.mcc001.3gppnetwork.org | The realm phones derive from the SIM |
| Subscriber data from | This install (built-in) | See step 4 |
| Default algorithm for new subscribers | Milenage | What Open5GS uses |
| Protect registrations with IPsec | Off for this first test | See the note below |
| Allow voice over Wi-Fi | Off until the optional VoWiFi section |
Save. The default IMPI of a new SIM then becomes <IMSI>@ims.mnc001.mcc001.3gppnetwork.org.
:::note IPsec (TS 33.203)
With IPsec off, registrations run over plain SIP on the ims 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. Open5GS: the ims APN and the P-CSCF address
Phones need a second session called ims with its own address range, and the P-CSCF address in the session setup. Make the changes below, then restart the daemons named at the end.
SMF: address pool for ims and the P-CSCF
In smf.yaml, give each DNN its own subnet (this shape is the one in the Open5GS sample file), and set p-cscf to MonoPbx. Both are keys under smf:.
smf:
session:
- subnet: 10.45.0.0/16
gateway: 10.45.0.1
dnn: internet
- subnet: 10.46.0.0/16
gateway: 10.46.0.1
dnn: ims
p-cscf:
- 192.0.2.10
The Open5GS sample file warns that a UE asking for a DNN other than the ones you list can crash the SMF and UPF, so list every DNN your phones use. For 5G, if you restrict DNNs with the SMF info: block, add ims to the DNN list of the slice.
UPF: the matching interface
upf.yaml needs the same two pools, and each has a network device with the gateway address (from the Open5GS sample file):
upf:
session:
- subnet: 10.45.0.0/16
gateway: 10.45.0.1
dnn: internet
- subnet: 10.46.0.0/16
gateway: 10.46.0.1
dnn: ims
dev: ogstun2
Create the second device and give it the gateway address (the internet pool keeps the default ogstun):
sudo ip tuntap add name ogstun2 mode tun
sudo ip addr add 10.46.0.1/16 dev ogstun2
sudo ip link set ogstun2 up
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.46.0.0/16 via 192.0.2.20 - Do not NAT the
imssubnet towards MonoPbx. MonoPbx asks the PCRF for a bearer using the phone's address as it sees it in SIP, and the PCRF finds the session by that address. - If you applied the hardening from the Open5GS quickstart (rules that drop traffic from the UE subnets to the core host), allow
10.46.0.0/16to192.0.2.10on UDP/TCP 5060 and on the rtpengine range. - Keep forwarding on (
net.ipv4.ip_forward=1), as for theinternetpool.
QoS of the ims session
QCI 5 (5QI 5) is the standard IMS signalling QoS and Open5GS needs it on the default bearer of the ims session. You set it per subscriber in step 4.
Restart the daemons that read these files:
sudo systemctl restart open5gs-smfd open5gs-upfd
Step 4. Subscribers
Each SIM exists in two places: in Open5GS (so the phone can attach) and in MonoPbx (so the phone can register for voice). Both must hold the same IMSI, K, OPc and AMF.
In the Open5GS WebUI
Open http://<open5gs host>:9999, Subscriber, and add or edit the SIM:
| WebUI field | Value |
|---|---|
| IMSI | 001010000000001 (the SIM's IMSI) |
| Subscriber Key (K) | the SIM's K |
| USIM Type / Operator Key | OPc (or OP) and its value |
| Authentication Management Field (AMF) | 8000 (the default) |
| MSISDN | optional, the phone number |
Under Slice Configurations, Session Configurations, add two sessions:
| DNN/APN | Type | 5QI/QCI | ARP Priority Level | Capability | Vulnerability |
|---|---|---|---|---|---|
internet | IPv4 | 9 | 8 | Disabled | Disabled |
ims | IPv4 | 5 | 1 | Disabled | Disabled |
Values are the ones in the Open5GS VoLTE tutorial. Give the ims session a Session-AMBR (for example 3850 Kbps down and 1530 Kbps up, from the same tutorial).
For dedicated bearers (the optional Rx step), add a PCC Rule to the ims session: 5QI/QCI 1 (voice), ARP priority 2, Capability Enabled, Vulnerability Enabled, MBR and GBR 128 Kbps both ways. Open5GS's PCRF looks for a rule with QCI 1 for each audio stream and refuses the request when there is none. Save.
In MonoPbx
- Go to Numbers and trunks, Private 4/5G, IMS subscribers, Add a subscriber.
- Enter the IMSI, 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.
- Pick the Extension this SIM belongs to. A SIM registers only against an enabled extension of an active user.
- MonoPbx adds the public identity (IMPU) a SIM without an ISIM application registers with,
sip:001010000000001@ims.mnc001.mcc001.3gppnetwork.org, and the default IMPI001010000000001@ims.mnc001.mcc001.3gppnetwork.orgon its own. Under Public identities (IMPU) add only more identities, for exampletel:+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 Open5GS authenticates the attach (its own HSS) 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, for HSSs that implement Cx; see IMS mode. This guide does not use it. :::
Step 5. Policy control over Rx (4G)
This step is optional. It makes Open5GS create a dedicated voice bearer (QCI 1) for each call. Skip it and calls use the default ims bearer, which is fine for a first test.
MonoPbx opens a Diameter connection to the Open5GS PCRF and sends Rx requests for the call's media. Open5GS answers by creating the bearer through the SMF.
Open5GS side: freeDiameter
Open5GS runs on freeDiameter. The PCRF only accepts peers it knows, so add MonoPbx to pcrf.conf (in the Open5GS install this is /etc/freeDiameter/pcrf.conf), and make the PCRF listen on an address MonoPbx can reach. The sample file listens on 127.0.0.9 only:
Identity = "pcrf.localdomain";
Realm = "localdomain";
ListenOn = "127.0.0.9";
ListenOn = "192.0.2.20";
NoRelay;
ConnectPeer = "smf.localdomain" { ConnectTo = "127.0.0.4"; No_TLS; };
ConnectPeer = "mpbx.ims.mnc001.mcc001.3gppnetwork.org" { ConnectTo = "192.0.2.10"; No_TLS; };
- Keep the lines that are already in your file (
Identity,Realm,TLS_*,LoadExtension, thesmfpeer). Only add the secondListenOnand thempbxConnectPeer. - The name in
ConnectPeermust be exactly the Origin-Host you give MonoPbx below. freeDiameter drops the connection if the identity in the capabilities answer differs. No_TLSmeans no TLS on the link, as in the sample file. MonoPbx does not listen for Diameter, so the PCRF's own attempts to connect to192.0.2.10will fail and be retried; that is harmless. The connection MonoPbx opens to the PCRF is the one that carries traffic.- Default Identity and Realm in Open5GS are
pcrf.localdomainandlocaldomain. If you changed them, use your values in MonoPbx. - If your freeDiameter build refuses two
ListenOnlines, replace the loopback line with the new address and changeConnectToinsmf.confto the same address.
Restart the PCRF and the SMF:
sudo systemctl restart open5gs-pcrfd open5gs-smfd
MonoPbx side: Diameter peer and policy control
In Numbers and trunks, Private 4/5G:
- Under Policy control (dedicated bearers) set Policy server to PCRF over Diameter Rx.
- Set Our Diameter Origin-Host to
mpbx.ims.mnc001.mcc001.3gppnetwork.organd Our Diameter Origin-Realm toims.mnc001.mcc001.3gppnetwork.org. - Under Diameter peers, Add a peer:
| Console field | Value |
|---|---|
| Name | open5gs-pcrf |
| Peer identity (Destination-Host) | pcrf.localdomain |
| Peer realm (Destination-Realm) | localdomain |
| Host name or IP address | 192.0.2.20 |
| Port | 3868 |
| Transport | TCP |
| Use TLS | off (the PCRF peer uses No_TLS) |
| Used for | Rx (policy control) |
| Priority (lowest first) | 1 |
| Send watchdog requests | on, 30 seconds |
| In use | on |
- Save, then restart the MonoPbx engine so it opens the connection (Diameter peers and policy control are read when the engines start):
docker compose -f compose.yaml -f compose.linux.yaml -f compose.ims.yaml restart mpbx-sip-engineon the Linux Compose bundle, or restart thempbxservice on a single-process install.
The Peer realm must be the PCRF's own realm: MonoPbx addresses every request to it and the PCRF does not relay messages for other realms.
The Status card at the bottom of the settings page shows the peer as Connected after a few seconds. Capability exchange (CER/CEA) needs the PCRF to support the Rx application and to answer with the identity you configured; otherwise the card says why the peer is down.
To protect the Diameter link with TLS, give MonoPbx the CA of the PCRF's certificate and switch Use TLS on; on the Open5GS side drop No_TLS from that ConnectPeer. This guide does not cover the certificate set-up.
5G (N5 to a PCF)
In a 5G core the Open5GS PCRF is not used. MonoPbx asks a PCF over HTTP for the same purpose (Policy server: PCF over HTTP (N5), the PCF base URL, authentication, and optional PCF source networks). It is meant for a PCF that accepts Npcf_PolicyAuthorization application-session requests as MonoPbx sends them.
Open5GS works with N5 from this MonoPbx version on. MonoPbx sends the supported-features attribute (suppFeat, the IMS-SBI feature) that the Open5GS PCF requires in an application-session create request; older versions did not, and the PCF refused every request with HTTP 400. Use this MonoPbx version or newer. In the Open5GS WebUI give the ims session a PCC Rule as for Rx (5QI 1, step 4), and check the PCF log for the application-session request after a call. If a request is refused, the call still runs on the default QoS flow of the ims session (5QI 5).
Optional: use MonoPbx as the HSS for the whole core
Open5GS ships its own HSS (UDM in 5G). MonoPbx can replace it: the subscribers you provision in MonoPbx (the same IMSI, K and OPc the SIMs carry) then authenticate the phones on the radio side too, so you keep one subscriber list. This covers 4G (the MME over S6a). A 5G AMF/UDM is not served this way.
:::caution Replace, do not mix Run either the Open5GS HSS or MonoPbx as the HSS of an MME, not both. Subscribers that exist only in the Open5GS WebUI cannot attach once the MME asks MonoPbx. :::
MonoPbx side
- In the server configuration set the Diameter listener, for example
MPBX__IMS__HSS__LISTEN=0.0.0.0:3868(or[ims.hss] listen = "192.0.2.10:3868"), and open TCP 3868 from the MME. The listener is plain TCP. - Under Diameter and policy set Our Diameter Origin-Host (
mpbx.ims.mnc001.mcc001.3gppnetwork.orgin this guide) and Origin-Realm (ims.mnc001.mcc001.3gppnetwork.org). The MME will use these as the HSS identity. - Under HSS and UDM, Interfaces the HSS answers, tick S6a. Leave Cx on if you use an IMS core that asks MonoPbx for subscriber data. Save and restart the MonoPbx engine.
- Check the APN profiles: they must name the APNs your SMF knows, for example
internet(default) andims. Give each SIM's subscriber the same IMSI as in the SIM, with its K and OPc, under IMS subscribers. Give the subscriber a phone number (E.164) on a public identity if the MME needs an MSISDN.
Open5GS side (MME): mme.conf (in the Open5GS install /etc/freeDiameter/mme.conf). The MME must know MonoPbx as its HSS peer: replace the hss.localdomain peer, and keep the Realm of the MME.
Identity = "mme.localdomain";
Realm = "localdomain";
ListenOn = "127.0.0.2";
No_SCTP;
ConnectPeer = "mpbx.ims.mnc001.mcc001.3gppnetwork.org" { ConnectTo = "192.0.2.10"; Port = 3868; No_TLS; };
No_SCTPmakes freeDiameter use TCP, which is what the MonoPbx listener speaks.- The name in
ConnectPeermust be exactly the Origin-Host set in MonoPbx, or freeDiameter drops the connection. - Open5GS' MME sends its requests to the realm of its
Destination-Realm; MonoPbx answers every S6a request that arrives on the connection, so no realm routing is needed. If your build of the MME addresses the old HSS realm, it is still answered. - Restart the MME:
sudo systemctl restart open5gs-mmed. Stopopen5gs-hssdif nothing else uses it.
Check it. Attach a phone. The MME log shows the capabilities exchange with MonoPbx, then the Authentication-Information and Update-Location answers; the MonoPbx log shows IMS HSS listening for Diameter and S6a ULR answered. An IMSI MonoPbx does not know is refused with user unknown and the phone is rejected. Suspending a subscriber under IMS subscribers with Send Cancel-Location on detaches it from the MME within about 15 seconds. If the MME reports no common application, S6a is switched off in MonoPbx (or the engine was not restarted after switching it on).
Step 6. Handsets
- Insert the programmed SIM. The phone must attach to your PLMN (
001/01) and have data on theinternetAPN. - Add an IMS APN: name
ims, APNims, typeims(some phones call the type "IMS" and keep it separate from the default data APN). The APN name must match the DNN you created in Open5GS. - Turn VoLTE on.
- Phones only use VoLTE where their carrier configuration allows it for the SIM's PLMN, and a lab PLMN has none. Phones differ here, so check what your handset supports.
- Android: the carrier configuration decides. The relevant keys in
CarrierConfigManagerareKEY_CARRIER_VOLTE_AVAILABLE_BOOL(carrier_volte_available_bool) for VoLTE andKEY_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: 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.
- Set the phone's SMSC address to the one you set in MonoPbx (step 7) if it asks for one.
- Toggle airplane mode so the phone attaches again and builds the
imssession. The phone should show a VoLTE or HD Voice indicator once it has registered.
If the SMF returned a P-CSCF address the phone will use it. On many phones you can read it from the modem or IMS log; it must be 192.0.2.10.
Step 7. First call and SMS
Calls.
- In the console, open IMS subscribers and check that the SIM's subscriber is Active.
- After the phone registers (see the checklist), call the SIM's extension from a desk phone or softphone registered to MonoPbx. The phone rings.
- Call another extension from the handset.
- 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 A VoLTE 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.
- 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. - 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.
- 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 attached and has internet on the
internetAPN. In Open5GS:sudo journalctl -u open5gs-mmed -u open5gs-smfdshow the attach and the session. - A second session exists for the
imsAPN, with an address from10.46.0.0/16(the SMF log shows the second session). - From the phone's
imsaddress, MonoPbx's SIP port answers: check on the MonoPbx host that SIP from10.46.x.xarrives (sudo tcpdump -ni any udp port 5060). - The phone's
REGISTERis answered with401and then200 OK. With the engine log at debug, MonoPbx names the refusal reason for a403(never the keys). - In the console, the SIM's extension shows as registered.
- Rx only: under Numbers and trunks, Private 4/5G, Network, the Status card lists the Diameter peer as Connected.
- Rx only: place a call, then look in
/var/log/open5gs/pcrf.logfor the Rx request from MonoPbx and in the SMF and MME logs for the creation of a dedicated bearer. Withdbg_msg_dumpsloaded as in the sample file, the PCRF prints the Diameter messages it receives. After the call the bearer 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
| Symptom | Likely cause | What to check |
|---|---|---|
The phone attaches but has no ims session | The APN is missing in the phone or in the subscriber, or the DNN has no pool | The ims APN on the phone matches the DNN exactly; the subscriber has an ims session in the WebUI; smf.yaml and upf.yaml both list the ims subnet; the SMF and UPF were restarted |
The phone has the ims session but never registers | No P-CSCF address was given | p-cscf is set under smf: and the SMF was restarted; the phone's IMS APN has type ims |
REGISTER never arrives at MonoPbx | Routing, firewall or NAT | The return route to 10.46.0.0/16; ports 5060 UDP/TCP open; no NAT of the ims subnet; the quickstart hardening rules |
REGISTER gets 401 again and again | The K or OPc differs between Open5GS and MonoPbx, or the phone rejects the network | Re-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 403 | The 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 up | The subscriber page; for a SIM added with an older version, add sip:<IMSI>@ims.mnc001.mcc001.3gppnetwork.org as an IMPU; IPsec setting |
REGISTER gets 500 with Retry-After | The subscriber back end is not available | The 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 extension | The SIM is linked to a different extension, or the extension is disabled | The link of the subscriber; the extension's status |
| Calls connect with one-way or no audio | The UPF cannot reach rtpengine, or rtpengine advertises an address the ims subnet cannot reach | Routing from 10.46.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 |
| The Diameter peer stays Down or Connecting | The PCRF does not know MonoPbx, the identities differ, or a firewall blocks 3868 | ConnectPeer name equals MonoPbx's Origin-Host exactly; Peer identity equals the PCRF's Identity; the PCRF listens on 192.0.2.20 (ss -ltn sport = :3868); TCP 3868 is open from the MonoPbx host; the status card shows the reason |
| The peer is Connected but calls have no dedicated bearer | No QCI 1 PCC rule, no Gx session for the phone's address, or NAT between the UPF and MonoPbx | The ims session has a QCI 1 PCC rule in the WebUI; pcrf.log for "No PCC Rule" or "Cannot find Gx Session"; the phone's address as MonoPbx sees it is not translated |
| Calls drop when a bearer cannot be set up | The PCRF refused or the radio does not support dedicated bearers | A refusal normally leaves the call on the default bearer; check the eNB supports QoS and dedicated bearers |
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. Open5GS does not take part: the tunnel carries only the phone's IMS signalling and media to MonoPbx, and there is no S2b connection to the Open5GS SMF.
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.mnc001.mcc001.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.mnc001.mcc001.pub.3gppnetwork.org (PLMN 001/01)
- On an iPhone the name is derived from the SIM's MCC and MNC and cannot be changed.
- The public
pub.3gppnetwork.orgzone 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
idin 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.mnc001.mcc001.pub.3gppnetwork.org with 192.0.2.30:
dnsmasq
address=/epdg.epc.mnc001.mcc001.pub.3gppnetwork.org/192.0.2.30
Unbound
server:
local-zone: "epdg.epc.mnc001.mcc001.pub.3gppnetwork.org." redirect
local-data: "epdg.epc.mnc001.mcc001.pub.3gppnetwork.org. 300 IN A 192.0.2.30"
BIND (named.conf, then a zone file)
zone "epdg.epc.mnc001.mcc001.pub.3gppnetwork.org" {
type master;
file "/etc/bind/db.epdg.mnc001.mcc001";
};
$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.mnc001.mcc001.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.Iwlankeys (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_STATICis0andEPDG_ADDRESS_PLMNis1; put0first 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 LTE the phone learns the P-CSCF address from the network when it sets up the
imssession: Open5GS puts thep-cscfaddresses ofsmf.yamlinto 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] pcscfto the phone in the IKEv2 configuration payload, together with the inner address and DNS servers.
If you use the IMS domain (ims.mnc001.mcc001.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
- Turn Wi-Fi Calling on and join the Wi-Fi network that uses your resolver.
- In the console, the Status card lists the ePDG with its tunnels and the leased inner addresses.
- The handset registers as for VoLTE and the extension shows as registered.
If the Rx policy server is on, a Wi-Fi call asks the Open5GS PCRF for a bearer using the phone's tunnel address, which the PCRF does not know. The PCRF refuses it, and the call continues without a dedicated bearer.
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
- IMS mode (VoLTE and VoWiFi): every setting, the status card and the error codes.
- IMS for a private 5G network with free5GC: the same set-up for a free5GC core.
- Network requirements: all ports.
- SMS and messaging: the SMS service that carries texts from and to the handsets.