yigid/openairinterface5g
1
0
Fork 0
mirror of https://gitlab.eurecom.fr/oai/openairinterface5g.git synced 2026-07-13 04:30:28 +00:00
Code Issues Packages Projects Releases Wiki Activity

Remove T documentation, put link to main repo

Robert Schmidt
2023-07-24 10:19:22 +02:00
parent d348e74582
commit 46fa2383d6
11 changed files with 2 additions and 635 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
T.md

@@ -1,19 +1,5 @@
# T tracer
The T tracer is sort of a *framework* to debug and monitor the softmodem.
The T tracer documentation has been moved to the main openairinterface5g repository [here](https://gitlab.eurecom.fr/oai/openairinterface5g/-/blob/develop/common/utils/T/DOC/T.md).
It is made of two main parts:
* an events' collector integrated to the real-time processing,
* a separate set of programs to receive, record, display, replay and
analyse the events sent by the collector.
## Documentation
* [Basic usage](T/basic)
* [Record](T/record)
* [Replay](T/replay)
* [Multiple tracers](T/multi)
* [MAC PDUs and wireshark](T/wireshark)
* [The *enb* tracer](T/enb)
* [The *to_vcd* tracer](T/to_vcd)
You can also find it via the README in the `doc` folder.

77
T/basic.md

@@ -1,77 +0,0 @@
# Basic usage of the T
## Compilation
### softmodem side
Simply call `build_oai` the usual way, for example `./build_oai --eNB -w USRP`.
The T tracer is compiled in by default.
### tracer side
Go to the directory `common/utils/T/tracer` and do `make`.
In case of failure with the following error:
```shell
/usr/bin/ld: cannot find -lXft
```
Run:
```shell
sudo apt-get install libxft-dev
```
## Run the softmodem
Run the softmodem with the option `--T_stdout 2` and it will wait for a
tracer to connect to it before processing. (This option is confusing
and may change in the future.)
```shell
cd cmake_targets/ran_build/build
sudo ./lte-softmodem -O [configuration file] --T_stdout 2
```
Additional options can be passed to the softmodem.
The option `--T_nowait` lets the processing start immediately without
first waiting for a tracer.
The option `--T_port [port]` changes the default port used by the
softmodem to wait for a tracer. The default port is 2021.
The option `--T_dont_fork` allows one to use gdb to debug problems
with the softmodem. Note that you then may have some "zombie"
processes after crashes, in which case you can run
`sudo killall -9 lte-softmodem` to get rid of them (`lte-softmodem`
to be replaced by the program you trace, like `lte-softmodem-nos1`
or `oaisim`).
The option `--T_stdout` also accepts values 0 (to disable output
on the terminal and only use the T tracer) and 1 (to disable
the T tracer and only output on the terminal). The default is
1.
## Run a tracer
Go into the directory `common/utils/T/tracer` and run for example
the `enb` tracer:
```shell
./enb -d ../T_messages.txt
```
To trace a remote program, use the `-ip` option. For example,
if you want to trace a program running on `192.168.12.148` do:
```shell
./enb -d ../T_messages.txt -ip 192.168.12.148
```
A graphical user interface will appear with which you can interact to
control the monitoring. See [there](T/enb) for more documentation
about the `enb` tracer.
It is possible to run several tracers at the same time. See
[here](T/multi).

3
T/enb.md

@@ -1,3 +0,0 @@
![enb_trace](/uploads/897da7e2c4bd00868c0ccb08fa6590ec/enb_trace.gif)
[source file of this image](/uploads/e942a44acf57adc60372b044f79255e1/enb_trace.odp)

BIN
T/example.raw

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 303 KiB

230
T/howtoconnectoaisimwithoaiepc.md

@@ -1,230 +0,0 @@
# How to connect oaisim with OAI EPC (on different machines)
**`Note: This tutorial assume that you already managed to have success compilation`**
**Refer to https://gitlab.eurecom.fr/oai/openairinterface5g/wikis/HowToConnectCOTSUEwithOAIeNBNew for detailed instructions on EPC**
**Note: This tutorial uses the latest develop branch with GTP kernel module from 4.7.x kernel. Please use the `DOCS/EPC_User_Guide.pdf` (from openair-cn repository, https://gitlab.eurecom.fr/oai/openair-cn.git) for OAI EPC Documentation. If you use other version of EPC, you need to modify the instructions accordingly**
## Example Setup
* IP of eNB : 192.168.12.117
* IP of EPC : 192.168.12.81
## OAISIM sim card information
* IMSI : 208930100001111
* Ki Value : 8baf473f2f8fd09487cccbd7097c6862
* Operator key : 1006020f0a478bf6b699f15c062e42b3
## EPC Setup
### 1. FQDN Configuration
`/etc/hosts` must contain the fqdn of the MME and HSS (same since both run on the same host):
(assuming the realm is openair4G.eur)
```
127.0.0.1 localhost
127.0.1.1 bouillabaisse.openair4G.eur bouillabaisse
```
### 2. Configuring and Building HSS
#### 2.1 Modified the `oai_db` in HSS database (Accessing HSS database through http://127.0.0.1/phpmyadmin is recommended)
* In table `mmeidentity`, enter the record corresponding to your MME:
![mmeidentity](/uploads/0cb7bbfbbf1f0bee2ba4803452733730/mmeidentity.png)
* In table `pdn`, enter the record allowing the IMSI mentioned above(`208930100001111`) to connect to an APN
* In table `users`, make sure the record with `imsi`=208930100001111 having correct `key` and `mmeidentity_idmmeidentity`. `key` should be 8baf473f2f8fd09487cccbd7097c6862 and `mmeidentity_idmmeidentity` should match the ID you put in `mmeidentity` table
#### 2.2 Also, you have to change the configuration file `/usr/local/etc/oai/hss.conf` like this:
```
HSS :
{
## MySQL mandatory options
MYSQL_server = "127.0.0.1"; # HSS S6a bind address
MYSQL_user = "MYSQL_USERNAME"; # Database server login
MYSQL_pass = "MYSQL_PASSWORD"; # Database server password
MYSQL_db = "oai_db"; # Your database name
## HSS options
OPERATOR_key = "1006020f0a478bf6b699f15c062e42b3"; # OP key for OAISIM
RANDOM = "true"; # True random or only pseudo random (for subscriber vector generation)
## Freediameter options
FD_conf = "/usr/local/etc/oai/freeDiameter/hss_fd.conf";
};
```
#### 2.3 Run HSS
```
bouillabaisse@bouillabaisse:~/openair-cn/SCRIPTS$ ./run_hss
```
### 3. Configuring and Building MME
#### 3.1 Check the following fields in your `/usr/local/etc/oai/mme.conf`
```
GUMMEI_LIST = (
{MCC="208" ; MNC="93"; MME_GID="4" ; MME_CODE="1"; } # YOUR GUMMEI CONFIG HERE
);
TAI_LIST = (
{MCC="208" ; MNC="93"; TAC = "1"; } # YOUR TAI CONFIG HERE
);
NETWORK_INTERFACES :
{
# MME binded interface for S1-C or S1-MME communication (S1AP), can be ethernet interface, virtual ethernet interface, we don't advise wireless interfaces
MME_INTERFACE_NAME_FOR_S1_MME = "eth1"; # YOUR NETWORK CONFIG HERE
MME_IPV4_ADDRESS_FOR_S1_MME = "192.168.12.81/24"; # YOUR NETWORK CONFIG HERE
# MME binded interface for S11 communication (GTPV2-C)
MME_INTERFACE_NAME_FOR_S11_MME = "eth1:11"; # YOUR NETWORK CONFIG HERE
MME_IPV4_ADDRESS_FOR_S11_MME = "192.11.12.81/24"; # YOUR NETWORK CONFIG HERE
MME_PORT_FOR_S11_MME = 2123; # YOUR NETWORK CONFIG HERE
};
S-GW :
{
# S-GW binded interface for S11 communication (GTPV2-C), if none selected the ITTI message interface is used
SGW_IPV4_ADDRESS_FOR_S11 = "192.21.12.81/24"; # YOUR NETWORK CONFIG HERE
};
```
#### 3.2 Run MME
```
bouillabaisse@bouillabaisse:~/openair-cn/SCRIPTS$ ./run_mme -i
```
### 3. Configuring and Building SPGW
#### 3.1 Check the following fields in your `/usr/local/etc/oai/spgw.conf`
```
S-GW :
{
NETWORK_INTERFACES :
{
# S-GW binded interface for S11 communication (GTPV2-C), if none selected the ITTI message interface is used
SGW_INTERFACE_NAME_FOR_S11 = "eth1:21"; # STRING, interface name, YOUR NETWORK CONFIG HERE
SGW_IPV4_ADDRESS_FOR_S11 = "192.21.12.81/24"; # STRING, CIDR, YOUR NETWORK CONFIG HERE
# S-GW binded interface for S1-U communication (GTPV1-U) can be ethernet interface, virtual ethernet interface, we don't advise wireless interfaces
SGW_INTERFACE_NAME_FOR_S1U_S12_S4_UP = "eth1"; # STRING, interface name, YOUR NETWORK CONFIG HERE, USE "lo" if S-GW run on eNB host
SGW_IPV4_ADDRESS_FOR_S1U_S12_S4_UP = "192.168.12.81/24"; # STRING, CIDR, YOUR NETWORK CONFIG HERE
SGW_IPV4_PORT_FOR_S1U_S12_S4_UP = 2152; # INTEGER, port number, PREFER NOT CHANGE UNLESS YOU KNOW WHAT YOU ARE DOING
# S-GW binded interface for S5 or S8 communication, not implemented, so leave it to none
SGW_INTERFACE_NAME_FOR_S5_S8_UP = "none"; # STRING, interface name, DO NOT CHANGE (NOT IMPLEMENTED YET)
SGW_IPV4_ADDRESS_FOR_S5_S8_UP = "0.0.0.0/24"; # STRING, CIDR, DO NOT CHANGE (NOT IMPLEMENTED YET)
};
}
P-GW =
{
NETWORK_INTERFACES :
{
# P-GW binded interface for S5 or S8 communication, not implemented, so leave it to none
PGW_INTERFACE_NAME_FOR_S5_S8 = "none"; # STRING, interface name, DO NOT CHANGE (NOT IMPLEMENTED YET)
# P-GW binded interface for SGI (egress/ingress internet traffic)
PGW_INTERFACE_NAME_FOR_SGI = "eth1"; # STRING, YOUR NETWORK CONFIG HERE
PGW_MASQUERADE_SGI = "yes"; # STRING, {"yes", "no"}. YOUR NETWORK CONFIG HERE, will do NAT for you if you put "yes".
UE_TCP_MSS_CLAMPING = "no"; # STRING, {"yes", "no"}.
};
# Pool of UE assigned IP addresses
# Do not make IP pools overlap
# first IPv4 address X.Y.Z.1 is reserved for GTP network device on SPGW
# Normally no more than 16 pools allowed, but since recent GTP kernel module use, only one pool allowed (TODO).
IP_ADDRESS_POOL :
{
IPV4_LIST = (
"172.16.0.0/12" # STRING, CIDR, YOUR NETWORK CONFIG HERE.
);
};
# DNS address communicated to UEs
DEFAULT_DNS_IPV4_ADDRESS = "192.168.12.100"; # YOUR NETWORK CONFIG HERE
DEFAULT_DNS_SEC_IPV4_ADDRESS = "8.8.4.4"; # YOUR NETWORK CONFIG HERE
# Non standard feature, normally should be set to "no", but you may need to set to yes for UE that do not explicitly request a PDN address through NAS signalling
FORCE_PUSH_PROTOCOL_CONFIGURATION_OPTIONS = "no"; # STRING, {"yes", "no"}.
UE_MTU = 1500 # INTEGER
};
```
#### 3.2 Run SPGW
```
bouillabaisse@bouillabaisse:~/openair-cn/SCRIPTS$ ./run_spgw -i
```
### 4. Expected Results for HSS, MME, SPGW, ifconfig
#### 4.1 HSS
![hss](/uploads/7ef0ea9e8fb768f9fcd5bfdab57b493d/hss.png)
#### 4.2 MME
![mme](/uploads/69b3e0ed231a136ba0d3ba4f08a27aeb/mme.png)
#### 4.3 SPGW
![spgw](/uploads/e8ab27eea228ce4538b7a3797f7d22bc/spgw.png)
#### 4.4 ifconfig
You should see `eth1:11`, `eth1:21`, and `gtp0` in ifconfig. The interface name will depend on what you put in the conf file.
![ifconfig](/uploads/57db43380fe81b939d4b21027e87c274/ifconfig.png)
## OAISIM Setup
### 1. Configuring OAISIM
Modify `~/OPENAIR_DIR/target/PROJECTS/GENERIC-LTE-EPC/CONF/enb.band7.generic.oaisim.local_mme.conf` and make sure the following fields are matching what you need.
```
//It should be like this for oaisim sim card
tracking_area_code = "1";
mobile_country_code = "208";
mobile_network_code = "93";
```
```
mme_ip_address = ( { ipv4 = "192.168.12.81"; //IP of MME
ipv6 = "192:168:30::17";
active = "yes";
preference = "ipv4";
}
);
NETWORK_INTERFACES :
{
ENB_INTERFACE_NAME_FOR_S1_MME = "eth0";
//The local interface goes to MME
ENB_IPV4_ADDRESS_FOR_S1_MME = "192.168.12.117/24";
ENB_INTERFACE_NAME_FOR_S1U = "eth0";
//The local interface goes to SGW
ENB_IPV4_ADDRESS_FOR_S1U = "192.168.12.117/24";
ENB_PORT_FOR_S1U = 2152; # Spec 2152
};
```
### 2. Compiling and Running OAISIM
```
cd ~/OPENAIR_DIR/cmake_targets
./build_oai -x -c --oaisim --UE
cd ~/OPENAIR_DIR/cmake_targets/tools/
sudo -E ./run_enb_ue_virt_s1
```
### 3. Expected Results for OAISIM and ifconfig
#### 3.1 OAISIM
![oaisim](/uploads/b41778083b6b900218776f43c9209501/oaisim.png)
#### 3.2 ifconfig
![oaisim_ifconfig](/uploads/995f4be6e7ae505795ac0cd2cc48918d/oaisim_ifconfig.png)
### 4. Setting Routing
In order to get the packets route back to UE, you also need to set the routing
```
ip rule add from 172.16.0.2/32 table 200
ip rule add to 172.16.0.2/32 table 200
```
### 5. Test
You can try to ping through `oip1` interface
![ping](/uploads/82eaff820cbe511c674c8dd835619de3/ping.png)
## Troubleshoot
1. Make sure the sim card information(IMSI, Ki, Operator Key) is consistent between eNB and HSS database
2. Make sure MCC=208, MNC=93 in eNB conf file and mme.conf
3. When the traffic of UE cannot go through, you need to check the routing on both UE side and EPC side
* UE side
![UE_routing](/uploads/1c9cfc03fa1a4ed1ae7ff4bcec5e1204/UE_routing.png)
* EPC side
![EPC_routing](/uploads/055b0802c7d207f509054f48e8ef096f/EPC_routing.png)

57
T/multi.md

@@ -1,57 +0,0 @@
# Multiple tracers
To connect several tracers to the same process, first launch the `multi`
tracer.
Run as:
```shell
cd common/utils/T/tracer
./multi -d ../T_messages.txt
```
Then connect other tracers (`enb`, `textlog`, `to_vcd`, etc.) to the
`multi` tracer.
For example (if you debug the `lte-softmodem`) in one terminal, run:
```shell
cd common/utils/T/tracer
./enb -d ../T_messages.txt -p 2022
```
That will launch the GUI tool to analyze the proper running of the
softmodem.
And in another terminal, run:
```shell
cd common/utils/T/tracer
./to_vcd -d ../T_messages.txt -p 2022 -vcd -o /tmp/openair_dump_eNB.vcd
```
That will dump the VCD traces generated by the softmodem to the
file `/tmp/openair_dump_eNB.vcd`.
The `multi` tracer waits for other tracers to connect to the port 2022.
So you pass `-p 2022` to a tracer so that it connects to the `multi`
tracer. This port can be changed with the `-lp` option.
For example to listen to port 4321, run `multi` as:
```shell
./multi -d ../T_messages.txt -lp 4321
```
Then you would pass `-p 4321` to any tracer for it to connect to `multi`.
As a reminder, to trace `lte-softmodem`, you run it as:
```shell
sudo ./lte-softmodem -O config_file.conf --T_stdout 0
```
The important part is `--T_stdout 0`.
The order to launch the various programs (`multi`, the softmodem, other
tracers) is not important.

34
T/record.md

@@ -1,34 +0,0 @@
# Record
First, read the [basic usage](T/basic) to compile things.
To record, you use the `record` tracer.
To send a trace to Eurecom, you run (unless we specifically ask you
to activate/deactivate specific traces):
```shell
./record -d ../T_messages.txt -o record.raw -ON -off VCD -off HEAVY -off LEGACY_GROUP_TRACE -off LEGACY_GROUP_DEBUG
```
And then you run the program to trace (`lte-softmodem`, `oaisim`, whatever)
as explained in [basic usage](T/basic).
To stop the recording, you simply press `control+c` to end `record`.
You send to Eurecom the file `record.raw`. The file `T_messages.txt` is not needed.
To get a list of options, run:
```shell
./record -h
```
The options `-ON`, `-OFF`, `-on` and `-off` are processed in order.
In the example above we first activate all the traces (`-ON`) and then
deactivate specific ones (more precisely, in this particular case:
the *groups* of traces `VCD`, `HEAVY`, `LEGACY_GROUP_TRACE` and
`LEGACY_GROUP_DEBUG`).
You can then [replay](T/replay) the recorded file or send it to others so they
can analyse things.

39
T/replay.md

@@ -1,39 +0,0 @@
# Replay
First, read the [basic usage](T/basic) to compile things.
Then, read [record](T/record) to know how to record a trace.
To replay, you use the `replay` program. It will act
as a *tracee* (`lte-softmodem`, `oaisim`, etc.).
Then you use your usual tracer, eg. `enb` or `textlog`.
Since the T is constantly evolving you may need to extract
`T_messages.txt` contained in a trace to be able to process
the trace.
## Example
Download [example.raw](example.raw). This example contains:
* MAC PDUs as sent and received by the eNodeB
* RRC info messages the eNodeB produced.
First step is to extract `T_messages.txt` from this trace.
```shell
./extract_config -i example.raw > extracted_T_messages.txt
```
Then you use `replay` to act as a regular *tracee*:
```shell
./replay -i example.raw
```
And then, while `replay` is still running, you use the tracer
you want, for example the `textlog` tracer:
```shell
./textlog -d extracted_T_messages.txt -no-gui -ON -full
```

21
T/to_vcd.md

@@ -1,21 +0,0 @@
# to_vcd
This tracer is used to dump a VCD trace of the softmodem.
The basic usage is:
```shell
cd common/utils/T/tracer
./to_vcd -d ../T_messages.txt -vcd -o /tmp/openair_dump_eNB.vcd
```
Apart from VCD specific traces, you can dump to VCD other T traces.
Use `-b` and `-l` options. For example, to only log DLSCH scheduler VCD traces, use:
```shell
./to_vcd -d ../T_messages.txt -o /tmp/openair_dump_eNB.vcd -b VCD_FUNCTION_SCHEDULE_DLSCH value mac_schedule_dlsch
```
For more help, run:
```shell
./to_vcd -h
```

158
T/wireshark.md

@@ -1,158 +0,0 @@
# MAC PDUs and wireshark
First, read the [basic usage](T/basic) to compile things.
It is possible to use `wireshark` to analyse MAC PDUs for UEs,
MIBs, SIBs, and random accesses seen by the eNodeB.
## Live usage
Launch wireshark and listen on the local interface (lo).
Set the filter to `udp.port==9999` and read below
for configuration.
Run the softmodem with the correct command line arguments
(see [basic usage](T/basic)).
Then run:
```shell
./macpdu2wireshark -d ../T_messages.txt -live
```
For other options of `macpdu2wireshark`, run:
```shell
./macpdu2wireshark -h
```
You can for example disable MIB and SIB logging, or log only
a given number of them.
## Record and replay
You need to record some specific traces. As of 2018-10-30
you have to use the group:
* `WIRESHARK`
That is, run:
```shell
./record -d ../T_messages.txt -o /tmp/record.raw -on WIRESHARK
```
With a recorded trace you then use `macpdu2wireshark`.
## Example
Download [example.raw](example.raw). This example contains
MIBs, SIBs and a connection made by an UE followed by its
disconnection.
First step is to extract `T_messages.txt` from this trace.
```shell
./extract_config -i example.raw > extracted_T_messages.txt
```
Then you run `wireshark`, capture on `lo` and set the
filter to `udp.dstport==9999`.
While `wireshark` is running, you do:
```shell
./macpdu2wireshark -d extracted_T_messages.txt -i example.raw -no-mib -no-sib
```
In `wireshark` you should see something similar to the following:
![wireshark window with dissected MAC PDUs](wireshark.png)
## Configure wireshark for LTE
To dissect the packets, you need to configure `wireshark`.
In the menu, choose `Edit->Preferences`.
In the preference window, unroll `Protocols`.
Go to `UDP` and activate `Try heuristic sub-dissectors first`.
Depending on your version of `wireshark`, you may need to go to `MAC-LTE`
and activate `Try Heuristic LTE-MAC over UDP framing` if this option
is present.
For newer versions (after 2.0 as says wireshark's documentation),
heuristic activation is moved to the `Enabled Protocols` window
(in the menu `Analyze`). In the `enabled protocols` window, search
for `lte` and select `mac_lte_udp` to have `MAC-LTE over UDP`.
You may also want to configure other parameters in `MAC-LTE`,
`RLC-LTE`, `PDCP-LTE`, and maybe others. Check the documentation
of `wireshark`.
It is advised to use a recent version of wireshark (say more than 2.4).
## Configure wireshark for NR
Use a recent version of wireshark. The steps below were done using
version 3.3.2. Maybe some options are different for your version
of wireshark. Adapt as necessary.
First, do the previous steps for LTE.
Then, in the menu, choose `Edit->Preferences`.
In the preference window, unroll `Protocols`.
Go to `MAC-NR`. Select both options (`Attempt to decode BCCH, PCCH and CCCH data using NR RRC dissector`
and `Attempt to dissect LCID 1-3 as srb1-3`).
For `Source of LCID -> drb channel settings` choose option `From static table`.
Then click the `Edit...` button of `LCID -> DRB Mappings Table`.
In the new window, click on `+`. Choose LCID `4`, DRBID `1`, UL RLC Bearer
Type `AM, SN Len=18`, same thing for DL RLC Bearer Type.
Then click OK.
Now, go to `RLC-NR`. Select `Call PDCP dissector for SRB PDUs`.
For `Call PDCP dissector for UL DRB PDUs` choose `18-bit SN`. Same
for DL.
Select `Call RRC dissector for CCCH PDUs`.
You don't need to select `May see RLC headers only` and
`Try to reassemble UM frames`.
Now, go to `PDCP-NR`. Select what you want in there. It's good
to select `Show uncompressed User-Plane data as IP`. Also good
to select `Show unciphered Signalling-Plane data as RRC`.
For `Do sequence number analysis` it can be good to use
`Only-RLC-frames` but anything will do. We don't use ROHC so you
don't need to select `Attempt to decode ROHC data`. And the
layer info to show depends on what you want to analyse.
`Traffic Info` is a good choice.
You are done with the preferences. You can click OK.
Then, in the menu `Analyze`, choose `Enabled Protocols...`. In the new window
search for `nr` and select `mac_nr_udp` to have `MAC-NR over UDP`.
And that's it. Maybe other settings can be changed, but those steps should be
enough for a start.
Note: not all versions of Wireshark correctly dissect encapsulated packets. For instance, we observed that Wireshark v3.4.8 did not call the PDCP dissector for a PDCP PDU split in two RLC SDUs. On the other hand, Wireshark v3.7.0 showed it just fine.
## Alternative to wireshark
While using `macpdu2wireshark` with the `-live` option, it is possible to use `tcpdump` instead of `wireshak` to record MAC PDUs and also other types of traffic (sctp, gtp) in the same output pcap file.
A "catch all" solution is to run:
```
sudo tcpdump -n -iany "udp port 9999 or udp port 2152 or sctp or port 38462 or port 38472 or port 38412 or port 2153" -w /tmp/rec.pcap
```
(This is an example, other solutions are also possible.)

BIN
T/wireshark.png

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 262 KiB