== Configuration The osmo-gsm-tester looks for configuration files in various standard directories in this order: - '$HOME/.config/osmo-gsm-tester/' - '/usr/local/etc/osmo-gsm-tester/' - '/etc/osmo-gsm-tester/' The config location can also be set by an environment variable '$OSMO_GSM_TESTER_CONF', which then overrides the above locations. The osmo-gsm-tester expects to find the following configuration files in a configuration directory: - 'paths.conf' - 'resources.conf' - 'default-suites.conf' (optional) - 'defaults.conf' (optional) === Format: YAML, and its Drawbacks The general configuration format used is YAML. The stock python YAML parser does have several drawbacks: too many complex possibilities and alternative ways of formatting a configuration, but at the time of writing seems to be the only widely used configuration format that offers a simple and human readable formatting as well as nested structuring. It is recommended to use only the exact YAML subset seen in this manual in case the osmo-gsm-tester should move to a less bloated parser in the future. Careful: if a configuration item consists of digits and starts with a zero, you need to quote it, or it may be interpreted as an octal notation integer! Please avoid using the octal notation on purpose, it is not provided intentionally. [[paths_conf]] === 'paths.conf' The 'paths.conf' file defines where to store the global state (of reserved resources) and where to find suite and scenario definitions. Any relative paths found in a 'paths.conf' file are interpreted as relative to the directory of that 'paths.conf' file. Example: ---- state_dir: '/var/run/osmo-gsm-tester' suites_dir: './suites' scenarios_dir: './scenarios' ---- If you would like to set up several separate 'paths.conf' files (not typical), note that the 'state_dir' is used to reserve resources, which only works when all configurations that share resources also use the same 'state_dir'. [[resources_conf]] === 'resources.conf' The 'resources.conf' file defines which hardware is connected to the main unit, as well as which limited configuration items (like IP addresses or ARFCNs) should be used. These resources are allocated dynamically and are not configured explicitly: - MSISDN: phone numbers are dealt out to test scripts in sequence on request. A 'resources.conf' is structured as a list of items for each resource type, where each item has one or more settings -- for an example, see <>. These kinds of resource are known: 'nitb_iface':: List of IP addresses to run osmo-nitb instances on. The main unit typically has a limited number of such IP addresses configured, which the connected BTS models can see on their network. 'addr'::: IPv4 address of the local interface. 'bts':: List of available BTS hardware. 'label'::: human readable label for your own reference 'type'::: which way to launch this BTS, one of - 'osmo-bts-sysmo' - 'osmo-bts-trx' - 'osmo-bts-octphy' - 'ipa-nanobts' 'addr'::: remote IP address of the BTS, used to start the BTS and tell it where to find the OsmoNITB. 'band'::: GSM band that this BTS shoud use (*TODO*: allow multiple bands). One of: - 'GSM-1800' - 'GSM-1900' - (*TODO*: more bands) 'trx_list'::: Specific TRX configurations for this BTS. There should be as many of these as the BTS has TRXes. (*TODO*: a way to define >1 TRX without special configuration for them.) 'hw_addr':::: Hardware (MAC) address of the TRX in the form of '11:22:33:44:55:66', only used for osmo-bts-octphy. (*TODO*: and nanobts??) 'net_device':::: Local network device to reach the TRX's 'hw_addr' at, only used for osmo-bts-octphy. 'arfcn':: List of ARFCNs to use for running BTSes, which defines the actual RF frequency bands used. 'arfcn'::: ARFCN number, see e.g. https://en.wikipedia.org/wiki/Absolute_radio-frequency_channel_number (note that the resource type 'arfcn' contains an item trait also named 'arfcn') 'band'::: GSM band name to use this ARFCN for, same as for 'bts:band' above. 'modem':: List of modems reachable via ofono and information on the inserted SIM card. (Note: the MSISDN is allocated dynamically in test scripts) 'label'::: human readable label for your own reference 'path'::: ofono's path for this modem, like '/modemkind_99' 'imsi'::: IMSI of the inserted SIM card, like '"123456789012345"' 'ki'::: 16 byte authentication/encryption KI of the inserted SIM card, in hexadecimal notation (32 characters) like + '"00112233445566778899aabbccddeeff"' (*TODO*: authentication algorithm, currently always comp128v1) Side note: at first sight it might make sense to the reader to rather structure e.g. the 'nitb_iface' or 'arfcn' configuration as + '"arfcn: GSM-1800: [512, 514, ...]"', + but the more verbose format is chosen to stay consistent with the general structure of resource configurations, which the resource allocation algorithm uses to resolve required resources according to their traits. These configurations look cumbersome because they exhibit only one trait / a trait that is repeated numerous times. No special notation for these cases is available (yet). [[default_suites]] === 'default-suites.conf' (optional) The 'default-suites.conf' file contains a list of 'suite:scenario+scenario+...' combination strings as defined by the 'osmo-gsm-tester.py -s' commandline option. If invoking the 'osmo-gsm-tester.py' without any suite definitions, the '-s' arguments are taken from this file instead. Each of these suite + scenario combinations is run in sequence. A suite name must match the name of a directory in the 'suites_dir' as defined by 'paths.conf'. A scenario name must match the name of a configuration file in the 'scenarios_dir' as defined by 'paths.conf' (optionally without the '.conf' suffix). For 'paths.conf', see <>. Example of a 'default-suites.conf' file: ---- - sms:sysmo - voice:sysmo+tch_f - voice:sysmo+tch_h - voice:sysmo+dyn_ts - sms:trx - voice:trx+tch_f - voice:trx+tch_h - voice:trx+dyn_ts ---- === 'defaults.conf' (optional) Each binary run by osmo-gsm-tester, e.g. 'osmo-nitb' or 'osmo-bts-sysmo', typically has a configuration file template that is populated with values for a trial run. Some of these values are provided by the 'resources.conf' from the allocated resource(s), but not all values can be populated this way: some osmo-nitb configuration values like the network name, encryption algorithm or timeslot channel combinations are in fact not resources (only the nitb's interface address is). These additional settings may be provided by the scenario configurations, but in case the provided scenarios leave some values unset, they are taken from this 'defaults.conf'. (A 'scenario.conf' providing a similar setting always has precedence over the values given in a 'defaults.conf'). *TODO* better match this format with 'resources.conf'? Example of a 'defaults.conf': ---- nitb: net: mcc: 1 mnc: 868 short_name: osmo-gsm-tester long_name: osmo-gsm-tester auth_policy: closed encryption: a5 0 nitb_bts: location_area_code: 23 base_station_id_code: 63 stream_id: 255 osmobsc_bts_type: sysmobts trx_list: - max_power_red: 22 arfcn: 868 timeslot_list: - phys_chan_config: CCCH+SDCCH4 - phys_chan_config: SDCCH8 - phys_chan_config: TCH/F_TCH/H_PDCH - phys_chan_config: TCH/F_TCH/H_PDCH - phys_chan_config: TCH/F_TCH/H_PDCH - phys_chan_config: TCH/F_TCH/H_PDCH - phys_chan_config: TCH/F_TCH/H_PDCH - phys_chan_config: TCH/F_TCH/H_PDCH ---- *TODO*: detailed descriptions