cosmetic: OsmoGSMTester: fix dir name
All other subdirs are without dashes, but I added Osmo-GSM-Tester with dashes.
Comply with the naming scheme and remove dashes.
Change-Id: I36d0c94dde5deffba04b27436ae499a42c519bec
diff --git a/doc/manuals/chapters/config.adoc b/doc/manuals/chapters/config.adoc
new file mode 100644
index 0000000..66f4b71
--- /dev/null
+++ b/doc/manuals/chapters/config.adoc
@@ -0,0 +1,225 @@
+== 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
+<<resources_conf_example>>.
+
+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 <<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' 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