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 | |
Oliver Smith | b252b4a | 2022-02-25 12:36:53 +0100 | [diff] [blame] | 13 | * Open config_2g3g in a text editor (original config) |
| 14 | * Open a new file in a text editor (your config) |
| 15 | * Copy over all lines you want to change in your config and edit them there |
| 16 | * Your resulting minimal config could look like this: |
Neels Hofmeyr | 697a617 | 2018-08-22 17:32:21 +0200 | [diff] [blame] | 17 | |
Oliver Smith | b252b4a | 2022-02-25 12:36:53 +0100 | [diff] [blame] | 18 | TERMINAL="tmux" |
Neels Hofmeyr | 697a617 | 2018-08-22 17:32:21 +0200 | [diff] [blame] | 19 | |
Oliver Smith | b252b4a | 2022-02-25 12:36:53 +0100 | [diff] [blame] | 20 | ETH_DEV=enp0s25 |
Neels Hofmeyr | 697a617 | 2018-08-22 17:32:21 +0200 | [diff] [blame] | 21 | |
Oliver Smith | b252b4a | 2022-02-25 12:36:53 +0100 | [diff] [blame] | 22 | TO_RAN_IP="192.168.1.123" |
| 23 | TO_RAN_IU_IP="192.168.1.42" |
Neels Hofmeyr | 697a617 | 2018-08-22 17:32:21 +0200 | [diff] [blame] | 24 | |
Oliver Smith | b252b4a | 2022-02-25 12:36:53 +0100 | [diff] [blame] | 25 | MCC=999 |
| 26 | MNC=99 |
Neels Hofmeyr | 697a617 | 2018-08-22 17:32:21 +0200 | [diff] [blame] | 27 | |
Oliver Smith | b252b4a | 2022-02-25 12:36:53 +0100 | [diff] [blame] | 28 | BTS0_IPA_UNIT="1234 0" |
| 29 | BTS0_ARFCN=800 |
| 30 | |
| 31 | * Create a network directory and generate configs: |
| 32 | |
| 33 | $ mkdir my_network |
| 34 | $ cd my_network |
| 35 | $ ../fill_config.py ../config_mine ../templates |
| 36 | |
| 37 | * Run the network: |
| 38 | |
| 39 | $ ./run.sh |
| 40 | |
| 41 | This launches numerous terminals with one component running in each. |
| 42 | Logs and pcap traces are being taken automatically. |
| 43 | |
| 44 | * Tear down: |
| 45 | |
| 46 | Hit enter in the original first terminal to tear down all programs. |
| 47 | Enter a name to save logs, otherwise all logging will be stored |
| 48 | under autolog/<timestamp>. |
| 49 | |
| 50 | * Regenerate configs: |
| 51 | |
| 52 | Modify your config and regenerate the network configs as follows, the same |
| 53 | original config, your config and templates will be used as last time. |
| 54 | |
| 55 | $ $EDITOR ../config_mine |
| 56 | $ ../fill_config.py |
| 57 | |
| 58 | ('make regen' also works) |
| 59 | |
| 60 | |
| 61 | === Advanced usage / more examples |
Neels Hofmeyr | 697a617 | 2018-08-22 17:32:21 +0200 | [diff] [blame] | 62 | |
| 63 | # own templates? |
Neels Hofmeyr | cbdd718 | 2019-03-04 00:39:32 +0100 | [diff] [blame] | 64 | cp -r ../templates ../templates_mine |
| 65 | $EDITOR ../templates_mine/* |
| 66 | ../fill_config.py ../templates_mine |
| 67 | # picks up same ../config_mine from last time, and ../templates_mine from cmdline |
Neels Hofmeyr | 697a617 | 2018-08-22 17:32:21 +0200 | [diff] [blame] | 68 | |
| 69 | |
Neels Hofmeyr | 5a9bf17 | 2018-08-23 15:31:44 +0200 | [diff] [blame] | 70 | If you wanted to change to dynamic timeslots, you can: |
| 71 | |
| 72 | cd .. |
Neels Hofmeyr | cbdd718 | 2019-03-04 00:39:32 +0100 | [diff] [blame] | 73 | mkdir templates_dyn |
| 74 | cd templates_dyn |
| 75 | ln -s ../templates/* . |
Neels Hofmeyr | 5a9bf17 | 2018-08-23 15:31:44 +0200 | [diff] [blame] | 76 | rm ./osmo-bsc.cfg |
Neels Hofmeyr | cbdd718 | 2019-03-04 00:39:32 +0100 | [diff] [blame] | 77 | cp ../templates/osmo-bsc.cfg . |
Neels Hofmeyr | 5a9bf17 | 2018-08-23 15:31:44 +0200 | [diff] [blame] | 78 | sed -i 's#TCH/F#TCH/F_TCH/H_PDCH#' osmo-bsc.cfg |
| 79 | |
| 80 | cd ../my_network |
Neels Hofmeyr | cbdd718 | 2019-03-04 00:39:32 +0100 | [diff] [blame] | 81 | ../fill_config.py ../templates_dyn |
Neels Hofmeyr | 5a9bf17 | 2018-08-23 15:31:44 +0200 | [diff] [blame] | 82 | |
| 83 | |
| 84 | If you moved your laptop to a different location, you can: |
| 85 | |
| 86 | cp ../config_mine ../config_foo |
| 87 | $EDITOR ../config_foo # set new IP address(es) |
| 88 | ../fill_config.py ../config_foo |
| 89 | |
Neels Hofmeyr | 697a617 | 2018-08-22 17:32:21 +0200 | [diff] [blame] | 90 | |
| 91 | === Config file templates |
| 92 | |
| 93 | A *directory* contains template files that are filled with specific values by the |
Neels Hofmeyr | cbdd718 | 2019-03-04 00:39:32 +0100 | [diff] [blame] | 94 | fill_config.py script. See e.g. templates/. |
Neels Hofmeyr | 697a617 | 2018-08-22 17:32:21 +0200 | [diff] [blame] | 95 | |
Neels Hofmeyr | 5a9bf17 | 2018-08-23 15:31:44 +0200 | [diff] [blame] | 96 | A *file* contains local config items as name=val pairs that are put into the |
Oliver Smith | b252b4a | 2022-02-25 12:36:53 +0100 | [diff] [blame] | 97 | templates. It is usually a subset of config_2g3g. |
Neels Hofmeyr | 697a617 | 2018-08-22 17:32:21 +0200 | [diff] [blame] | 98 | |
Neels Hofmeyr | 57e4288 | 2018-08-23 15:19:35 +0200 | [diff] [blame] | 99 | The fill_config.py script helps to fill the templates with the config values. Simply |
| 100 | invoke fill_config.py with a dir argument (templates dir) and a file argument (specific |
Oliver Smith | fd7446f | 2018-10-22 11:59:55 +0200 | [diff] [blame] | 101 | config values). The dir argument can be used in the templates with ${NET_DIR}, |
| 102 | temporary files (sockets etc.) should be placed inside this folder. |
Neels Hofmeyr | 697a617 | 2018-08-22 17:32:21 +0200 | [diff] [blame] | 103 | |
| 104 | If one or both are omitted, the script tries to re-use the most recent paths, |
| 105 | they were stored in local files '.last_config' and '.last_templates'. |
| 106 | |
Oliver Smith | b252b4a | 2022-02-25 12:36:53 +0100 | [diff] [blame] | 107 | The -o parameter of fill_config.py can be used to supply a different original |
| 108 | config file than config_2g3g. If it is omitted, the path is read from a |
| 109 | '.last_config_orig' file inside the network directory if present, and config_2g3g |
| 110 | is used otherwise. |
| 111 | |
Neels Hofmeyr | 697a617 | 2018-08-22 17:32:21 +0200 | [diff] [blame] | 112 | The result is a complete set of .cfg files that match your local machine and |
| 113 | network config. |
| 114 | |
| 115 | |
| 116 | === Launch |
| 117 | |
Neels Hofmeyr | cbdd718 | 2019-03-04 00:39:32 +0100 | [diff] [blame] | 118 | A run.sh script template (templates/run.sh) also gets filled with specifics and |
Neels Hofmeyr | 697a617 | 2018-08-22 17:32:21 +0200 | [diff] [blame] | 119 | placed next to the .cfg files. |
| 120 | |
| 121 | run.sh uses sudo to start tcpdump, configure ip forwarding and masquerading |
| 122 | (for the GGSN's APN tunnel required for data services). |
| 123 | |
| 124 | When you launch run.sh, many xterms are launched, and when hitting enter, all |
| 125 | of them get destroyed again. This is obviously intended to be run on your |
Oliver Smith | b2a83f7 | 2022-02-25 12:49:17 +0100 | [diff] [blame] | 126 | desktop computer or laptop, not on a remote box. |
| 127 | |
| 128 | It's also possible to set TERMINAL="tmux" in your network configuration, then |
| 129 | run.sh starts a tmux session and runs each Osmocom program as own tmux window |
| 130 | inside that session. Switch to the first window (^B + 0) and hit enter to close |
| 131 | all windows and the whole tmux session. This does work over SSH. |
Neels Hofmeyr | 697a617 | 2018-08-22 17:32:21 +0200 | [diff] [blame] | 132 | |
| 133 | |
| 134 | === Logging and pcaps |
| 135 | |
| 136 | The run.sh script automatically stores all configs, logs and pcap traces in |
| 137 | ./autolog/<timestamp> dirs. After closing the components (by hitting enter), |
| 138 | you may also enter a name for the logs, after which they are stored in |
| 139 | ./logs/<name>. The idea is to keep all important logs with a name, and that you |
| 140 | can every now and then just 'rm -rf ./autolog' to make space. |
| 141 | |
| 142 | |
| 143 | === 3G |
| 144 | |
| 145 | You may notice that the templates include nano3G.txt files. These include a |
| 146 | convenient listing of commands to connect to an ip.access nano3G DMI and |
| 147 | connect it to the HNBGW as configured by the templates. |
| 148 | |
| 149 | |
| 150 | === 2G BTS |
| 151 | |
Oliver Smith | 321a47c | 2022-02-21 16:25:37 +0100 | [diff] [blame] | 152 | You can either let osmo-dev run osmo-bts-virtual, or connect a real BTS to the |
| 153 | BSC + CN started by osmo-dev. |
Neels Hofmeyr | 697a617 | 2018-08-22 17:32:21 +0200 | [diff] [blame] | 154 | |
Oliver Smith | 321a47c | 2022-02-21 16:25:37 +0100 | [diff] [blame] | 155 | To start osmo-bts-virtual, set BTS0_RUN_IN_OSMO_DEV=1 and/or |
| 156 | BTS1_RUN_IN_OSMO_DEV=1 in your copy of config_2g3g. |
| 157 | |
| 158 | To connect your real BTS, typically you'd need to edit only the |
| 159 | /etc/osmocom/osmo-bts.cfg to match your IP address and ipa unit-id: |
Neels Hofmeyr | 697a617 | 2018-08-22 17:32:21 +0200 | [diff] [blame] | 160 | |
| 161 | bts 0 |
Neels Hofmeyr | 5a9bf17 | 2018-08-23 15:31:44 +0200 | [diff] [blame] | 162 | oml remote-ip 192.168.0.23 |
| 163 | ipa unit-id 1234 0 |