In this chapter
Separate the profile from the chip
The eSIM profile contains subscriber information. The eUICC is the secure physical component that stores and uses that profile. Many phones have an eUICC built in. Removable eUICCs also exist and fit into a SIM slot, but their management tools and handset compatibility need checking before purchase. An eSIM is therefore not simply a file you copy into Android or iOS storage.
The provisioning service makes the profile available for secure download. In the consumer eSIM system, that server is called an SM-DP+. The phone's Local Profile Assistant, or LPA, handles the installation process. An activation code identifies the server and the profile to retrieve. A QR code is one convenient way to present that activation information to the phone.
The Osmocom eSIM developer documentation explains these roles. Keep them separate from the 4G core. The provisioning server delivers the profile to the device; the core later authenticates the subscriber when the device joins your radio network. A successful profile download does not prove that the core subscriber entry or the radio is configured correctly.
Use the practical route for normal phones
For ordinary consumer phones, use a service that can publish your private network profiles through a GSMA accredited SM-DP+. One available example is the sysmocom eSIM Manager. It supports private or campus network provisioning, rather than only resale of a public operator's data plan. Confirm availability, account requirements, supported profile templates, charges and support terms directly with the provider.
Its user manual describes selecting a profile template, personalising subscriber parameters, publishing profiles and retrieving output and activation files. The output file supplies values such as IMSI, K and OPc for the core. The activation file supplies the download information. For normal consumer devices, select the GSMA accredited provisioning route. Its separate test route is for compatible test eUICCs.
Before buying profiles, tell the provider what you need: LTE access, the intended network identity, the handset model and firmware, and whether native IMS voice is required. Ask which template is appropriate. Also establish who may access your subscriber key material, how records are exported and deleted, and what happens if you change provider. A procurement conversation at this stage is easier than discovering after issuing profiles that an essential capability is absent.
Prepare one subscriber before issuing a batch
- Choose one test phone and record its exact regional model, operating system and eSIM support. Check that it is unlocked and can use the intended LTE band.
- Confirm the phone's eUICC is compatible with the provider's production provisioning service and chosen profile template.
- Agree the network identity and subscriber numbering plan. Keep two-digit and three-digit MNCs distinct throughout your records.
- Create a single profile using the provider's documented workflow. Use unique credentials intended for your network, rather than shared example keys.
- Retrieve the subscriber output through the provider's secure export process. Store it in your protected operator records.
- Provision the matching subscriber in the core. Check the exact IMSI, algorithm, K, OP or OPc and intended data APN.
- Complete any IMS-side subscriber and identity configuration required by your voice design.
- Retrieve the activation information and deliver it securely to the intended device owner. Treat it as a credential that can enable installation.
- Install the profile on the test phone, then test the network before producing a larger batch.
Keep an inventory relationship between the profile's ICCID, its IMSI, the device owner and its current status. Do not use a publicly accessible spreadsheet for that relationship. Give users a clear subscriber name so they can distinguish your network from their everyday mobile subscription when choosing which SIM handles data or calls.
Install and test the profile
Connect the phone to a working internet connection, commonly Wi-Fi, so it can reach the provisioning service. Open the phone's eSIM or mobile-plan settings and follow the manufacturer's process for scanning the activation code or entering its details. Keep the activation code visible on a separate trusted screen if the phone cannot scan an image displayed on itself.
After installation, check that the intended profile is enabled. On a dual-SIM phone, explicitly select the private profile for the mobile data test. Temporarily disabling the other SIM can make diagnosis easier. Turn off Wi-Fi for the actual mobile network data test so that a working Wi-Fi connection cannot hide a failed LTE session.
First confirm that the profile installed. Next confirm that the phone can select your network. Then confirm core authentication, a data address and access to an allowed service. Finally test IMS registration and calls if those are part of the build. These are separate checkpoints with different failure causes.
Keep a small results sheet using inventory names. Include the installation date, software version and each checkpoint's result. Record whether a reboot or switching airplane mode on and off restores service. Test a second device only after the first gives a repeatable result. A controlled sequence makes it much easier to identify whether a later failure comes from the profile, the phone or a network change.
Understand why a laboratory eSIM server is different
Osmocom's osmo-smdpp is explicitly a proof-of-concept implementation for research and development. Its documentation says regular production eUICCs require the appropriate accredited server certificates. The test implementation can be used with eUICCs that trust the matching GSMA SGP.26 test certificates. That is a specialised lab arrangement, not a shortcut for provisioning every ordinary phone.
Do not put a test certificate setup into the secure-network instructions as if it had the same trust properties as a production provisioning service. The private keys associated with the standard test certificate arrangement are public. A test download working in a laboratory establishes that the experiment works; it does not establish a suitable production security design.
A removable test eUICC can be useful for learning how profile installation works. Keep that experiment separate from profiles issued to people who expect their access credentials to remain private. Label test cards clearly, keep them out of normal distribution and avoid relying on shared test credentials for live subscribers.
Troubleshoot at the correct boundary
| Where it fails | What to check first |
|---|---|
| The phone will not install the profile. | Internet reachability, activation details, whether the profile is already consumed or restricted, eUICC compatibility and the production versus test provisioning route. |
| The profile installs but no network appears. | The radio's authorised operating state, timing, frequency, band support, coverage and broadcast network identity. |
| The phone finds the network but authentication fails. | The core subscriber entry, IMSI, authentication algorithm, matching secret values and relevant core logs. |
| The phone attaches but has no usable data. | The data APN, subscriber service settings, address allocation, routing, firewall rules and DNS. |
| Data works but calls fail. | The handset's IMS policy and compatibility, IMS provisioning, P-CSCF discovery and voice service logs. |
The Open5GS VoLTE study guide illustrates that handset VoLTE enablement and IMS configuration need their own work. Treat any published handset compatibility examples as test reports for a particular setup, rather than a promise that every firmware version will work.
Operate profiles securely after installation
Keep subscriber output files and activation files out of website uploads, support screenshots, public repositories and ordinary group chats. If you need an instructional screenshot, use a clearly fictional activation example. Do not photograph a real activation QR code for this guide.
Plan what happens when a phone is lost, replaced or sold. Disabling the subscriber in the core prevents further access through that subscriber account. Deleting a profile from one phone is a different action and should not be your only revocation process. Ask the provider how profile re-downloads, replacements and transfer restrictions work before promising users that moving to a new phone will be automatic.
Keep encrypted backups of the information needed to rebuild the core subscriber database. Limit operator access and record administrative changes. Review provider retention and deletion controls after a successful export, without deleting the only copy of records you still need to operate the network.
Continue to maintain the normal network security controls after choosing eSIMs. The delivery format does not replace firewall policy, software updates, secure management access or protected backhaul. Its practical benefit is a different way to distribute subscriber credentials, while the radio and core still need the same careful commissioning.
Further reading
Read the sysmocom eSIM Manager manual for its service workflow, the Osmocom SM-DP+ explanation for the architecture, and the osmo-smdpp limitations before attempting a separate laboratory provisioning experiment.