From fceb8e14dec6267461d899effc4f738327d83628 Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Tue, 12 May 2020 13:04:00 +0200 Subject: [PATCH] doc/manuals: Swap order of schemas and config files First explain the different config files and directories, later describe the schemas used in each of them. Change-Id: Iaf31808a655a5c77a1dfaa155e86d42585130820 --- doc/manuals/chapters/config.adoc | 422 +++++++++++++++---------------- 1 file changed, 211 insertions(+), 211 deletions(-) diff --git a/doc/manuals/chapters/config.adoc b/doc/manuals/chapters/config.adoc index c302cd69..fec5c878 100644 --- a/doc/manuals/chapters/config.adoc +++ b/doc/manuals/chapters/config.adoc @@ -1,216 +1,5 @@ == Configuration -=== Schemas - -All configuration attributes in {app-name} are stored and provided as YAML -files, which are handled internally mostly as sets of dictionaries, lists and -scalars. Each of these configurations have a known format (set of keys and -values), which is called 'schema'. Each provided configuration is validated -against its 'schema' at parse time. Hence, 'schemas' can be seen as a namespace -containing a structured tree of configuration attributes. Each attribute has a -schema type assigned which constrains the type of value it can hold. - -There are several well-known schemas used across {app-name}, and they are -described in following sub-sections. - -[[schema_main_cfg]] -==== Schema 'main config' - -This schema defines all the attributes available in {app-name} the main -configuration file <>, and it is used to validate it. - -[[schema_resources]] -==== Schema 'resources' - -This schema defines all the attributes which can be assigned to -a _resource_, and it is used to validate the <> -file. Hence, the <> contains a list of elements -for each resource type. This schema is also used and extended by the -<>. - -It is important to understand that the content in this schema refers to a list of -resources for each resource class. Since a list is ordered by definition, it -clearly identifies specific resources by order. This is important when applying -filters or modifiers, since they are applied per-resource in the list. One can -for instance apply attribute A to first resource of class C, while not applying -it or applying another attribute B to second resources of the same class. As a -result, complex forms can be used to filter and modify a list of resources -required by a testsuite. - -On the other hand, it's also important to note that lists for simple or scalar -types are currently being treated as unordered sets, which mean combination of -filters or modifiers apply differently. In the future, it may be possible to -have both behaviors for scalar/simple types by using also the YAML 'set' type in -{app-name}. - -//TODO: update this list and use a table for each resource type in its own object section -//// -These kinds of resources and their attributes 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' -//// - -[[schema_want]] -==== Schema 'want' - -This schema is basically the same as the <> one, but -with an extra 'times' attribute for each resource item. All 'times' attributes -are expanded before matching. For example, if a 'suite.conf' requests two BTS, -one 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 ----- - -[[schema_config]] -==== Schema 'config' - -This schema defines all the attributes which can be used by object classes or -tests during test execution. The main difference between this schema and the -<> schema is that the former contains configuration -to be applied globally for all objects being used, while the later applies -attributes to a specific object in the list of allocated resources. This schema -hence allows setting attributes for objects which are not allocated as resources -and hence not directly accessible through scenarios, like a BSC or an iperf3 -client. - -This schema is built dynamically at runtime from content registered by: -- object classes registering their own attributes -- test suite registering their own attributes through <> - and tests being able to later retrieve them through 'testenv' API. - -[[schema_all]] -==== Schema 'all' - -This schema is basically an aggregated namespace for <> schema -and <> schema, and is the one used by -<> and <> files. It contains -these main element sections::: - -[[schema_all_sec_resources]] -- Section 'resources': Contains a set of elements validated with <> - schema. In <> it is used to construct the list of - requested resources. In <>, it is used to inject - attributes to the initial <> _resources_ section and - hence further restrain it. -[[schema_all_sec_modifiers]] -- Section 'modifiers': Both in <> and - <>, values presented in here are injected into - the content of the <> after - _resource_ allocation, hereby overwriting attributes passed to the object - class instance managing the specific _resource_ (matches by resource type and - list position). Since it is combined with the content of - <>, it is clear that the - <> is used to validate this content. -[[schema_all_sec_config]] -- Section 'config': Contains configuration attributes for {app-name} object - classes which are not _resources_, and hence cannot be configured with - <>. They can overwrite values provided in the - <> file. Content in this section follows the - <> schema. - -//TODO: defaults.timeout should be change in code to be config.test_timeout or similar -//TODO: 'config' should be split into its own schema and validate defaults.conf - [[config]] === Configuration files and directories @@ -642,6 +431,217 @@ bsc_bts: - phys_chan_config: TCH/F_TCH/H_PDCH ---- +=== Schemas + +All configuration attributes in {app-name} are stored and provided as YAML +files, which are handled internally mostly as sets of dictionaries, lists and +scalars. Each of these configurations have a known format (set of keys and +values), which is called 'schema'. Each provided configuration is validated +against its 'schema' at parse time. Hence, 'schemas' can be seen as a namespace +containing a structured tree of configuration attributes. Each attribute has a +schema type assigned which constrains the type of value it can hold. + +There are several well-known schemas used across {app-name}, and they are +described in following sub-sections. + +[[schema_main_cfg]] +==== Schema 'main config' + +This schema defines all the attributes available in {app-name} the main +configuration file <>, and it is used to validate it. + +[[schema_resources]] +==== Schema 'resources' + +This schema defines all the attributes which can be assigned to +a _resource_, and it is used to validate the <> +file. Hence, the <> contains a list of elements +for each resource type. This schema is also used and extended by the +<>. + +It is important to understand that the content in this schema refers to a list of +resources for each resource class. Since a list is ordered by definition, it +clearly identifies specific resources by order. This is important when applying +filters or modifiers, since they are applied per-resource in the list. One can +for instance apply attribute A to first resource of class C, while not applying +it or applying another attribute B to second resources of the same class. As a +result, complex forms can be used to filter and modify a list of resources +required by a testsuite. + +On the other hand, it's also important to note that lists for simple or scalar +types are currently being treated as unordered sets, which mean combination of +filters or modifiers apply differently. In the future, it may be possible to +have both behaviors for scalar/simple types by using also the YAML 'set' type in +{app-name}. + +//TODO: update this list and use a table for each resource type in its own object section +//// +These kinds of resources and their attributes 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' +//// + +[[schema_want]] +==== Schema 'want' + +This schema is basically the same as the <> one, but +with an extra 'times' attribute for each resource item. All 'times' attributes +are expanded before matching. For example, if a 'suite.conf' requests two BTS, +one 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 +---- + +[[schema_config]] +==== Schema 'config' + +This schema defines all the attributes which can be used by object classes or +tests during test execution. The main difference between this schema and the +<> schema is that the former contains configuration +to be applied globally for all objects being used, while the later applies +attributes to a specific object in the list of allocated resources. This schema +hence allows setting attributes for objects which are not allocated as resources +and hence not directly accessible through scenarios, like a BSC or an iperf3 +client. + +This schema is built dynamically at runtime from content registered by: +- object classes registering their own attributes +- test suite registering their own attributes through <> + and tests being able to later retrieve them through 'testenv' API. + +[[schema_all]] +==== Schema 'all' + +This schema is basically an aggregated namespace for <> schema +and <> schema, and is the one used by +<> and <> files. It contains +these main element sections::: + +[[schema_all_sec_resources]] +- Section 'resources': Contains a set of elements validated with <> + schema. In <> it is used to construct the list of + requested resources. In <>, it is used to inject + attributes to the initial <> _resources_ section and + hence further restrain it. +[[schema_all_sec_modifiers]] +- Section 'modifiers': Both in <> and + <>, values presented in here are injected into + the content of the <> after + _resource_ allocation, hereby overwriting attributes passed to the object + class instance managing the specific _resource_ (matches by resource type and + list position). Since it is combined with the content of + <>, it is clear that the + <> is used to validate this content. +[[schema_all_sec_config]] +- Section 'config': Contains configuration attributes for {app-name} object + classes which are not _resources_, and hence cannot be configured with + <>. They can overwrite values provided in the + <> file. Content in this section follows the + <> schema. + +//TODO: defaults.timeout should be change in code to be config.test_timeout or similar +//TODO: 'config' should be split into its own schema and validate defaults.conf + === Example Setup {app-name} comes with an example official setup which is the one used to run