modify.md 6.72 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
# 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:

29
    sudo /local/repository/bin/enb.kill.sh
30 31 32

Run this on the `epc` node:

33 34 35
    sudo /local/repository/bin/mme.kill.sh
    sudo /local/repository/bin/hss.kill.sh
    sudo /local/repository/bin/spgw.kill.sh
36 37 38 39 40 41 42 43 44 45 46 47 48 49

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:

50 51
    cd /opt/oai/openairinterface5g
    git log
52 53 54 55 56 57 58

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:

59 60
    cd /opt/oai/openairinterface5g/cmake_targets
    sudo ./build_oai --eNB -w USRP
61 62 63 64 65 66 67 68 69 70 71 72

### 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:

73 74
    cd /opt/oai/openair-cn/SCRIPTS
    sudo ./build_mme
75 76 77

To build the HSS from source:

78 79
    cd /opt/oai/openair-cn/SCRIPTS
    sudo ./build_hss
80 81

To build the SPGW from source:
82 83 84

    cd /opt/oai/openair-cn/SCRIPTS
    sudo ./build_spgw
85 86 87 88 89 90 91 92 93 94


### 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:

95
    sudo /local/repository/bin/config_oai.pl -r EPC
96 97 98

On the `enb` node:

99
    sudo /local/repository/bin/config_oai.pl -r ENB
100 101 102 103 104 105 106

### 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.

107 108 109
    cd /opt/oai/openair-cn
    git remote add myrepo url-or-ssh-path-to-my-repo
    git push myrepo
110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186

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)