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