Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 1 | == Configuration |
| 2 | |
Neels Hofmeyr | b52df17 | 2017-05-14 20:09:35 +0200 | [diff] [blame] | 3 | [[config_paths]] |
| 4 | === Config Paths |
| 5 | |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 6 | The osmo-gsm-tester looks for configuration files in various standard |
| 7 | directories in this order: |
| 8 | |
| 9 | - '$HOME/.config/osmo-gsm-tester/' |
| 10 | - '/usr/local/etc/osmo-gsm-tester/' |
| 11 | - '/etc/osmo-gsm-tester/' |
| 12 | |
| 13 | The config location can also be set by an environment variable |
| 14 | '$OSMO_GSM_TESTER_CONF', which then overrides the above locations. |
| 15 | |
| 16 | The osmo-gsm-tester expects to find the following configuration files in a |
| 17 | configuration directory: |
| 18 | |
| 19 | - 'paths.conf' |
| 20 | - 'resources.conf' |
| 21 | - 'default-suites.conf' (optional) |
| 22 | - 'defaults.conf' (optional) |
| 23 | |
Neels Hofmeyr | b52df17 | 2017-05-14 20:09:35 +0200 | [diff] [blame] | 24 | These are described in detail in the following sections. |
| 25 | |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 26 | === Format: YAML, and its Drawbacks |
| 27 | |
| 28 | The general configuration format used is YAML. The stock python YAML parser |
| 29 | does have several drawbacks: too many complex possibilities and alternative |
| 30 | ways of formatting a configuration, but at the time of writing seems to be the |
| 31 | only widely used configuration format that offers a simple and human readable |
| 32 | formatting as well as nested structuring. It is recommended to use only the |
| 33 | exact YAML subset seen in this manual in case the osmo-gsm-tester should move |
| 34 | to a less bloated parser in the future. |
| 35 | |
| 36 | Careful: if a configuration item consists of digits and starts with a zero, you |
| 37 | need to quote it, or it may be interpreted as an octal notation integer! Please |
| 38 | avoid using the octal notation on purpose, it is not provided intentionally. |
| 39 | |
| 40 | [[paths_conf]] |
| 41 | === 'paths.conf' |
| 42 | |
| 43 | The 'paths.conf' file defines where to store the global state (of reserved |
| 44 | resources) and where to find suite and scenario definitions. |
| 45 | |
| 46 | Any relative paths found in a 'paths.conf' file are interpreted as relative to |
| 47 | the directory of that 'paths.conf' file. |
| 48 | |
| 49 | Example: |
| 50 | |
| 51 | ---- |
Neels Hofmeyr | b52df17 | 2017-05-14 20:09:35 +0200 | [diff] [blame] | 52 | state_dir: '/var/tmp/osmo-gsm-tester/state' |
| 53 | suites_dir: '/usr/local/src/osmo-gsm-tester/suites' |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 54 | scenarios_dir: './scenarios' |
| 55 | ---- |
| 56 | |
Pau Espin Pedrol | 21f2b8f | 2017-11-02 17:57:58 +0100 | [diff] [blame] | 57 | [[state_dir]] |
| 58 | ==== 'state_dir' |
| 59 | |
| 60 | It contains global or system-wide state for osmo-gsm-tester. In a typical state |
| 61 | dir you can find the following files: |
| 62 | |
| 63 | 'last_used_msisdn.state':: |
| 64 | Contains last used msisdn number, which is automatically increased every |
| 65 | time osmo-gsm-tester needs to assign a new subscriber in a test. |
| 66 | 'lock':: |
| 67 | Lock file used to implement a mutual exclusion zone around the |
| 68 | 'reserved_resources.state' file. |
| 69 | 'reserved_resources.state':: |
| 70 | File containing a set of reserved resources by any number of |
| 71 | osmo-gsm-tester instances. Each osmo-gsm-tester instance is responsible |
| 72 | to clear its resources from the list once it is done using them and are |
| 73 | no longer reserved. |
| 74 | |
Neels Hofmeyr | b52df17 | 2017-05-14 20:09:35 +0200 | [diff] [blame] | 75 | If you would like to set up several separate configurations (not typical), note |
| 76 | that the 'state_dir' is used to reserve resources, which only works when all |
| 77 | configurations that share resources also use the same 'state_dir'. |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 78 | |
Pau Espin Pedrol | 21f2b8f | 2017-11-02 17:57:58 +0100 | [diff] [blame] | 79 | This way, several concurrent users of osmo-gsm-tester (ie. several |
| 80 | osmo-gsm-tester processes running in parallel) can run without interfering with |
| 81 | each other (e.g. using same ARFCN, same IP or same ofono modem path). |
| 82 | |
Pau Espin Pedrol | dfdb703 | 2017-11-02 17:50:08 +0100 | [diff] [blame] | 83 | [[suites_dir]] |
| 84 | ==== 'suites_dir' |
| 85 | |
| 86 | Suites contain a set of tests which are designed to be run together to test a |
| 87 | set of features given a specific set of resources. As a result, resources are |
| 88 | allocated per suite and not per test. |
| 89 | |
| 90 | Tests for a given suite are located in the form of '.py' python scripts in the |
| 91 | same directory where the 'suite.conf' lays. |
| 92 | |
Pau Espin Pedrol | 6131f35 | 2017-11-02 14:45:46 +0100 | [diff] [blame] | 93 | [[scenarios_dir]] |
| 94 | ==== 'scenarios_dir' |
| 95 | |
| 96 | This dir contains scenario configuration files. |
| 97 | |
| 98 | Scenarios define constraints to serve the resource requests of a 'suite.conf', |
| 99 | to select specific resources from the general resource pool specified in 'resources.conf'. |
| 100 | |
| 101 | All 'times' attributes are expanded before matching. For example, if a 'suite.conf' |
| 102 | requests two BTS, we may enforce that both BTS should be of type 'osmo-bts-sysmo' in |
| 103 | these ways: |
| 104 | |
| 105 | ---- |
| 106 | resources: |
| 107 | bts: |
| 108 | - type: osmo-bts-sysmo |
| 109 | - type: osmo-bts-sysmo |
| 110 | ---- |
| 111 | |
| 112 | or alternatively, |
| 113 | |
| 114 | ---- |
| 115 | resources: |
| 116 | bts: |
| 117 | - times: 2 |
| 118 | type: osmo-bts-sysmo |
| 119 | ---- |
| 120 | |
| 121 | If only one resource is specified in the scenario, then the resource allocator |
| 122 | assumes the restriction is to be applied to the first resource and that remaining |
| 123 | resources have no restrictions to be taken into consideration. |
| 124 | |
| 125 | To apply restrictions only on the second resource, the first element can be left |
| 126 | emtpy, like: |
| 127 | |
| 128 | ---- |
| 129 | resources: |
| 130 | bts: |
| 131 | - {} |
| 132 | - type: osmo-bts-sysmo |
| 133 | ---- |
| 134 | |
| 135 | On the 'osmo_gsm_tester.py' command line and the 'default_suites.conf', any number of |
| 136 | such scenario configurations can be combined in the form: |
| 137 | |
| 138 | ---- |
| 139 | <suite_name>:<scenario>[+<scenario>[+...]] |
| 140 | ---- |
| 141 | |
| 142 | e.g. |
| 143 | |
| 144 | ---- |
| 145 | my_suite:sysmo+tch_f+amr |
| 146 | ---- |
| 147 | |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 148 | [[resources_conf]] |
| 149 | === 'resources.conf' |
| 150 | |
| 151 | The 'resources.conf' file defines which hardware is connected to the main unit, |
| 152 | as well as which limited configuration items (like IP addresses or ARFCNs) |
| 153 | should be used. |
| 154 | |
| 155 | These resources are allocated dynamically and are not configured explicitly: |
| 156 | |
| 157 | - MSISDN: phone numbers are dealt out to test scripts in sequence on request. |
| 158 | |
| 159 | A 'resources.conf' is structured as a list of items for each resource type, |
| 160 | where each item has one or more settings -- for an example, see |
| 161 | <<resources_conf_example>>. |
| 162 | |
| 163 | These kinds of resource are known: |
| 164 | |
Neels Hofmeyr | 5d0330f | 2017-05-18 18:38:50 +0200 | [diff] [blame] | 165 | 'ip_address':: |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 166 | List of IP addresses to run osmo-nitb instances on. The main unit |
| 167 | typically has a limited number of such IP addresses configured, which |
| 168 | the connected BTS models can see on their network. |
| 169 | 'addr'::: |
| 170 | IPv4 address of the local interface. |
| 171 | |
| 172 | 'bts':: |
| 173 | List of available BTS hardware. |
| 174 | 'label'::: |
| 175 | human readable label for your own reference |
| 176 | 'type'::: |
| 177 | which way to launch this BTS, one of |
| 178 | - 'osmo-bts-sysmo' |
| 179 | - 'osmo-bts-trx' |
| 180 | - 'osmo-bts-octphy' |
| 181 | - 'ipa-nanobts' |
Pau Espin Pedrol | 264829e | 2017-11-02 16:43:04 +0100 | [diff] [blame] | 182 | 'ipa_unit_id'::: |
| 183 | ip.access unit id to be used by the BTS, written into BTS and BSC config. |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 184 | 'addr'::: |
Pau Espin Pedrol | 264829e | 2017-11-02 16:43:04 +0100 | [diff] [blame] | 185 | Remote IP address of the BTS for BTS like sysmoBTS, and local IP address |
| 186 | to bind to for locally run BTS such as osmo-bts-trx. |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 187 | 'band'::: |
| 188 | GSM band that this BTS shoud use (*TODO*: allow multiple bands). One of: |
| 189 | - 'GSM-1800' |
| 190 | - 'GSM-1900' |
| 191 | - (*TODO*: more bands) |
| 192 | 'trx_list'::: |
| 193 | Specific TRX configurations for this BTS. There should be as many of |
| 194 | these as the BTS has TRXes. (*TODO*: a way to define >1 TRX without |
| 195 | special configuration for them.) |
| 196 | 'hw_addr':::: |
| 197 | Hardware (MAC) address of the TRX in the form of '11:22:33:44:55:66', |
| 198 | only used for osmo-bts-octphy. (*TODO*: and nanobts??) |
| 199 | 'net_device':::: |
| 200 | Local network device to reach the TRX's 'hw_addr' at, only used for |
Pau Espin Pedrol | 264829e | 2017-11-02 16:43:04 +0100 | [diff] [blame] | 201 | osmo-bts-octphy. Example: 'eth0'. |
| 202 | 'nominal_power':::: |
| 203 | Nominal power to be used by the TRX. |
| 204 | 'max_power_red':::: |
| 205 | Max power reduction to apply to the nominal power of the TRX. |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 206 | 'arfcn':: |
| 207 | List of ARFCNs to use for running BTSes, which defines the actual RF |
| 208 | frequency bands used. |
| 209 | 'arfcn'::: |
| 210 | ARFCN number, see e.g. |
| 211 | https://en.wikipedia.org/wiki/Absolute_radio-frequency_channel_number |
| 212 | (note that the resource type 'arfcn' contains an item trait also named |
Pau Espin Pedrol | 264829e | 2017-11-02 16:43:04 +0100 | [diff] [blame] | 213 | 'arfcn'). |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 214 | 'band'::: |
| 215 | GSM band name to use this ARFCN for, same as for 'bts:band' above. |
| 216 | |
| 217 | 'modem':: |
| 218 | List of modems reachable via ofono and information on the inserted SIM |
Pau Espin Pedrol | 264829e | 2017-11-02 16:43:04 +0100 | [diff] [blame] | 219 | card. (Note: the MSISDN is allocated dynamically in test scripts). |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 220 | 'label'::: |
Pau Espin Pedrol | 264829e | 2017-11-02 16:43:04 +0100 | [diff] [blame] | 221 | Human readable label for your own reference, which also appears in logs. |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 222 | 'path'::: |
Pau Espin Pedrol | 264829e | 2017-11-02 16:43:04 +0100 | [diff] [blame] | 223 | Ofono's path for this modem, like '/modemkind_99'. |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 224 | 'imsi'::: |
Pau Espin Pedrol | 264829e | 2017-11-02 16:43:04 +0100 | [diff] [blame] | 225 | IMSI of the inserted SIM card, like '"123456789012345"'. |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 226 | 'ki'::: |
| 227 | 16 byte authentication/encryption KI of the inserted SIM card, in |
| 228 | hexadecimal notation (32 characters) like + |
Pau Espin Pedrol | 264829e | 2017-11-02 16:43:04 +0100 | [diff] [blame] | 229 | '"00112233445566778899aabbccddeeff"'. |
| 230 | 'auth_algo'::: |
| 231 | Authentication algorithm to be used with the SIM card. One of: |
| 232 | - 'none' |
| 233 | - 'xor' |
| 234 | - 'comp128v1' |
| 235 | 'ciphers'::: |
| 236 | List of ciphers that this modem supports, used to match |
| 237 | requirements in suites or scenarios. Any combination of: |
| 238 | - 'a5_0' |
| 239 | - 'a5_1' |
| 240 | - 'a5_2' |
| 241 | - 'a5_3' |
| 242 | - 'a5_4' |
| 243 | - 'a5_5' |
| 244 | - 'a5_6' |
| 245 | - 'a5_7' |
| 246 | 'features'::: |
| 247 | List of features that this modem supports, used to match requirements in |
| 248 | suites or scenarios. Any combination of: |
| 249 | - 'sms' |
| 250 | - 'gprs' |
| 251 | - 'voice' |
| 252 | - 'ussd' |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 253 | |
| 254 | Side note: at first sight it might make sense to the reader to rather structure |
Neels Hofmeyr | 5d0330f | 2017-05-18 18:38:50 +0200 | [diff] [blame] | 255 | e.g. the 'ip_address' or 'arfcn' configuration as + |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 256 | '"arfcn: GSM-1800: [512, 514, ...]"', + |
| 257 | but the more verbose format is chosen to stay consistent with the general |
| 258 | structure of resource configurations, which the resource allocation algorithm |
| 259 | uses to resolve required resources according to their traits. These |
| 260 | configurations look cumbersome because they exhibit only one trait / a trait |
| 261 | that is repeated numerous times. No special notation for these cases is |
| 262 | available (yet). |
| 263 | |
| 264 | [[default_suites]] |
| 265 | === 'default-suites.conf' (optional) |
| 266 | |
| 267 | The 'default-suites.conf' file contains a list of 'suite:scenario+scenario+...' |
| 268 | combination strings as defined by the 'osmo-gsm-tester.py -s' commandline |
| 269 | option. If invoking the 'osmo-gsm-tester.py' without any suite definitions, the |
| 270 | '-s' arguments are taken from this file instead. Each of these suite + scenario |
| 271 | combinations is run in sequence. |
| 272 | |
| 273 | A suite name must match the name of a directory in the 'suites_dir' as defined |
| 274 | by 'paths.conf'. |
| 275 | |
| 276 | A scenario name must match the name of a configuration file in the |
| 277 | 'scenarios_dir' as defined by 'paths.conf' (optionally without the '.conf' |
| 278 | suffix). |
| 279 | |
| 280 | For 'paths.conf', see <<paths_conf>>. |
| 281 | |
| 282 | Example of a 'default-suites.conf' file: |
| 283 | |
| 284 | ---- |
| 285 | - sms:sysmo |
| 286 | - voice:sysmo+tch_f |
| 287 | - voice:sysmo+tch_h |
| 288 | - voice:sysmo+dyn_ts |
| 289 | - sms:trx |
| 290 | - voice:trx+tch_f |
| 291 | - voice:trx+tch_h |
| 292 | - voice:trx+dyn_ts |
| 293 | ---- |
| 294 | |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 295 | === 'defaults.conf' (optional) |
| 296 | |
| 297 | Each binary run by osmo-gsm-tester, e.g. 'osmo-nitb' or 'osmo-bts-sysmo', |
| 298 | typically has a configuration file template that is populated with values for a |
| 299 | trial run. |
| 300 | |
| 301 | Some of these values are provided by the 'resources.conf' from the allocated |
| 302 | resource(s), but not all values can be populated this way: some osmo-nitb |
| 303 | configuration values like the network name, encryption algorithm or timeslot |
| 304 | channel combinations are in fact not resources (only the nitb's interface |
| 305 | address is). These additional settings may be provided by the scenario |
| 306 | configurations, but in case the provided scenarios leave some values unset, |
Pau Espin Pedrol | 6fa6199 | 2017-11-02 16:57:22 +0100 | [diff] [blame] | 307 | they are taken from this 'defaults.conf'. (A 'scenario.conf' or a |
| 308 | 'resources.conf' providing a similar setting always has precedence over the |
| 309 | values given in a 'defaults.conf'). |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 310 | |
| 311 | Example of a 'defaults.conf': |
| 312 | |
| 313 | ---- |
| 314 | nitb: |
| 315 | net: |
Pau Espin Pedrol | 6fa6199 | 2017-11-02 16:57:22 +0100 | [diff] [blame] | 316 | mcc: 901 |
| 317 | mnc: 70 |
| 318 | short_name: osmo-gsm-tester-nitb |
| 319 | long_name: osmo-gsm-tester-nitb |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 320 | auth_policy: closed |
Pau Espin Pedrol | 6fa6199 | 2017-11-02 16:57:22 +0100 | [diff] [blame] | 321 | encryption: a5_0 |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 322 | |
Pau Espin Pedrol | 6fa6199 | 2017-11-02 16:57:22 +0100 | [diff] [blame] | 323 | bsc: |
| 324 | net: |
| 325 | mcc: 901 |
| 326 | mnc: 70 |
| 327 | short_name: osmo-gsm-tester-msc |
| 328 | long_name: osmo-gsm-tester-msc |
| 329 | auth_policy: closed |
| 330 | encryption: a5_0 |
| 331 | authentication: optional |
| 332 | |
| 333 | msc: |
| 334 | net: |
| 335 | mcc: 901 |
| 336 | mnc: 70 |
| 337 | short_name: osmo-gsm-tester-msc |
| 338 | long_name: osmo-gsm-tester-msc |
| 339 | auth_policy: closed |
| 340 | encryption: a5_0 |
| 341 | authentication: optional |
| 342 | |
| 343 | bsc_bts: |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 344 | location_area_code: 23 |
| 345 | base_station_id_code: 63 |
| 346 | stream_id: 255 |
| 347 | osmobsc_bts_type: sysmobts |
| 348 | trx_list: |
Pau Espin Pedrol | 6fa6199 | 2017-11-02 16:57:22 +0100 | [diff] [blame] | 349 | - nominal_power: 23 |
| 350 | max_power_red: 0 |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 351 | arfcn: 868 |
| 352 | timeslot_list: |
| 353 | - phys_chan_config: CCCH+SDCCH4 |
| 354 | - phys_chan_config: SDCCH8 |
| 355 | - phys_chan_config: TCH/F_TCH/H_PDCH |
| 356 | - phys_chan_config: TCH/F_TCH/H_PDCH |
| 357 | - phys_chan_config: TCH/F_TCH/H_PDCH |
| 358 | - phys_chan_config: TCH/F_TCH/H_PDCH |
| 359 | - phys_chan_config: TCH/F_TCH/H_PDCH |
| 360 | - phys_chan_config: TCH/F_TCH/H_PDCH |
| 361 | ---- |