Add your first subscriber

Install the subscriber editor privately

This chapter is for the Open5GS branch. If you chose VectorCore, use its HSS APN, authentication and subscriber provisioning steps in the VectorCore chapter instead of installing a second subscriber database.

The Open5GS WebUI provides a form for adding SIM subscriptions. It is administration software with access to valuable secrets. Install it only after the firewall is in place. Use the current instructions from the Open5GS quickstart and a supported Node.js runtime. The following uses the NodeSource Node.js 22 repository on Ubuntu 24.04. Check the NodeSource instructions and the Open5GS WebUI release requirements if the supported runtime changes.

sudo install -d -m 755 /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key   -o /tmp/nodesource.asc
sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg /tmp/nodesource.asc
echo 'deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_22.x nodistro main'   | sudo tee /etc/apt/sources.list.d/nodesource.list
sudo apt update
sudo apt install nodejs
node --version
npm --version
curl -fsSL https://open5gs.org/open5gs/assets/webui/install   -o /tmp/open5gs-webui-install.sh
less /tmp/open5gs-webui-install.sh

Press q to leave less. Read the script and check its version and download source before running it. It installs and starts a WebUI service and may replace an existing WebUI installation, which is why this path is for a fresh lab. Do not use it as an unreviewed production upgrade.

sudo bash /tmp/open5gs-webui-install.sh
sudo test -f /usr/lib/node_modules/open5gs/.env
sudo chown open5gs:open5gs /usr/lib/node_modules/open5gs/.env
sudo chmod 600 /usr/lib/node_modules/open5gs/.env
sudo systemctl edit open5gs-webui

Add this service override:

[Service]
Environment=HOSTNAME=127.0.0.1
User=open5gs
Group=open5gs

sudo systemctl daemon-reload
sudo systemctl restart open5gs-webui
sudo ss -ltnp | grep ':9999'
systemctl is-active open5gs-webui

Expected: the WebUI listens at 127.0.0.1:9999 and remains active as the open5gs user. The official installer supplies that account through the core packages and sets ownership of the application directory. The explicit ownership and mode commands above protect the generated session and token secrets. If the expected .env file is absent, inspect the service error before proceeding. If a dependency or build fails, read the error and use the matching release's instructions. Do not disable certificate checks, open the UI publicly or select an obsolete runtime merely to hide a build failure.

Open the UI through SSH

On your administrator computer, keep this command running, substituting your Ubuntu username and reserved management address:

ssh -N -L 9999:127.0.0.1:9999 builder@192.168.50.10

Open http://127.0.0.1:9999 in that computer's browser. The local browser connection goes through your encrypted SSH session to the private editor. The official fresh installation uses the documented initial account admin with password 1423. Change that password in the account menu immediately, before entering any subscriber. Store the replacement in your password manager. An initial login that does not work is a reason to check the install and account initialisation, not to expose the database.

Add the card you actually have

1. Open Subscribers, choose the add button and enter the card's identity and security values.
2. Add or edit the session to use internet and IPv4. Keep the default data bearer policy appropriate for ordinary Internet data.
3. Save the record and confirm there is one intended subscription for that IMSI.
4. Keep the supplier's original secret sheet in encrypted storage. Your public build notebook should contain a card nickname and last few identity digits, not K or OPc.

New subscriptions are normally picked up by the HSS without a restart. A changed existing subscription may need a fresh phone attachment and, for some cached profile changes, an MME restart in the private lab. Such a restart disconnects test users. Read the installed release's behaviour before using it on a service with subscribers.

Authentication errors are usually a mismatch

The phone and HSS independently calculate responses using their shared long-term material. They do not send K over the air as a normal password. A wrong IMSI, wrong K, wrong OPc type, wrong MNC length or mismatched card can prevent attachment. Repeated failures are a reason to compare the supplier sheet and HSS entry carefully. Do not generate a new random key in only one place.

For a reused SIM, sequence-number resynchronisation can also matter. Read the authentication error and use the supported resynchronisation path. Never respond by accepting all SIMs or bypassing authentication. The physical SIM and eSIM chapters explain how to obtain compatible credentials and protect them.

Checkpoint

You should have one subscriber record, a changed administrator password, a private WebUI listener and the matching card physically ready. The card's IMSI prefix, the MME PLMN and the radio PLMN must agree before the first attachment attempt.