<p>pespin <strong>submitted</strong> this change.</p><p><a href="https://gerrit.osmocom.org/c/osmo-gsm-tester/+/17447">View Change</a></p><div style="white-space:pre-wrap">Approvals:
pespin: Looks good to me, approved
Jenkins Builder: Verified
</div><pre style="font-family: monospace,monospace; white-space: pre-wrap;">doc/manual: Refactor, rewrite, improve and update most of the User Manual<br><br>* Some TODOs are added as comments which actually require code changes.<br> These are details which showed up as incongruences or missing bits<br> while writing the documentation for them.<br><br>* Some sections are introduced but still waiting to be writen soon:<br>** Debugging section<br>** Docker Setup section<br>** Ansible Setup section<br>** Troubleshooting (add jenkins red cross button sending kill -9)<br>** resources.conf attribute list needs to be converted to a table<br><br>* Device related setup needs to be updated and extended<br>* Parametrized scenarios need to be documented<br>* 4G resources documentation needs to be added.<br><br>Change-Id: Ifc2a3c74d45336cc988b76c0ff68a85311e4dd40<br>---<br>M .gitignore<br>A doc/manuals/chapters/ansible.adoc<br>M doc/manuals/chapters/config.adoc<br>A doc/manuals/chapters/docker.adoc<br>M doc/manuals/chapters/install.adoc<br>A doc/manuals/chapters/install_device.adoc<br>M doc/manuals/chapters/intro.adoc<br>A doc/manuals/chapters/resource_pool.adoc<br>M doc/manuals/chapters/trial.adoc<br>A doc/manuals/chapters/troubleshooting.adoc<br>M doc/manuals/osmo-gsm-tester-manual-docinfo.xml<br>M doc/manuals/osmo-gsm-tester-manual.adoc<br>12 files changed, 930 insertions(+), 767 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/.gitignore b/.gitignore</span><br><span>index 47e9f86..f281be1 100644</span><br><span>--- a/.gitignore</span><br><span>+++ b/.gitignore</span><br><span>@@ -19,6 +19,6 @@</span><br><span> doc/manuals/*__*.png</span><br><span> doc/manuals/*.check</span><br><span> doc/manuals/generated/</span><br><span style="color: hsl(0, 100%, 40%);">-doc/manuals/osmomsc-usermanual.xml</span><br><span style="color: hsl(120, 100%, 40%);">+doc/manuals/osmo-gsm-tester-manual.xml</span><br><span> doc/manuals/common</span><br><span> doc/manuals/build</span><br><span>diff --git a/doc/manuals/chapters/ansible.adoc b/doc/manuals/chapters/ansible.adoc</span><br><span>new file mode 100644</span><br><span>index 0000000..b672528</span><br><span>--- /dev/null</span><br><span>+++ b/doc/manuals/chapters/ansible.adoc</span><br><span>@@ -0,0 +1,6 @@</span><br><span style="color: hsl(120, 100%, 40%);">+[[ansible]]</span><br><span style="color: hsl(120, 100%, 40%);">+== Ansible Setup</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Available in osmocom's osmo-ci.git subdirectory 'ansible/', see there 'gsm-tester/README.md'.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+//TODO: Explain more where to find, how to build, how to use.</span><br><span>diff --git a/doc/manuals/chapters/config.adoc b/doc/manuals/chapters/config.adoc</span><br><span>index 7e250e0..bb0cec2 100644</span><br><span>--- a/doc/manuals/chapters/config.adoc</span><br><span>+++ b/doc/manuals/chapters/config.adoc</span><br><span>@@ -1,166 +1,43 @@</span><br><span> == Configuration</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-[[config_paths]]</span><br><span style="color: hsl(0, 100%, 40%);">-=== Config Paths</span><br><span style="color: hsl(120, 100%, 40%);">+=== Schemas</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-The osmo-gsm-tester looks for configuration files in various standard</span><br><span style="color: hsl(0, 100%, 40%);">-directories in this order:</span><br><span style="color: hsl(120, 100%, 40%);">+All configuration attributes in {app-name} are stored and provided as YAML</span><br><span style="color: hsl(120, 100%, 40%);">+files, which are handled internally mostly as sets of dictionaries, lists and</span><br><span style="color: hsl(120, 100%, 40%);">+scalars. Each of these configurations have a known format, which is called</span><br><span style="color: hsl(120, 100%, 40%);">+'schema'. Each provided configuration is validated against its 'schema' at parse</span><br><span style="color: hsl(120, 100%, 40%);">+time. Hence, 'schemas' can be seen as a namespace containing a structured tree</span><br><span style="color: hsl(120, 100%, 40%);">+of configuration attributes. Each attribute has a schema type assigned which</span><br><span style="color: hsl(120, 100%, 40%);">+constrains the type of value it can hold.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-- '$HOME/.config/osmo-gsm-tester/'</span><br><span style="color: hsl(0, 100%, 40%);">-- '/usr/local/etc/osmo-gsm-tester/'</span><br><span style="color: hsl(0, 100%, 40%);">-- '/etc/osmo-gsm-tester/'</span><br><span style="color: hsl(120, 100%, 40%);">+There are several well-known schemas used across {app-name}, and they are</span><br><span style="color: hsl(120, 100%, 40%);">+described in following sub-sections.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-The config location can also be set by an environment variable</span><br><span style="color: hsl(0, 100%, 40%);">-'$OSMO_GSM_TESTER_CONF', which then overrides the above locations.</span><br><span style="color: hsl(120, 100%, 40%);">+[[schema_resources]]</span><br><span style="color: hsl(120, 100%, 40%);">+==== Schema 'resources'</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-The osmo-gsm-tester expects to find the following configuration files in a</span><br><span style="color: hsl(0, 100%, 40%);">-configuration directory:</span><br><span style="color: hsl(120, 100%, 40%);">+This schema defines all the attributes which can be assigned to</span><br><span style="color: hsl(120, 100%, 40%);">+a _resource_, and it is used to validate the <<resources_conf,resources.conf>></span><br><span style="color: hsl(120, 100%, 40%);">+file. Hence, the <<resources_conf,resources.conf>> contains a list of elements</span><br><span style="color: hsl(120, 100%, 40%);">+for each resource type.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-- 'paths.conf'</span><br><span style="color: hsl(0, 100%, 40%);">-- 'resources.conf'</span><br><span style="color: hsl(0, 100%, 40%);">-- 'default-suites.conf' (optional)</span><br><span style="color: hsl(0, 100%, 40%);">-- 'defaults.conf' (optional)</span><br><span style="color: hsl(120, 100%, 40%);">+It is important to understand that the content in this schema refers to a list of</span><br><span style="color: hsl(120, 100%, 40%);">+resources for each resource class. Since a list is ordered by definition, it</span><br><span style="color: hsl(120, 100%, 40%);">+clearly identifies specific resources by order. This is important when applying</span><br><span style="color: hsl(120, 100%, 40%);">+filters or modifiers, since they are applied per-resource in the list. One can</span><br><span style="color: hsl(120, 100%, 40%);">+for instance apply attribute A to first resource of class C, while not applying</span><br><span style="color: hsl(120, 100%, 40%);">+it or applying another attribute B to second resources of the same class. As a</span><br><span style="color: hsl(120, 100%, 40%);">+result, complex forms can be used to filter and modify a list of resources</span><br><span style="color: hsl(120, 100%, 40%);">+required by a testsuite.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-These are described in detail in the following sections.</span><br><span style="color: hsl(120, 100%, 40%);">+On the other hand, it's also important to note that lists for simple or scalar</span><br><span style="color: hsl(120, 100%, 40%);">+types are currently being treated as unordered sets, which mean combination of</span><br><span style="color: hsl(120, 100%, 40%);">+filters or modifiers apply differently. In the future, it may be possible to</span><br><span style="color: hsl(120, 100%, 40%);">+have both behaviors for scalar/simple types by using also the YAML 'set' type in</span><br><span style="color: hsl(120, 100%, 40%);">+{app-handle}.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-=== Format: YAML, and its Drawbacks</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-The general configuration format used is YAML. The stock python YAML parser</span><br><span style="color: hsl(0, 100%, 40%);">-does have several drawbacks: too many complex possibilities and alternative</span><br><span style="color: hsl(0, 100%, 40%);">-ways of formatting a configuration, but at the time of writing seems to be the</span><br><span style="color: hsl(0, 100%, 40%);">-only widely used configuration format that offers a simple and human readable</span><br><span style="color: hsl(0, 100%, 40%);">-formatting as well as nested structuring. It is recommended to use only the</span><br><span style="color: hsl(0, 100%, 40%);">-exact YAML subset seen in this manual in case the osmo-gsm-tester should move</span><br><span style="color: hsl(0, 100%, 40%);">-to a less bloated parser in the future.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Careful: if a configuration item consists of digits and starts with a zero, you</span><br><span style="color: hsl(0, 100%, 40%);">-need to quote it, or it may be interpreted as an octal notation integer! Please</span><br><span style="color: hsl(0, 100%, 40%);">-avoid using the octal notation on purpose, it is not provided intentionally.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-[[paths_conf]]</span><br><span style="color: hsl(0, 100%, 40%);">-=== 'paths.conf'</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-The 'paths.conf' file defines where to store the global state (of reserved</span><br><span style="color: hsl(0, 100%, 40%);">-resources) and where to find suite and scenario definitions.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Any relative paths found in a 'paths.conf' file are interpreted as relative to</span><br><span style="color: hsl(0, 100%, 40%);">-the directory of that 'paths.conf' file.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Example:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-state_dir: '/var/tmp/osmo-gsm-tester/state'</span><br><span style="color: hsl(0, 100%, 40%);">-suites_dir: '/usr/local/src/osmo-gsm-tester/suites'</span><br><span style="color: hsl(0, 100%, 40%);">-scenarios_dir: './scenarios'</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-[[state_dir]]</span><br><span style="color: hsl(0, 100%, 40%);">-==== 'state_dir'</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-It contains global or system-wide state for osmo-gsm-tester. In a typical state</span><br><span style="color: hsl(0, 100%, 40%);">-dir you can find the following files:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-'last_used_msisdn.state'::</span><br><span style="color: hsl(0, 100%, 40%);">- Contains last used msisdn number, which is automatically increased every</span><br><span style="color: hsl(0, 100%, 40%);">- time osmo-gsm-tester needs to assign a new subscriber in a test.</span><br><span style="color: hsl(0, 100%, 40%);">-'lock'::</span><br><span style="color: hsl(0, 100%, 40%);">- Lock file used to implement a mutual exclusion zone around the</span><br><span style="color: hsl(0, 100%, 40%);">- 'reserved_resources.state' file.</span><br><span style="color: hsl(0, 100%, 40%);">-'reserved_resources.state'::</span><br><span style="color: hsl(0, 100%, 40%);">- File containing a set of reserved resources by any number of</span><br><span style="color: hsl(0, 100%, 40%);">- osmo-gsm-tester instances. Each osmo-gsm-tester instance is responsible</span><br><span style="color: hsl(0, 100%, 40%);">- to clear its resources from the list once it is done using them and are</span><br><span style="color: hsl(0, 100%, 40%);">- no longer reserved.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-If you would like to set up several separate configurations (not typical), note</span><br><span style="color: hsl(0, 100%, 40%);">-that the 'state_dir' is used to reserve resources, which only works when all</span><br><span style="color: hsl(0, 100%, 40%);">-configurations that share resources also use the same 'state_dir'.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-This way, several concurrent users of osmo-gsm-tester (ie. several</span><br><span style="color: hsl(0, 100%, 40%);">-osmo-gsm-tester processes running in parallel) can run without interfering with</span><br><span style="color: hsl(0, 100%, 40%);">-each other (e.g. using same ARFCN, same IP or same ofono modem path).</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-[[suites_dir]]</span><br><span style="color: hsl(0, 100%, 40%);">-==== 'suites_dir'</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Suites contain a set of tests which are designed to be run together to test a</span><br><span style="color: hsl(0, 100%, 40%);">-set of features given a specific set of resources. As a result, resources are</span><br><span style="color: hsl(0, 100%, 40%);">-allocated per suite and not per test.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Tests for a given suite are located in the form of '.py' python scripts in the</span><br><span style="color: hsl(0, 100%, 40%);">-same directory where the 'suite.conf' lays.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-[[scenarios_dir]]</span><br><span style="color: hsl(0, 100%, 40%);">-==== 'scenarios_dir'</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-This dir contains scenario configuration files.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Scenarios define constraints to serve the resource requests of a 'suite.conf',</span><br><span style="color: hsl(0, 100%, 40%);">-to select specific resources from the general resource pool specified in 'resources.conf'.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-All 'times' attributes are expanded before matching. For example, if a 'suite.conf'</span><br><span style="color: hsl(0, 100%, 40%);">-requests two BTS, we may enforce that both BTS should be of type 'osmo-bts-sysmo' in</span><br><span style="color: hsl(0, 100%, 40%);">-these ways:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-resources:</span><br><span style="color: hsl(0, 100%, 40%);">- bts:</span><br><span style="color: hsl(0, 100%, 40%);">- - type: osmo-bts-sysmo</span><br><span style="color: hsl(0, 100%, 40%);">- - type: osmo-bts-sysmo</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-or alternatively,</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-resources:</span><br><span style="color: hsl(0, 100%, 40%);">- bts:</span><br><span style="color: hsl(0, 100%, 40%);">- - times: 2</span><br><span style="color: hsl(0, 100%, 40%);">- type: osmo-bts-sysmo</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-If only one resource is specified in the scenario, then the resource allocator</span><br><span style="color: hsl(0, 100%, 40%);">-assumes the restriction is to be applied to the first resource and that remaining</span><br><span style="color: hsl(0, 100%, 40%);">-resources have no restrictions to be taken into consideration.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-To apply restrictions only on the second resource, the first element can be left</span><br><span style="color: hsl(0, 100%, 40%);">-emtpy, like:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-resources:</span><br><span style="color: hsl(0, 100%, 40%);">- bts:</span><br><span style="color: hsl(0, 100%, 40%);">- - {}</span><br><span style="color: hsl(0, 100%, 40%);">- - type: osmo-bts-sysmo</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-On the 'osmo_gsm_tester.py' command line and the 'default_suites.conf', any number of</span><br><span style="color: hsl(0, 100%, 40%);">-such scenario configurations can be combined in the form:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-<suite_name>:<scenario>[+<scenario>[+...]]</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-e.g.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-my_suite:sysmo+tch_f+amr</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-[[resources_conf]]</span><br><span style="color: hsl(0, 100%, 40%);">-=== 'resources.conf'</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-The 'resources.conf' file defines which hardware is connected to the main unit,</span><br><span style="color: hsl(0, 100%, 40%);">-as well as which limited configuration items (like IP addresses or ARFCNs)</span><br><span style="color: hsl(0, 100%, 40%);">-should be used.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-These resources are allocated dynamically and are not configured explicitly:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-- MSISDN: phone numbers are dealt out to test scripts in sequence on request.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-A 'resources.conf' is structured as a list of items for each resource type,</span><br><span style="color: hsl(0, 100%, 40%);">-where each item has one or more settings -- for an example, see</span><br><span style="color: hsl(0, 100%, 40%);">-<<resources_conf_example>>.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-These kinds of resource are known:</span><br><span style="color: hsl(120, 100%, 40%);">+//TODO: update this list and use a table for each resource type</span><br><span style="color: hsl(120, 100%, 40%);">+These kinds of resources and their attributes are known:</span><br><span> </span><br><span> 'ip_address'::</span><br><span> List of IP addresses to run osmo-nitb instances on. The main unit</span><br><span>@@ -251,6 +128,278 @@</span><br><span> - 'voice'</span><br><span> - 'ussd'</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+[[schema_want]]</span><br><span style="color: hsl(120, 100%, 40%);">+==== Schema 'want'</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This schema is basically the same as the <<schema_resources,resources>> one, but</span><br><span style="color: hsl(120, 100%, 40%);">+with an extra 'times' attribute for each resource item. All 'times' attributes</span><br><span style="color: hsl(120, 100%, 40%);">+are expanded before matching. For example, if a 'suite.conf' requests two BTS,</span><br><span style="color: hsl(120, 100%, 40%);">+one may enforce that both BTS should be of type 'osmo-bts-sysmo' in these ways:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+resources:</span><br><span style="color: hsl(120, 100%, 40%);">+ bts:</span><br><span style="color: hsl(120, 100%, 40%);">+ - type: osmo-bts-sysmo</span><br><span style="color: hsl(120, 100%, 40%);">+ - type: osmo-bts-sysmo</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+or alternatively,</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+resources:</span><br><span style="color: hsl(120, 100%, 40%);">+ bts:</span><br><span style="color: hsl(120, 100%, 40%);">+ - times: 2</span><br><span style="color: hsl(120, 100%, 40%);">+ type: osmo-bts-sysmo</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[schema_conf]]</span><br><span style="color: hsl(120, 100%, 40%);">+==== Schema 'conf'</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This schema is used by <<suite_conf,suite.conf>> and <<scenario_conf,scenario.conf>> files. It contains 3 main element sections:::</span><br><span style="color: hsl(120, 100%, 40%);">+[[schema_conf_sec_resources]]</span><br><span style="color: hsl(120, 100%, 40%);">+- Section 'resources': Contains a set of elements validated with <<schema_resources,resources>></span><br><span style="color: hsl(120, 100%, 40%);">+ schema. In <<suite_conf,suite.conf>> it is used to construct the list of</span><br><span style="color: hsl(120, 100%, 40%);">+ requested resources. In <<scenario_conf,scenario.conf>>, it is used to inject</span><br><span style="color: hsl(120, 100%, 40%);">+ attributes to the initial <<suites_conf,suites.conf>> _resources_ section and</span><br><span style="color: hsl(120, 100%, 40%);">+ hence further restrain it.</span><br><span style="color: hsl(120, 100%, 40%);">+[[schema_conf_sec_modifiers]]</span><br><span style="color: hsl(120, 100%, 40%);">+- Section 'modifiers': Both in <<suite_conf,suite.conf>> and</span><br><span style="color: hsl(120, 100%, 40%);">+ <<scenario_conf,scenario.conf>>, values presented in here are injected into</span><br><span style="color: hsl(120, 100%, 40%);">+ the content of the <<schema_conf_sec_resources,resources section>> after</span><br><span style="color: hsl(120, 100%, 40%);">+ _resource_ allocation, hereby overwriting attributes passed to the object</span><br><span style="color: hsl(120, 100%, 40%);">+ class instance managing the specific _resource_ (matches by resource type and</span><br><span style="color: hsl(120, 100%, 40%);">+ list position). Since it is combined with the content of</span><br><span style="color: hsl(120, 100%, 40%);">+ <<schema_conf_sec_resources,resources section>>, it is clear that the</span><br><span style="color: hsl(120, 100%, 40%);">+ <<schema_resources,resources schema>> is used to validate this content.</span><br><span style="color: hsl(120, 100%, 40%);">+[[schema_conf_sec_config]]</span><br><span style="color: hsl(120, 100%, 40%);">+- Section 'config': Contains configuration attributes for {app-name} classes which are</span><br><span style="color: hsl(120, 100%, 40%);">+ not _resources_, and hence cannot be configured with <<schema_modifiers,modifiers>>.</span><br><span style="color: hsl(120, 100%, 40%);">+ They can overwrite values provided in the <<defaults_conf,defaults.conf>> file.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+//TODO: defaults.timeout should be change in code to be config.test_timeout or similar</span><br><span style="color: hsl(120, 100%, 40%);">+//TODO: 'config' should be split into its own schema and validate defaults.conf</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[config_paths]]</span><br><span style="color: hsl(120, 100%, 40%);">+=== Config Paths</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The osmo-gsm-tester looks for configuration files in various standard</span><br><span style="color: hsl(120, 100%, 40%);">+directories in this order:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+- '$HOME/.config/osmo-gsm-tester/'</span><br><span style="color: hsl(120, 100%, 40%);">+- '/usr/local/etc/osmo-gsm-tester/'</span><br><span style="color: hsl(120, 100%, 40%);">+- '/etc/osmo-gsm-tester/'</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The config location can also be set by an environment variable</span><br><span style="color: hsl(120, 100%, 40%);">+'$OSMO_GSM_TESTER_CONF', which then overrides the above locations.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The osmo-gsm-tester expects to find the following configuration files in a</span><br><span style="color: hsl(120, 100%, 40%);">+configuration directory:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+- <<paths_conf,paths.conf>></span><br><span style="color: hsl(120, 100%, 40%);">+- <<resource_conf,resources.conf>></span><br><span style="color: hsl(120, 100%, 40%);">+- <<default_suites_conf,default-suites.conf>> (optional)</span><br><span style="color: hsl(120, 100%, 40%);">+- <<defaults_conf,defaults.conf>> (optional)</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+These are described in detail in the following sections.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[paths_conf]]</span><br><span style="color: hsl(120, 100%, 40%);">+==== 'paths.conf'</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The 'paths.conf' file defines where to store the global state (of reserved</span><br><span style="color: hsl(120, 100%, 40%);">+resources) and where to find suite and scenario definitions.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Any relative paths found in a 'paths.conf' file are interpreted as relative to</span><br><span style="color: hsl(120, 100%, 40%);">+the directory of that 'paths.conf' file.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+There's not yet any well-known schema to validate this file contents since it</span><br><span style="color: hsl(120, 100%, 40%);">+has only 3 attributes.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.Sample paths.conf file:</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+state_dir: '/var/tmp/osmo-gsm-tester/state'</span><br><span style="color: hsl(120, 100%, 40%);">+suites_dir: '/usr/local/src/osmo-gsm-tester/suites'</span><br><span style="color: hsl(120, 100%, 40%);">+scenarios_dir: './scenarios'</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[state_dir]]</span><br><span style="color: hsl(120, 100%, 40%);">+===== 'state_dir'</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+It contains global or system-wide state for osmo-gsm-tester. In a typical state</span><br><span style="color: hsl(120, 100%, 40%);">+dir you can find the following files:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+'last_used_*.state'::</span><br><span style="color: hsl(120, 100%, 40%);">+ Contains stateful content spanning accross {app-name} instances and</span><br><span style="color: hsl(120, 100%, 40%);">+ runs. For instance, 'last used msisdn number.state' is automatically</span><br><span style="color: hsl(120, 100%, 40%);">+ (and atomically) increased every time osmo-gsm-tester needs to assign a</span><br><span style="color: hsl(120, 100%, 40%);">+ new subscriber in a test, ensuring tests get unique msisdn numbers.</span><br><span style="color: hsl(120, 100%, 40%);">+'reserved_resources.state'::</span><br><span style="color: hsl(120, 100%, 40%);">+ File containing a set of reserved resources by any number of</span><br><span style="color: hsl(120, 100%, 40%);">+ osmo-gsm-tester instances (aka pool of allocated resources). Each</span><br><span style="color: hsl(120, 100%, 40%);">+ osmo-gsm-tester instance is responsible to clear its resources from the</span><br><span style="color: hsl(120, 100%, 40%);">+ list once it is done using them and are no longer reserved.</span><br><span style="color: hsl(120, 100%, 40%);">+'lock'::</span><br><span style="color: hsl(120, 100%, 40%);">+ Lock file used to implement a mutual exclusion zone around any state</span><br><span style="color: hsl(120, 100%, 40%);">+ files in the 'state_dir', to prevent race conditions between different</span><br><span style="color: hsl(120, 100%, 40%);">+ {app-name} instances running in parallel.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This way, several concurrent users of osmo-gsm-tester (ie. several</span><br><span style="color: hsl(120, 100%, 40%);">+osmo-gsm-tester processes running in parallel) can run without interfering with</span><br><span style="color: hsl(120, 100%, 40%);">+each other (e.g. using same ARFCN, same IP or same ofono modem path).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+If you would like to set up several separate configurations (not typical), note</span><br><span style="color: hsl(120, 100%, 40%);">+that the 'state_dir' is used to reserve resources, which only works when all</span><br><span style="color: hsl(120, 100%, 40%);">+configurations that share resources also use the same 'state_dir'. It's also</span><br><span style="color: hsl(120, 100%, 40%);">+important to notice that since resources are stored in YAML dictionary form, if</span><br><span style="color: hsl(120, 100%, 40%);">+same physical device is described differently in several</span><br><span style="color: hsl(120, 100%, 40%);">+<<resource_conf,resources.conf>> files (used by different {app-name} instances),</span><br><span style="color: hsl(120, 100%, 40%);">+resource allocation may not work as expected.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[suites_dir]]</span><br><span style="color: hsl(120, 100%, 40%);">+===== 'suites_dir'</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Suites contain a set of tests which are designed to be run together to test a</span><br><span style="color: hsl(120, 100%, 40%);">+set of features given a specific set of resources. As a result, resources are</span><br><span style="color: hsl(120, 100%, 40%);">+allocated per suite and not per test.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Tests for a given suite are located in the form of '.py' python scripts in the</span><br><span style="color: hsl(120, 100%, 40%);">+same directory where the <<suite_conf,suite.conf>> lays.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Tests in the same testsuite willing to use some shared code can do so by putting</span><br><span style="color: hsl(120, 100%, 40%);">+it eg. in '$suites_dir/$suitename/lib/testlib.py':</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+#!/usr/bin/env python3</span><br><span style="color: hsl(120, 100%, 40%);">+from osmo_gsm_tester.testenv import *</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+def my_shared_code(foo):</span><br><span style="color: hsl(120, 100%, 40%);">+ return foo.bar()</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+and then in the test itself use it this way:</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+#!/usr/bin/env python3</span><br><span style="color: hsl(120, 100%, 40%);">+from osmo_gsm_tester.testenv import *</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+import testlib</span><br><span style="color: hsl(120, 100%, 40%);">+suite.test_import_modules_register_for_cleanup(testlib)</span><br><span style="color: hsl(120, 100%, 40%);">+from testlib import my_shared_code</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+bar = my_shared_code(foo)</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.Sample 'suites_dir' directory tree:</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+suites_dir/</span><br><span style="color: hsl(120, 100%, 40%);">+|-- suiteA</span><br><span style="color: hsl(120, 100%, 40%);">+| |-- suite.conf</span><br><span style="color: hsl(120, 100%, 40%);">+| '-- testA.py</span><br><span style="color: hsl(120, 100%, 40%);">+|-- suiteB</span><br><span style="color: hsl(120, 100%, 40%);">+| |-- testB.py</span><br><span style="color: hsl(120, 100%, 40%);">+| |-- testC.py</span><br><span style="color: hsl(120, 100%, 40%);">+| |-- lib</span><br><span style="color: hsl(120, 100%, 40%);">+| | '-- testlib.py</span><br><span style="color: hsl(120, 100%, 40%);">+| '-- suite.conf</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[suite_conf]]</span><br><span style="color: hsl(120, 100%, 40%);">+===== 'suite.conf'</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This file content is parsed using the <<schema_want,Want>> schema.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+It provides</span><br><span style="color: hsl(120, 100%, 40%);">+{app-name} with the base restrictions (later to be further filtered by</span><br><span style="color: hsl(120, 100%, 40%);">+<<scenario_conf,scenario>> files) to apply when allocating resources.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+It can also override attributes for the allocated resources through the</span><br><span style="color: hsl(120, 100%, 40%);">+<<schema_want,modifiers>> section (to be further modified by</span><br><span style="color: hsl(120, 100%, 40%);">+<<scenario_conf,scenario>> files later on). Similary it can do the same for</span><br><span style="color: hsl(120, 100%, 40%);">+general configuration options (no per-resource) through the</span><br><span style="color: hsl(120, 100%, 40%);">+<<schema_want,config>> section.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.Sample 'suite.conf' file:</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+resources:</span><br><span style="color: hsl(120, 100%, 40%);">+ ip_address:</span><br><span style="color: hsl(120, 100%, 40%);">+ - times: 9 # msc, bsc, hlr, stp, mgw*2, sgsn, ggsn, iperf3srv</span><br><span style="color: hsl(120, 100%, 40%);">+ bts:</span><br><span style="color: hsl(120, 100%, 40%);">+ - times: 1</span><br><span style="color: hsl(120, 100%, 40%);">+ modem:</span><br><span style="color: hsl(120, 100%, 40%);">+ - times: 2</span><br><span style="color: hsl(120, 100%, 40%);">+ features:</span><br><span style="color: hsl(120, 100%, 40%);">+ - gprs</span><br><span style="color: hsl(120, 100%, 40%);">+ - voice</span><br><span style="color: hsl(120, 100%, 40%);">+ - times: 2</span><br><span style="color: hsl(120, 100%, 40%);">+ features:</span><br><span style="color: hsl(120, 100%, 40%);">+ - gprs</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+config:</span><br><span style="color: hsl(120, 100%, 40%);">+ bsc:</span><br><span style="color: hsl(120, 100%, 40%);">+ net:</span><br><span style="color: hsl(120, 100%, 40%);">+ codec_list:</span><br><span style="color: hsl(120, 100%, 40%);">+ - fr1</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+defaults:</span><br><span style="color: hsl(120, 100%, 40%);">+ timeout: 50s</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[scenarios_dir]]</span><br><span style="color: hsl(120, 100%, 40%);">+===== 'scenarios_dir'</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This dir contains scenario configuration files.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.Sample 'scenarios_dir' directory tree:</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+scenarios_dir/</span><br><span style="color: hsl(120, 100%, 40%);">+|-- scenarioA.conf</span><br><span style="color: hsl(120, 100%, 40%);">+'-- scenarioB.conf</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[scenario_conf]]</span><br><span style="color: hsl(120, 100%, 40%);">+===== 'scenario conf file'</span><br><span style="color: hsl(120, 100%, 40%);">+Scenarios define further constraints to serve the resource requests of a</span><br><span style="color: hsl(120, 100%, 40%);">+<<suite_conf,suite.conf>>, ie. to select specific resources from the general</span><br><span style="color: hsl(120, 100%, 40%);">+resource pool specified in <<resource_conf,resources.conf>>.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+If only one resource is specified in the scenario, then the resource allocator</span><br><span style="color: hsl(120, 100%, 40%);">+assumes the restriction is to be applied to the first resource and that remaining</span><br><span style="color: hsl(120, 100%, 40%);">+resources have no restrictions to be taken into consideration.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+To apply restrictions only on the second resource, the first element can be left</span><br><span style="color: hsl(120, 100%, 40%);">+emtpy, like:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+resources:</span><br><span style="color: hsl(120, 100%, 40%);">+ bts:</span><br><span style="color: hsl(120, 100%, 40%);">+ - {}</span><br><span style="color: hsl(120, 100%, 40%);">+ - type: osmo-bts-sysmo</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+On the 'osmo_gsm_tester.py' command line and the</span><br><span style="color: hsl(120, 100%, 40%);">+<<default_suites_conf,default_suites.conf>>, any number of such scenario</span><br><span style="color: hsl(120, 100%, 40%);">+configurations can be combined in the form:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+<suite_name>:<scenario>[+<scenario>[+...]]</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+e.g.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+my_suite:sysmo+tch_f+amr</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[resources_conf]]</span><br><span style="color: hsl(120, 100%, 40%);">+==== 'resources.conf'</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+//TODO: update this section</span><br><span style="color: hsl(120, 100%, 40%);">+The 'resources.conf' file defines which hardware is connected to the main unit,</span><br><span style="color: hsl(120, 100%, 40%);">+as well as which limited configuration items (like IP addresses or ARFCNs)</span><br><span style="color: hsl(120, 100%, 40%);">+should be used.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+A 'resources.conf' is validated by the <<schema_resources,resources schema>>.</span><br><span style="color: hsl(120, 100%, 40%);">+That means it is structured as a list of items for each resource type, where</span><br><span style="color: hsl(120, 100%, 40%);">+each item has one or more attributes -- for an example, see</span><br><span style="color: hsl(120, 100%, 40%);">+<<resources_conf_example>>.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> Side note: at first sight it might make sense to the reader to rather structure</span><br><span> e.g. the 'ip_address' or 'arfcn' configuration as +</span><br><span> '"arfcn: GSM-1800: [512, 514, ...]"', +</span><br><span>@@ -262,25 +411,22 @@</span><br><span> available (yet).</span><br><span> </span><br><span> [[default_suites]]</span><br><span style="color: hsl(0, 100%, 40%);">-=== 'default-suites.conf' (optional)</span><br><span style="color: hsl(120, 100%, 40%);">+==== 'default-suites.conf' (optional)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-The 'default-suites.conf' file contains a list of 'suite:scenario+scenario+...'</span><br><span style="color: hsl(120, 100%, 40%);">+The 'default-suites.conf' file contains a YAML list of 'suite:scenario+scenario+...'</span><br><span> combination strings as defined by the 'osmo-gsm-tester.py -s' commandline</span><br><span> option. If invoking the 'osmo-gsm-tester.py' without any suite definitions, the</span><br><span> '-s' arguments are taken from this file instead. Each of these suite + scenario</span><br><span> combinations is run in sequence.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-A suite name must match the name of a directory in the 'suites_dir' as defined</span><br><span style="color: hsl(0, 100%, 40%);">-by 'paths.conf'.</span><br><span style="color: hsl(120, 100%, 40%);">+A suite name must match the name of a directory in the</span><br><span style="color: hsl(120, 100%, 40%);">+<<suites_dir,suites_dir/>> as defined by <<paths_conf,paths.conf>>.</span><br><span> </span><br><span> A scenario name must match the name of a configuration file in the</span><br><span style="color: hsl(0, 100%, 40%);">-'scenarios_dir' as defined by 'paths.conf' (optionally without the '.conf'</span><br><span style="color: hsl(0, 100%, 40%);">-suffix).</span><br><span style="color: hsl(120, 100%, 40%);">+<<scenarios_dir,scnearios_dir/>> as defined by <<paths_conf,paths.conf>></span><br><span style="color: hsl(120, 100%, 40%);">+(optionally without the '.conf' suffix).</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-For 'paths.conf', see <<paths_conf>>.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Example of a 'default-suites.conf' file:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(120, 100%, 40%);">+.Sample 'default-suites.conf' file:</span><br><span> ----</span><br><span> - sms:sysmo</span><br><span> - voice:sysmo+tch_f</span><br><span>@@ -292,24 +438,28 @@</span><br><span> - voice:trx+dyn_ts</span><br><span> ----</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-=== 'defaults.conf' (optional)</span><br><span style="color: hsl(120, 100%, 40%);">+==== 'defaults.conf' (optional)</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+In {app-name} object instances requested by the test and created by the suite</span><br><span style="color: hsl(120, 100%, 40%);">+relate to a specific allocated resource. That's not always the case, and even if</span><br><span style="color: hsl(120, 100%, 40%);">+it the case the information stored in <<resources_conf,resources.conf>> for that</span><br><span style="color: hsl(120, 100%, 40%);">+resource may not contain tons of attributes which the object class needs to</span><br><span style="color: hsl(120, 100%, 40%);">+manage the resource.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+For this exact reason, the 'defaults.conf' file exist. It contains a set of</span><br><span style="color: hsl(120, 100%, 40%);">+default attributes and values (in YAML format) that object classes can use to</span><br><span style="color: hsl(120, 100%, 40%);">+fill in the missing gaps, or to provide values which can easily be changed or</span><br><span style="color: hsl(120, 100%, 40%);">+overwritten by <<suite_conf,suite.conf>> or <<scenario_conf,scenario.conf>></span><br><span style="color: hsl(120, 100%, 40%);">+files through modifiers.</span><br><span> </span><br><span> Each binary run by osmo-gsm-tester, e.g. 'osmo-nitb' or 'osmo-bts-sysmo',</span><br><span> typically has a configuration file template that is populated with values for a</span><br><span style="color: hsl(0, 100%, 40%);">-trial run.</span><br><span style="color: hsl(120, 100%, 40%);">+trial run. Hence, a <<suite_conf,suite.conf>>, <<scenario_conf,scenario.conf>></span><br><span style="color: hsl(120, 100%, 40%);">+or a <<resources_conf,resources.conf>> providing a similar setting always has</span><br><span style="color: hsl(120, 100%, 40%);">+precedence over the values given in a 'defaults.conf'</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-Some of these values are provided by the 'resources.conf' from the allocated</span><br><span style="color: hsl(0, 100%, 40%);">-resource(s), but not all values can be populated this way: some osmo-nitb</span><br><span style="color: hsl(0, 100%, 40%);">-configuration values like the network name, encryption algorithm or timeslot</span><br><span style="color: hsl(0, 100%, 40%);">-channel combinations are in fact not resources (only the nitb's interface</span><br><span style="color: hsl(0, 100%, 40%);">-address is). These additional settings may be provided by the scenario</span><br><span style="color: hsl(0, 100%, 40%);">-configurations, but in case the provided scenarios leave some values unset,</span><br><span style="color: hsl(0, 100%, 40%);">-they are taken from this 'defaults.conf'. (A 'scenario.conf' or a</span><br><span style="color: hsl(0, 100%, 40%);">-'resources.conf' providing a similar setting always has precedence over the</span><br><span style="color: hsl(0, 100%, 40%);">-values given in a 'defaults.conf').</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-Example of a 'defaults.conf':</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(120, 100%, 40%);">+.Sample 'defaults.conf' file:</span><br><span> ----</span><br><span> nitb:</span><br><span> net:</span><br><span>@@ -359,3 +509,53 @@</span><br><span> - phys_chan_config: TCH/F_TCH/H_PDCH</span><br><span> - phys_chan_config: TCH/F_TCH/H_PDCH</span><br><span> ----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Example Setup</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+{app-name} comes with an example official setup which is the one used to run</span><br><span style="color: hsl(120, 100%, 40%);">+Osmocom's setup. There are actually two different available setups: a</span><br><span style="color: hsl(120, 100%, 40%);">+production one and an RnD one, used to develop {app-name} itself. These two set</span><br><span style="color: hsl(120, 100%, 40%);">+ups share mostly all configuration, main difference being the</span><br><span style="color: hsl(120, 100%, 40%);">+<<resources_conf,resources.conf>> file being used.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+All {app-name} related configuration for that environment is publicly available in 'osmo-gsm-tester.git' itself:::</span><br><span style="color: hsl(120, 100%, 40%);">+- <<paths_conf,paths.conf>>: Available Available under 'example/', with its paths already configured to take</span><br><span style="color: hsl(120, 100%, 40%);">+ required bits from inside the git repository.</span><br><span style="color: hsl(120, 100%, 40%);">+- <<suite_dir,suites_dir>>: Available under 'suites/'</span><br><span style="color: hsl(120, 100%, 40%);">+- <<scenarios_dir,scenarios_dir>>: Available under 'example/scenarios/'</span><br><span style="color: hsl(120, 100%, 40%);">+- <<resource_conf,resources.conf>>: Available under 'example/' as</span><br><span style="color: hsl(120, 100%, 40%);">+ 'resources.conf.prod' for Production setup and as 'resources.conf.rnd' for the</span><br><span style="color: hsl(120, 100%, 40%);">+ RnD setup. One must use a symbolic link to have it available as 'resources.conf'.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+//TODO: resources.conf file path should be modifiable through paths.conf!</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== Typical Invocations</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Each invocation of osmo-gsm-tester deploys a set of pre-compiled binaries for</span><br><span style="color: hsl(120, 100%, 40%);">+the Osmocom core network as well as for the Osmocom based BTS models. To create</span><br><span style="color: hsl(120, 100%, 40%);">+such a set of binaries, see <<trials>>.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Examples for launching test trials:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+- Run the default suites (see <<default_suites>>) on a given set of binaries:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+osmo-gsm-tester.py path/to/my-trial</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+- Run an explicit choice of 'suite:scenario' combinations:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+osmo-gsm-tester.py path/to/my-trial -s sms:sysmo -s sms:trx -s sms:nanobts</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+- Run one 'suite:scenario1+scenario2' combination, setting log level to 'debug'</span><br><span style="color: hsl(120, 100%, 40%);">+ and enabling logging of full python tracebacks, and also only run just the</span><br><span style="color: hsl(120, 100%, 40%);">+ 'mo_mt_sms.py' test from the suite, e.g. to investigate a test failure:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+osmo-gsm-tester.py path/to/my-trial -s sms:sysmo+foobar -l dbg -T -t mo_mt</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+A test script may also be run step-by-step in a python debugger, see</span><br><span style="color: hsl(120, 100%, 40%);">+<<debugging>>.</span><br><span>diff --git a/doc/manuals/chapters/docker.adoc b/doc/manuals/chapters/docker.adoc</span><br><span>new file mode 100644</span><br><span>index 0000000..b7560e1</span><br><span>--- /dev/null</span><br><span>+++ b/doc/manuals/chapters/docker.adoc</span><br><span>@@ -0,0 +1,6 @@</span><br><span style="color: hsl(120, 100%, 40%);">+[[docker]]</span><br><span style="color: hsl(120, 100%, 40%);">+== Docker Setup</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Available in osmocom's docker-playground.git subdirectory 'osmo-gsm-tester/'.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+//TODO: Explain more where to find, how to build, how to use.</span><br><span>diff --git a/doc/manuals/chapters/install.adoc b/doc/manuals/chapters/install.adoc</span><br><span>index d19f909..e062b8d 100644</span><br><span>--- a/doc/manuals/chapters/install.adoc</span><br><span>+++ b/doc/manuals/chapters/install.adoc</span><br><span>@@ -1,49 +1,11 @@</span><br><span style="color: hsl(0, 100%, 40%);">-== Installation on Main Unit</span><br><span style="color: hsl(120, 100%, 40%);">+== {app-name} Installation</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-The main unit is a general purpose computer that orchestrates the tests. It</span><br><span style="color: hsl(0, 100%, 40%);">-runs the core network components, controls the modems and so on. This can be</span><br><span style="color: hsl(0, 100%, 40%);">-anything from a dedicated production rack unit to your laptop at home.</span><br><span style="color: hsl(120, 100%, 40%);">+=== Trial Builder</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-This manual will assume that tests are run from a jenkins build slave, by a user</span><br><span style="color: hsl(0, 100%, 40%);">-named 'jenkins' that belong to group 'osmo-gsm-tester'. The user configuration</span><br><span style="color: hsl(0, 100%, 40%);">-for manual test runs and/or a different user name is identical, simply replace</span><br><span style="color: hsl(0, 100%, 40%);">-the user name or group.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-=== Osmo-gsm-tester Dependencies</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-On a Debian/Ubuntu based system, these commands install the packages needed to</span><br><span style="color: hsl(0, 100%, 40%);">-run the osmo-gsm-tester.py code, i.e. install these on your main unit:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-apt-get install \</span><br><span style="color: hsl(0, 100%, 40%);">- dbus \</span><br><span style="color: hsl(0, 100%, 40%);">- tcpdump \</span><br><span style="color: hsl(0, 100%, 40%);">- sqlite3 \</span><br><span style="color: hsl(0, 100%, 40%);">- python3 \</span><br><span style="color: hsl(0, 100%, 40%);">- python3-yaml \</span><br><span style="color: hsl(0, 100%, 40%);">- python3-mako \</span><br><span style="color: hsl(0, 100%, 40%);">- python3-gi \</span><br><span style="color: hsl(0, 100%, 40%);">- ofono \</span><br><span style="color: hsl(0, 100%, 40%);">- patchelf \</span><br><span style="color: hsl(0, 100%, 40%);">- sudo \</span><br><span style="color: hsl(0, 100%, 40%);">- libcap2-bin \</span><br><span style="color: hsl(0, 100%, 40%);">- python3-pip</span><br><span style="color: hsl(0, 100%, 40%);">-pip3 install pydbus</span><br><span style="color: hsl(0, 100%, 40%);">-pip3 install git+git://github.com/podshumok/python-smpplib.git</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-IMPORTANT: ofono may need to be installed from source to contain the most</span><br><span style="color: hsl(0, 100%, 40%);">-recent fixes needed to operate your modems. This depends on the modem hardware</span><br><span style="color: hsl(0, 100%, 40%);">-used and the tests run. Please see <<hardware_modems>>.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-To run osmo-bts-trx with a USRP attached, you may need to install a UHD driver.</span><br><span style="color: hsl(0, 100%, 40%);">-Please refer to http://osmocom.org/projects/osmotrx/wiki/OsmoTRX#UHD for</span><br><span style="color: hsl(0, 100%, 40%);">-details; the following is an example for the B200 family USRP devices:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-apt-get install libuhd-dev uhd-host</span><br><span style="color: hsl(0, 100%, 40%);">-/usr/lib/uhd/utils/uhd_images_downloader.py</span><br><span>-----</span><br><span style="color: hsl(120, 100%, 40%);">+The Trial Builder is the jenkins build slave (host) building all sysroot binary</span><br><span style="color: hsl(120, 100%, 40%);">+packages used later by {app-name} to run the tests. It's purpose is to build the</span><br><span style="color: hsl(120, 100%, 40%);">+sysroots and provide them to {app-anme}, for instance, as jenkins job artifacts</span><br><span style="color: hsl(120, 100%, 40%);">+which the {app-name} runner job can fetch.</span><br><span> </span><br><span> [[jenkins_deps]]</span><br><span> ==== Osmocom Build Dependencies</span><br><span>@@ -56,11 +18,109 @@</span><br><span> osmo-bts-sysmo build needs the sysmoBTS SDK installed on the build slave, which</span><br><span> should match the installed sysmoBTS firmware.</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+==== Add Build Jobs</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+There are various jenkins-build-* scripts in osmo-gsm-tester/contrib/, which</span><br><span style="color: hsl(120, 100%, 40%);">+can be called as jenkins build jobs to build and bundle binaries as artifacts,</span><br><span style="color: hsl(120, 100%, 40%);">+to be run on the osmo-gsm-tester main unit and/or BTS hardware.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Be aware of the dependencies, as hinted at in <<jenkins_deps>>.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+While the various binaries could technically be built on the osmo-gsm-tester</span><br><span style="color: hsl(120, 100%, 40%);">+main unit, it is recommended to use a separate build slave, to take load off</span><br><span style="color: hsl(120, 100%, 40%);">+of the main unit.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Please note nowadays we set up all the osmocom jenkins jobs (including</span><br><span style="color: hsl(120, 100%, 40%);">+{app-name} ones) using 'jenkins-job-builder'. You can find all the</span><br><span style="color: hsl(120, 100%, 40%);">+configuration's in Osmocom's 'osmo-ci.git' files 'jobs/osmo-gsm-tester-*.yml.</span><br><span style="color: hsl(120, 100%, 40%);">+Explanation below on how to set up jobs manually is left as a reference for</span><br><span style="color: hsl(120, 100%, 40%);">+other projects.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+On your jenkins master, set up build jobs to call these scripts -- typically</span><br><span style="color: hsl(120, 100%, 40%);">+one build job per script. Look in contrib/ and create one build job for each of</span><br><span style="color: hsl(120, 100%, 40%);">+the BTS types you would like to test, as well as one for the 'build-osmo-nitb'.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+These are generic steps to configure a jenkins build</span><br><span style="color: hsl(120, 100%, 40%);">+job for each of these build scripts, by example of the</span><br><span style="color: hsl(120, 100%, 40%);">+jenkins-build-osmo-nitb.sh script; all that differs to the other scripts is the</span><br><span style="color: hsl(120, 100%, 40%);">+"osmo-nitb" part:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* 'Project name': "osmo-gsm-tester_build-osmo-nitb" +</span><br><span style="color: hsl(120, 100%, 40%);">+ (Replace 'osmo-nitb' according to which build script this is for)</span><br><span style="color: hsl(120, 100%, 40%);">+* 'Discard old builds' +</span><br><span style="color: hsl(120, 100%, 40%);">+ Configure this to taste, for example:</span><br><span style="color: hsl(120, 100%, 40%);">+** 'Max # of build to keep': "20"</span><br><span style="color: hsl(120, 100%, 40%);">+* 'Restrict where this project can be run': Choose a build slave label that</span><br><span style="color: hsl(120, 100%, 40%);">+ matches the main unit's architecture and distribution, typically a Debian</span><br><span style="color: hsl(120, 100%, 40%);">+ system, e.g.: "linux_amd64_debian8"</span><br><span style="color: hsl(120, 100%, 40%);">+* 'Source Code Management':</span><br><span style="color: hsl(120, 100%, 40%);">+** 'Git'</span><br><span style="color: hsl(120, 100%, 40%);">+*** 'Repository URL': "git://git.osmocom.org/osmo-gsm-tester"</span><br><span style="color: hsl(120, 100%, 40%);">+*** 'Branch Specifier': "*/master"</span><br><span style="color: hsl(120, 100%, 40%);">+*** 'Additional Behaviors'</span><br><span style="color: hsl(120, 100%, 40%);">+**** 'Check out to a sub-directory': "osmo-gsm-tester"</span><br><span style="color: hsl(120, 100%, 40%);">+* 'Build Triggers' +</span><br><span style="color: hsl(120, 100%, 40%);">+ The decision on when to build is complex. Here are some examples:</span><br><span style="color: hsl(120, 100%, 40%);">+** Once per day: +</span><br><span style="color: hsl(120, 100%, 40%);">+ 'Build periodically': "H H * * *"</span><br><span style="color: hsl(120, 100%, 40%);">+** For the Osmocom project, the purpose is to verify our software changes.</span><br><span style="color: hsl(120, 100%, 40%);">+ Hence we would like to test every time our code has changed:</span><br><span style="color: hsl(120, 100%, 40%);">+*** We could add various git repositories to watch, and enable 'Poll SCM'.</span><br><span style="color: hsl(120, 100%, 40%);">+*** On jenkins.osmocom.org, we have various jobs that build the master branches</span><br><span style="color: hsl(120, 100%, 40%);">+ of their respective git repositories when a new change was merged. Here, we</span><br><span style="color: hsl(120, 100%, 40%);">+ can thus trigger e.g. an osmo-nitb build for osmo-gsm-tester everytime the</span><br><span style="color: hsl(120, 100%, 40%);">+ master build has run: +</span><br><span style="color: hsl(120, 100%, 40%);">+ 'Build after other projects are built': "OpenBSC"</span><br><span style="color: hsl(120, 100%, 40%);">+*** Note that most of the Osmocom projects also need to be re-tested when their</span><br><span style="color: hsl(120, 100%, 40%);">+ dependencies like libosmo* have changed. Triggering on all those changes</span><br><span style="color: hsl(120, 100%, 40%);">+ typically causes more jenkins runs than necessary: for example, it rebuilds</span><br><span style="color: hsl(120, 100%, 40%);">+ once per each dependency that has rebuilt due to one libosmocore change.</span><br><span style="color: hsl(120, 100%, 40%);">+ There is so far no trivial way known to avoid this. It is indeed safest to</span><br><span style="color: hsl(120, 100%, 40%);">+ rebuild more often.</span><br><span style="color: hsl(120, 100%, 40%);">+* 'Build'</span><br><span style="color: hsl(120, 100%, 40%);">+** 'Execute Shell'</span><br><span style="color: hsl(120, 100%, 40%);">++</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+#!/bin/sh</span><br><span style="color: hsl(120, 100%, 40%);">+set -e -x</span><br><span style="color: hsl(120, 100%, 40%);">+./osmo-gsm-tester/contrib/jenkins-build-osmo-nitb.sh</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">++</span><br><span style="color: hsl(120, 100%, 40%);">+(Replace 'osmo-nitb' according to which build script this is for)</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* 'Post-build Actions'</span><br><span style="color: hsl(120, 100%, 40%);">+** 'Archive the artifacts': "*.tgz, *.md5" +</span><br><span style="color: hsl(120, 100%, 40%);">+ (This step is important to be able to use the built binaries in the run job</span><br><span style="color: hsl(120, 100%, 40%);">+ below.)</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+TIP: When you've created one build job, it is convenient to create further</span><br><span style="color: hsl(120, 100%, 40%);">+build jobs by copying the first one and, e.g., simply replacing all "osmo-nitb"</span><br><span style="color: hsl(120, 100%, 40%);">+with "osmo-bts-trx".</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[install_main_unit]]</span><br><span style="color: hsl(120, 100%, 40%);">+=== Main Unit</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The main unit is a general purpose computer that orchestrates the tests. It</span><br><span style="color: hsl(120, 100%, 40%);">+runs the core network components, controls the modems and so on. This can be</span><br><span style="color: hsl(120, 100%, 40%);">+anything from a dedicated production rack unit to your laptop at home.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This manual will assume that tests are run from a jenkins build slave, by a user</span><br><span style="color: hsl(120, 100%, 40%);">+named 'jenkins' that belongs to group 'osmo-gsm-tester'. The user configuration</span><br><span style="color: hsl(120, 100%, 40%);">+for manual test runs and/or a different user name is identical, simply replace</span><br><span style="color: hsl(120, 100%, 40%);">+the user name or group.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Please, note installation steps and dependencies needed will depend on lots of</span><br><span style="color: hsl(120, 100%, 40%);">+factors, like your distribution, your specific setup, which hardware you plan to</span><br><span style="color: hsl(120, 100%, 40%);">+support, etc.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This section aims at being one place to document the rationale behind certain</span><br><span style="color: hsl(120, 100%, 40%);">+configurations being done in one way or another. For an up to date step by step</span><br><span style="color: hsl(120, 100%, 40%);">+detailed way to install and maintain the Osmocom {app-name} setup, one will want</span><br><span style="color: hsl(120, 100%, 40%);">+to look at the <<ansible,ansible scripts section>>.</span><br><span> </span><br><span> [[configure_jenkins_slave]]</span><br><span style="color: hsl(0, 100%, 40%);">-=== Jenkins Build and Run Slave</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-==== Create 'jenkins' User on Main Unit</span><br><span style="color: hsl(120, 100%, 40%);">+==== Create 'jenkins' User</span><br><span> </span><br><span> On the main unit, create a jenkins user:</span><br><span> </span><br><span>@@ -176,81 +236,6 @@</span><br><span> </span><br><span> The build slave should be able to start now.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-==== Add Build Jobs</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-There are various jenkins-build-* scripts in osmo-gsm-tester/contrib/, which</span><br><span style="color: hsl(0, 100%, 40%);">-can be called as jenkins build jobs to build and bundle binaries as artifacts,</span><br><span style="color: hsl(0, 100%, 40%);">-to be run on the osmo-gsm-tester main unit and/or BTS hardware.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Be aware of the dependencies, as hinted at in <<jenkins_deps>>.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-While the various binaries could technically be built on the osmo-gsm-tester</span><br><span style="color: hsl(0, 100%, 40%);">-main unit, it is recommended to use a separate build slave, to take load off</span><br><span style="color: hsl(0, 100%, 40%);">-of the main unit.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-On your jenkins master, set up build jobs to call these scripts -- typically</span><br><span style="color: hsl(0, 100%, 40%);">-one build job per script. Look in contrib/ and create one build job for each of</span><br><span style="color: hsl(0, 100%, 40%);">-the BTS types you would like to test, as well as one for the 'build-osmo-nitb'.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-These are generic steps to configure a jenkins build</span><br><span style="color: hsl(0, 100%, 40%);">-job for each of these build scripts, by example of the</span><br><span style="color: hsl(0, 100%, 40%);">-jenkins-build-osmo-nitb.sh script; all that differs to the other scripts is the</span><br><span style="color: hsl(0, 100%, 40%);">-"osmo-nitb" part:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-* 'Project name': "osmo-gsm-tester_build-osmo-nitb" +</span><br><span style="color: hsl(0, 100%, 40%);">- (Replace 'osmo-nitb' according to which build script this is for)</span><br><span style="color: hsl(0, 100%, 40%);">-* 'Discard old builds' +</span><br><span style="color: hsl(0, 100%, 40%);">- Configure this to taste, for example:</span><br><span style="color: hsl(0, 100%, 40%);">-** 'Max # of build to keep': "20"</span><br><span style="color: hsl(0, 100%, 40%);">-* 'Restrict where this project can be run': Choose a build slave label that</span><br><span style="color: hsl(0, 100%, 40%);">- matches the main unit's architecture and distribution, typically a Debian</span><br><span style="color: hsl(0, 100%, 40%);">- system, e.g.: "linux_amd64_debian8"</span><br><span style="color: hsl(0, 100%, 40%);">-* 'Source Code Management':</span><br><span style="color: hsl(0, 100%, 40%);">-** 'Git'</span><br><span style="color: hsl(0, 100%, 40%);">-*** 'Repository URL': "git://git.osmocom.org/osmo-gsm-tester"</span><br><span style="color: hsl(0, 100%, 40%);">-*** 'Branch Specifier': "*/master"</span><br><span style="color: hsl(0, 100%, 40%);">-*** 'Additional Behaviors'</span><br><span style="color: hsl(0, 100%, 40%);">-**** 'Check out to a sub-directory': "osmo-gsm-tester"</span><br><span style="color: hsl(0, 100%, 40%);">-* 'Build Triggers' +</span><br><span style="color: hsl(0, 100%, 40%);">- The decision on when to build is complex. Here are some examples:</span><br><span style="color: hsl(0, 100%, 40%);">-** Once per day: +</span><br><span style="color: hsl(0, 100%, 40%);">- 'Build periodically': "H H * * *"</span><br><span style="color: hsl(0, 100%, 40%);">-** For the Osmocom project, the purpose is to verify our software changes.</span><br><span style="color: hsl(0, 100%, 40%);">- Hence we would like to test every time our code has changed:</span><br><span style="color: hsl(0, 100%, 40%);">-*** We could add various git repositories to watch, and enable 'Poll SCM'.</span><br><span style="color: hsl(0, 100%, 40%);">-*** On jenkins.osmocom.org, we have various jobs that build the master branches</span><br><span style="color: hsl(0, 100%, 40%);">- of their respective git repositories when a new change was merged. Here, we</span><br><span style="color: hsl(0, 100%, 40%);">- can thus trigger e.g. an osmo-nitb build for osmo-gsm-tester everytime the</span><br><span style="color: hsl(0, 100%, 40%);">- master build has run: +</span><br><span style="color: hsl(0, 100%, 40%);">- 'Build after other projects are built': "OpenBSC"</span><br><span style="color: hsl(0, 100%, 40%);">-*** Note that most of the Osmocom projects also need to be re-tested when their</span><br><span style="color: hsl(0, 100%, 40%);">- dependencies like libosmo* have changed. Triggering on all those changes</span><br><span style="color: hsl(0, 100%, 40%);">- typically causes more jenkins runs than necessary: for example, it rebuilds</span><br><span style="color: hsl(0, 100%, 40%);">- once per each dependency that has rebuilt due to one libosmocore change.</span><br><span style="color: hsl(0, 100%, 40%);">- There is so far no trivial way known to avoid this. It is indeed safest to</span><br><span style="color: hsl(0, 100%, 40%);">- rebuild more often.</span><br><span style="color: hsl(0, 100%, 40%);">-* 'Build'</span><br><span style="color: hsl(0, 100%, 40%);">-** 'Execute Shell'</span><br><span style="color: hsl(0, 100%, 40%);">-+</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-#!/bin/sh</span><br><span style="color: hsl(0, 100%, 40%);">-set -e -x</span><br><span style="color: hsl(0, 100%, 40%);">-./osmo-gsm-tester/contrib/jenkins-build-osmo-nitb.sh</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-+</span><br><span style="color: hsl(0, 100%, 40%);">-(Replace 'osmo-nitb' according to which build script this is for)</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-* 'Post-build Actions'</span><br><span style="color: hsl(0, 100%, 40%);">-** 'Archive the artifacts': "*.tgz, *.md5" +</span><br><span style="color: hsl(0, 100%, 40%);">- (This step is important to be able to use the built binaries in the run job</span><br><span style="color: hsl(0, 100%, 40%);">- below.)</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-TIP: When you've created one build job, it is convenient to create further</span><br><span style="color: hsl(0, 100%, 40%);">-build jobs by copying the first and, e.g., simply replacing all "osmo-nitb"</span><br><span style="color: hsl(0, 100%, 40%);">-with "osmo-bts-trx".</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span> ==== Add Run Job</span><br><span> </span><br><span> This is the jenkins job that runs the tests on the GSM hardware:</span><br><span>@@ -258,6 +243,15 @@</span><br><span> * It sources the artifacts from jenkins' build jobs.</span><br><span> * It runs on the osmo-gsm-tester main unit.</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+Sample script to run {app-name} as a jenkins job can be found in</span><br><span style="color: hsl(120, 100%, 40%);">+'osmo-gsm-tester.git' file 'contrib/jenkins-run.sh'.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Please note nowadays we set up all the osmocom jenkins jobs (including</span><br><span style="color: hsl(120, 100%, 40%);">+{app-name} ones) using 'jenkins-job-builder'. You can find all the</span><br><span style="color: hsl(120, 100%, 40%);">+configuration's in Osmocom's 'osmo-ci.git' files 'jobs/osmo-gsm-tester-*.yml.</span><br><span style="color: hsl(120, 100%, 40%);">+Explanation below on how to set up jobs manually is left as a reference for</span><br><span style="color: hsl(120, 100%, 40%);">+other projects.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> Here is the configuration for the run job:</span><br><span> </span><br><span> * 'Project name': "osmo-gsm-tester_run"</span><br><span>@@ -330,10 +324,47 @@</span><br><span> and 'trial-N-bin.tgz' archives are produced by the 'jenkins-run.sh' script,</span><br><span> both for successful and failing runs.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-=== Install osmo-gsm-tester on Main Unit</span><br><span style="color: hsl(120, 100%, 40%);">+==== Install osmo-gsm-tester</span><br><span> </span><br><span> This assumes you have already created the jenkins user (see <<configure_jenkins_slave>>).</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+Dependencies needed will depend on lots of factors, like your distribution, your</span><br><span style="color: hsl(120, 100%, 40%);">+specific setup, which hardware you plan to support, etc.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+On a Debian/Ubuntu based system, these commands install the packages needed to</span><br><span style="color: hsl(120, 100%, 40%);">+run the osmo-gsm-tester.py code, i.e. install these on your main unit:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+apt-get install \</span><br><span style="color: hsl(120, 100%, 40%);">+ dbus \</span><br><span style="color: hsl(120, 100%, 40%);">+ tcpdump \</span><br><span style="color: hsl(120, 100%, 40%);">+ sqlite3 \</span><br><span style="color: hsl(120, 100%, 40%);">+ python3 \</span><br><span style="color: hsl(120, 100%, 40%);">+ python3-setuptools \</span><br><span style="color: hsl(120, 100%, 40%);">+ python3-yaml \</span><br><span style="color: hsl(120, 100%, 40%);">+ python3-mako \</span><br><span style="color: hsl(120, 100%, 40%);">+ python3-gi \</span><br><span style="color: hsl(120, 100%, 40%);">+ python3-numpy \</span><br><span style="color: hsl(120, 100%, 40%);">+ python3-wheel \</span><br><span style="color: hsl(120, 100%, 40%);">+ ofono \</span><br><span style="color: hsl(120, 100%, 40%);">+ patchelf \</span><br><span style="color: hsl(120, 100%, 40%);">+ sudo \</span><br><span style="color: hsl(120, 100%, 40%);">+ libcap2-bin \</span><br><span style="color: hsl(120, 100%, 40%);">+ python3-pip \</span><br><span style="color: hsl(120, 100%, 40%);">+ udhcpc \</span><br><span style="color: hsl(120, 100%, 40%);">+ iperf3 \</span><br><span style="color: hsl(120, 100%, 40%);">+ locales</span><br><span style="color: hsl(120, 100%, 40%);">+pip3 install \</span><br><span style="color: hsl(120, 100%, 40%);">+ "git+https://github.com/podshumok/python-smpplib.git@master#egg=smpplib" \</span><br><span style="color: hsl(120, 100%, 40%);">+ pydbus \</span><br><span style="color: hsl(120, 100%, 40%);">+ pyusb \</span><br><span style="color: hsl(120, 100%, 40%);">+ pysispm</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+IMPORTANT: ofono may need to be installed from source to contain the most</span><br><span style="color: hsl(120, 100%, 40%);">+recent fixes needed to operate your modems. This depends on the modem hardware</span><br><span style="color: hsl(120, 100%, 40%);">+used and the tests run. Please see <<hardware_modems>>.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> ==== User Permissions</span><br><span> </span><br><span> On the main unit, create a group for all users that should be allowed to use</span><br><span>@@ -350,8 +381,6 @@</span><br><span> A user added to a group needs to re-login for the group permissions to take</span><br><span> effect.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-This group needs the following permissions:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span> ===== Paths</span><br><span> </span><br><span> Assuming that you are using the example config, prepare a system wide state</span><br><span>@@ -384,7 +413,7 @@</span><br><span> to access the org.ofono DBus path:</span><br><span> </span><br><span> ----</span><br><span style="color: hsl(0, 100%, 40%);">-cat > /etc/dbus-1/system.d/osmo-gsm-tester.conf <<END</span><br><span style="color: hsl(120, 100%, 40%);">+# cat > /etc/dbus-1/system.d/osmo-gsm-tester.conf <<END</span><br><span> <!-- Additional rules for the osmo-gsm-tester to access org.ofono from user</span><br><span> land --></span><br><span> </span><br><span>@@ -402,6 +431,21 @@</span><br><span> </span><br><span> (No restart of dbus nor ofono necessary.)</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+[[install_slave_unit]]</span><br><span style="color: hsl(120, 100%, 40%);">+=== Slave Unit(s)</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The slave units are the hosts used by {app-name} to run proceses on. It may be</span><br><span style="color: hsl(120, 100%, 40%);">+the <<install_main_unit,Main Unit>> itself and processes will be run locally, or</span><br><span style="color: hsl(120, 100%, 40%);">+it may be a remote host were processes are run usually through SSH.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This guide assumes slaves unit(s) use same configuration as the Main Unit, that</span><br><span style="color: hsl(120, 100%, 40%);">+is, it runs under 'jenkins' user which is a member of the 'osmo-gsm-tester' user</span><br><span style="color: hsl(120, 100%, 40%);">+group. In order to do so, follow the instruction under the</span><br><span style="color: hsl(120, 100%, 40%);">+<<install_main_unit,Main Unit>> section above. Keep in mind the 'jenkins' user</span><br><span style="color: hsl(120, 100%, 40%);">+on the Main Unit will need to be able to log in through SSH as the slave unit</span><br><span style="color: hsl(120, 100%, 40%);">+'jenkins' user to run the processes. No direct access from Jenkins Master node</span><br><span style="color: hsl(120, 100%, 40%);">+is required here.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> [[install_capture_packets]]</span><br><span> ===== Capture Packets</span><br><span> </span><br><span>@@ -464,6 +508,10 @@</span><br><span> sysctl -w kernel.core_pattern=core</span><br><span> ----</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+TIP: Files required to be installed under '/etc/security/limits.d/' can be found</span><br><span style="color: hsl(120, 100%, 40%);">+under 'osmo-gsm-tester.git/utils/limits.d/', so one can simply cp them from</span><br><span style="color: hsl(120, 100%, 40%);">+there.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> ===== Allow Realtime Priority</span><br><span> </span><br><span> Certain binaries should be run with real-time priority, like 'osmo-bts-trx'.</span><br><span>@@ -476,25 +524,20 @@</span><br><span> </span><br><span> Re-login the user to make these changes take effect.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-[[user_config_uhd]]</span><br><span style="color: hsl(0, 100%, 40%);">-===== UHD</span><br><span style="color: hsl(120, 100%, 40%);">+TIP: Files required to be installed under '/etc/security/limits.d/' can be found</span><br><span style="color: hsl(120, 100%, 40%);">+under 'osmo-gsm-tester.git/utils/limits.d/', so one can simply cp them from</span><br><span style="color: hsl(120, 100%, 40%);">+there.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-Grant permission to use the UHD driver to run USRP devices for osmo-bts-trx, by</span><br><span style="color: hsl(0, 100%, 40%);">-adding the jenkins user to the 'usrp' group:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-gpasswd -a jenkins usrp</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-===== Allow CAP_NET_RAW capability</span><br><span style="color: hsl(120, 100%, 40%);">+===== Allow capabilities: 'CAP_NET_RAW', 'CAP_NET_ADMIN', 'CAP_SYS_ADMIN'</span><br><span> </span><br><span> Certain binaries require 'CAP_NET_RAW' to be set, like 'osmo-bts-octphy' as it</span><br><span style="color: hsl(0, 100%, 40%);">-uses a 'AF_PACKET' socket.</span><br><span style="color: hsl(120, 100%, 40%);">+uses a 'AF_PACKET' socket. Similarly, others (like osmo-ggsn) require</span><br><span style="color: hsl(120, 100%, 40%);">+'CAP_NET_ADMIN' to be able to create tun devices, and so on.</span><br><span> </span><br><span> To be able to set the following capability without being root, osmo-gsm-tester</span><br><span> uses sudo to gain permissions to set the capability.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-This is the script that osmo-gsm-tester expects on the main unit:</span><br><span style="color: hsl(120, 100%, 40%);">+This is the script that osmo-gsm-tester expects on the host running the process:</span><br><span> </span><br><span> ----</span><br><span> echo /usr/local/bin/osmo-gsm-tester_setcap_net_raw.sh <<EOF</span><br><span>@@ -504,7 +547,7 @@</span><br><span> chmod +x /usr/local/bin/osmo-gsm-tester_setcap_net_raw.sh</span><br><span> ----</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-Now, again on the main unit, we need to provide sudo access to this script for</span><br><span style="color: hsl(120, 100%, 40%);">+Now, again on the same host, we need to provide sudo access to this script for</span><br><span> osmo-gsm-tester:</span><br><span> </span><br><span> ----</span><br><span>@@ -515,6 +558,32 @@</span><br><span> The script file name 'osmo-gsm-tester_setcap_net_raw.sh' is important, as</span><br><span> osmo-gsm-tester expects to find a script with this name in '$PATH' at run time.</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+TIP: Files required to be installed under '/etc/sudoers.d/' can be found</span><br><span style="color: hsl(120, 100%, 40%);">+under 'osmo-gsm-tester.git/utils/sudoers.d/', so one can simply cp them from</span><br><span style="color: hsl(120, 100%, 40%);">+there.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+TIP: Files required to be installed under '/usr/local/bin/' can be found</span><br><span style="color: hsl(120, 100%, 40%);">+under 'osmo-gsm-tester.git/utils/bin/', so one can simply cp them from</span><br><span style="color: hsl(120, 100%, 40%);">+there.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[user_config_uhd]]</span><br><span style="color: hsl(120, 100%, 40%);">+===== UHD</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Grant permission to use the UHD driver to run USRP devices for osmo-bts-trx, by</span><br><span style="color: hsl(120, 100%, 40%);">+adding the jenkins user to the 'usrp' group:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+gpasswd -a jenkins usrp</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+To run osmo-bts-trx with a USRP attached, you may need to install a UHD driver.</span><br><span style="color: hsl(120, 100%, 40%);">+Please refer to http://osmocom.org/projects/osmotrx/wiki/OsmoTRX#UHD for</span><br><span style="color: hsl(120, 100%, 40%);">+details; the following is an example for the B200 family USRP devices:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+apt-get install libuhd-dev uhd-host</span><br><span style="color: hsl(120, 100%, 40%);">+/usr/lib/uhd/utils/uhd_images_downloader.py</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span> </span><br><span> ==== Log Rotation</span><br><span> </span><br><span>@@ -578,87 +647,3 @@</span><br><span> </span><br><span> NOTE: The configuration will be looked up in various places, see</span><br><span> <<config_paths>>.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-== Hardware Choice and Configuration</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-=== SysmoBTS</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-To use the SysmoBTS in the osmo-gsm-tester, the following systemd services must</span><br><span style="color: hsl(0, 100%, 40%);">-be disabled:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-systemctl mask osmo-nitb osmo-bts-sysmo osmo-pcu sysmobts-mgr</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-This stops the stock setup keeping the BTS in operation and hence allows the</span><br><span style="color: hsl(0, 100%, 40%);">-osmo-gsm-tester to install and launch its own versions of the SysmoBTS</span><br><span style="color: hsl(0, 100%, 40%);">-software.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-==== IP Address</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-To ensure that the SysmoBTS is always reachable at a fixed known IP address,</span><br><span style="color: hsl(0, 100%, 40%);">-configure the eth0 to use a static IP address:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Adjust '/etc/network/interfaces' and replace the line</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-iface eth0 inet dhcp</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-with</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-iface eth0 inet static</span><br><span style="color: hsl(0, 100%, 40%);">- address 10.42.42.114</span><br><span style="color: hsl(0, 100%, 40%);">- netmask 255.255.255.0</span><br><span style="color: hsl(0, 100%, 40%);">- gateway 10.42.42.1</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-You may set the name server in '/etc/resolve.conf' (most likely to the IP of</span><br><span style="color: hsl(0, 100%, 40%);">-the gateway), but this is not really needed by the osmo-gsm-tester.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-==== Allow Core Files</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-In case a binary run for the test crashes, a core file of the crash should be</span><br><span style="color: hsl(0, 100%, 40%);">-written. This requires a limits rule. Append a line to /etc/limits like:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-ssh root@10.42.42.114</span><br><span style="color: hsl(0, 100%, 40%);">-echo "* C16384" >> /etc/limits</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-==== Reboot</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Reboot the BTS and make sure that the IP address for eth0 is now indeed</span><br><span style="color: hsl(0, 100%, 40%);">-10.42.42.114, and that no osmo* programs are running.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-ip a</span><br><span style="color: hsl(0, 100%, 40%);">-ps w | grep osmo</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-==== SSH Access</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Make sure that the jenkins user on the main unit is able to login on the</span><br><span style="color: hsl(0, 100%, 40%);">-sysmoBTS, possibly erasing outdated host keys after a new rootfs was loaded:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-On the main unit, for example do:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-su - jenkins</span><br><span style="color: hsl(0, 100%, 40%);">-ssh root@10.42.42.114</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Fix any problems until you get a login on the sysmoBTS.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-[[hardware_modems]]</span><br><span style="color: hsl(0, 100%, 40%);">-=== Modems</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-TODO: describe modem choices and how to run ofono</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-[[hardware_trx]]</span><br><span style="color: hsl(0, 100%, 40%);">-=== osmo-bts-trx</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-TODO: describe B200 family</span><br><span>diff --git a/doc/manuals/chapters/install_device.adoc b/doc/manuals/chapters/install_device.adoc</span><br><span>new file mode 100644</span><br><span>index 0000000..60c3936</span><br><span>--- /dev/null</span><br><span>+++ b/doc/manuals/chapters/install_device.adoc</span><br><span>@@ -0,0 +1,82 @@</span><br><span style="color: hsl(120, 100%, 40%);">+== Hardware Choice and Configuration</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== SysmoBTS</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+To use the SysmoBTS in the osmo-gsm-tester, the following systemd services must</span><br><span style="color: hsl(120, 100%, 40%);">+be disabled:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+systemctl mask osmo-nitb osmo-bts-sysmo osmo-pcu sysmobts-mgr</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This stops the stock setup keeping the BTS in operation and hence allows the</span><br><span style="color: hsl(120, 100%, 40%);">+osmo-gsm-tester to install and launch its own versions of the SysmoBTS</span><br><span style="color: hsl(120, 100%, 40%);">+software.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== IP Address</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+To ensure that the SysmoBTS is always reachable at a fixed known IP address,</span><br><span style="color: hsl(120, 100%, 40%);">+configure the eth0 to use a static IP address:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Adjust '/etc/network/interfaces' and replace the line</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+iface eth0 inet dhcp</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+with</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+iface eth0 inet static</span><br><span style="color: hsl(120, 100%, 40%);">+ address 10.42.42.114</span><br><span style="color: hsl(120, 100%, 40%);">+ netmask 255.255.255.0</span><br><span style="color: hsl(120, 100%, 40%);">+ gateway 10.42.42.1</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+You may set the name server in '/etc/resolve.conf' (most likely to the IP of</span><br><span style="color: hsl(120, 100%, 40%);">+the gateway), but this is not really needed by the osmo-gsm-tester.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== Allow Core Files</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+In case a binary run for the test crashes, a core file of the crash should be</span><br><span style="color: hsl(120, 100%, 40%);">+written. This requires a limits rule. Append a line to /etc/limits like:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+ssh root@10.42.42.114</span><br><span style="color: hsl(120, 100%, 40%);">+echo "* C16384" >> /etc/limits</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== Reboot</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Reboot the BTS and make sure that the IP address for eth0 is now indeed</span><br><span style="color: hsl(120, 100%, 40%);">+10.42.42.114, and that no osmo* programs are running.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+ip a</span><br><span style="color: hsl(120, 100%, 40%);">+ps w | grep osmo</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== SSH Access</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Make sure that the jenkins user on the main unit is able to login on the</span><br><span style="color: hsl(120, 100%, 40%);">+sysmoBTS, possibly erasing outdated host keys after a new rootfs was loaded:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+On the main unit, for example do:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+su - jenkins</span><br><span style="color: hsl(120, 100%, 40%);">+ssh root@10.42.42.114</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Fix any problems until you get a login on the sysmoBTS.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[hardware_modems]]</span><br><span style="color: hsl(120, 100%, 40%);">+=== Modems</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+TODO: describe modem choices and how to run ofono</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[hardware_trx]]</span><br><span style="color: hsl(120, 100%, 40%);">+=== osmo-bts-trx</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+TODO: describe B200 family</span><br><span>diff --git a/doc/manuals/chapters/intro.adoc b/doc/manuals/chapters/intro.adoc</span><br><span>index 14daba4..9b7131d 100644</span><br><span>--- a/doc/manuals/chapters/intro.adoc</span><br><span>+++ b/doc/manuals/chapters/intro.adoc</span><br><span>@@ -1,31 +1,56 @@</span><br><span style="color: hsl(0, 100%, 40%);">-== Introduction with Examples</span><br><span style="color: hsl(120, 100%, 40%);">+== Introduction</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-The osmo-gsm-tester is software to run automated tests of real GSM hardware,</span><br><span style="color: hsl(120, 100%, 40%);">+{app-name} is a software to run automated tests on real GSM hardware,</span><br><span> foremost to verify that ongoing Osmocom software development continues to work</span><br><span style="color: hsl(0, 100%, 40%);">-with various BTS models, while being flexibly configurable and extendable.</span><br><span style="color: hsl(120, 100%, 40%);">+with various BTS models, while being flexibly configurable and extendable to</span><br><span style="color: hsl(120, 100%, 40%);">+work for other technologies, setups and projects. It can be used for instance to</span><br><span style="color: hsl(120, 100%, 40%);">+test a 3G or 4G network.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-A 'main unit' (general purpose computer) is connected via ethernet and/or USB to</span><br><span style="color: hsl(0, 100%, 40%);">-any number of BTS models and to any number of GSM modems via USB. The modems</span><br><span style="color: hsl(0, 100%, 40%);">-and BTS instances' RF transceivers are typically wired directly to each other</span><br><span style="color: hsl(0, 100%, 40%);">-via RF distribution chambers to bypass the air medium and avoid disturbing real</span><br><span style="color: hsl(0, 100%, 40%);">-production cellular networks. Furthermore, the setup may include adjustable RF</span><br><span style="color: hsl(0, 100%, 40%);">-attenuators to model various distances between modems and base stations.</span><br><span style="color: hsl(120, 100%, 40%);">+{app-name} (python3 process) runs on a host (general purpose computer) named</span><br><span style="color: hsl(120, 100%, 40%);">+the 'main unit'. It may optionally be connected to any number of 'slave units',</span><br><span style="color: hsl(120, 100%, 40%);">+which {app-name} may use to orchestrate processes remotely, usually through SSH.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-The osmo-gsm-tester software runs on the main unit to orchestrate the various</span><br><span style="color: hsl(0, 100%, 40%);">-GSM hardware and run predefined test scripts. It typically receives binary</span><br><span style="color: hsl(0, 100%, 40%);">-packages from a jenkins build service. It then automatically configures and</span><br><span style="color: hsl(0, 100%, 40%);">-launches an Osmocom core network on the main unit and sets up and runs BTS</span><br><span style="color: hsl(0, 100%, 40%);">-models as well as modems to form a complete ad-hoc GSM network. On this setup,</span><br><span style="color: hsl(0, 100%, 40%);">-predefined test suites, combined with various scenario definitions, are run to</span><br><span style="color: hsl(0, 100%, 40%);">-verify stability of the system.</span><br><span style="color: hsl(120, 100%, 40%);">+Hardware devices such as BTS, SDRs, modems, smart plugs, etc. are then connected</span><br><span style="color: hsl(120, 100%, 40%);">+to either the main unit or slaves units via IP, raw ethernet, USB or any other</span><br><span style="color: hsl(120, 100%, 40%);">+means·</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-The osmo-gsm-tester is implemented in Python (version 3). It uses the ofono</span><br><span style="color: hsl(0, 100%, 40%);">-daemon to control the modems connected via USB. BTS software is either run</span><br><span style="color: hsl(0, 100%, 40%);">-directly on the main unit (e.g. for osmo-bts-trx, osmo-bts-octphy), run via SSH</span><br><span style="color: hsl(0, 100%, 40%);">-(e.g. for a sysmoBTS) or assumed to run on a connected BTS model (e.g. for</span><br><span style="color: hsl(0, 100%, 40%);">-ip.access nanoBTS).</span><br><span style="color: hsl(120, 100%, 40%);">+The modems and BTS instances' RF transceivers are typically wired directly to</span><br><span style="color: hsl(120, 100%, 40%);">+each other via RF distribution chambers to bypass the air medium and avoid</span><br><span style="color: hsl(120, 100%, 40%);">+disturbing real production cellular networks. Furthermore, the setup may include</span><br><span style="color: hsl(120, 100%, 40%);">+adjustable RF attenuators to model various distances between modems and base</span><br><span style="color: hsl(120, 100%, 40%);">+stations.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-.Typical osmo-gsm-tester setup</span><br><span style="color: hsl(120, 100%, 40%);">+Each of these devices, having each a different physical setup and configuration,</span><br><span style="color: hsl(120, 100%, 40%);">+supported features, attributes, etc., is referred in {app-name} terminology as a</span><br><span style="color: hsl(120, 100%, 40%);">+_resource_. Each _resource_ is an instance of _resource class_. A</span><br><span style="color: hsl(120, 100%, 40%);">+_resource_class_ may be for instance a _modem_ or a _bts_. For instance, an</span><br><span style="color: hsl(120, 100%, 40%);">+{app-name} setup may have 2 _modem_ instances and 1 _bts_ instances. Each of</span><br><span style="color: hsl(120, 100%, 40%);">+these _resources_ are listed and described in configuration files passed to</span><br><span style="color: hsl(120, 100%, 40%);">+{app-name}, which maintains a pool of _resources_ (available, in use, etc.).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+{app-name} typically receives from a jenkins build service the software or</span><br><span style="color: hsl(120, 100%, 40%);">+firmware binary packages to be used and tested. {app-name} then launches a</span><br><span style="color: hsl(120, 100%, 40%);">+specific set of testsuites which, in turn, contain each a set of python test</span><br><span style="color: hsl(120, 100%, 40%);">+scripts. Each test uses the _testenv_ API provided by {app-name} to configure,</span><br><span style="color: hsl(120, 100%, 40%);">+launch and manage the different nodes and processes from the provided binary</span><br><span style="color: hsl(120, 100%, 40%);">+packages to form a complete ad-hoc GSM network.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Testsuites themselves contain configuration files to list how many resources it</span><br><span style="color: hsl(120, 100%, 40%);">+requires to run its tests. It also provides means to _filter_ which kind of</span><br><span style="color: hsl(120, 100%, 40%);">+_resources_ will be needed based on their attributes. This allows, for instance,</span><br><span style="color: hsl(120, 100%, 40%);">+asking {app-name} to provide a _modem_ supporting GPRS, or to provide a specific</span><br><span style="color: hsl(120, 100%, 40%);">+model of _bts_ such as a nanoBTS. Testsuites also allow receiving _modifiers_,</span><br><span style="color: hsl(120, 100%, 40%);">+which overwrite some of the default values that {app-name} itself or different</span><br><span style="color: hsl(120, 100%, 40%);">+_resources_ use.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Moreover, one may want to run the same testsuite several tiems, each with</span><br><span style="color: hsl(120, 100%, 40%);">+different set of _resources_. For instance, one may want to run a testsuite with</span><br><span style="color: hsl(120, 100%, 40%);">+a sysmoBTS and later with a nanoBTS. This is supported by leaving the testsuite</span><br><span style="color: hsl(120, 100%, 40%);">+configuration generic enough and then passing _scenarios_ to it, which allow</span><br><span style="color: hsl(120, 100%, 40%);">+applying extra _filters_ or _modifiers_. Scenarios can also be combined to</span><br><span style="color: hsl(120, 100%, 40%);">+filter further or to apply further modifications.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.Sample osmo-gsm-tester node 2G setup</span><br><span> [graphviz]</span><br><span> ----</span><br><span> digraph G {</span><br><span>@@ -35,8 +60,8 @@</span><br><span> label = "GSM Hardware";</span><br><span> style=dotted</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- modem0 [shape=box label="Modems..."]</span><br><span style="color: hsl(0, 100%, 40%);">- modem1 [shape=box label="Modems..."]</span><br><span style="color: hsl(120, 100%, 40%);">+ modem0 [shape=box label="Modem (Quectel EC20)"]</span><br><span style="color: hsl(120, 100%, 40%);">+ modem1 [shape=box label="Modems (SierraWireless MC7455)"]</span><br><span> osmo_bts_sysmo [label="sysmocom sysmoBTS\nrunning osmo-bts-sysmo" shape=box]</span><br><span> B200 [label="Ettus B200" shape=box]</span><br><span> sysmoCell5K [label="sysmocom sysmoCell5000" shape=box]</span><br><span>@@ -46,13 +71,16 @@</span><br><span> </span><br><span> {modem0 modem1 osmo_bts_sysmo B200 octphy nanoBTS sysmoCell5K}->rf_distribution [dir=both arrowhead="curve" arrowtail="curve"]</span><br><span> }</span><br><span style="color: hsl(120, 100%, 40%);">+ subgraph cluster_slave_unit {</span><br><span style="color: hsl(120, 100%, 40%);">+ label = "Slave Unit"</span><br><span style="color: hsl(120, 100%, 40%);">+ osmo_trx [label="osmo-trx"]</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span> subgraph cluster_main_unit {</span><br><span> label = "Main Unit"</span><br><span> osmo_gsm_tester [label="Osmo-GSM-Tester\ntest suites\n& scenarios"]</span><br><span> subgraph {</span><br><span> rank=same</span><br><span> ofono [label="ofono daemon"]</span><br><span style="color: hsl(0, 100%, 40%);">- osmo_trx [label="osmo-trx"]</span><br><span> osmo_bts_trx [label="osmo-bts-trx"]</span><br><span> osmo_bts_octphy [label="osmo-bts-octphy"]</span><br><span> OsmoNITB [label="BSC + Core Network\n(Osmo{NITB,MSC,BSC,HLR,...})"]</span><br><span>@@ -62,339 +90,15 @@</span><br><span> </span><br><span> jenkins->osmo_gsm_tester [label="trial\n(binaries)"]</span><br><span> osmo_gsm_tester->jenkins [label="results"]</span><br><span style="color: hsl(0, 100%, 40%);">- ofono->{modem0 modem1} [label="USB"]</span><br><span style="color: hsl(120, 100%, 40%);">+ ofono->{modem0 modem1} [label="QMI/USB"]</span><br><span> osmo_gsm_tester->{OsmoNITB osmo_bts_trx osmo_bts_octphy}</span><br><span style="color: hsl(0, 100%, 40%);">- osmo_gsm_tester->osmo_bts_sysmo [taillabel="SSH"]</span><br><span style="color: hsl(120, 100%, 40%);">+ osmo_gsm_tester->{osmo_trx, osmo_bts_sysmo} [taillabel="SSH"]</span><br><span> osmo_gsm_tester->ofono [taillabel="DBus"]</span><br><span style="color: hsl(0, 100%, 40%);">- osmo_trx->B200 [label="USB"]</span><br><span style="color: hsl(0, 100%, 40%);">- osmo_bts_trx->{osmo_trx sysmoCell5K} [dir=both label="UDP"]</span><br><span style="color: hsl(120, 100%, 40%);">+ osmo_trx->B200 [label="UHD/USB"]</span><br><span style="color: hsl(120, 100%, 40%);">+ osmo_bts_trx->{osmo_trx sysmoCell5K} [dir=both label="TRXC+TRXD/UDP"]</span><br><span> osmo_bts_octphy->octphy [label="raw eth"]</span><br><span> {osmo_bts_sysmo nanoBTS}->OsmoNITB [label="IP"]</span><br><span> {B200 octphy}->OsmoNITB [label="eth" style=invis]</span><br><span> {osmo_bts_trx osmo_bts_octphy}->OsmoNITB</span><br><span> }</span><br><span> ----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-.Example of how to select resources and configurations: scenarios may pick specific resources (here BTS and ARFCN), remaining requirements are picked as available (here two modems and a NITB interface)</span><br><span style="color: hsl(0, 100%, 40%);">-[graphviz]</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-digraph G {</span><br><span style="color: hsl(0, 100%, 40%);">- rankdir=TB;</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- suite_scenarios [label="Suite+Scenarios selection\nsms:sysmo+band1800"]</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- subgraph {</span><br><span style="color: hsl(0, 100%, 40%);">- rank=same;</span><br><span style="color: hsl(0, 100%, 40%);">- suite</span><br><span style="color: hsl(0, 100%, 40%);">- scenarios</span><br><span style="color: hsl(0, 100%, 40%);">- }</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- subgraph cluster_scenarios {</span><br><span style="color: hsl(0, 100%, 40%);">- label = "Scenarios";</span><br><span style="color: hsl(0, 100%, 40%);">- u_sysmoBTS [label="Scenario: sysmo\nbts: type: osmo-bts-sysmo"]</span><br><span style="color: hsl(0, 100%, 40%);">- u_trx [label="Scenario: trx\nbts: type: osmo-bts-trx"]</span><br><span style="color: hsl(0, 100%, 40%);">- u_arfcn [label="Scenario: band1800\narfcn: band: GSM-1800"]</span><br><span style="color: hsl(0, 100%, 40%);">- }</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- subgraph cluster_suite {</span><br><span style="color: hsl(0, 100%, 40%);">- label = "Suite: sms";</span><br><span style="color: hsl(0, 100%, 40%);">- requires [label="Requirements (suite.conf):\nmodem: times: 2\nbts\nip_address\narfcn"]</span><br><span style="color: hsl(0, 100%, 40%);">- subgraph cluster_tests {</span><br><span style="color: hsl(0, 100%, 40%);">- label = "Test Scripts (py)";</span><br><span style="color: hsl(0, 100%, 40%);">- mo_mt_sms</span><br><span style="color: hsl(0, 100%, 40%);">- etc</span><br><span style="color: hsl(0, 100%, 40%);">- }</span><br><span style="color: hsl(0, 100%, 40%);">- }</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- subgraph cluster_resources {</span><br><span style="color: hsl(0, 100%, 40%);">- label = "Resources";</span><br><span style="color: hsl(0, 100%, 40%);">- rankdir=TB;</span><br><span style="color: hsl(0, 100%, 40%);">- nitb_addr1 [label="NITB interface addr\n10.42.42.1"]</span><br><span style="color: hsl(0, 100%, 40%);">- nitb_addr2 [label="NITB interface addr\n10.42.42.2"]</span><br><span style="color: hsl(0, 100%, 40%);">- Modem0</span><br><span style="color: hsl(0, 100%, 40%);">- Modem1</span><br><span style="color: hsl(0, 100%, 40%);">- Modem2</span><br><span style="color: hsl(0, 100%, 40%);">- sysmoBTS [label="osmo-bts-sysmo"]</span><br><span style="color: hsl(0, 100%, 40%);">- osmo_bts_trx [label="osmo-bts-trx"]</span><br><span style="color: hsl(0, 100%, 40%);">- arfcn1 [label="arfcn: 512\nband: GSM-1800"]</span><br><span style="color: hsl(0, 100%, 40%);">- arfcn2 [label="arfcn: 540\nband: GSM-1900"]</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- arfcn1->arfcn2 [style=invis]</span><br><span style="color: hsl(0, 100%, 40%);">- nitb_addr1->nitb_addr2 [style=invis]</span><br><span style="color: hsl(0, 100%, 40%);">- Modem0 -> Modem1 -> Modem2 [style=invis]</span><br><span style="color: hsl(0, 100%, 40%);">- sysmoBTS -> osmo_bts_trx [style=invis]</span><br><span style="color: hsl(0, 100%, 40%);">- }</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- suite_scenarios -> {suite scenarios}</span><br><span style="color: hsl(0, 100%, 40%);">- scenarios -> { u_arfcn u_sysmoBTS }</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- suite -> requires</span><br><span style="color: hsl(0, 100%, 40%);">- requires -> Modem0</span><br><span style="color: hsl(0, 100%, 40%);">- requires -> Modem1</span><br><span style="color: hsl(0, 100%, 40%);">- requires -> sysmoBTS</span><br><span style="color: hsl(0, 100%, 40%);">- requires -> arfcn1</span><br><span style="color: hsl(0, 100%, 40%);">- requires -> nitb_addr1</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- { u_sysmoBTS u_arfcn } -> requires [label="influences\nresource\nselection"]</span><br><span style="color: hsl(0, 100%, 40%);">-}</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-.Example of a "trial" containing binaries built by a jenkins</span><br><span style="color: hsl(0, 100%, 40%);">-[graphviz]</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-digraph G {</span><br><span style="color: hsl(0, 100%, 40%);">- subgraph cluster_trial {</span><br><span style="color: hsl(0, 100%, 40%);">- label = "Trial (binaries)"</span><br><span style="color: hsl(0, 100%, 40%);">- sysmo [label="osmo-bts-sysmo.build-23.tgz\n(osmo-bts-sysmo\n+ deps\ncompiled for sysmoBTS)"]</span><br><span style="color: hsl(0, 100%, 40%);">- trx [label="osmo-bts.build-5.tgz\n(osmo-bts-octphy + osmo-bts-trx\n+ deps\ncompiled for main unit)"]</span><br><span style="color: hsl(0, 100%, 40%);">- nitb [label="osmo-nitb.build-42.tgz\n(osmo-nitb\n+ deps\ncompiled for main unit)"]</span><br><span style="color: hsl(0, 100%, 40%);">- checksums [label="checksums.md5"]</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- checksums -> {sysmo trx nitb}</span><br><span style="color: hsl(0, 100%, 40%);">- }</span><br><span style="color: hsl(0, 100%, 40%);">-}</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-=== Typical Test Script</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-A typical single test script (part of a suite) may look like this:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-#!/usr/bin/env python3</span><br><span style="color: hsl(0, 100%, 40%);">-from osmo_gsm_tester.testenv import *</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-hlr = suite.hlr()</span><br><span style="color: hsl(0, 100%, 40%);">-bts = suite.bts()</span><br><span style="color: hsl(0, 100%, 40%);">-mgcpgw = suite.mgcpgw(bts_ip=bts.remote_addr())</span><br><span style="color: hsl(0, 100%, 40%);">-msc = suite.msc(hlr, mgcpgw)</span><br><span style="color: hsl(0, 100%, 40%);">-bsc = suite.bsc(msc)</span><br><span style="color: hsl(0, 100%, 40%);">-stp = suite.stp()</span><br><span style="color: hsl(0, 100%, 40%);">-ms_mo = suite.modem()</span><br><span style="color: hsl(0, 100%, 40%);">-ms_mt = suite.modem()</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-hlr.start()</span><br><span style="color: hsl(0, 100%, 40%);">-stp.start()</span><br><span style="color: hsl(0, 100%, 40%);">-msc.start()</span><br><span style="color: hsl(0, 100%, 40%);">-mgcpgw.start()</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-bsc.bts_add(bts)</span><br><span style="color: hsl(0, 100%, 40%);">-bsc.start()</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-bts.start()</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-hlr.subscriber_add(ms_mo)</span><br><span style="color: hsl(0, 100%, 40%);">-hlr.subscriber_add(ms_mt)</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-ms_mo.connect(msc.mcc_mnc())</span><br><span style="color: hsl(0, 100%, 40%);">-ms_mt.connect(msc.mcc_mnc())</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-ms_mo.log_info()</span><br><span style="color: hsl(0, 100%, 40%);">-ms_mt.log_info()</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-print('waiting for modems to attach...')</span><br><span style="color: hsl(0, 100%, 40%);">-wait(ms_mo.is_connected, msc.mcc_mnc())</span><br><span style="color: hsl(0, 100%, 40%);">-wait(ms_mt.is_connected, msc.mcc_mnc())</span><br><span style="color: hsl(0, 100%, 40%);">-wait(msc.subscriber_attached, ms_mo, ms_mt)</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-sms = ms_mo.sms_send(ms_mt)</span><br><span style="color: hsl(0, 100%, 40%);">-wait(ms_mt.sms_was_received, sms)</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-=== Resource Resolution</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-- A global configuration 'resources.conf' defines which hardware is connected to the</span><br><span style="color: hsl(0, 100%, 40%);">- osmo-gsm-tester main unit.</span><br><span style="color: hsl(0, 100%, 40%);">-- Each suite contains a number of test scripts. The amount of resources a test</span><br><span style="color: hsl(0, 100%, 40%);">- may use is defined by the test suite's 'suite.conf'.</span><br><span style="color: hsl(0, 100%, 40%);">-- Which specific modems, BTS models, NITB IP addresses etc. are made available</span><br><span style="color: hsl(0, 100%, 40%);">- to a test run is typically determined by 'suite.conf' and a combination of scenario</span><br><span style="color: hsl(0, 100%, 40%);">- configurations -- or picked automatically if not.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-[[resources_conf_example]]</span><br><span style="color: hsl(0, 100%, 40%);">-=== Typical 'resources.conf'</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-A global configuration of hardware may look like below; for details, see</span><br><span style="color: hsl(0, 100%, 40%);">-<<resources_conf>>.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-ip_address:</span><br><span style="color: hsl(0, 100%, 40%);">-- addr: 10.42.42.2</span><br><span style="color: hsl(0, 100%, 40%);">-- addr: 10.42.42.3</span><br><span style="color: hsl(0, 100%, 40%);">-- addr: 10.42.42.4</span><br><span style="color: hsl(0, 100%, 40%);">-- addr: 10.42.42.5</span><br><span style="color: hsl(0, 100%, 40%);">-- addr: 10.42.42.6</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-bts:</span><br><span style="color: hsl(0, 100%, 40%);">-- label: sysmoBTS 1002</span><br><span style="color: hsl(0, 100%, 40%);">- type: osmo-bts-sysmo</span><br><span style="color: hsl(0, 100%, 40%);">- ipa_unit_id: 1</span><br><span style="color: hsl(0, 100%, 40%);">- addr: 10.42.42.114</span><br><span style="color: hsl(0, 100%, 40%);">- band: GSM-1800</span><br><span style="color: hsl(0, 100%, 40%);">- ciphers:</span><br><span style="color: hsl(0, 100%, 40%);">- - a5_0</span><br><span style="color: hsl(0, 100%, 40%);">- - a5_1</span><br><span style="color: hsl(0, 100%, 40%);">- - a5_3</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-- label: Ettus B200</span><br><span style="color: hsl(0, 100%, 40%);">- type: osmo-bts-trx</span><br><span style="color: hsl(0, 100%, 40%);">- ipa_unit_id: 6</span><br><span style="color: hsl(0, 100%, 40%);">- addr: 10.42.42.50</span><br><span style="color: hsl(0, 100%, 40%);">- band: GSM-1800</span><br><span style="color: hsl(0, 100%, 40%);">- launch_trx: true</span><br><span style="color: hsl(0, 100%, 40%);">- ciphers:</span><br><span style="color: hsl(0, 100%, 40%);">- - a5_0</span><br><span style="color: hsl(0, 100%, 40%);">- - a5_1</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-- label: sysmoCell 5000</span><br><span style="color: hsl(0, 100%, 40%);">- type: osmo-bts-trx</span><br><span style="color: hsl(0, 100%, 40%);">- ipa_unit_id: 7</span><br><span style="color: hsl(0, 100%, 40%);">- addr: 10.42.42.51</span><br><span style="color: hsl(0, 100%, 40%);">- band: GSM-1800</span><br><span style="color: hsl(0, 100%, 40%);">- trx_remote_ip: 10.42.42.112</span><br><span style="color: hsl(0, 100%, 40%);">- ciphers:</span><br><span style="color: hsl(0, 100%, 40%);">- - a5_0</span><br><span style="color: hsl(0, 100%, 40%);">- - a5_1</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-- label: OCTBTS 3500</span><br><span style="color: hsl(0, 100%, 40%);">- type: osmo-bts-octphy</span><br><span style="color: hsl(0, 100%, 40%);">- ipa_unit_id: 8</span><br><span style="color: hsl(0, 100%, 40%);">- addr: 10.42.42.52</span><br><span style="color: hsl(0, 100%, 40%);">- band: GSM-1800</span><br><span style="color: hsl(0, 100%, 40%);">- trx_list:</span><br><span style="color: hsl(0, 100%, 40%);">- - hw_addr: 00:0c:90:2e:80:1e</span><br><span style="color: hsl(0, 100%, 40%);">- net_device: eth1</span><br><span style="color: hsl(0, 100%, 40%);">- - hw_addr: 00:0c:90:2e:87:52</span><br><span style="color: hsl(0, 100%, 40%);">- net_device: eth1</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-arfcn:</span><br><span style="color: hsl(0, 100%, 40%);">- - arfcn: 512</span><br><span style="color: hsl(0, 100%, 40%);">- band: GSM-1800</span><br><span style="color: hsl(0, 100%, 40%);">- - arfcn: 514</span><br><span style="color: hsl(0, 100%, 40%);">- band: GSM-1800</span><br><span style="color: hsl(0, 100%, 40%);">- - arfcn: 516</span><br><span style="color: hsl(0, 100%, 40%);">- band: GSM-1800</span><br><span style="color: hsl(0, 100%, 40%);">- - arfcn: 546</span><br><span style="color: hsl(0, 100%, 40%);">- band: GSM-1900</span><br><span style="color: hsl(0, 100%, 40%);">- - arfcn: 548</span><br><span style="color: hsl(0, 100%, 40%);">- band: GSM-1900</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-modem:</span><br><span style="color: hsl(0, 100%, 40%);">-- label: sierra_1</span><br><span style="color: hsl(0, 100%, 40%);">- path: '/sierra_1'</span><br><span style="color: hsl(0, 100%, 40%);">- imsi: '901700000009031'</span><br><span style="color: hsl(0, 100%, 40%);">- ki: '80A37E6FDEA931EAC92FFA5F671EFEAD'</span><br><span style="color: hsl(0, 100%, 40%);">- auth_algo: 'xor'</span><br><span style="color: hsl(0, 100%, 40%);">- ciphers:</span><br><span style="color: hsl(0, 100%, 40%);">- - a5_0</span><br><span style="color: hsl(0, 100%, 40%);">- - a5_1</span><br><span style="color: hsl(0, 100%, 40%);">- features:</span><br><span style="color: hsl(0, 100%, 40%);">- - 'sms'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'voice'</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-- label: gobi_0</span><br><span style="color: hsl(0, 100%, 40%);">- path: '/gobi_0'</span><br><span style="color: hsl(0, 100%, 40%);">- imsi: '901700000009030'</span><br><span style="color: hsl(0, 100%, 40%);">- ki: 'BB70807226393CDBAC8DD3439FF54252'</span><br><span style="color: hsl(0, 100%, 40%);">- auth_algo: 'xor'</span><br><span style="color: hsl(0, 100%, 40%);">- ciphers:</span><br><span style="color: hsl(0, 100%, 40%);">- - a5_0</span><br><span style="color: hsl(0, 100%, 40%);">- - a5_1</span><br><span style="color: hsl(0, 100%, 40%);">- features:</span><br><span style="color: hsl(0, 100%, 40%);">- - 'sms'</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-=== Typical 'suites/*/suite.conf'</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-The configuration that reserves a number of resources for a test suite may look</span><br><span style="color: hsl(0, 100%, 40%);">-like this:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-resources:</span><br><span style="color: hsl(0, 100%, 40%);">- ip_address:</span><br><span style="color: hsl(0, 100%, 40%);">- - times: 1</span><br><span style="color: hsl(0, 100%, 40%);">- bts:</span><br><span style="color: hsl(0, 100%, 40%);">- - times: 1</span><br><span style="color: hsl(0, 100%, 40%);">- modem:</span><br><span style="color: hsl(0, 100%, 40%);">- - times: 2</span><br><span style="color: hsl(0, 100%, 40%);">- features:</span><br><span style="color: hsl(0, 100%, 40%);">- - sms</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-It may also request e.g. specific BTS models, but this is typically left to</span><br><span style="color: hsl(0, 100%, 40%);">-scenario configurations.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-=== Typical 'scenarios/*.conf'</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-For a suite as above run as-is, any available resources are picked. This may be</span><br><span style="color: hsl(0, 100%, 40%);">-combined with any number of scenario definitions to constrain which specific</span><br><span style="color: hsl(0, 100%, 40%);">-resources should be used, e.g.:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-resources:</span><br><span style="color: hsl(0, 100%, 40%);">- bts:</span><br><span style="color: hsl(0, 100%, 40%);">- - type: osmo-bts-sysmo</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Which 'ip_address' or 'modem' is used in particular doesn't really matter, so</span><br><span style="color: hsl(0, 100%, 40%);">-it can be left up to the osmo-gsm-tester to pick these automatically.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Any number of such scenario configurations can be combined in the form</span><br><span style="color: hsl(0, 100%, 40%);">-'<suite_name>:<scenario>+<scenario>+...', e.g. 'my_suite:sysmo+tch_f+amr'.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-=== Typical Invocations</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Each invocation of osmo-gsm-tester deploys a set of pre-compiled binaries for</span><br><span style="color: hsl(0, 100%, 40%);">-the Osmocom core network as well as for the Osmocom based BTS models. To create</span><br><span style="color: hsl(0, 100%, 40%);">-such a set of binaries, see <<trials>>.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Examples for launching test trials:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-- Run the default suites (see <<default_suites>>) on a given set of binaries:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-osmo-gsm-tester.py path/to/my-trial</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-- Run an explicit choice of 'suite:scenario' combinations:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-osmo-gsm-tester.py path/to/my-trial -s sms:sysmo -s sms:trx -s sms:nanobts</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-- Run one 'suite:scenario' combination, setting log level to 'debug' and</span><br><span style="color: hsl(0, 100%, 40%);">- enabling logging of full python tracebacks, and also only run just the</span><br><span style="color: hsl(0, 100%, 40%);">- 'mo_mt_sms.py' test from the suite, e.g. to investigate a test failure:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-osmo-gsm-tester.py path/to/my-trial -s sms:sysmo -l dbg -T -t mo_mt</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-A test script may also be run step-by-step in a python debugger, see</span><br><span style="color: hsl(0, 100%, 40%);">-<<debugging>>.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-=== Resource Reservation for Concurrent Trials</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-While a test suite runs, the used resources are noted in a global state</span><br><span style="color: hsl(0, 100%, 40%);">-directory in a reserved-resources file. This way, any number of trials may be</span><br><span style="color: hsl(0, 100%, 40%);">-run consecutively without resource conflicts. Any test trial will only use</span><br><span style="color: hsl(0, 100%, 40%);">-resources that are currently not reserved by any other test suite. The</span><br><span style="color: hsl(0, 100%, 40%);">-reservation state is human readable.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-The global state directory is protected by a file lock to allow access by</span><br><span style="color: hsl(0, 100%, 40%);">-separate processes.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Also, the binaries from a trial are never installed system-wide, but are run</span><br><span style="color: hsl(0, 100%, 40%);">-with a specific 'LD_LIBRARY_PATH' pointing at the trial's 'inst', so that</span><br><span style="color: hsl(0, 100%, 40%);">-several trials can run consecutively without conflicting binary versions. For</span><br><span style="color: hsl(0, 100%, 40%);">-some specific binaries which require extra permissions (such as osmo-bts-octphy</span><br><span style="color: hsl(0, 100%, 40%);">-requiring 'CAP_NET_RAW'), 'patchelf' program is used to modify the binary</span><br><span style="color: hsl(0, 100%, 40%);">-'RPATH' field instead because the OS dynamic linker skips 'LD_LIBRARY_PATH' for</span><br><span style="color: hsl(0, 100%, 40%);">-binaries with special permissions.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Once a test suite run is complete, all its reserved resources are torn down (if</span><br><span style="color: hsl(0, 100%, 40%);">-the test scripts have not done so already), and the reservations are released</span><br><span style="color: hsl(0, 100%, 40%);">-automatically.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-If required resources are unavailable, the test trial fails. For consecutive</span><br><span style="color: hsl(0, 100%, 40%);">-test trials, a test run needs to either wait for resources to become available,</span><br><span style="color: hsl(0, 100%, 40%);">-or test suites need to be scheduled to make sense. (*<- TODO*)</span><br><span>diff --git a/doc/manuals/chapters/resource_pool.adoc b/doc/manuals/chapters/resource_pool.adoc</span><br><span>new file mode 100644</span><br><span>index 0000000..4a56767</span><br><span>--- /dev/null</span><br><span>+++ b/doc/manuals/chapters/resource_pool.adoc</span><br><span>@@ -0,0 +1,107 @@</span><br><span style="color: hsl(120, 100%, 40%);">+== Resource Resolution</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+- A global configuration <<resources_conf,resources.conf>> defines which hardware is plugged to the</span><br><span style="color: hsl(120, 100%, 40%);">+ {app-name} setup, be it the main unit or any slave unit. This list becomes the</span><br><span style="color: hsl(120, 100%, 40%);">+ 'resource pool'.</span><br><span style="color: hsl(120, 100%, 40%);">+- Each suite contains a number of test scripts. The amount of resources a test</span><br><span style="color: hsl(120, 100%, 40%);">+ may use is defined by the test suite's <<suite_conf,suite.conf>>.</span><br><span style="color: hsl(120, 100%, 40%);">+- Which specific modems, BTS models, NITB IP addresses etc. are made available</span><br><span style="color: hsl(120, 100%, 40%);">+ to a test run is typically determined by <<suite_conf,suite.conf>> and a combination of <<scenario_conf,scenario</span><br><span style="color: hsl(120, 100%, 40%);">+ configurations>> -- or picked automatically if not.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.Example of how to select resources and configurations: scenarios may pick specific resources (here BTS and ARFCN), remaining requirements are picked as available (here two modems and a NITB interface)</span><br><span style="color: hsl(120, 100%, 40%);">+[graphviz]</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+digraph G {</span><br><span style="color: hsl(120, 100%, 40%);">+ rankdir=TB;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ suite_scenarios [label="Suite+Scenarios selection\nsms:sysmo+band1800+mod-bts0-chanallocdescend"]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ subgraph {</span><br><span style="color: hsl(120, 100%, 40%);">+ rank=same;</span><br><span style="color: hsl(120, 100%, 40%);">+ suite</span><br><span style="color: hsl(120, 100%, 40%);">+ scenarios</span><br><span style="color: hsl(120, 100%, 40%);">+ defaults_conf [label="defaults.conf:\nbsc: net: encryption: a5_0"]</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ subgraph cluster_scenarios {</span><br><span style="color: hsl(120, 100%, 40%);">+ label = "Scenarios";</span><br><span style="color: hsl(120, 100%, 40%);">+ u_sysmoBTS [label="Scenario: sysmo\nresources: bts: type: osmo-bts-sysmo"]</span><br><span style="color: hsl(120, 100%, 40%);">+ u_trx [label="Scenario: trx\nresources: bts: type: osmo-bts-trx"]</span><br><span style="color: hsl(120, 100%, 40%);">+ u_arfcn [label="Scenario: band1800\nresources: arfcn: band: GSM-1800"]</span><br><span style="color: hsl(120, 100%, 40%);">+ u_chanallocdesc [label="Scenario: band1800\nmodifiers: bts: channel_allocator: descending"]</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ subgraph cluster_suite {</span><br><span style="color: hsl(120, 100%, 40%);">+ label = "Suite: sms";</span><br><span style="color: hsl(120, 100%, 40%);">+ requires [label="Requirements (suite.conf):\nmodem: times: 2\nbts\nip_address\narfcn"]</span><br><span style="color: hsl(120, 100%, 40%);">+ subgraph cluster_tests {</span><br><span style="color: hsl(120, 100%, 40%);">+ label = "Test mo_mt_sms.py";</span><br><span style="color: hsl(120, 100%, 40%);">+ obj_nitb [label="object NITB\n(process using 10.42.42.2)"]</span><br><span style="color: hsl(120, 100%, 40%);">+ bts0 [label="object bts[0]"]</span><br><span style="color: hsl(120, 100%, 40%);">+ modem0 [label="object modem[0]"]</span><br><span style="color: hsl(120, 100%, 40%);">+ modem1 [label="object modem[1]"]</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ subgraph cluster_resources {</span><br><span style="color: hsl(120, 100%, 40%);">+ label = "Available Resources (not already allocated by other Osmo-GSM-Tester instance)";</span><br><span style="color: hsl(120, 100%, 40%);">+ rankdir=TB;</span><br><span style="color: hsl(120, 100%, 40%);">+ nitb_addrA [label="NITB interface addr\n10.42.42.1"]</span><br><span style="color: hsl(120, 100%, 40%);">+ nitb_addrA [label="NITB interface addr\n10.42.42.2"]</span><br><span style="color: hsl(120, 100%, 40%);">+ ModemA</span><br><span style="color: hsl(120, 100%, 40%);">+ ModemB</span><br><span style="color: hsl(120, 100%, 40%);">+ ModemC</span><br><span style="color: hsl(120, 100%, 40%);">+ sysmoBTS [label="osmo-bts-sysmo"]</span><br><span style="color: hsl(120, 100%, 40%);">+ osmo_bts_trx [label="osmo-bts-trx"]</span><br><span style="color: hsl(120, 100%, 40%);">+ arfcnA [label="arfcn: 512\nband: GSM-1800"]</span><br><span style="color: hsl(120, 100%, 40%);">+ arfcnB [label="arfcn: 540\nband: GSM-1900"]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ arfcnA->arfcnB [style=invis]</span><br><span style="color: hsl(120, 100%, 40%);">+ nitb_addrA->nitb_addrB [style=invis]</span><br><span style="color: hsl(120, 100%, 40%);">+ ModemA -> ModemB -> ModemC [style=invis]</span><br><span style="color: hsl(120, 100%, 40%);">+ sysmoBTS -> osmo_bts_trx [style=invis]</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ suite_scenarios -> {suite scenarios}</span><br><span style="color: hsl(120, 100%, 40%);">+ scenarios -> { u_arfcn u_sysmoBTS u_chanallocdesc }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ suite -> requires</span><br><span style="color: hsl(120, 100%, 40%);">+ requires -> ModemA</span><br><span style="color: hsl(120, 100%, 40%);">+ requires -> ModemB</span><br><span style="color: hsl(120, 100%, 40%);">+ requires -> sysmoBTS</span><br><span style="color: hsl(120, 100%, 40%);">+ requires -> arfcnA</span><br><span style="color: hsl(120, 100%, 40%);">+ requires -> nitb_addrA</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ { u_sysmoBTS u_arfcn } -> requires [label="influences\nresource\nselection"]</span><br><span style="color: hsl(120, 100%, 40%);">+ u_chanallocdesc -> bts0 [label="influences\nbts[0]\nbehavior"]</span><br><span style="color: hsl(120, 100%, 40%);">+ defaults_conf -> obj_nitb [label="provides default values"]</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Resource Reservation for Concurrent Trials</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+While a test suite runs, the used resources are noted in a global state</span><br><span style="color: hsl(120, 100%, 40%);">+directory in a reserved-resources file. This way, any number of trials may be</span><br><span style="color: hsl(120, 100%, 40%);">+run consecutively without resource conflicts. Any test trial will only use</span><br><span style="color: hsl(120, 100%, 40%);">+resources that are currently not reserved by any other test suite. The</span><br><span style="color: hsl(120, 100%, 40%);">+reservation state is human readable.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The global state directory is protected by a file lock to allow access by</span><br><span style="color: hsl(120, 100%, 40%);">+separate processes.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Also, the binaries from a trial are never installed system-wide, but are run</span><br><span style="color: hsl(120, 100%, 40%);">+with a specific 'LD_LIBRARY_PATH' pointing at the <<trials,trial's inst>>, so that</span><br><span style="color: hsl(120, 100%, 40%);">+several trials can run consecutively without conflicting binary versions. For</span><br><span style="color: hsl(120, 100%, 40%);">+some specific binaries which require extra permissions (such as osmo-bts-octphy</span><br><span style="color: hsl(120, 100%, 40%);">+requiring 'CAP_NET_RAW'), 'patchelf' program is used to modify the binary</span><br><span style="color: hsl(120, 100%, 40%);">+'RPATH' field instead because the OS dynamic linker skips 'LD_LIBRARY_PATH' for</span><br><span style="color: hsl(120, 100%, 40%);">+binaries with special permissions.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Once a test suite run is complete, all its reserved resources are torn down (if</span><br><span style="color: hsl(120, 100%, 40%);">+the test scripts have not done so already), and the reservations are released</span><br><span style="color: hsl(120, 100%, 40%);">+automatically.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+If required resources are unavailable, the test trial fails. For consecutive</span><br><span style="color: hsl(120, 100%, 40%);">+test trials, a test run needs to either wait for resources to become available,</span><br><span style="color: hsl(120, 100%, 40%);">+or test suites need to be scheduled to make sense. (*<- TODO*)</span><br><span>diff --git a/doc/manuals/chapters/trial.adoc b/doc/manuals/chapters/trial.adoc</span><br><span>index bc9fe05..4b52608 100644</span><br><span>--- a/doc/manuals/chapters/trial.adoc</span><br><span>+++ b/doc/manuals/chapters/trial.adoc</span><br><span>@@ -1,13 +1,29 @@</span><br><span> [[trials]]</span><br><span> == Trial: Binaries to be Tested</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-A trial is a set of pre-built binaries to be tested. They are typically built</span><br><span style="color: hsl(120, 100%, 40%);">+A trial is a set of pre-built sysroot archives to be tested. They are typically built</span><br><span> by jenkins using the build scripts found in osmo-gsm-tester's source in the</span><br><span> 'contrib/' dir, see <<install_add_jenkins_slave>>.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-A trial comes in the form of a directory containing a number of '*.tgz' tar</span><br><span style="color: hsl(0, 100%, 40%);">-archives as well as a 'checksums.md5' file to verify the tar archives'</span><br><span style="color: hsl(0, 100%, 40%);">-integrity.</span><br><span style="color: hsl(120, 100%, 40%);">+A trial comes in the form of a directory containing a number of '<inst-name>.*tgz' tar</span><br><span style="color: hsl(120, 100%, 40%);">+archives (containing different sysroots) as well as a 'checksums.md5' file to</span><br><span style="color: hsl(120, 100%, 40%);">+verify the tar archives' integrity.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.Example of a "trial" containing binaries built by a jenkins job</span><br><span style="color: hsl(120, 100%, 40%);">+[graphviz]</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+digraph G {</span><br><span style="color: hsl(120, 100%, 40%);">+ subgraph cluster_trial {</span><br><span style="color: hsl(120, 100%, 40%);">+ label = "Trial (binaries)"</span><br><span style="color: hsl(120, 100%, 40%);">+ sysmo [label="osmo-bts-sysmo.build-23.tgz\n(osmo-bts-sysmo\n+ deps\ncompiled for sysmoBTS)"]</span><br><span style="color: hsl(120, 100%, 40%);">+ trx [label="osmo-bts.build-5.tgz\n(osmo-bts-octphy + osmo-bts-trx\n+ deps\ncompiled for main unit)"]</span><br><span style="color: hsl(120, 100%, 40%);">+ nitb [label="osmo-nitb.build-42.tgz\n(osmo-nitb\n+ deps\ncompiled for main unit)"]</span><br><span style="color: hsl(120, 100%, 40%);">+ checksums [label="checksums.md5"]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ checksums -> {sysmo trx nitb}</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span> </span><br><span> When the osmo-gsm-tester is invoked to run on such a trial directory, it will</span><br><span> create a sub directory named 'inst' and unpack the tar archives into it.</span><br><span>@@ -28,4 +44,22 @@</span><br><span> * generating md5 sums for the various tar.gz containing software builds to be tested,</span><br><span> * cleaning up after the build,</span><br><span> * saving extra logs such as journalctl output from ofonod,</span><br><span style="color: hsl(0, 100%, 40%);">-* generating a final .tar.gz file with all the logs and reports.</span><br><span style="color: hsl(120, 100%, 40%);">+* generating a final .tar.gz file with all the logs and reports to store as jenkins archives.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+{app-name} tests create objects to manage the allocated resources during test</span><br><span style="color: hsl(120, 100%, 40%);">+lifetime. These objects, in turn, usually run and manage processes started from</span><br><span style="color: hsl(120, 100%, 40%);">+the trail's sysroot binaries. {app-name} provide APIs for those object classes</span><br><span style="color: hsl(120, 100%, 40%);">+to discover, unpack and run those binaries. An object class simply needs to</span><br><span style="color: hsl(120, 100%, 40%);">+request the name of the sysroot it wants to use (for instance 'osmo-bsc'), and</span><br><span style="color: hsl(120, 100%, 40%);">+{app-name} will take care of preparing everything and providing the sysroot path</span><br><span style="color: hsl(120, 100%, 40%);">+to it. It's a duty of the resource class to copy over the sysroot to the</span><br><span style="color: hsl(120, 100%, 40%);">+destination if the intention is to run the binary remotely on another host.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+When seeking a sysroot of a given name '<inst-name>' in the 'inst/' directory,</span><br><span style="color: hsl(120, 100%, 40%);">+{app-name} will look for 'tgz' files starting with the pattern '<inst-name>.'</span><br><span style="color: hsl(120, 100%, 40%);">+(up to the first dot). That means, suffixes are available for {app-name} user to</span><br><span style="color: hsl(120, 100%, 40%);">+identify the content, for instance having an incrementing version counter or a</span><br><span style="color: hsl(120, 100%, 40%);">+commit hash. Hence, these example files are considered valid and will be</span><br><span style="color: hsl(120, 100%, 40%);">+selected by {app-name} for 'osmo-bsc': 'osmo-bsc.tgz', 'osmo-bsc.build-23.tgz',</span><br><span style="color: hsl(120, 100%, 40%);">+'osmo-bsc.5f3e0dd2.tgz', 'osmo-bsc.armv7.build-2.tgz'. If either none or more</span><br><span style="color: hsl(120, 100%, 40%);">+than one valid file is found matching the pattern, an exception will be thrown.</span><br><span>diff --git a/doc/manuals/chapters/troubleshooting.adoc b/doc/manuals/chapters/troubleshooting.adoc</span><br><span>new file mode 100644</span><br><span>index 0000000..a3b5c8b</span><br><span>--- /dev/null</span><br><span>+++ b/doc/manuals/chapters/troubleshooting.adoc</span><br><span>@@ -0,0 +1,15 @@</span><br><span style="color: hsl(120, 100%, 40%);">+== Troubleshooting</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Format: YAML, and its Drawbacks</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The general configuration format used is YAML. The stock python YAML parser</span><br><span style="color: hsl(120, 100%, 40%);">+does have several drawbacks: too many complex possibilities and alternative</span><br><span style="color: hsl(120, 100%, 40%);">+ways of formatting a configuration, but at the time of writing seems to be the</span><br><span style="color: hsl(120, 100%, 40%);">+only widely used configuration format that offers a simple and human readable</span><br><span style="color: hsl(120, 100%, 40%);">+formatting as well as nested structuring. It is recommended to use only the</span><br><span style="color: hsl(120, 100%, 40%);">+exact YAML subset seen in this manual in case the osmo-gsm-tester should move</span><br><span style="color: hsl(120, 100%, 40%);">+to a less bloated parser in the future.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Careful: if a configuration item consists of digits and starts with a zero, you</span><br><span style="color: hsl(120, 100%, 40%);">+need to quote it, or it may be interpreted as an octal notation integer! Please</span><br><span style="color: hsl(120, 100%, 40%);">+avoid using the octal notation on purpose, it is not provided intentionally.</span><br><span>diff --git a/doc/manuals/osmo-gsm-tester-manual-docinfo.xml b/doc/manuals/osmo-gsm-tester-manual-docinfo.xml</span><br><span>index 923b8ad..d7b112f 100644</span><br><span>--- a/doc/manuals/osmo-gsm-tester-manual-docinfo.xml</span><br><span>+++ b/doc/manuals/osmo-gsm-tester-manual-docinfo.xml</span><br><span>@@ -21,10 +21,21 @@</span><br><span> <jobtitle>Senior Developer</jobtitle></span><br><span> </affiliation></span><br><span> </author></span><br><span style="color: hsl(120, 100%, 40%);">+ <author></span><br><span style="color: hsl(120, 100%, 40%);">+ <firstname>Pau</firstname></span><br><span style="color: hsl(120, 100%, 40%);">+ <surname>Espin Pedrol</surname></span><br><span style="color: hsl(120, 100%, 40%);">+ <email>pespin@sysmocom.de</email></span><br><span style="color: hsl(120, 100%, 40%);">+ <authorinitials>PE</authorinitials></span><br><span style="color: hsl(120, 100%, 40%);">+ <affiliation></span><br><span style="color: hsl(120, 100%, 40%);">+ <shortaffil>sysmocom</shortaffil></span><br><span style="color: hsl(120, 100%, 40%);">+ <orgname>sysmocom - s.f.m.c. GmbH</orgname></span><br><span style="color: hsl(120, 100%, 40%);">+ <jobtitle>Software Developer</jobtitle></span><br><span style="color: hsl(120, 100%, 40%);">+ </affiliation></span><br><span style="color: hsl(120, 100%, 40%);">+ </author></span><br><span> </authorgroup></span><br><span> </span><br><span> <copyright></span><br><span style="color: hsl(0, 100%, 40%);">- <year>2017</year></span><br><span style="color: hsl(120, 100%, 40%);">+ <year>2017-2020</year></span><br><span> <holder>sysmocom - s.f.m.c. GmbH</holder></span><br><span> </copyright></span><br><span> </span><br><span>diff --git a/doc/manuals/osmo-gsm-tester-manual.adoc b/doc/manuals/osmo-gsm-tester-manual.adoc</span><br><span>index 6f0edf7..afee29b 100644</span><br><span>--- a/doc/manuals/osmo-gsm-tester-manual.adoc</span><br><span>+++ b/doc/manuals/osmo-gsm-tester-manual.adoc</span><br><span>@@ -1,20 +1,33 @@</span><br><span style="color: hsl(0, 100%, 40%);">-Osmo-GSM-Tester Manual</span><br><span style="color: hsl(0, 100%, 40%);">-======================</span><br><span style="color: hsl(0, 100%, 40%);">-Neels Hofmeyr <nhofmeyr@sysmocom.de></span><br><span style="color: hsl(120, 100%, 40%);">+:app-name: Osmo-GSM-Tester</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+{app-name} Manual</span><br><span style="color: hsl(120, 100%, 40%);">+=================</span><br><span style="color: hsl(120, 100%, 40%);">+Neels Hofmeyr <nhofmeyr@sysmocom.de>, Pau Espin Pedrol <pespin@sysmocom.de></span><br><span> </span><br><span> == WARNING: Work in Progress</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-*NOTE: The osmo-gsm-tester is still in pre-alpha stage: some parts are still</span><br><span style="color: hsl(0, 100%, 40%);">-incomplete, and details will still change and move around.*</span><br><span style="color: hsl(120, 100%, 40%);">+*NOTE: {app-name} is still under heavy development stage: some parts are still</span><br><span style="color: hsl(120, 100%, 40%);">+incomplete, and details can still change and move around as new features are</span><br><span style="color: hsl(120, 100%, 40%);">+added and improvements made.*</span><br><span> </span><br><span> include::{srcdir}/chapters/intro.adoc[]</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-include::{srcdir}/chapters/install.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+include::{srcdir}/chapters/trial.adoc[]</span><br><span> </span><br><span> include::{srcdir}/chapters/config.adoc[]</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-include::{srcdir}/chapters/trial.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+include::{srcdir}/chapters/resource_pool.adoc[]</span><br><span> </span><br><span> include::{srcdir}/chapters/test_api.adoc[]</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+include::{srcdir}/chapters/install.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+include::{srcdir}/chapters/install_device.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+include::{srcdir}/chapters/ansible.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+include::{srcdir}/chapters/docker.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> include::{srcdir}/chapters/debugging.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+include::{srcdir}/chapters/troubleshooting.adoc[]</span><br><span></span><br></pre><p>To view, visit <a href="https://gerrit.osmocom.org/c/osmo-gsm-tester/+/17447">change 17447</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://gerrit.osmocom.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.osmocom.org/c/osmo-gsm-tester/+/17447"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: osmo-gsm-tester </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-Change-Id: Ifc2a3c74d45336cc988b76c0ff68a85311e4dd40 </div>
<div style="display:none"> Gerrit-Change-Number: 17447 </div>
<div style="display:none"> Gerrit-PatchSet: 2 </div>
<div style="display:none"> Gerrit-Owner: pespin <pespin@sysmocom.de> </div>
<div style="display:none"> Gerrit-Reviewer: Jenkins Builder </div>
<div style="display:none"> Gerrit-Reviewer: pespin <pespin@sysmocom.de> </div>
<div style="display:none"> Gerrit-MessageType: merged </div>