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