fixed typos and added more clear transitions between open5gs tutorial and our tutorial. added footnotes.

Author: infrared0

docs/tutorials/epc-setup.md

@@ -1,5 +1,5 @@
 ---
-title: Step 1. LTE Core Network Setup
+title: Step 1. LTE EPC (Evolved Packet Core) Network Setup
 ---
 # Introduction and Overview
 
@@ -17,7 +17,7 @@ You can find more detailed documentation and diagrams of the Open5GS software ar
 
 ## Operating System Support
 
-In SCN we will typically perform these installation steps using a fresh install of Ubuntu 22.04 on an x86-64-based computer; however, any operating system that `open5gs` supports should work.
+In SCN we will typically perform these installation steps using a fresh install of Ubuntu 24.04 on an x86-64-based computer; however, any operating system that `open5gs` supports should work.
 
 Note: When you're installing Ubuntu, we suggest choosing the "minimal install" option that doesn’t install extra unnecessary software. In prior installs this has led to version conflicts.
 
@@ -35,54 +35,68 @@ As of November 2024, in the [Open5GS software package](https://github.com/open5g
 
 We would also recommend running the optional WebUI (Web User Interface) service: `open5gs-webui.service`.
 
-The following steps will walk you through this installation process.
+The following steps will walk you through this installation process.[^1]
 
-# Step 1: Install Open5GS (Notes and Pointers)
+[^1]: A similar step-by-step tutorial to this one can be found [here](https://medium.com/networkers-fiit-stu/setting-up-open5gs-a-step-by-step-guide-or-how-we-set-up-our-lab-environment-5da1c8db0439).
 
-Install Open5GS following the [Open5GS Quickstart documentation](https://open5gs.org/open5gs/docs/guide/01-quickstart/) based on your operating system and desired implementation (e.g. "bare metal" directly on the operating system vs. [Docker](https://github.com/wildeyedskies/docker-open5gs-basic-config)).
-There are even [VoLTE](https://open5gs.org/open5gs/docs/tutorial/02-VoLTE-setup/) and [Dockerized VoLTE](https://open5gs.org/open5gs/docs/tutorial/03-VoLTE-dockerized/) implementations of Open5GS.
-A similar step-by-step tutorial to this one can be found [here](https://medium.com/networkers-fiit-stu/setting-up-open5gs-a-step-by-step-guide-or-how-we-set-up-our-lab-environment-5da1c8db0439).
+# Step 1: Install Open5GS
 
-In SCN we have run Open5GS successfully using Ubuntu 20.04 and 22.04, on bare metal or in Virtual Machines, installed via the `apt` package manager (see Step "2. Install Open5GS with a Package Manager" of the [Quickstart](https://open5gs.org/open5gs/docs/guide/01-quickstart/)).
+## Follow the [Open5GS Quickstart guide](https://open5gs.org/open5gs/docs/guide/01-quickstart/) to install Open5gs.
+
+Complete at least Section 2 of the guide based on your operating system (OS) and desired implementation (e.g. "bare metal" directly on the OS vs. [Docker](https://github.com/wildeyedskies/docker-open5gs-basic-config)).[^2]
+
+[^2]: There are even [VoLTE](https://open5gs.org/open5gs/docs/tutorial/02-VoLTE-setup/) and [Dockerized VoLTE](https://open5gs.org/open5gs/docs/tutorial/03-VoLTE-dockerized/) implementations of Open5GS. 
+
+In SCN we have run Open5GS successfully using Ubuntu 20.04, 22.04, and 24.04 (on bare metal or in Virtual Machines) and installed via the `apt` package manager (see Step "2. Install Open5GS with a Package Manager" of the [Quickstart](https://open5gs.org/open5gs/docs/guide/01-quickstart/)).
 First install MongoDB as described in the Quickstart. Then follow instructions under the "Ubuntu" section to install Open5GS via apt.
 
-Note: If installing over a `ssh` connection, we recommend using `tmux` or another program in case you get disconnected from the session in the process. 
+We also recommend Section 3, though it is not required.
+This will later allow you to register subscribers via the GUI steps provided in the "Register Subscriber Information" section of the Quickstart.
+
+After these two sections of the Quickstart, you can mostly return to our tutorial here.
+However, later on in the Networking section we will also be completing the Quickstart steps to "enable forwarding and add the NAT rule" section called "Adding a route for the UE to have WAN connectivity," so you can complete them now if you wish.
+
+_Note: If installing Open5GS over a_ `ssh` _connection, we recommend using_ `tmux` _or another program in case you get disconnected from the session in the process._
 
-## Configure MME and SGWU
+# Step 2: Configure Open5gs Components (MME and SGWU)
 
-Note that for our LTE setup, the MME and SGWU are the only components whose config files you will really need to change from the defaults.
+For our LTE setup, the MME and SGWU are the only components whose config files you will need to change from the defaults.
 
-### MME
+## MME
 Edit the `/etc/open5gs/mme.yaml` file (as root or using `sudo`) as follows:
-- Under `mme:` -> `s1ap:` -> `server:` -> `address:`, set the IP address you will assign to the network interface (likely an ethernet port) on your EPC computer which will be connecting to the eNB. In this tutorial (to match with the Network Configuration section that follows), we will use `192.168.150.1`.
+- Under `mme:` -> `s1ap:` -> `server:` -> `address:`, set the IP address you will assign to the network interface (likely an ethernet port) on your EPC computer which will be connecting to the eNB. In this tutorial (to match with the Network Configuration section that follows), we will use `192.168.150.2`.
 - Under both `mme:` -> `gummei:` and `mme:` -> `tai:`, you will need to change the `plmn_id:` (`mcc:` and `mnc:` values) to match the PLMN you are using for your network. In SCN we use `315` for the MCC and `010` for the MNC, as explained in the "Quick explanation" below.
 
 **Quick explanation:** "PLMN" refers to the [Public Land Mobile Network](https://en.wikipedia.org/wiki/Public_land_mobile_network), in which every network has to have a unique carrier ID defined by the 3-digit "mobile country code (MCC)" and a 2 or 3-digit "mobile network code (MNC)". Alternately, for iPhone compatibility in the US, SCN uses the CBRS "private LTE" PLMN assigned by Apple as described in [this doc](https://support.apple.com/guide/deployment/support-for-private-5g-and-lte-networks-depac6747317/web).
 
 - Note that for the purposes of eNB config later, the Tracking Area Code (or TAC) listed under `mme:` -> `tai:` -> `tac:` will need to match the TAC number configured on the eNB (using the default of 1 is fine). 
 - Optional: Edit `network_name:` (full and short) and `mme_name:` as desired. One of these names will show up on smartphones' lock screens as the "carrier" when the phone is attached to the network.
 
-### SGWU
+## SGWU
 Edit the `/etc/open5gs/sgwu.yaml` file (as root or using `sudo`) as follows:
-- Under `sgwu:` -> `gtpu:` -> `server:` -> `address:`, set the IP address you will assign to the network interface on your EPC computer which will be connecting to the eNB (this should be the same as the IP address of the MME set above, if the MME and SGWU are running on the same machine). In this tutorial we will use `192.168.150.1`.
+- Under `sgwu:` -> `gtpu:` -> `server:` -> `address:`, set the IP address you will assign to the network interface on your EPC computer which will be connecting to the eNB (this should be the same as the IP address of the MME set above, if the MME and SGWU are running on the same machine). In this tutorial we will use `192.168.150.2`.
 
 As mentioned in the Quickstart, after changing the config files, you will need to restart the corresponding Open5GS daemons:
 ```bash
 sudo systemctl restart open5gs-mmed
 sudo systemctl restart open5gs-sgwud
 ```
-However, the MME will likely not start correctly until networking is configured, as described below.
+However, the MME will not start correctly until networking is configured, as described below.
 
-# Step 2: Configure Networking
+# Step 3: Configure Networking
 
-Remember to follow all the network configuration steps in the [Open5GS Quickstart documentation](https://open5gs.org/open5gs/docs/guide/01-quickstart/). For SCN's Ubuntu machines, this means:
+Setting up networking can be the most finicky part of Open5GS configuration, and the source of most failures/bugs.
 
-- Allowing IP forwarding on your machine, e.g. via the following command:
-```bash
-sudo sysctl -w net.ipv4.ip_forward=1
-```
+For SCN's Ubuntu machines, this means:
+
+- Allowing IP forwarding on your machine, e.g. via the following options:
+  - For immediate application, run the command 
+    ```bash
+    sudo sysctl -w net.ipv4.ip_forward=1
+    ```
+  - For persistence, in `/etc/sysctl.conf` remove the `#` comment symbol from the front of the line that says `net.ipv4.ip_forward=1`
 - Using Netplan to configure network interfaces with IP addresses in the desired way.
-- Setting up NAT rules using `iptables` so that traffic from the eNB can reach the Internet and vice versa
+- Setting up NAT rules using `iptables` so that traffic from the eNB can reach the Internet and vice versa. 
 
 The latter two steps are explained in detail below. 
 
@@ -99,7 +113,7 @@ line. A list of network interfaces will appear in the terminal. Find the ones
 corresponding to your ethernet ports (their names usually start with “eth,”
 “enp,” or “enx”).
 
-For Ubuntu 22.04, we're currently using the Netplan program to manage our network configuration.
+For Ubuntu 24.04, we're currently using the Netplan program to manage our network configuration.
 Create a file in the `/etc/netplan` directory (i.e. a folder) named
 `99-open5gs-config.yaml`, and add the following lines, substituting the correct
 interface names and subnets for your configuration:
@@ -155,7 +169,7 @@ route local traffic between the EPC and eNB.
 network:
   ethernets:
     enp1s0: # name of ethernet interface
-      dhcp4: true
+      dhcp4: yes
       addresses:
         - 192.168.150.2/24 # list all downstream networks
         - 192.168.151.2/24
@@ -175,7 +189,7 @@ recommended configuration above, you may need to connect that EPC ethernet port
 to something (e.g. the eNB, a switch, another machine) via an ethernet cable to
 wake the interface up (so that it becomes active and takes on the assigned IP
 addresses). This is because the open5gs MME needs to "bind" (or associate) its S1 interface to one of those IP
-addresses (in this case `192.168.0.2`). Until those IP addresses exist on your machine,
+addresses (in this case `192.168.150.2`). Until those IP addresses exist on your machine,
 the MME will continually throw errors if you try to run it.
 
 ## Setting `iptables` NAT rules to connect the eNB to the Internet
@@ -186,9 +200,11 @@ There might be an easier way to do this, but we've found the cleanest and most r
 
 ```bash
 sudo iptables -t nat -A POSTROUTING -s 192.168.151.0/24 -j MASQUERADE
+sudo iptables -t nat -A POSTROUTING -s 10.45.0.0/16 ! -o ogstun -j MASQUERADE
 ```
 
 **Quick explanation:** The `-t nat` option tells IPTables to install the rule in the correct "table" containing all the NAT rules, and the `-A` option means we're **A**dding the rule as opposed to **D**eleting it (`-D`). `POSTROUTING` is the "chain," or particular list of rules, that this type of NAT rule should go in (more on that [here](https://rlworkman.net/howtos/iptables/chunkyhtml/c962.html) and in this [diagram](https://upload.wikimedia.org/wikipedia/commons/3/37/Netfilter-packet-flow.svg) if you're interested). `-s 192.168.151.0/24` means that we're applying this rule to packets from the **S**ource IP addresses described by the subnet `192.168.151.0/24`. `-j MASQUERADE` means the action we'll be **J**umping to as a result of this rule is "masquerading" the source IP address as my EPC's WAN IP address.
+The second rule allows traffic from the LTE clients on the open5gs subnet to get routed out to the Internet as well.
 
 ### 'Persist' IPTables Configuration
 
@@ -211,7 +227,7 @@ sudo iptables-save > /etc/iptables/rules.v4
 sudo iptables-restore < /etc/iptables/rules.v4
 ```
 
-# Step 3: Start and monitor Open5GS software services
+# Step 4: Start and monitor Open5GS software services
 
 Ubuntu’s built-in logging and monitoring services can be used to monitor the core network services. For example, for seeing the output logs of the MME software component we described in the first section, run the following command in the Terminal:
 
@@ -225,7 +241,7 @@ OR
 sudo systemctl status open5gs-mmed.service
 ```
 
-_Tab complete may be able to fill in the service name for systemctl at least._
+_Tab complete may be able to fill in the service name for_ `systemctl` _though often not for_ `journalctl`.
 
 Learning to read output logs is really important for managing software infrastructure! Simply Googling output messages that seem important but that you don't understand can be a good first step to figuring out how a system is working. Another interesting tool to investigate is [Wireshark](https://www.wireshark.org/), which is essentially a graphical user interface (GUI) version of the [tcpdump](https://www.tcpdump.org/) command line tool that can show you the communications [packets](https://en.wikipedia.org/wiki/Network_packet) flowing through the various network cards on your computer.
 
@@ -244,12 +260,14 @@ The following command will start only the systemd services required for LTE. How
 sudo systemctl start open5gs-hssd.service open5gs-mmed.service open5gs-sgwud.service open5gs-sgwcd.service open5gs-pcrfd.service open5gs-upfd.service open5gs-smfd.service
 ```
 
-### Install and Start the WebUI
+### Start the WebUI
 
-The WebUI is another systemd service and runs by default on your local computer at port 9999. 
-It requires some more dependencies to install, such as `nodejs` (see Step "3. Install the WebUI of Open5GS" in the [Quickstart](https://open5gs.org/open5gs/docs/guide/01-quickstart/)). You can reach it by navigating to `http://localhost:9999` in your web browser.
+The WebUI is another (optional) systemd service you may have chosen to install while following the Open5gs Quickstart.
+It is a web portal that runs by default on port 9999 on the EPC computer. 
+You can reach it by navigating to `http://localhost:9999` in your web browser.
+It requires some more dependencies to install, such as `nodejs` (see Step "3. Install the WebUI of Open5GS" in the [Quickstart](https://open5gs.org/open5gs/docs/guide/01-quickstart/)).
 
-If not already started, start it with the following command:
+If the service has not already started, start it with the following command:
 
 ```bash
 sudo systemctl start open5gs-webui.service
@@ -259,7 +277,7 @@ The default WebUI login credentials are as follows:
 - Username : admin
 - Password : 1423
 
-# Step 4: Add Users to Open5GS database
+# Step 5: Add Users to Open5GS database
 
 (Note that an important pre-condition to adding users is to have SIM cards or eSIMs to give to the users for authentication, along with their respective IMSIs and secret keys to register them onto the EPC. These must be procured separately. 
 WIP- We will endeavor to make guides for these processes available soon.)
@@ -289,7 +307,7 @@ add_ue_with_apn {imsi key opc apn}: adds a user to the database with a specific
 
 The help text also tells you that "default values are as follows: APN "internet", dl_bw/ul_bw 1 Gbps, PGW address is 127.0.0.3, IPv4 only".
 
-# Step 5: Maintenance and Management
+# Step 6: Maintenance and Management
 
 ## Updating Open5GS
 WIP: We are working on an Ansible-based management script for updates and will post updates as they occur.

mkdocs.yml

@@ -4,3 +4,6 @@ theme: readthedocs
 plugins:
   - search
   - awesome-pages
+
+markdown_extensions:
+  - markdown.extensions.footnotes