Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 1 | == Configuration |
| 2 | |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 3 | === Schemas |
Neels Hofmeyr | b52df17 | 2017-05-14 20:09:35 +0200 | [diff] [blame] | 4 | |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 5 | All configuration attributes in {app-name} are stored and provided as YAML |
| 6 | files, which are handled internally mostly as sets of dictionaries, lists and |
| 7 | scalars. Each of these configurations have a known format, which is called |
| 8 | 'schema'. Each provided configuration is validated against its 'schema' at parse |
| 9 | time. Hence, 'schemas' can be seen as a namespace containing a structured tree |
| 10 | of configuration attributes. Each attribute has a schema type assigned which |
| 11 | constrains the type of value it can hold. |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 12 | |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 13 | There are several well-known schemas used across {app-name}, and they are |
| 14 | described in following sub-sections. |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 15 | |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 16 | [[schema_resources]] |
| 17 | ==== Schema 'resources' |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 18 | |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 19 | This schema defines all the attributes which can be assigned to |
| 20 | a _resource_, and it is used to validate the <<resources_conf,resources.conf>> |
| 21 | file. Hence, the <<resources_conf,resources.conf>> contains a list of elements |
| 22 | for each resource type. |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 23 | |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 24 | It is important to understand that the content in this schema refers to a list of |
| 25 | resources for each resource class. Since a list is ordered by definition, it |
| 26 | clearly identifies specific resources by order. This is important when applying |
| 27 | filters or modifiers, since they are applied per-resource in the list. One can |
| 28 | for instance apply attribute A to first resource of class C, while not applying |
| 29 | it or applying another attribute B to second resources of the same class. As a |
| 30 | result, complex forms can be used to filter and modify a list of resources |
| 31 | required by a testsuite. |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 32 | |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 33 | On the other hand, it's also important to note that lists for simple or scalar |
| 34 | types are currently being treated as unordered sets, which mean combination of |
| 35 | filters or modifiers apply differently. In the future, it may be possible to |
| 36 | have both behaviors for scalar/simple types by using also the YAML 'set' type in |
| 37 | {app-handle}. |
Neels Hofmeyr | b52df17 | 2017-05-14 20:09:35 +0200 | [diff] [blame] | 38 | |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 39 | //TODO: update this list and use a table for each resource type |
| 40 | These kinds of resources and their attributes are known: |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 41 | |
Neels Hofmeyr | 5d0330f | 2017-05-18 18:38:50 +0200 | [diff] [blame] | 42 | 'ip_address':: |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 43 | List of IP addresses to run osmo-nitb instances on. The main unit |
| 44 | typically has a limited number of such IP addresses configured, which |
| 45 | the connected BTS models can see on their network. |
| 46 | 'addr'::: |
| 47 | IPv4 address of the local interface. |
| 48 | |
| 49 | 'bts':: |
| 50 | List of available BTS hardware. |
| 51 | 'label'::: |
| 52 | human readable label for your own reference |
| 53 | 'type'::: |
| 54 | which way to launch this BTS, one of |
| 55 | - 'osmo-bts-sysmo' |
| 56 | - 'osmo-bts-trx' |
| 57 | - 'osmo-bts-octphy' |
| 58 | - 'ipa-nanobts' |
Pau Espin Pedrol | 264829e | 2017-11-02 16:43:04 +0100 | [diff] [blame] | 59 | 'ipa_unit_id'::: |
| 60 | 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] | 61 | 'addr'::: |
Pau Espin Pedrol | 264829e | 2017-11-02 16:43:04 +0100 | [diff] [blame] | 62 | Remote IP address of the BTS for BTS like sysmoBTS, and local IP address |
| 63 | to bind to for locally run BTS such as osmo-bts-trx. |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 64 | 'band'::: |
| 65 | GSM band that this BTS shoud use (*TODO*: allow multiple bands). One of: |
| 66 | - 'GSM-1800' |
| 67 | - 'GSM-1900' |
| 68 | - (*TODO*: more bands) |
| 69 | 'trx_list'::: |
| 70 | Specific TRX configurations for this BTS. There should be as many of |
| 71 | these as the BTS has TRXes. (*TODO*: a way to define >1 TRX without |
| 72 | special configuration for them.) |
| 73 | 'hw_addr':::: |
| 74 | Hardware (MAC) address of the TRX in the form of '11:22:33:44:55:66', |
| 75 | only used for osmo-bts-octphy. (*TODO*: and nanobts??) |
| 76 | 'net_device':::: |
| 77 | 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] | 78 | osmo-bts-octphy. Example: 'eth0'. |
| 79 | 'nominal_power':::: |
| 80 | Nominal power to be used by the TRX. |
| 81 | 'max_power_red':::: |
| 82 | Max power reduction to apply to the nominal power of the TRX. |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 83 | 'arfcn':: |
| 84 | List of ARFCNs to use for running BTSes, which defines the actual RF |
| 85 | frequency bands used. |
| 86 | 'arfcn'::: |
| 87 | ARFCN number, see e.g. |
| 88 | https://en.wikipedia.org/wiki/Absolute_radio-frequency_channel_number |
| 89 | (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] | 90 | 'arfcn'). |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 91 | 'band'::: |
| 92 | GSM band name to use this ARFCN for, same as for 'bts:band' above. |
| 93 | |
| 94 | 'modem':: |
| 95 | 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] | 96 | card. (Note: the MSISDN is allocated dynamically in test scripts). |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 97 | 'label'::: |
Pau Espin Pedrol | 264829e | 2017-11-02 16:43:04 +0100 | [diff] [blame] | 98 | Human readable label for your own reference, which also appears in logs. |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 99 | 'path'::: |
Pau Espin Pedrol | 264829e | 2017-11-02 16:43:04 +0100 | [diff] [blame] | 100 | Ofono's path for this modem, like '/modemkind_99'. |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 101 | 'imsi'::: |
Pau Espin Pedrol | 264829e | 2017-11-02 16:43:04 +0100 | [diff] [blame] | 102 | IMSI of the inserted SIM card, like '"123456789012345"'. |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 103 | 'ki'::: |
| 104 | 16 byte authentication/encryption KI of the inserted SIM card, in |
| 105 | hexadecimal notation (32 characters) like + |
Pau Espin Pedrol | 264829e | 2017-11-02 16:43:04 +0100 | [diff] [blame] | 106 | '"00112233445566778899aabbccddeeff"'. |
| 107 | 'auth_algo'::: |
| 108 | Authentication algorithm to be used with the SIM card. One of: |
| 109 | - 'none' |
| 110 | - 'xor' |
| 111 | - 'comp128v1' |
| 112 | 'ciphers'::: |
| 113 | List of ciphers that this modem supports, used to match |
| 114 | requirements in suites or scenarios. Any combination of: |
| 115 | - 'a5_0' |
| 116 | - 'a5_1' |
| 117 | - 'a5_2' |
| 118 | - 'a5_3' |
| 119 | - 'a5_4' |
| 120 | - 'a5_5' |
| 121 | - 'a5_6' |
| 122 | - 'a5_7' |
| 123 | 'features'::: |
| 124 | List of features that this modem supports, used to match requirements in |
| 125 | suites or scenarios. Any combination of: |
| 126 | - 'sms' |
| 127 | - 'gprs' |
| 128 | - 'voice' |
| 129 | - 'ussd' |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 130 | |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 131 | [[schema_want]] |
| 132 | ==== Schema 'want' |
| 133 | |
| 134 | This schema is basically the same as the <<schema_resources,resources>> one, but |
| 135 | with an extra 'times' attribute for each resource item. All 'times' attributes |
| 136 | are expanded before matching. For example, if a 'suite.conf' requests two BTS, |
| 137 | one may enforce that both BTS should be of type 'osmo-bts-sysmo' in these ways: |
| 138 | |
| 139 | ---- |
| 140 | resources: |
| 141 | bts: |
| 142 | - type: osmo-bts-sysmo |
| 143 | - type: osmo-bts-sysmo |
| 144 | ---- |
| 145 | |
| 146 | or alternatively, |
| 147 | |
| 148 | ---- |
| 149 | resources: |
| 150 | bts: |
| 151 | - times: 2 |
| 152 | type: osmo-bts-sysmo |
| 153 | ---- |
| 154 | |
| 155 | [[schema_conf]] |
| 156 | ==== Schema 'conf' |
| 157 | |
| 158 | This schema is used by <<suite_conf,suite.conf>> and <<scenario_conf,scenario.conf>> files. It contains 3 main element sections::: |
| 159 | [[schema_conf_sec_resources]] |
| 160 | - Section 'resources': Contains a set of elements validated with <<schema_resources,resources>> |
| 161 | schema. In <<suite_conf,suite.conf>> it is used to construct the list of |
| 162 | requested resources. In <<scenario_conf,scenario.conf>>, it is used to inject |
Pau Espin Pedrol | c1220e1 | 2020-03-16 19:50:40 +0100 | [diff] [blame] | 163 | attributes to the initial <<suite_conf,suite.conf>> _resources_ section and |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 164 | hence further restrain it. |
| 165 | [[schema_conf_sec_modifiers]] |
| 166 | - Section 'modifiers': Both in <<suite_conf,suite.conf>> and |
| 167 | <<scenario_conf,scenario.conf>>, values presented in here are injected into |
| 168 | the content of the <<schema_conf_sec_resources,resources section>> after |
| 169 | _resource_ allocation, hereby overwriting attributes passed to the object |
| 170 | class instance managing the specific _resource_ (matches by resource type and |
| 171 | list position). Since it is combined with the content of |
| 172 | <<schema_conf_sec_resources,resources section>>, it is clear that the |
| 173 | <<schema_resources,resources schema>> is used to validate this content. |
| 174 | [[schema_conf_sec_config]] |
| 175 | - Section 'config': Contains configuration attributes for {app-name} classes which are |
| 176 | not _resources_, and hence cannot be configured with <<schema_modifiers,modifiers>>. |
| 177 | They can overwrite values provided in the <<defaults_conf,defaults.conf>> file. |
| 178 | |
| 179 | //TODO: defaults.timeout should be change in code to be config.test_timeout or similar |
| 180 | //TODO: 'config' should be split into its own schema and validate defaults.conf |
| 181 | |
| 182 | [[config_paths]] |
| 183 | === Config Paths |
| 184 | |
| 185 | The osmo-gsm-tester looks for configuration files in various standard |
| 186 | directories in this order: |
| 187 | |
| 188 | - '$HOME/.config/osmo-gsm-tester/' |
| 189 | - '/usr/local/etc/osmo-gsm-tester/' |
| 190 | - '/etc/osmo-gsm-tester/' |
| 191 | |
| 192 | The config location can also be set by an environment variable |
| 193 | '$OSMO_GSM_TESTER_CONF', which then overrides the above locations. |
| 194 | |
| 195 | The osmo-gsm-tester expects to find the following configuration files in a |
| 196 | configuration directory: |
| 197 | |
| 198 | - <<paths_conf,paths.conf>> |
| 199 | - <<resource_conf,resources.conf>> |
| 200 | - <<default_suites_conf,default-suites.conf>> (optional) |
| 201 | - <<defaults_conf,defaults.conf>> (optional) |
| 202 | |
| 203 | These are described in detail in the following sections. |
| 204 | |
| 205 | [[paths_conf]] |
| 206 | ==== 'paths.conf' |
| 207 | |
| 208 | The 'paths.conf' file defines where to store the global state (of reserved |
| 209 | resources) and where to find suite and scenario definitions. |
| 210 | |
| 211 | Any relative paths found in a 'paths.conf' file are interpreted as relative to |
| 212 | the directory of that 'paths.conf' file. |
| 213 | |
| 214 | There's not yet any well-known schema to validate this file contents since it |
| 215 | has only 3 attributes. |
| 216 | |
| 217 | .Sample paths.conf file: |
| 218 | ---- |
| 219 | state_dir: '/var/tmp/osmo-gsm-tester/state' |
| 220 | suites_dir: '/usr/local/src/osmo-gsm-tester/suites' |
| 221 | scenarios_dir: './scenarios' |
| 222 | ---- |
| 223 | |
| 224 | [[state_dir]] |
| 225 | ===== 'state_dir' |
| 226 | |
| 227 | It contains global or system-wide state for osmo-gsm-tester. In a typical state |
| 228 | dir you can find the following files: |
| 229 | |
| 230 | 'last_used_*.state':: |
| 231 | Contains stateful content spanning accross {app-name} instances and |
| 232 | runs. For instance, 'last used msisdn number.state' is automatically |
| 233 | (and atomically) increased every time osmo-gsm-tester needs to assign a |
| 234 | new subscriber in a test, ensuring tests get unique msisdn numbers. |
| 235 | 'reserved_resources.state':: |
| 236 | File containing a set of reserved resources by any number of |
| 237 | osmo-gsm-tester instances (aka pool of allocated resources). Each |
| 238 | osmo-gsm-tester instance is responsible to clear its resources from the |
| 239 | list once it is done using them and are no longer reserved. |
| 240 | 'lock':: |
| 241 | Lock file used to implement a mutual exclusion zone around any state |
| 242 | files in the 'state_dir', to prevent race conditions between different |
| 243 | {app-name} instances running in parallel. |
| 244 | |
| 245 | This way, several concurrent users of osmo-gsm-tester (ie. several |
| 246 | osmo-gsm-tester processes running in parallel) can run without interfering with |
| 247 | each other (e.g. using same ARFCN, same IP or same ofono modem path). |
| 248 | |
| 249 | If you would like to set up several separate configurations (not typical), note |
| 250 | that the 'state_dir' is used to reserve resources, which only works when all |
| 251 | configurations that share resources also use the same 'state_dir'. It's also |
| 252 | important to notice that since resources are stored in YAML dictionary form, if |
| 253 | same physical device is described differently in several |
| 254 | <<resource_conf,resources.conf>> files (used by different {app-name} instances), |
| 255 | resource allocation may not work as expected. |
| 256 | |
| 257 | [[suites_dir]] |
| 258 | ===== 'suites_dir' |
| 259 | |
| 260 | Suites contain a set of tests which are designed to be run together to test a |
| 261 | set of features given a specific set of resources. As a result, resources are |
| 262 | allocated per suite and not per test. |
| 263 | |
| 264 | Tests for a given suite are located in the form of '.py' python scripts in the |
| 265 | same directory where the <<suite_conf,suite.conf>> lays. |
| 266 | |
| 267 | Tests in the same testsuite willing to use some shared code can do so by putting |
| 268 | it eg. in '$suites_dir/$suitename/lib/testlib.py': |
| 269 | ---- |
| 270 | #!/usr/bin/env python3 |
| 271 | from osmo_gsm_tester.testenv import * |
| 272 | |
| 273 | def my_shared_code(foo): |
| 274 | return foo.bar() |
| 275 | ---- |
| 276 | |
| 277 | and then in the test itself use it this way: |
| 278 | ---- |
| 279 | #!/usr/bin/env python3 |
| 280 | from osmo_gsm_tester.testenv import * |
| 281 | |
| 282 | import testlib |
| 283 | suite.test_import_modules_register_for_cleanup(testlib) |
| 284 | from testlib import my_shared_code |
| 285 | |
| 286 | bar = my_shared_code(foo) |
| 287 | ---- |
| 288 | |
| 289 | .Sample 'suites_dir' directory tree: |
| 290 | ---- |
| 291 | suites_dir/ |
| 292 | |-- suiteA |
| 293 | | |-- suite.conf |
| 294 | | '-- testA.py |
| 295 | |-- suiteB |
| 296 | | |-- testB.py |
| 297 | | |-- testC.py |
| 298 | | |-- lib |
| 299 | | | '-- testlib.py |
| 300 | | '-- suite.conf |
| 301 | ---- |
| 302 | |
| 303 | [[suite_conf]] |
| 304 | ===== 'suite.conf' |
| 305 | |
| 306 | This file content is parsed using the <<schema_want,Want>> schema. |
| 307 | |
| 308 | It provides |
| 309 | {app-name} with the base restrictions (later to be further filtered by |
| 310 | <<scenario_conf,scenario>> files) to apply when allocating resources. |
| 311 | |
| 312 | It can also override attributes for the allocated resources through the |
| 313 | <<schema_want,modifiers>> section (to be further modified by |
| 314 | <<scenario_conf,scenario>> files later on). Similary it can do the same for |
| 315 | general configuration options (no per-resource) through the |
| 316 | <<schema_want,config>> section. |
| 317 | |
| 318 | .Sample 'suite.conf' file: |
| 319 | ---- |
| 320 | resources: |
| 321 | ip_address: |
| 322 | - times: 9 # msc, bsc, hlr, stp, mgw*2, sgsn, ggsn, iperf3srv |
| 323 | bts: |
| 324 | - times: 1 |
| 325 | modem: |
| 326 | - times: 2 |
| 327 | features: |
| 328 | - gprs |
| 329 | - voice |
| 330 | - times: 2 |
| 331 | features: |
| 332 | - gprs |
| 333 | |
| 334 | config: |
| 335 | bsc: |
| 336 | net: |
| 337 | codec_list: |
| 338 | - fr1 |
| 339 | |
| 340 | defaults: |
| 341 | timeout: 50s |
| 342 | ---- |
| 343 | |
| 344 | [[scenarios_dir]] |
| 345 | ===== 'scenarios_dir' |
| 346 | |
| 347 | This dir contains scenario configuration files. |
| 348 | |
| 349 | .Sample 'scenarios_dir' directory tree: |
| 350 | ---- |
| 351 | scenarios_dir/ |
| 352 | |-- scenarioA.conf |
| 353 | '-- scenarioB.conf |
| 354 | ---- |
| 355 | |
| 356 | [[scenario_conf]] |
| 357 | ===== 'scenario conf file' |
| 358 | Scenarios define further constraints to serve the resource requests of a |
| 359 | <<suite_conf,suite.conf>>, ie. to select specific resources from the general |
| 360 | resource pool specified in <<resource_conf,resources.conf>>. |
| 361 | |
| 362 | If only one resource is specified in the scenario, then the resource allocator |
| 363 | assumes the restriction is to be applied to the first resource and that remaining |
| 364 | resources have no restrictions to be taken into consideration. |
| 365 | |
| 366 | To apply restrictions only on the second resource, the first element can be left |
| 367 | emtpy, like: |
| 368 | |
| 369 | ---- |
| 370 | resources: |
| 371 | bts: |
| 372 | - {} |
| 373 | - type: osmo-bts-sysmo |
| 374 | ---- |
| 375 | |
| 376 | On the 'osmo_gsm_tester.py' command line and the |
| 377 | <<default_suites_conf,default_suites.conf>>, any number of such scenario |
| 378 | configurations can be combined in the form: |
| 379 | |
| 380 | ---- |
| 381 | <suite_name>:<scenario>[+<scenario>[+...]] |
| 382 | ---- |
| 383 | |
| 384 | e.g. |
| 385 | |
| 386 | ---- |
| 387 | my_suite:sysmo+tch_f+amr |
| 388 | ---- |
| 389 | |
Pau Espin Pedrol | 7dc2216 | 2020-03-11 19:57:45 +0100 | [diff] [blame] | 390 | *_Parametrized scenario conf files_*: |
| 391 | |
| 392 | Furthermore, scenario '.conf' files can be parametrized. The concept is similar to that |
| 393 | of systemd's Template Unit Files. That is, an scenario file can be written so |
| 394 | that some values inside it can be passed at the time of referencing the |
| 395 | scenario name. The idea behind its existence is to re-use the same |
| 396 | scenario file for a set of attributes which are changed and that can have a lot |
| 397 | of different values. For instance, if a scenario is aimed at setting or |
| 398 | filtering some specific attribute holding an integer value, without parametrized |
| 399 | scenarios then a separate file would be needed for each value the user wanted to use. |
| 400 | |
| 401 | A parametrized scenario file, similar to systemd Template Unit Files, |
| 402 | contain the character '@' in their file name, ie follow the syntax below: |
| 403 | ---- |
| 404 | scenario-name@param1,param2,param3,[...],paramN.conf |
| 405 | ---- |
| 406 | |
| 407 | Then, its content can be written this way: |
| 408 | ---- |
| 409 | $ cat $scenario_dir/my-parametrized-scenario@.conf |
| 410 | resources: |
| 411 | enb: |
| 412 | - type: srsenb |
| 413 | rf_dev_type: ${param1} |
| 414 | modifiers: |
| 415 | enb: |
| 416 | - num_prb: ${param2} |
| 417 | ---- |
| 418 | |
| 419 | Finally, it can be referenced during {app-name} execution this wya, for instance when running a suite named '4g': |
| 420 | ---- |
| 421 | - 4g:my-parametrized-scenario@UHD,6 |
| 422 | ---- |
| 423 | This way {app-name} when parsing the scenarios and combining them with the suite will:: |
| 424 | . Find out it is parametrized (name contains '@'). |
| 425 | . Split the name |
| 426 | ('my-parametrized-scenario') from the parameter list (param1='UHD', param2='6') |
| 427 | . Attempt to match a '.conf' file fully matching name and parameters (hence |
| 428 | specific content can be set for specific values while still using parameters |
| 429 | for general values), and otherwise match only by name. |
| 430 | . Generate the final |
| 431 | scenario content from the template available in the matched '.conf' file. |
| 432 | |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 433 | [[resources_conf]] |
| 434 | ==== 'resources.conf' |
| 435 | |
| 436 | //TODO: update this section |
| 437 | The 'resources.conf' file defines which hardware is connected to the main unit, |
| 438 | as well as which limited configuration items (like IP addresses or ARFCNs) |
| 439 | should be used. |
| 440 | |
| 441 | A 'resources.conf' is validated by the <<schema_resources,resources schema>>. |
| 442 | That means it is structured as a list of items for each resource type, where |
| 443 | each item has one or more attributes -- for an example, see |
| 444 | <<resources_conf_example>>. |
| 445 | |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 446 | 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] | 447 | e.g. the 'ip_address' or 'arfcn' configuration as + |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 448 | '"arfcn: GSM-1800: [512, 514, ...]"', + |
| 449 | but the more verbose format is chosen to stay consistent with the general |
| 450 | structure of resource configurations, which the resource allocation algorithm |
| 451 | uses to resolve required resources according to their traits. These |
| 452 | configurations look cumbersome because they exhibit only one trait / a trait |
| 453 | that is repeated numerous times. No special notation for these cases is |
| 454 | available (yet). |
| 455 | |
Pau Espin Pedrol | c1220e1 | 2020-03-16 19:50:40 +0100 | [diff] [blame] | 456 | [[default_suites_conf]] |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 457 | ==== 'default-suites.conf' (optional) |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 458 | |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 459 | The 'default-suites.conf' file contains a YAML list of 'suite:scenario+scenario+...' |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 460 | combination strings as defined by the 'osmo-gsm-tester.py -s' commandline |
| 461 | option. If invoking the 'osmo-gsm-tester.py' without any suite definitions, the |
| 462 | '-s' arguments are taken from this file instead. Each of these suite + scenario |
| 463 | combinations is run in sequence. |
| 464 | |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 465 | A suite name must match the name of a directory in the |
| 466 | <<suites_dir,suites_dir/>> as defined by <<paths_conf,paths.conf>>. |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 467 | |
| 468 | A scenario name must match the name of a configuration file in the |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 469 | <<scenarios_dir,scnearios_dir/>> as defined by <<paths_conf,paths.conf>> |
| 470 | (optionally without the '.conf' suffix). |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 471 | |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 472 | .Sample 'default-suites.conf' file: |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 473 | ---- |
| 474 | - sms:sysmo |
| 475 | - voice:sysmo+tch_f |
| 476 | - voice:sysmo+tch_h |
| 477 | - voice:sysmo+dyn_ts |
| 478 | - sms:trx |
| 479 | - voice:trx+tch_f |
| 480 | - voice:trx+tch_h |
| 481 | - voice:trx+dyn_ts |
| 482 | ---- |
| 483 | |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 484 | ==== 'defaults.conf' (optional) |
| 485 | |
| 486 | In {app-name} object instances requested by the test and created by the suite |
| 487 | relate to a specific allocated resource. That's not always the case, and even if |
| 488 | it the case the information stored in <<resources_conf,resources.conf>> for that |
| 489 | resource may not contain tons of attributes which the object class needs to |
| 490 | manage the resource. |
| 491 | |
| 492 | For this exact reason, the 'defaults.conf' file exist. It contains a set of |
| 493 | default attributes and values (in YAML format) that object classes can use to |
| 494 | fill in the missing gaps, or to provide values which can easily be changed or |
| 495 | overwritten by <<suite_conf,suite.conf>> or <<scenario_conf,scenario.conf>> |
| 496 | files through modifiers. |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 497 | |
| 498 | Each binary run by osmo-gsm-tester, e.g. 'osmo-nitb' or 'osmo-bts-sysmo', |
| 499 | typically has a configuration file template that is populated with values for a |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 500 | trial run. Hence, a <<suite_conf,suite.conf>>, <<scenario_conf,scenario.conf>> |
| 501 | or a <<resources_conf,resources.conf>> providing a similar setting always has |
| 502 | precedence over the values given in a 'defaults.conf' |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 503 | |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 504 | |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 505 | .Sample 'defaults.conf' file: |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 506 | ---- |
| 507 | nitb: |
| 508 | net: |
Pau Espin Pedrol | 6fa6199 | 2017-11-02 16:57:22 +0100 | [diff] [blame] | 509 | mcc: 901 |
| 510 | mnc: 70 |
| 511 | short_name: osmo-gsm-tester-nitb |
| 512 | long_name: osmo-gsm-tester-nitb |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 513 | auth_policy: closed |
Pau Espin Pedrol | 6fa6199 | 2017-11-02 16:57:22 +0100 | [diff] [blame] | 514 | encryption: a5_0 |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 515 | |
Pau Espin Pedrol | 6fa6199 | 2017-11-02 16:57:22 +0100 | [diff] [blame] | 516 | bsc: |
| 517 | net: |
| 518 | mcc: 901 |
| 519 | mnc: 70 |
| 520 | short_name: osmo-gsm-tester-msc |
| 521 | long_name: osmo-gsm-tester-msc |
| 522 | auth_policy: closed |
| 523 | encryption: a5_0 |
| 524 | authentication: optional |
| 525 | |
| 526 | msc: |
| 527 | net: |
| 528 | mcc: 901 |
| 529 | mnc: 70 |
| 530 | short_name: osmo-gsm-tester-msc |
| 531 | long_name: osmo-gsm-tester-msc |
| 532 | auth_policy: closed |
| 533 | encryption: a5_0 |
| 534 | authentication: optional |
| 535 | |
| 536 | bsc_bts: |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 537 | location_area_code: 23 |
| 538 | base_station_id_code: 63 |
| 539 | stream_id: 255 |
| 540 | osmobsc_bts_type: sysmobts |
| 541 | trx_list: |
Pau Espin Pedrol | 6fa6199 | 2017-11-02 16:57:22 +0100 | [diff] [blame] | 542 | - nominal_power: 23 |
| 543 | max_power_red: 0 |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 544 | arfcn: 868 |
| 545 | timeslot_list: |
| 546 | - phys_chan_config: CCCH+SDCCH4 |
| 547 | - phys_chan_config: SDCCH8 |
| 548 | - phys_chan_config: TCH/F_TCH/H_PDCH |
| 549 | - phys_chan_config: TCH/F_TCH/H_PDCH |
| 550 | - phys_chan_config: TCH/F_TCH/H_PDCH |
| 551 | - phys_chan_config: TCH/F_TCH/H_PDCH |
| 552 | - phys_chan_config: TCH/F_TCH/H_PDCH |
| 553 | - phys_chan_config: TCH/F_TCH/H_PDCH |
| 554 | ---- |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 555 | |
| 556 | === Example Setup |
| 557 | |
| 558 | {app-name} comes with an example official setup which is the one used to run |
| 559 | Osmocom's setup. There are actually two different available setups: a |
| 560 | production one and an RnD one, used to develop {app-name} itself. These two set |
| 561 | ups share mostly all configuration, main difference being the |
| 562 | <<resources_conf,resources.conf>> file being used. |
| 563 | |
Pau Espin Pedrol | c1220e1 | 2020-03-16 19:50:40 +0100 | [diff] [blame] | 564 | All {app-name} related configuration for that environment is publicly available |
| 565 | in 'osmo-gsm-tester.git' itself: |
| 566 | |
| 567 | - <<paths_conf,paths.conf>>: Available Available under 'example/', with its paths |
| 568 | already configured to take required bits from inside the git repository. |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 569 | - <<suite_dir,suites_dir>>: Available under 'suites/' |
| 570 | - <<scenarios_dir,scenarios_dir>>: Available under 'example/scenarios/' |
| 571 | - <<resource_conf,resources.conf>>: Available under 'example/' as |
| 572 | 'resources.conf.prod' for Production setup and as 'resources.conf.rnd' for the |
Pau Espin Pedrol | c1220e1 | 2020-03-16 19:50:40 +0100 | [diff] [blame] | 573 | RnD setup. One must use a symbolic link to have it available as |
| 574 | 'resources.conf'. |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 575 | |
| 576 | //TODO: resources.conf file path should be modifiable through paths.conf! |
| 577 | |
| 578 | ==== Typical Invocations |
| 579 | |
| 580 | Each invocation of osmo-gsm-tester deploys a set of pre-compiled binaries for |
| 581 | the Osmocom core network as well as for the Osmocom based BTS models. To create |
| 582 | such a set of binaries, see <<trials>>. |
| 583 | |
| 584 | Examples for launching test trials: |
| 585 | |
Pau Espin Pedrol | c1220e1 | 2020-03-16 19:50:40 +0100 | [diff] [blame] | 586 | - Run the default suites (see <<default_suites_conf,default_suites.conf>>) on a |
| 587 | given set of binaries: |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 588 | |
| 589 | ---- |
| 590 | osmo-gsm-tester.py path/to/my-trial |
| 591 | ---- |
| 592 | |
| 593 | - Run an explicit choice of 'suite:scenario' combinations: |
| 594 | |
| 595 | ---- |
| 596 | osmo-gsm-tester.py path/to/my-trial -s sms:sysmo -s sms:trx -s sms:nanobts |
| 597 | ---- |
| 598 | |
| 599 | - Run one 'suite:scenario1+scenario2' combination, setting log level to 'debug' |
| 600 | and enabling logging of full python tracebacks, and also only run just the |
| 601 | 'mo_mt_sms.py' test from the suite, e.g. to investigate a test failure: |
| 602 | |
| 603 | ---- |
| 604 | osmo-gsm-tester.py path/to/my-trial -s sms:sysmo+foobar -l dbg -T -t mo_mt |
| 605 | ---- |
| 606 | |
| 607 | A test script may also be run step-by-step in a python debugger, see |
| 608 | <<debugging>>. |