Neels Hofmeyr | 697a617 | 2018-08-22 17:32:21 +0200 | [diff] [blame^] | 1 | === WHAT IS THIS? |
| 2 | |
| 3 | * quickly configure, launch and tear down an entire Osmocom core network on |
| 4 | your box (see net/README). |
| 5 | |
| 6 | This is the set of tools I wrote for myself and use every day to run and test |
| 7 | the Osmocom core network. I hope this helps, and I would appreciate |
| 8 | contributions of any improvements you may have! |
| 9 | |
| 10 | |
| 11 | === Quick Start |
| 12 | |
| 13 | cp config_2g3g config_mine |
| 14 | $EDITOR config_mine |
| 15 | # update IP addresses and device names as required |
| 16 | |
| 17 | mkdir my_network |
| 18 | cd my_network |
| 19 | ../cfg.sh ../config_mine ../tmpl_std |
| 20 | |
| 21 | ./run.sh |
| 22 | # Launches numerous x-terminals with one component running in each. |
| 23 | # Logs and pcap traces are being taken automatically. |
| 24 | |
| 25 | # hit enter in the original first terminal to tear down all programs. |
| 26 | # Enter a name to save logs, otherwise all logging will be stored |
| 27 | # under autolog/<timestamp> |
| 28 | |
| 29 | Then possibly modify the config and refresh: |
| 30 | |
| 31 | # tweak config? |
| 32 | $EDITOR ../config_mine |
| 33 | ../cfg.sh |
| 34 | # picks up same ../config_mine and ../tmpl_std from last time |
| 35 | |
| 36 | # own templates? |
| 37 | cp -r ../tmpl_std ../tmpl_mine |
| 38 | $EDITOR ../tmpl_mine/* |
| 39 | ../cfg.sh ../tmpl_mine |
| 40 | # picks up same ../config_mine from last time, and ../tmpl_mine from cmdline |
| 41 | |
| 42 | |
| 43 | |
| 44 | === Config file templates |
| 45 | |
| 46 | A *directory* contains template files that are filled with specific values by the |
| 47 | cfg.sh script (aided by fill_config.py). See e.g. tmpl_std/. |
| 48 | |
| 49 | A *file* contains local config items that are put into the templates. See e.g. |
| 50 | config_2g3g. |
| 51 | |
| 52 | The cfg.sh script helps to fill the templates with the config values. Simply |
| 53 | invoke cfg.sh with a dir argument (templates dir) and a file argument (specific |
| 54 | config values). |
| 55 | |
| 56 | If one or both are omitted, the script tries to re-use the most recent paths, |
| 57 | they were stored in local files '.last_config' and '.last_templates'. |
| 58 | |
| 59 | The result is a complete set of .cfg files that match your local machine and |
| 60 | network config. |
| 61 | |
| 62 | |
| 63 | === Launch |
| 64 | |
| 65 | A run.sh script template (tmpl_std/run.sh) also gets filled with specifics and |
| 66 | placed next to the .cfg files. |
| 67 | |
| 68 | run.sh uses sudo to start tcpdump, configure ip forwarding and masquerading |
| 69 | (for the GGSN's APN tunnel required for data services). |
| 70 | |
| 71 | When you launch run.sh, many xterms are launched, and when hitting enter, all |
| 72 | of them get destroyed again. This is obviously intended to be run on your |
| 73 | desktop computer or laptop, not on a remote box. It may also make sense to |
| 74 | launch all of them in the current shell, and maybe or maybe not switch off |
| 75 | stderr logging; or to launch each component in a tmux window or whatnot -- if |
| 76 | you figure out something in that line, I would be glad to get contributions and |
| 77 | incorporate that. |
| 78 | |
| 79 | |
| 80 | === Logging and pcaps |
| 81 | |
| 82 | The run.sh script automatically stores all configs, logs and pcap traces in |
| 83 | ./autolog/<timestamp> dirs. After closing the components (by hitting enter), |
| 84 | you may also enter a name for the logs, after which they are stored in |
| 85 | ./logs/<name>. The idea is to keep all important logs with a name, and that you |
| 86 | can every now and then just 'rm -rf ./autolog' to make space. |
| 87 | |
| 88 | |
| 89 | === 3G |
| 90 | |
| 91 | You may notice that the templates include nano3G.txt files. These include a |
| 92 | convenient listing of commands to connect to an ip.access nano3G DMI and |
| 93 | connect it to the HNBGW as configured by the templates. |
| 94 | |
| 95 | |
| 96 | === 2G BTS |
| 97 | |
| 98 | At the time of writing, there are no osmo-bts.cfg files, since this is intended |
| 99 | for the core network and BSC components only. Feel free to add! |
| 100 | |
| 101 | Typically you'd need to edit only the /etc/osmocom/osmo-bts.cfg to match your |
| 102 | IP address and ipa unit-id: |
| 103 | |
| 104 | bts 0 |
| 105 | oml remote-ip 192.168.0.123 |
| 106 | ipa unit-id 1800 0 |