Commit bc0d5d1a authored by Jonathon Duerig's avatar Jonathon Duerig

Add documentation for the profile.

parent fb700396
# Getting started
Be sure to setup your SSH keys as outlined in the manual; it's better
to log in via a real SSH client to the nodes in your experiment.
The Open Air Interface source is located under `/opt/oai` on the enb1
and epc nodes. It is mounted as a clone of a remote blockstore
(dataset) maintained by PhantomNet. Feel free to change anything in
here, but be aware that your changes will not persist when your
experiment terminates.
To access the UE via ADB, first log in to the `adb-tgt` node, then run
`pnadb -a` to connect to the UE. Use ADB commands as per normal
afterward. If/when you reboot the UE, be aware that you will need to
again run `pnadb -a` to reestablish the ADB connection; wait a minute
or so for the UE to become available again before doing this.
The OAI mobile networking functions should automatically start up when
your experiment starts up. You can pull up and monitor the OAI
processes on the `epc` and `enb1` nodes. Execute `sudo screen -ls` to
see what sessions are available. The commands for controlling services
on these nodes are located in `/local/repository/bin`.
For more detailed information, see control.md, inspect.md, and modify.md.
# Controlling Your Experiment
The UE and all of the OAI services can be controlled from the command
line by logging into the appropriate nodes. In addition, all nodes in
the experiment can be rebooted or reloaded (reload means loading a
fresh disk image wiping out any changes) from the portal
interface. After any reboot, all services will automatically start and
the UE should attach and connect to provide end-to-end connectivity.
## UE Control
Log into the `adb-tgt` node on your experiment. This node links to the
UE via an adb proxy with this command:
pnadb -a
Sometimes just after rebooting this command will fail to connect. If
so, try running it again after a few minutes. If it persists, you can
reboot or reload (reload means loading a fresh disk image) the UE and
try connecting again once it is complete.
You can log into the UE using adb:
adb shell
From there, you can manipulate or run any system on the phone. To see
if there is end to end connectivity, try `ping 8.8.8.8` for example.
The adb node can be rebooted from the command line with:
adb reboot
Any other adb command can be run as well.
## eNodeB Control
The startup script on the `enb1` node always waits for the EPC node
and then starts the enb service when booting. You can start the enb
service by hand by running:
sudo /local/repository/bin/enb.start.sh
Or you can kill a running enb service with:
sudo /local/repository/bin/enb.kill.sh
The enb service should be started last because if it doesn't detect an
mme when it starts, it will never connect.
## EPC Control
The startup script on the `epc` boots up the hss, mme, and spgw
services. After all three of these are started, it syncronises with
the startup script on the `enb1`. To manually start any of these
services, run one of these scripts on the `epc` node:
sudo /local/repository/bin/hss.start.sh
sudo /local/repository/bin/mme.start.sh
sudo /local/repository/bin/spgw.start.sh
When starting them all by hand, make sure to start them in that order.
To kill these scripts, just run one of these on the `epc` node:
sudo /local/repository/bin/hss.kill.sh
sudo /local/repository/bin/mme.kill.sh
sudo /local/repository/bin/spgw.kill.sh
## Restarting without rebooting
If you want to restart all the services but don't want to reboot the
nodes themselves, you can first kill all services, then on the `enb1`
node, run:
sudo /local/repository/bin/config_oai.pl -r ENB
And on the `epc` node, run:
sudo /local/repository/bin/config_oai.pl -r EPC
## Tweaking Configuration
The source templates for the configuration files are at
`/local/repository/etc/*.conf`. These are used only once when the
experiment boots for the first time. They in turn generate the
configuration files which are located at `/usr/local/etc/oai/*.conf`
on both the `epc` and `enb1` nodes. The generated configuration files
can be modified, but those changes will be lost if the node is
reloaded, the experiment ends, or you force them to be regenerated
from the templates.
To change configuration permanently, you will want to fork the
repository for this profile, make a copy of it, and change the
configuration files in your forked repo.
# Inspecting Your Experiment
There are a lot of moving parts in an OAI system. In order to see them
all going at once, it is best to have multiple vantage points into the
system.
## Inspecting the UE
The UE is a Nexus 5 running a vanilla Android. Currently, you are able
to interact and inspect the UE using adb from the `adb-tgt` node. Once
you log into the `adb-tgt` node, you first need to make sure that the
adb is connected to the UE through our proxy.
pnadb -a
Sometimes just after rebooting this command will fail to connect. If
so, try running it again after a few minutes. If it persists, you can
reboot or reload (reload means loading a fresh disk image) the UE and
try connecting again once it is complete.
Once connected through the proxy, almost any adb command will
work. You can log into the UE with:
adb shell
You can inspect its device logs as well. Most usefully, you can see its radio log:
adb logcat -b radio
## Startup Scripts
The startup script at `/local/repository/config_oai.pl` runs on both
the `epc` and `enb1` nodes. In both cases, it logs its progress to
`/var/log/oai/startup.log`. You can see there what it is doing and
whether it has started up the services.
## Inspecting the eNodeB
The eNodeB is an Intel NUC connected to a USRP software-defined
radio. To learn more about it, log into the `enb1` node. The eNodeB
service is attached to a `screen` and also clones its output to a log
in `/var/log/oai/enb.log`.
To view the live output via screen, run:
sudo screen -r enb
To detach from the screen without stopping the program, type `Ctrl-a d`.
You can find out more about using screen with `man screen`.
Since the eNodeB is development software that is still under
production, there are still a lot of cases where it might abort on an
error instead of handling it gracefully. If this happens, the screen
will go away, but the log file persists so you can investigate the
cause. And you can restart the service by hand with:
sudo /lcoal/repository/bin/enb.start.sh
## Inspecting the EPC
The EPC works in much the same way as the eNodeB. The MME, HSS, and
SPGW services all run on the `epc` node. These services log to:
/var/log/oai/mme.log
/var/log/oai/hss.log
/var/log/oai/spgw.log
And they all have screen sessions as well that can be found at:
sudo screen -r mme
sudo screen -r hss
sudo screen -r spgw
In particular, by default the MME logs a status message every few
seconds which indicates if there is a connected eNodeB, attached UE,
or connected UE.
## Debugging the system
As a system under development, OAI is not always stable.
It is likely that there will be errors that crop up either on the RAN
side or at the EPC. When an error happens on the RAN side, the eNodeB
will flag it to its log file and send a `UE Context Release` message
to the MME.
In the current version, the MME will often respond by setting the UE
to an idle state from which it never comes up. You can see this by
looking at the MME logs and seeing that it lists the UE as attached
but not connected.
If you see this happen, rebooting the associated nodes or restarting
the services should allow the UE to reconnect.
## Capturing Traffic
The control traffic for OAI can be captured with tcpdump on the proper
interfaces. For example, if you log into the `enb1` node, you can look
at the configuration file for the enb service at
`/usr/local/etc/oai/enb.conf`. There, you will find that the
`mme_ip_address` is likely set to something like `10.10.4.2`. Then by
running `ifconfig`, you can find the vlan interface on that same
subnet. And now you can run something like:
sudo tcpdump -i vlan123
This will let you see the traffic as it flows or you can redirect the
output to a file and run wireshark or other analysis software on it.
## HSS Database
The HSS has a database which is used as a persistent store for things
like valid IMSI values for UEs. This database is pre-populated with
the IMSI of your UE when the experiment begins.
Look in `/usr/local/etc/oai/hss.conf` to see the database
parameters. You can then log into the database to see or change the
persistent state of the HSS:
mysql --user=root --password=linux oai_db
# Modifying Your Experiment
This profile is meant to be a jumping-off point for creating your own
experiments. As such, you have access to the source code for OAI
itself, the ability to modify and recompile it, and you can even
create your own profiles by cloning this repository.
## Source Code
The source code for OAI is located in `/opt/oai` on both the `enb1`
and `epc` nodes. This source code is a snapshot of the [official
repositories](https://gitlab.eurecom.fr/oai).
The `/opt/oai` directory is a mounted blockstore which acts as a local
clone. It is both readable and writeable, but the changes you make
won't persist when your experiment is gone.
### Before Building
When building, installation will fail if the associated service is
still running. In addition, OAI is still a work in progress and is
therefore somewhat fragile when the services don't start up in the
right order. For these reasons, it is usually best to kill all
services before building from source and then restart them in the
correct order afterwards.
Run this on the `enb1` node:
sudo /local/repository/bin/enb.kill.sh
Run this on the `epc` node:
sudo /local/repository/bin/mme.kill.sh
sudo /local/repository/bin/hss.kill.sh
sudo /local/repository/bin/spgw.kill.sh
After these steps, rebuild whichever services you have modified as described below.
### Building the eNodeB
The official repository for the eNodeB source code is
[here](https://gitlab.eurecom.fr/oai/openairinterface5g) along with
[build
documentation](https://gitlab.eurecom.fr/oai/openairinterface5g). A
snapshot of that repository can be found on the `enb1` node in your
experiment located at `/opt/oai/openairinterface5g`.
You can see exactly which commit this blockstore was forked from:
cd /opt/oai/openairinterface5g
git log
Aside from a minor patch which slimmed down the build dependencies,
this is a snapshot of the development branch of the repository.
If you would like to rebuild the source after making some
modification, first kill the enodeb service:
cd /opt/oai/openairinterface5g/cmake_targets
sudo ./build_oai --eNB -w USRP
### Building the MME, HSS, or SPGW
The core network services have a separate
[repository](https://gitlab.eurecom.fr/oai/openair-cn) and are built
using a slightly different
[procedure](https://gitlab.eurecom.fr/oai/openairinterface5g/wikis/AutoBuild#building-the-epc-modules-newer-version-latest-developmaster-branch). The
snapshot for this repository is located on the `epc` node in your
experiment in the `/opt/oai/openair-cn` directory.
To build the MME from source:
cd /opt/oai/openair-cn/SCRIPTS
sudo ./build_mme
To build the HSS from source:
cd /opt/oai/openair-cn/SCRIPTS
sudo ./build_hss
To build the SPGW from source:
cd /opt/oai/openair-cn/SCRIPTS
sudo ./build_spgw
### Restarting After Rebuilding
You can re-run the startup script on both `enb1` and `epc` nodes. This
will start all services again and syncronize their startups to ensure
the start in the proper order.
On the `epc` node:
sudo /local/repository/bin/config_oai.pl -r EPC
On the `enb` node:
sudo /local/repository/bin/config_oai.pl -r ENB
### Saving Source Code Changes Permanently
In order to save changes permanently, you will need an external git
repository. Then add it as a remote in `/opt/oai/openair-cn` or
`/opt/oai/openairinterface5g` and push up your changes.
cd /opt/oai/openair-cn
git remote add myrepo url-or-ssh-path-to-my-repo
git push myrepo
Then on later experiments you can add your experiment as a remote,
pull, and rebuild.
## Modifying This Profile
This profile is itself in a git repository. Whenever an experiment is
instantiated, that repository is cloned to `/local/repository`. You
can make your own clone of the repository, modify either the resource
allocation geni-lib script or any of the startup or utility scripts,
and create a new profile based on your cloned repository.
### Resource Allocation
The resource allocation script is in `/local/repository/profile.py`
and this Python script is run before the experiment begins to specify the
resources that will be used for the experiment. You could modify it to
add other compute nodes, other radios, or change what scripts are run
at startup.
The geni-lib libraries that are used to build up this resource
specification are described in our
[documentation](http://docs.powderwireless.net/geni-lib.html). Modifying
`profile.py` after an experiment begins won't change the allocated
resources of that experiment.
### Startup Scripts
In `profile.py`, a startup script is specified for the `enb1` and
`epc` nodes. That script is located in
`/local/repository/bin/config_oai.pl`. This script is executed (with
`/the parameters specified in `profile.py`) at experiment startup and
`/every time the experiment boots.
The first time `config_oai.pl` runs, it uses the configuration
templates in `/local/repository/etc/*` to generate configuration files
for all of the OAI services. Then it touches
`/var/emulab/boot/OAI_CONFIG_DONE` so that it won't regenerate those
files on future run-throughs. If you want to regenerate the
configuration files on `enb1` or `epc`, remove
`/var/emulab/boot/OAI_CONFIG_DONE` and rerun `config_oai.pl`.
After generating the configuration files, `config_oai.pl` starts up
all the services in a synchronized way. The instance running on the
`epc` node starts up the MME, HSS, and SPGW and then waits. And the
instance running on the `enb1` node waits until all the other services
are started before beginning the eNodeB. If one is run without the
other, it will wait forever. The `config_oai.pl` script logs its
output to `/var/log/oai/startup.log` in addition to printing it to
standard out.
### Service Scripts
The other scripts in `/local/repository/bin` provide a way to manage
each individual service by hand. They can start or stop any of the OAI
services. There is no synchronization here. Each one of them sets up a
screen session, and also clones their output to log files into a file
in `/var/log/oai`.
### Creating a Profile
While any of these scripts can be modified, the changes won't persist
unless you create your own profile. Go to the portal, select this
profile, and click 'copy'.
A pop-up box will tell you the URL of this repository and you will
need to use that URL to fork this repository using gitlab or github or
some other git hosting service.
Once you have forked the repository, you can paste the URL for the new
repository and then your new profile will point at your new
repository. In order to have the new profile automatically track
changes to the forked repository, you will need to set up a push hook
on the fork.
[Full Documentation on Repository-Based Profiles](http://docs.powderwireless.net/creating-profiles.html#%28part._repo-based-profiles%29)
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment