340 lines
10 KiB
Plaintext
340 lines
10 KiB
Plaintext
== 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'
|
|
----
|
|
|
|
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'.
|
|
|
|
[[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
|
|
----
|