| == Configuration |
| |
| [[config_paths]] |
| === Config Paths |
| |
| 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) |
| |
| These are described in detail in the following sections. |
| |
| === 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/tmp/osmo-gsm-tester/state' |
| suites_dir: '/usr/local/src/osmo-gsm-tester/suites' |
| scenarios_dir: './scenarios' |
| ---- |
| |
| [[state_dir]] |
| ==== 'state_dir' |
| |
| It contains global or system-wide state for osmo-gsm-tester. In a typical state |
| dir you can find the following files: |
| |
| 'last_used_msisdn.state':: |
| Contains last used msisdn number, which is automatically increased every |
| time osmo-gsm-tester needs to assign a new subscriber in a test. |
| 'lock':: |
| Lock file used to implement a mutual exclusion zone around the |
| 'reserved_resources.state' file. |
| 'reserved_resources.state':: |
| File containing a set of reserved resources by any number of |
| osmo-gsm-tester instances. Each osmo-gsm-tester instance is responsible |
| to clear its resources from the list once it is done using them and are |
| no longer reserved. |
| |
| If you would like to set up several separate configurations (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'. |
| |
| This way, several concurrent users of osmo-gsm-tester (ie. several |
| osmo-gsm-tester processes running in parallel) can run without interfering with |
| each other (e.g. using same ARFCN, same IP or same ofono modem path). |
| |
| [[suites_dir]] |
| ==== 'suites_dir' |
| |
| Suites contain a set of tests which are designed to be run together to test a |
| set of features given a specific set of resources. As a result, resources are |
| allocated per suite and not per test. |
| |
| Tests for a given suite are located in the form of '.py' python scripts in the |
| same directory where the 'suite.conf' lays. |
| |
| [[scenarios_dir]] |
| ==== 'scenarios_dir' |
| |
| This dir contains scenario configuration files. |
| |
| Scenarios define constraints to serve the resource requests of a 'suite.conf', |
| to select specific resources from the general resource pool specified in 'resources.conf'. |
| |
| All 'times' attributes are expanded before matching. For example, if a 'suite.conf' |
| requests two BTS, we may enforce that both BTS should be of type 'osmo-bts-sysmo' in |
| these ways: |
| |
| ---- |
| resources: |
| bts: |
| - type: osmo-bts-sysmo |
| - type: osmo-bts-sysmo |
| ---- |
| |
| or alternatively, |
| |
| ---- |
| resources: |
| bts: |
| - times: 2 |
| type: osmo-bts-sysmo |
| ---- |
| |
| If only one resource is specified in the scenario, then the resource allocator |
| assumes the restriction is to be applied to the first resource and that remaining |
| resources have no restrictions to be taken into consideration. |
| |
| To apply restrictions only on the second resource, the first element can be left |
| emtpy, like: |
| |
| ---- |
| resources: |
| bts: |
| - {} |
| - type: osmo-bts-sysmo |
| ---- |
| |
| On the 'osmo_gsm_tester.py' command line and the 'default_suites.conf', any number of |
| such scenario configurations can be combined in the form: |
| |
| ---- |
| <suite_name>:<scenario>[+<scenario>[+...]] |
| ---- |
| |
| e.g. |
| |
| ---- |
| my_suite:sysmo+tch_f+amr |
| ---- |
| |
| [[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 |
| <<resources_conf_example>>. |
| |
| These kinds of resource are known: |
| |
| 'ip_address':: |
| 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' |
| 'ipa_unit_id'::: |
| ip.access unit id to be used by the BTS, written into BTS and BSC config. |
| 'addr'::: |
| Remote IP address of the BTS for BTS like sysmoBTS, and local IP address |
| to bind to for locally run BTS such as osmo-bts-trx. |
| '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. Example: 'eth0'. |
| 'nominal_power':::: |
| Nominal power to be used by the TRX. |
| 'max_power_red':::: |
| Max power reduction to apply to the nominal power of the TRX. |
| '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, which also appears in logs. |
| '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"'. |
| 'auth_algo'::: |
| Authentication algorithm to be used with the SIM card. One of: |
| - 'none' |
| - 'xor' |
| - 'comp128v1' |
| 'ciphers'::: |
| List of ciphers that this modem supports, used to match |
| requirements in suites or scenarios. Any combination of: |
| - 'a5_0' |
| - 'a5_1' |
| - 'a5_2' |
| - 'a5_3' |
| - 'a5_4' |
| - 'a5_5' |
| - 'a5_6' |
| - 'a5_7' |
| 'features'::: |
| List of features that this modem supports, used to match requirements in |
| suites or scenarios. Any combination of: |
| - 'sms' |
| - 'gprs' |
| - 'voice' |
| - 'ussd' |
| |
| Side note: at first sight it might make sense to the reader to rather structure |
| e.g. the 'ip_address' 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 <<paths_conf>>. |
| |
| 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' or a |
| 'resources.conf' providing a similar setting always has precedence over the |
| values given in a 'defaults.conf'). |
| |
| Example of a 'defaults.conf': |
| |
| ---- |
| nitb: |
| net: |
| mcc: 901 |
| mnc: 70 |
| short_name: osmo-gsm-tester-nitb |
| long_name: osmo-gsm-tester-nitb |
| auth_policy: closed |
| encryption: a5_0 |
| |
| bsc: |
| net: |
| mcc: 901 |
| mnc: 70 |
| short_name: osmo-gsm-tester-msc |
| long_name: osmo-gsm-tester-msc |
| auth_policy: closed |
| encryption: a5_0 |
| authentication: optional |
| |
| msc: |
| net: |
| mcc: 901 |
| mnc: 70 |
| short_name: osmo-gsm-tester-msc |
| long_name: osmo-gsm-tester-msc |
| auth_policy: closed |
| encryption: a5_0 |
| authentication: optional |
| |
| bsc_bts: |
| location_area_code: 23 |
| base_station_id_code: 63 |
| stream_id: 255 |
| osmobsc_bts_type: sysmobts |
| trx_list: |
| - nominal_power: 23 |
| max_power_red: 0 |
| 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 |
| ---- |