mirror of https://gerrit.osmocom.org/osmo-dev
189 lines
6.0 KiB
Plaintext
189 lines
6.0 KiB
Plaintext
=== WHAT IS THIS?
|
|
|
|
* quickly configure, launch and tear down an entire Osmocom core network on
|
|
your box (see net/README).
|
|
|
|
This is the set of tools I wrote for myself and use every day to run and test
|
|
the Osmocom core network. I hope this helps, and I would appreciate
|
|
contributions of any improvements you may have!
|
|
|
|
|
|
=== Quick Start
|
|
|
|
* Open config_2g3g in a text editor (original config)
|
|
* Open a new file in a text editor (your config)
|
|
* Copy over all lines you want to change in your config and edit them there
|
|
* Your resulting minimal config could look like this:
|
|
|
|
TERMINAL="tmux"
|
|
|
|
ETH_DEV=enp0s25
|
|
|
|
TO_RAN_IP="192.168.1.123"
|
|
TO_RAN_IU_IP="192.168.1.42"
|
|
|
|
MCC=999
|
|
MNC=99
|
|
|
|
BTS0_IPA_UNIT="1234 0"
|
|
BTS0_ARFCN=800
|
|
|
|
* Create a network directory and generate configs:
|
|
|
|
$ mkdir my_network
|
|
$ cd my_network
|
|
$ ../fill_config.py ../config_mine ../templates
|
|
|
|
* Run the network:
|
|
|
|
$ ./run.sh
|
|
|
|
This launches numerous terminals with one component running in each.
|
|
Logs and pcap traces are being taken automatically.
|
|
|
|
* Tear down:
|
|
|
|
Hit enter in the original first terminal to tear down all programs.
|
|
Enter a name to save logs, otherwise all logging will be stored
|
|
under autolog/<timestamp>.
|
|
|
|
* Regenerate configs:
|
|
|
|
Modify your config and regenerate the network configs as follows, the same
|
|
original config, your config and templates will be used as last time.
|
|
|
|
$ $EDITOR ../config_mine
|
|
$ ../fill_config.py
|
|
|
|
('make regen' also works)
|
|
|
|
|
|
=== Advanced usage / more examples
|
|
|
|
# own templates?
|
|
cp -r ../templates ../templates_mine
|
|
$EDITOR ../templates_mine/*
|
|
../fill_config.py ../templates_mine
|
|
# picks up same ../config_mine from last time, and ../templates_mine from cmdline
|
|
|
|
|
|
If you wanted to change to dynamic timeslots, you can:
|
|
|
|
cd ..
|
|
mkdir templates_dyn
|
|
cd templates_dyn
|
|
ln -s ../templates/* .
|
|
rm ./osmo-bsc.cfg
|
|
cp ../templates/osmo-bsc.cfg .
|
|
sed -i 's#TCH/F#TCH/F_TCH/H_PDCH#' osmo-bsc.cfg
|
|
|
|
cd ../my_network
|
|
../fill_config.py ../templates_dyn
|
|
|
|
|
|
If you moved your laptop to a different location, you can:
|
|
|
|
cp ../config_mine ../config_foo
|
|
$EDITOR ../config_foo # set new IP address(es)
|
|
../fill_config.py ../config_foo
|
|
|
|
|
|
=== Config file templates
|
|
|
|
A *directory* contains template files that are filled with specific values by the
|
|
fill_config.py script. See e.g. templates/.
|
|
|
|
A *file* contains local config items as name=val pairs that are put into the
|
|
templates. It is usually a subset of config_2g3g.
|
|
|
|
The fill_config.py script helps to fill the templates with the config values. Simply
|
|
invoke fill_config.py with a dir argument (templates dir) and a file argument (specific
|
|
config values). The dir argument can be used in the templates with ${NET_DIR},
|
|
temporary files (sockets etc.) should be placed inside this folder.
|
|
|
|
If one or both are omitted, the script tries to re-use the most recent paths,
|
|
they were stored in local files '.last_config' and '.last_templates'.
|
|
|
|
The -o parameter of fill_config.py can be used to supply a different original
|
|
config file than config_2g3g. If it is omitted, the path is read from a
|
|
'.last_config_orig' file inside the network directory if present, and config_2g3g
|
|
is used otherwise.
|
|
|
|
The result is a complete set of .cfg files that match your local machine and
|
|
network config.
|
|
|
|
|
|
=== Launch
|
|
|
|
A run.sh script template (templates/run.sh) also gets filled with specifics and
|
|
placed next to the .cfg files.
|
|
|
|
run.sh uses sudo to start tcpdump, configure ip forwarding and masquerading
|
|
(for the GGSN's APN tunnel required for data services).
|
|
|
|
When you launch run.sh, many xterms are launched, and when hitting enter, all
|
|
of them get destroyed again. This is obviously intended to be run on your
|
|
desktop computer or laptop, not on a remote box.
|
|
|
|
It's also possible to set TERMINAL="tmux" in your network configuration, then
|
|
run.sh starts a tmux session and runs each Osmocom program as own tmux window
|
|
inside that session. Switch to the first window (^B + 0) and hit enter to close
|
|
all windows and the whole tmux session. This does work over SSH.
|
|
|
|
|
|
=== Wrap commands in gdb, valgrind, udtrace etc.
|
|
|
|
During development it's useful to wrap Osmocom programs inside gdb, valgrind or
|
|
other tools. For each program where you want to do this, copy the CMD_ line
|
|
from config_2g3g to your config and adjust it accordingly.
|
|
|
|
==== Examples: gdb, valgrind, strace
|
|
|
|
CMD_MSC="LD_LIBRARY_PATH=/usr/local/lib gdb -ex run --args osmo-msc"
|
|
CMD_MSC="valgrind osmo-msc"
|
|
CMD_MSC="strace osmo-msc"
|
|
|
|
==== Example: udtrace
|
|
|
|
To use udtrace on the MNCC socket, use the following with an adjusted
|
|
/path/to/udtrace. Explanation of the enviornment variables:
|
|
- LD_LIBRARY_PATH allows linking to titan if udtrace was compiled with titan
|
|
support
|
|
- LD_PRELOAD of libasan allows building osmo-msc with the sanitize.opts
|
|
- the tee saves the stderr logging as well as the udtrace output to new file
|
|
current_log/osmo-msc.out, since udtrace will not show in osmo-msc.log
|
|
|
|
CMD_MSC="LD_LIBRARY_PATH=/usr/lib/titan LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libasan.so.5:/path/to/udtrace/libudtrace.so osmo-msc 2>&1 | tee -a current_log/osmo-msc.out"
|
|
|
|
|
|
=== Logging and pcaps
|
|
|
|
The run.sh script automatically stores all configs, logs and pcap traces in
|
|
./autolog/<timestamp> dirs. After closing the components (by hitting enter),
|
|
you may also enter a name for the logs, after which they are stored in
|
|
./logs/<name>. The idea is to keep all important logs with a name, and that you
|
|
can every now and then just 'rm -rf ./autolog' to make space.
|
|
|
|
|
|
=== 3G
|
|
|
|
You may notice that the templates include nano3G.txt files. These include a
|
|
convenient listing of commands to connect to an ip.access nano3G DMI and
|
|
connect it to the HNBGW as configured by the templates.
|
|
|
|
|
|
=== 2G BTS
|
|
|
|
You can either let osmo-dev run osmo-bts-virtual, or connect a real BTS to the
|
|
BSC + CN started by osmo-dev.
|
|
|
|
To start osmo-bts-virtual, set BTS0_RUN_IN_OSMO_DEV=1 and/or
|
|
BTS1_RUN_IN_OSMO_DEV=1 in your copy of config_2g3g.
|
|
|
|
To connect your real BTS, typically you'd need to edit only the
|
|
/etc/osmocom/osmo-bts.cfg to match your IP address and ipa unit-id:
|
|
|
|
bts 0
|
|
oml remote-ip 192.168.0.23
|
|
ipa unit-id 1234 0
|