From 48323bd2993636c6233b365c28c80da84eb417e2 Mon Sep 17 00:00:00 2001 From: herlesupreeth Date: Wed, 10 Jan 2024 17:10:48 +0530 Subject: [PATCH] Update VoLTE tutorials --- docs/_docs/tutorial/02-VoLTE-setup.md | 2 +- docs/_docs/tutorial/03-VoLTE-dockerized.md | 175 ++++++++++++--------- 2 files changed, 99 insertions(+), 78 deletions(-) diff --git a/docs/_docs/tutorial/02-VoLTE-setup.md b/docs/_docs/tutorial/02-VoLTE-setup.md index 755f26a90..5411eb896 100644 --- a/docs/_docs/tutorial/02-VoLTE-setup.md +++ b/docs/_docs/tutorial/02-VoLTE-setup.md @@ -457,7 +457,7 @@ $ mysql ``` $ cd ~ && git clone https://github.com/herlesupreeth/Kamailio_IMS_Config -$ cd Kamailio_IMS_Config +$ cd Kamailio_IMS_Config && git checkout 5.3 $ cp -r kamailio_icscf /etc $ cp -r kamailio_pcscf /etc $ cp -r kamailio_scscf /etc diff --git a/docs/_docs/tutorial/03-VoLTE-dockerized.md b/docs/_docs/tutorial/03-VoLTE-dockerized.md index 77033e782..33b33a516 100644 --- a/docs/_docs/tutorial/03-VoLTE-dockerized.md +++ b/docs/_docs/tutorial/03-VoLTE-dockerized.md @@ -5,63 +5,56 @@ head_inline: "" Setup description: - MCC: 001, MNC: 01 -- Docker-compose +- Docker + Docker Compose +- VM/Physical machine running Ubuntu 20.04 or 22.04 - srsENB + USRP B210 or a commercial eNB - Sysmocom USIM - sysmoUSIM-SJS1 -- UE: Mi 9 Pro 5G. Other UE are being tested. +- UE: Mi 9 Pro 5G, Oneplus 5, iPhone X and above, Nokia 5.3. Other UE are being tested. {: .blue} #### 0. Introduction -This tutorial introduces an install-and-run lab for Open5GS + Kamailio IMS -VoLTE study, a follow-up project of [Open5GS Tutorial: VoLTE Setup with Kamailio IMS and Open5GS](https://open5gs.org/open5gs/docs/tutorial/02-VoLTE-setup/). +This tutorial introduces an install-and-run setup for Open5GS + Kamailio IMS VoLTE study. -The main purpose is to save researchers' and students' time to debug for a -minimum-viable environment before actual study can be proceeded. - -**Important notice before you start** - -1. Java 7 is downloaded from an alternative location. You have to agree with - Oracle's term of service and have an Oracle account, to legally use Java SDK - 7u80. By using this repo, I assume you have the legal right to use it and - hold no liability. - -You have to prepare IMSI, Ki, OP/OPc, SQN of your SIM cards. +The main purpose is to save researchers' and students' time to debug for a minimum-viable environment before actual study can be proceeded. #### 1. Prepare SIM cards for VoLTE -1. Wrong KIC / KID / KIK bricks your SIM card. +Program IMSI, Ki, OP/OPc, SQN for the SIM cards you plan to use. + +If VoLTE is not enabled on your Android phone then please refer to the instructions mentioned here: [VoLTE settings overriding](https://github.com/herlesupreeth/CoIMS_Wiki/blob/master/README.md). +{: .notice--info} + +1. Using wrong KIC / KID / KIK bricks your SIM card and is irrecoverable 2. Use MCC = 001, MNC = 01 for a test network, unless you know your MCC/MNC is supported by Android Carrier Privileges. +{: .notice--warning} -Refer to: https://github.com/herlesupreeth/CoIMS_Wiki/blob/master/README.md -* gp --key-enc --key-mac --key-dek -lvi -* gp --key-enc --key-mac --key-dek --unlock -* gp --install applet.cap -* gp -a 00A4040009A00000015141434C0000 -a 80E2900033F031E22FE11E4F06FFFFFFFFFFFFC114E46872F28B350B7E1F140DE535C2A8D5804F0BE3E30DD00101DB080000000000000001 -* gp --acr-list-aram +#### 2. Build Open5GS, Kamailio docker images -#### 2. Build Open5GS, Kamailio with docker-compose +* Mandatory requirements: + * [docker-ce](https://docs.docker.com/install/linux/docker-ce/ubuntu) - Version 22.0.5 or above + * [docker compose](https://docs.docker.com/compose) - Version 2.14 or above -Mandatory requirements: - * [docker-ce](https://docs.docker.com/install/linux/docker-ce/ubuntu) - * [docker-compose](https://docs.docker.com/compose) - -Install docker-compose and make sure it works before going forward. - -Clone the repository and build base docker images of open5gs and Kamailio: +Clone repository and build base docker image of open5gs and kamailio: ``` +# Build docker images for open5gs EPC/5GC components git clone https://github.com/herlesupreeth/docker_open5gs cd docker_open5gs/base docker build --no-cache --force-rm -t docker_open5gs . +# Build docker images for kamailio IMS components cd ../ims_base docker build --no-cache --force-rm -t docker_kamailio . + +# Build docker images for additional components +cd .. +docker compose -f 4g-volte-deploy.yaml build ``` #### 3. Configuring your setup -`.env` is the only file most of them need to edit as per their deployment needs +`.env` is the only file most of them need to edit as per your deployment needs {: .notice--warning} Edit only the following parameters in `.env` as per your setup @@ -69,15 +62,15 @@ Edit only the following parameters in `.env` as per your setup ``` MCC MNC -TEST_NETWORK --> Change this only if it clashes with the internal network at your home/office -DOCKER_HOST_IP --> This is the IP address of the host running your docker setup -SGWU_ADVERTISE_IP --> Change this to value of DOCKER_HOST_IP set above only if eNB is not running the same docker network/host +DOCKER_HOST_IP --> This is the IP address of the host running (EPC+IMS) +SGWU_ADVERTISE_IP --> Change this to value of DOCKER_HOST_IP +UE_IPV4_INTERNET --> Change this to your desired (Not conflicted) UE network ip range for internet APN +UE_IPV4_IMS --> Change this to your desired (Not conflicted) UE network ip range for ims APN ``` If eNB is NOT running in the same docker network/host as the host running the dockerized Core + IMS then follow the below additional steps -Under `mme` section in docker-compose file (`docker-compose.yaml`, `nsa-deploy.yaml`), uncomment the following part - +Under **mme** section in docker compose file (**4g-volte-deploy.yaml**), uncomment the following part ``` ... # ports: @@ -85,8 +78,7 @@ Under `mme` section in docker-compose file (`docker-compose.yaml`, `nsa-deploy.y ... ``` -Under `sgwu` section in docker-compose file (`docker-compose.yaml`, `nsa-deploy.yaml`), uncomment the following part - +Then, uncomment the following part under **sgwu** section ``` ... # ports: @@ -94,57 +86,96 @@ Under `sgwu` section in docker-compose file (`docker-compose.yaml`, `nsa-deploy. ... ``` -#### 4. Building 4G/5G Core + IMS related components images +#### 4. Deploying 4G/5G Core + IMS related components images ``` cd docker_open5gs source .env -docker-compose -f deploy-all.yaml build --no-cache -docker-compose -f deploy-all.yaml up +sudo ufw disable +sudo sysctl -w net.ipv4.ip_forward=1 +docker compose -f 4g-volte-deploy.yaml up ``` #### 5. (Optional) Run srsENB in a separate container -I use srsENB and USRP B210 in the lab. Sometimes you may want to restart -srsENB while keeping the core network running. It is thus recommended to run -srsENB separately. +Sometimes you may want to restart srsENB while keeping the core network running. It is thus recommended to run srsENB separately. + +In order to run srsENB in a separate host, clone the docker_open5gs repository as mentioned above and build srsENB docker images. + +``` +# Build docker images for srsRAN_4G eNB +cd ../srslte +docker build --no-cache --force-rm -t docker_srslte . +``` + +And, edit only the following parameters in **.env** as per your setup + +``` +MCC +MNC +DOCKER_HOST_IP --> This is the IP address of the host running eNB +MME_IP --> Change this to IP address of host running (EPC+IMS) +SRS_ENB_IP --> Change this to the IP address of the host running eNB +``` + +Replace the following part in the docker compose file (**srsenb.yaml**) +``` + networks: + default: + ipv4_address: ${SRS_ENB_IP} +networks: + default: + external: + name: docker_open5gs_default +``` +with +``` + network_mode: host +``` ``` cd docker_open5gs source .env -docker-compose -f srsenb.yaml build --no-cache -docker-compose -f srsenb.yaml up +sudo cpupower frequency-set -g performance +docker compose -f srsenb.yaml up -d && docker container attach srsenb ``` -#### 6. Configuration and register two UE +#### 6. Configuration and provisioning of SIM information in HSS and HLR -If there is a need to change the Core Network component configuration files -found under their respective folder, make sure to re-compile images using -`docker-compose build` again. +If there is a need to change the Core Network component configuration, then corresponding configuration files can be found under their respective folders. {: .notice--warning} -Open (http://:3000) in a web browser, where is -the IP of the machine/VM running the open5gs containers. Login with following -credentials +- Provision SIM details in open5gs HSS + +Open (http://:3000) in a web browser, where is the IP of the machine/VM running the open5gs containers. Login with following credentials ``` Username : admin Password : 1423 ``` -Follow the instructions in [VoLTE Setup](https://open5gs.org/open5gs/docs/tutorial/02-VoLTE-setup/): -- Step 18, set IMSI, Ki, OP, SQN and APN of your SIM cards. - **Important!** Set the type of both APN to IPv4. Kamailio does not support VoLTE over - IPv6 at the moment. (See the screenshot below.) -- Step 20, add IMS subscriptions to FHoSS. +Add users with their corresponding IMSI, Ki, OP/OPc value and APN settings. The APN settings should look like below: + +
+APN Configuration:
+---------------------------------------------------------------------------------------------------------------------
+| APN      | Type | QCI | ARP | Capability | Vulnerablility | MBR DL/UL(Kbps)     | GBR DL/UL(Kbps) | PGW IP        |
+---------------------------------------------------------------------------------------------------------------------
+| internet | IPv4 | 9   | 8   | Disabled   | Disabled       | unlimited/unlimited |                 |               |
+---------------------------------------------------------------------------------------------------------------------
+| ims      | IPv4 | 5   | 1   | Disabled   | Disabled       | 3850/1530           |                 |               |
+|          |      | 1   | 2   | Enabled    | Enabled        | 128/128             | 128/128         |               |
+|          |      | 2   | 4   | Enabled    | Enabled        | 128/128             | 128/128         |               |
+---------------------------------------------------------------------------------------------------------------------
+
+ +**Important!** Set the type of both APN to IPv4. Kamailio does not support VoLTE over IPv6 at the moment. (See the screenshot below) ![Set both type to IPv4 only](https://raw.githubusercontent.com/miaoski/docker_open5gs/gh-pages/screenshots/subscriber-type-ipv4.png) -For already running systems, copy SQN from Open5GS and type it in FHoSS. You -can type SQN in decimal. FHoSS will automagically convert it to hex. +- Provision IMSI and MSISDN in osmohlr to allow [SMS over SGs](https://github.com/herlesupreeth/docker_open5gs#provisioning-of-imsi-and-msisdn-with-osmohlr-as-follows) -Pay special attention to copy/paste. You might have leading or trailing spaces -in FHoSS, resulting in failed connections! +- Provision SIM information in pyHSS [IMS](https://github.com/herlesupreeth/docker_open5gs#provisioning-of-sim-information-in-pyhss-is-as-follows) #### 7. Debugging with Wireshark @@ -152,15 +183,13 @@ Thanks to Open5GS, the topology is super similar to [SAE on Wikipedia](https://e ![Network topology of Open5GS + IMS](https://raw.githubusercontent.com/miaoski/docker_open5gs/master/network-topology.png) - **APN** On your cellphone, there should be *internet* and *ims*. -CoIMS should look like the one below. If you don't know what CoIMS is, please -refer to step 23 of VoLTE Setup. +If CoIMS is used to force enable VoLTE on the Android device, it should look like in the screenshot below: @@ -173,13 +202,11 @@ When DNS is not properly set, you may end up with 478 Unresolvable destination ( ![478 unresolvable destination](https://raw.githubusercontent.com/miaoski/docker_open5gs/gh-pages/screenshots/478-unresolvable-destination.png) -If the port if not open, or DNS is not properly configured, the phone cannot -reach P-CSCF and fails. +If the port if not open, or DNS is not properly configured, the phone cannot reach P-CSCF and fails. ![RST at port 5060](https://raw.githubusercontent.com/miaoski/docker_open5gs/gh-pages/screenshots/RST-5060.png) -If there is an NAT between PGW and P-CSCF, IPsec-NAT would not work, and the -PCAP looks like the one below. N.B. that you need to run P-CSCF as root, in +If there is an NAT between PGW and P-CSCF, IPsec-NAT would not work, and the PCAP looks like the one below. Note that you need to run P-CSCF as root, in order to add xfrm state and policy. ![401 Unauthorized](https://raw.githubusercontent.com/miaoski/docker_open5gs/gh-pages/screenshots/401-unauthorized.png) @@ -193,17 +220,12 @@ Herle Supreeth has shared PCAP files of successful calls, including - [Non-IPSec UE to IPSec UE calling]({{ site.url }}{{ site.baseurl }}/assets/pcapng/nonipsec_to_ipsec_call.pcapng) - [IPSec UE to Non-IPSec UE calling]({{ site.url }}{{ site.baseurl }}/assets/pcapng/ipsec_to_nonipsec_call.pcapng) -The successful calls were made with a commercial eNB (in his case a Casa -smallcell), while srsENB the ACK takes a very long time to reach the UE, -resulting in disconnected calls. **UE registration** ![UE registration with IPSec](https://raw.githubusercontent.com/miaoski/docker_open5gs/gh-pages/screenshots/ue-ipsec.png) -From the screenshot, we see a UE that supports IPSec got a response from -S-CSCF, indicating that ipsec-3gpp is supported, protocol is ESP (ethernet -proto 50, IPSec). Client port (port-c) is 5100 and server port (port-s) 6100. +From the screenshot, we see a UE that supports IPSec got a response from S-CSCF, indicating that ipsec-3gpp is supported, protocol is ESP (ethernet proto 50, IPSec). Client port (port-c) is 5100 and server port (port-s) 6100. Refer to [IMS/SIP - Basic Procedures](https://www.sharetechnote.com/html/IMS_SIP_Procedure_Reg_Auth_IPSec.html) if you want to know more. Also, notice that packets after 401 Unauthorized are transmitted over ESP. @@ -216,8 +238,7 @@ If a UE does not support IPSec, you don't see the "security-server", as shown be ![ipsec to ipsec call](https://raw.githubusercontent.com/miaoski/docker_open5gs/gh-pages/screenshots/ipsec-to-ipsec%20calls.png) -The Wireshark above shows that after several IPSec (ESP) packets, S-CSCF is -sending a SIP INVITE for UE 03 to UE 04. To be more precise, +The Wireshark above shows that after several IPSec (ESP) packets, S-CSCF is sending a SIP INVITE for UE 03 to UE 04. To be more precise, ``` Request-Line: INVITE sip:0398765432100;phone-context=0498765432100@0498765432100;user=phone SIP/2.0