summaryrefslogtreecommitdiffstats
path: root/doc/manuals/chapters/config.adoc
blob: def9843f1a9e935085ebe06ccd88b65405f8f397 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
== 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
----