Skip to main content

Private 4/5G (IMS mode, VoLTE / VoNR)

:::info What Private 4/5G is Private 4/5G requires your private RAN / VoWiFi and your private PGW/SGW/PCRF. MonoPbx acts as the IMS and, optionally, as the HSS/UDM and as an Rx client for dedicated bearers. MonoPbx does not implement a private core: it complements an existing one with a rich IMS and private eSIMs out of the box, which makes private corporate or lab networks easy to deploy and scale. Want SIMs that roam in several countries without any radio or core of your own? See Global eSIM. :::

:::tip Looking for the overview? See the IMS, VoLTE and VoWiFi page on the MonoPbx website, and the network requirements for the ports of the ePDG (UDP 500 and 4500). :::

IMS mode lets MonoPbx act as the IMS core for an operator's own SIMs. Handsets register over the mobile network (VoLTE) or over any Wi-Fi through an ePDG (VoWiFi), prove who they are with the SIM, and use the PBX for voice and SMS. Each SIM is bound to an ordinary extension, so a call to the extension rings the handset's cellular number and the other way round.

It is optional and off by default. Nothing described here runs, and the console shows only an explanation, until a system administrator switches it on.

:::info Who this is for Mobile operators, private-LTE and campus-network operators, and MVNOs that run their own packet core. You need the SIMs' keys (K and OPc, or OP) or an HSS or UDM that holds them. :::

Step-by-step guides​

Walkthroughs from an empty server to a first call, with the exact settings on both sides:

What you run​

ProcessNeedsWhat it does
The PBX enginenothing specialRegisters the handsets, checks the SIM (IMS-AKA), carries SMS, talks to your HSS, UDM, PCRF or PCF, and authenticates VoWiFi tunnels
The P-CSCF role (mpbx --role pcscf)Linux, CAP_NET_ADMINTerminates the handsets' SIP and sets up the IPsec tunnels of TS 33.203
The ePDG (mpbx-epdg)Linux, a public address, a certificate, CAP_NET_ADMIN and permission to bind UDP 500 and 4500IKEv2 and ESP for VoWiFi handsets. It never holds a SIM key

The privileged processes talk to the engine over authenticated links (a shared secret of 32 random bytes per link, openssl rand -base64 32). Keep those links on a private network.

Connections to an HSS (Cx) or a PCRF (Rx) run over TCP or SCTP, each with optional TLS and a trusted CA certificate of your own. SCTP works on Linux only and is not multi-homed. Each peer has its own priority, watchdog interval and role, so you can keep a primary and a backup. Settings are on the same page as the peers; there is no separate package to install.

Turn it on​

IMS mode is on by default on every install (the installers write MPBX_IMS_ENABLED=true; the server default of [ims] enabled is true), with VoWiFi and the mobile codecs on in the initial settings. With no SIMs nothing changes for your phones. To turn it off, set MPBX_IMS_ENABLED=false in .env (Compose and the installers) or [ims] enabled = false in the install configuration and restart; every IMS page then shows that IMS mode is off. Numbers and trunks, Private 4/5G appears in the admin console's sidebar once a mobile network is connected (an engine reports a Diameter peer, a P-CSCF link or an ePDG) or the company has an IMS subscriber; until then open /admin/ims or find the pages with Ctrl K. It has these pages, as tabs: Network, HSS and UDM, Diameter and policy, Security, VoWiFi, Media, IMS subscribers and eSIM. The old address /admin/ims opens Network.

Settings​

Each page of Numbers and trunks, Private 4/5G (system administrators) saves its own part of the settings:

  • Network: the subscriber data back end (this PBX, an HSS over Diameter Cx, or a 5G UDM over Nudm), the initial settings and the caller ID format. The initial settings are MCC and MNC (new installs start with the lab values 001 and 01, and the home domain ims.mnc001.mcc001.3gppnetwork.org), the IMS home domain (calculated as ims.mnc<MNC>.mcc<MCC>.3gppnetwork.org and following the MCC and MNC until you edit it), the IMPI format (default {imsi}@{ims_domain}) and IMPU formats (default sip:{imsi}@{ims_domain}, and tel:{msisdn} when you give SIMs phone numbers) with a live example, the SMS centre number, an optional P-CSCF address for new SIMs, and the IMSI range of new eSIMs (two 15-digit IMSIs that start with the MCC and MNC; the default of the MCC and MNC is filled in and stored on the first save, leading zeros included, see eSIM). The page ends with a Status card, described below.
  • HSS and UDM: which interfaces the built-in HSS answers and its APN profiles (see The built-in HSS); the algorithm of new subscribers (Milenage or TUAK); for a 5G UDM the base URL, authentication, a write-only token, the CA, the IMS resource and the serving network name. The Diameter peers of an external HSS are on Diameter and policy.
  • Diameter and policy: our Diameter identity, the Diameter peers table (TCP or SCTP, TLS, role, priority, watchdog), and policy control (off, Diameter Rx to a PCRF, or HTTP N5 to a PCF) which asks your core for a dedicated bearer for each call's media. Policy control is independent of where subscriber data comes from.
  • Security: IPsec on or off for VoLTE registrations, the algorithms you allow, and the P-CSCF SPI range.
  • VoWiFi: voice over Wi-Fi on or off (on in a new install), and the SPI range of the ePDG. The ePDG process itself (mpbx-epdg, UDP 500 and 4500, a certificate for its name) is not started by the installers: set it up when you use VoWiFi, and open those two UDP ports.
  • Media: mobile codecs (on in a new install): offers AMR-WB and AMR to IMS handsets and adds G.711 for the other side of the call, so a handset can talk to desk phones and trunks. It needs a media server (rtpengine) that can encode AMR, and the AMR and EVS codec licences are your responsibility; check them, and switch it off here if they do not suit you.

Some values are set in the server configuration file because they open sockets or load certificates: the P-CSCF and ePDG addresses, ports, identity and certificate files. Security and VoWiFi list them read-only with a Restart required badge; edit the file and restart the PBX to change them.

Secrets (the N5 and UDM tokens) are write-only: once stored they are never shown again. The page shows only that one is set.

The built-in HSS​

The subscribers you provision here (IMSI, K, OPc or OP, SQN) are also an HSS that other nodes can talk to over Diameter, so MonoPbx can replace the HSS of a private core as well as serve its own IMS. The HSS listens for Diameter when [ims.hss] listen is set in the server configuration (for example MPBX__IMS__HSS__LISTEN=0.0.0.0:3868; plain TCP, so keep it on the core network or behind a TLS proxy) and the IMS settings have a Diameter Origin-Host and Origin-Realm (page Diameter and policy). Open TCP port 3868 to the nodes that connect.

InterfaceStandardPeerMessages answered
Cx (application 16777216)TS 29.229the IMS core (an S-CSCF or I-CSCF)UAR, MAR (IMS-AKA vectors, resynchronisation), SAR (the IMS subscription), LIR
S6a (application 16777251)TS 29.272an MME (for example Open5GS)AIR (E-UTRAN vectors with K_ASME, up to 5 per request, resynchronisation with AUTS), ULR (subscription data), PUR, NOR

On Mobile network (VoLTE / VoNR), HSS and UDM, the card Interfaces the HSS answers switches each interface on or off (Cx is on and S6a is off in a new install). The capabilities exchange (CER/CEA) advertises exactly the enabled interfaces: a peer that asks only for a disabled one is refused with DIAMETER_NO_COMMON_APPLICATION (5010) and disconnected. A change applies when the engine restarts. The same card sets:

  • Send Cancel-Location: when on, a subscriber that is suspended or removed is cancelled at the MME that last attached it (a CLR with cancellation type SUBSCRIPTION_WITHDRAWAL), checked every 15 seconds. The MME that attached before the last engine restart is not known until the subscriber attaches again.
  • UE-AMBR (uplink and downlink, kbit/s) and Access restrictions (the Access-Restriction-Data mask of TS 29.272: a set bit forbids an access, 0 allows all): sent for every subscriber.

The vectors come from the same K, OPc and sequence number as IMS-AKA, so a SIM can use both. A subscriber must be active; a suspended or unknown IMSI is answered DIAMETER_ERROR_USER_UNKNOWN (5001). A bad AUTS in a resynchronisation is refused (DIAMETER_AUTHENTICATION_DATA_UNAVAILABLE, 4181) and changes nothing. The AMF of the subscriber is used as stored: the default 8000 has the separation bit E-UTRAN needs.

APN profiles​

The subscription data an MME gets at attach (ULR) carries the subscriber's MSISDN (the E.164 number of its default public identity), the UE-AMBR, the access restrictions and an APN configuration for each APN profile. Profiles are defined once for the install, in the card APN profiles:

FieldMeaning
APNThe network identifier: labels of letters, digits and hyphens separated by dots (63 characters per label, 100 in all), not ending in .gprs. Stored in lower case.
PDN typeIPv4, IPv6 or IPv4 and IPv6.
QCI1 to 9, 65, 66, 67, 69, 70, 75, 79, 80 or 82 to 86.
ARP priority1 (highest) to 15, with may pre-empt and may be pre-empted.
APN-AMBRUplink and downlink in kbit/s (1 to 4294967).
DefaultExactly one APN is the default (the Context-Identifier of the profile); a new default replaces the old one, and the default cannot be deleted.
EmergencyAn emergency APN; it cannot be the default.

A new install has internet (QCI 9, the default), ims (QCI 5, IPv4 and IPv6) and sos (emergency, QCI 5). Every subscriber has all profiles unless you assign some: open the subscriber under IMS subscribers and tick the APN profiles it may use (nothing ticked means all). The MME sees a change at the subscriber's next attach.

Point an MME at MonoPbx​

Give the MME a Diameter peer for MonoPbx (the Origin-Host and Origin-Realm of the IMS settings) at the address and port of [ims.hss] listen, over TCP, and tell it the HSS realm. For Open5GS this is one ConnectPeer in mme.conf; see IMS for a private network with Open5GS. Not done: SCTP and TLS on the HSS listener, Insert-Subscriber-Data (a change is seen at the next attach), and the S6a Delete-Subscriber-Data and Reset requests.

eSIM packs​

Under Numbers and trunks, Private 4/5G, eSIM you can buy eSIMs for your own network instead of ordering plastic SIMs. Each eSIM carries your MCC and MNC, the IMS domain, the IMPI and IMPU formats and the SMS centre number from the initial settings, and is installed on a phone by scanning a QR code.

Before you buy:

  1. On Network, save your MCC, MNC, the IMSI range and the other initial settings. The Buy buttons stay disabled, with a link to the settings, until MCC, MNC and the IMSI range are saved; the server refuses an order without them as well. New installs start with the lab values MCC 001, MNC 01 and the domain ims.mnc001.mcc001.3gppnetwork.org, and the SMS centre number is a placeholder (+000000000000): replace them with your own.
  2. Sign in to your MonoPbx licence account from the Licence page, and add a payment method to that account. The eSIM page shows the card that will be charged (for example "Paying with Visa •••• 4242 (exp 12/28)"). Without a card it shows a warning and a button that opens your account in a new tab; when you come back, the page checks again. Buying is also disabled until a card is on file.
  3. Optionally set the SIM profile and the ICCID prefix on the same page (see below).

Packs of 1, 10 and 50 eSIMs are offered; the prices are shown on the pack cards, with the price per eSIM and the total, and the largest pack is marked Best value. Buy asks you to confirm the pack, the total and the card, and then charges the card. If the card is declined you see a message and the same button to update the payment method. The order then appears in the Orders table as it is built, with its progress. Each order shows its id in short form (the first block; hover for the full id, or press Copy to put it on the clipboard: it is the id on your receipt and the one support asks for), and an order that failed shows the reason. When money was returned to the card, the order says Refunded or Partly refunded with the amount (Refund in progress until the card refund has been made).

When the eSIMs are ready they are delivered to this PBX in encrypted form and written into the built-in HSS in one step, so they can register at once. The eSIMs table lists each ICCID, IMSI, phone number and the state in the HSS; Show QR code displays the activation code to scan on a phone. The history of your orders and eSIMs is kept by MonoPbx and shown here even if this PBX lost its own copy; the keys are not: the HSS here is the only place that keeps them.

Download the key file​

To load the same eSIMs into another core network (for example Open5GS), download the key file of an order: a CSV with ICCID, IMSI, phone number, K, OPc, AMF, SQN, PINs and PUKs, ADM1, the activation code, the IMPI and IMPUs. It can be downloaded only once: the page asks you to confirm, and afterwards the PBX no longer has the file (a second try answers that it is gone). Store the file safely; it holds secrets. The download is recorded in the audit log, and only system administrators can make it.

SIM profile and ICCID prefix​

The SIM profile card sets what the eSIMs are built with: the service provider name (1 to 16 characters, default MonoPbx), when the phone shows it (always, hidden when roaming, with the network name, or both rules), an optional network name, equivalent home networks (EHPLMN), preferred and allowed networks with the radio technologies each may use (4G, 5G, 3G, 2G; at most 20), and forbidden networks (at most 4). A network is an MCC of 3 digits and an MNC of 2 or 3 digits; a network cannot be listed twice.

Android apps with carrier privileges lists apps (at most 10) by the SHA-256 or SHA-1 hash of their signing certificate (the output of apksigner verify --print-certs, or the app signing key in the Play Console; with or without colons) and, optionally, a package name. They are saved with the order; they are applied to SIMs in a later version.

The ICCID prefix is the digits after 89 in each eSIM's ICCID (1 to 8 digits). The default 99901 is a private range; change it only if you own an ICCID issuer range.

Subscribers​

Company administrators add subscribers under Numbers and trunks, Private 4/5G, IMS subscribers: the IMSI, K and OPc (or OP), the algorithm (Milenage or TUAK), the linked extension and the public identities. K and OPc are sealed on entry and can never be read back, exported or shown in an audit record; to change them you rotate them. A SIM's access policy says where it may register: any, volte (through the P-CSCF only) or vowifi (through the ePDG only). For many SIMs use the bulk import, or mpbx ims import for large batches.

A SIM registers only when its subscriber is active, linked to an enabled extension of an active user, and its access policy allows the access. Anything else is refused with a bare 403; the handset learns nothing about why.

VoLTE​

  1. Configure the settings above and add the subscribers.
  2. For IPsec, run the P-CSCF role on a Linux host: its address, the link address and the shared secret go in its configuration, and the engines get the matching link_connect. Handsets then negotiate the IPsec tunnel with the SIP Security-Client header, as TS 33.203 requires, and the engine refuses a registration that must be protected and is not.
  3. Set the SMS centre number on Network to carry SMS over IMS.

VoWiFi​

  1. On the engines: [ims.epdg] link_listen, the link secret, and the same pool the ePDG uses.
  2. On the ePDG host: the public address, an IKE id (an FQDN), a certificate chain and key for it, link_connect, the inner address pool, the pcscf and dns addresses sent to handsets.
  3. Configure the handsets' carrier settings to use the ePDG's FQDN.

The ePDG offers modern key exchange only (X25519, P-256, P-384), authenticates the handset with EAP-AKA' through the engine, and gives it an inner address, the P-CSCF and DNS addresses. A handset that connects again replaces its older tunnel. When the engine is unreachable the ePDG refuses every tunnel rather than letting anyone in.

Status​

The Network page ends with a Status card, refreshed every ten seconds:

  • each Diameter peer (Cx and Rx) as connected, connecting or down, with the reason;
  • the P-CSCF link of each engine;
  • each ePDG: the tunnels in use and the inner addresses leased from its pool.

A process that stops reporting disappears from the card after 30 seconds.

Alerts and errors​

A subscriber back end that is down fails closed (registrations are refused with 500, never served from weaker data) and raises the IMS subscriber back end unavailable alert. API error codes begin with MPBX-IMS-, for example MPBX-IMS-OFF (IMS is off on the node), MPBX-IMS-SETTINGS-INVALID, MPBX-IMS-PEER-IN-USE, MPBX-IMS-HSS-INVALID and MPBX-IMS-APN-INVALID; the API error codes list every one with its fix.

Good to know​

  • IMS identities never work as SIP digest usernames, and a failed IMS registration never falls back to digest.
  • VoWiFi hosts should drop packets whose source is in the ePDG pool unless they arrive through a tunnel: the PBX reads a source inside the pool as the Wi-Fi access.
  • Not supported: IKE message fragmentation, MOBIKE, and rekeying of a tunnel (a handset that rekeys simply reconnects).

Working with the lists​

The Diameter peers and the APN profiles are tables with a ... menu per row (Edit, Delete); Add a peer and Add an APN profile open the form in a dialog, and a delete asks first. The eSIM orders and SIMs are read-only tables. Every page of the Mobile network section starts with the shared header (section, title, one sentence). Below 640 pixels wide the tables turn into cards.