net/README

=== 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