This is merely a historical archive of years 2008-2021, before the migration to mailman3.
A maintained and still updated list archive can be found at https://lists.osmocom.org/hyperkitty/list/gerrit-log@lists.osmocom.org/.
pespin gerrit-no-reply at lists.osmocom.orgpespin has uploaded this change for review. ( https://gerrit.osmocom.org/c/osmo-gsm-tester/+/18215 ) Change subject: doc/manuals: Swap order of schemas and config files ...................................................................... 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 --- M doc/manuals/chapters/config.adoc 1 file changed, 211 insertions(+), 211 deletions(-) git pull ssh://gerrit.osmocom.org:29418/osmo-gsm-tester refs/changes/15/18215/1 diff --git a/doc/manuals/chapters/config.adoc b/doc/manuals/chapters/config.adoc index c302cd6..fec5c87 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 <<main_conf,main.conf>>, 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 <<resources_conf,resources.conf>> -file. Hence, the <<resources_conf,resources.conf>> contains a list of elements -for each resource type. This schema is also used and extended by the -<<schema_want,'want' schema>>. - -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 <<schema_resources,resources>> 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_resources,resources>> 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 <<suite_conf,suite.conf>> - and tests being able to later retrieve them through 'testenv' API. - -[[schema_all]] -==== Schema 'all' - -This schema is basically an aggregated namespace for <<schema_want,want>> schema -and <<schema_config,config>> schema, and is the one used by -<<suite_conf,suite.conf>> and <<scenario_conf,scenario.conf>> files. It contains -these main element sections::: - -[[schema_all_sec_resources]] -- Section 'resources': Contains a set of elements validated with <<schema_want,want>> - schema. In <<suite_conf,suite.conf>> it is used to construct the list of - requested resources. In <<scenario_conf,scenario.conf>>, it is used to inject - attributes to the initial <<suite_conf,suite.conf>> _resources_ section and - hence further restrain it. -[[schema_all_sec_modifiers]] -- Section 'modifiers': Both in <<suite_conf,suite.conf>> and - <<scenario_conf,scenario.conf>>, values presented in here are injected into - the content of the <<schema_all_sec_resources,resources section>> 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 - <<schema_all_sec_resources,resources section>>, it is clear that the - <<schema_want,want schema>> 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 - <<schema_all_sec_modifiers,modifiers>>. They can overwrite values provided in the - <<defaults_conf,defaults.conf>> file. Content in this section follows the - <<schema_config,config>> 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 @@ - 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 <<main_conf,main.conf>>, 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 <<resources_conf,resources.conf>> +file. Hence, the <<resources_conf,resources.conf>> contains a list of elements +for each resource type. This schema is also used and extended by the +<<schema_want,'want' schema>>. + +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 <<schema_resources,resources>> 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_resources,resources>> 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 <<suite_conf,suite.conf>> + and tests being able to later retrieve them through 'testenv' API. + +[[schema_all]] +==== Schema 'all' + +This schema is basically an aggregated namespace for <<schema_want,want>> schema +and <<schema_config,config>> schema, and is the one used by +<<suite_conf,suite.conf>> and <<scenario_conf,scenario.conf>> files. It contains +these main element sections::: + +[[schema_all_sec_resources]] +- Section 'resources': Contains a set of elements validated with <<schema_want,want>> + schema. In <<suite_conf,suite.conf>> it is used to construct the list of + requested resources. In <<scenario_conf,scenario.conf>>, it is used to inject + attributes to the initial <<suite_conf,suite.conf>> _resources_ section and + hence further restrain it. +[[schema_all_sec_modifiers]] +- Section 'modifiers': Both in <<suite_conf,suite.conf>> and + <<scenario_conf,scenario.conf>>, values presented in here are injected into + the content of the <<schema_all_sec_resources,resources section>> 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 + <<schema_all_sec_resources,resources section>>, it is clear that the + <<schema_want,want schema>> 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 + <<schema_all_sec_modifiers,modifiers>>. They can overwrite values provided in the + <<defaults_conf,defaults.conf>> file. Content in this section follows the + <<schema_config,config>> 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 -- To view, visit https://gerrit.osmocom.org/c/osmo-gsm-tester/+/18215 To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: osmo-gsm-tester Gerrit-Branch: master Gerrit-Change-Id: Iaf31808a655a5c77a1dfaa155e86d42585130820 Gerrit-Change-Number: 18215 Gerrit-PatchSet: 1 Gerrit-Owner: pespin <pespin at sysmocom.de> Gerrit-MessageType: newchange -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.osmocom.org/pipermail/gerrit-log/attachments/20200512/71cae0fb/attachment.htm>