<p>osmith <strong>merged</strong> this change.</p><p><a href="https://gerrit.osmocom.org/12000">View Change</a></p><div style="white-space:pre-wrap">Approvals:
Jenkins Builder: Verified
Pau Espin Pedrol: Looks good to me, approved
</div><pre style="font-family: monospace,monospace; white-space: pre-wrap;">remove OsmoGSMTester files (now avail in osmo-gsm-tester.git)<br><br>Files were added in osmo-gsm-tester.git Change-Id<br>I8a34871948425ea40f40dbb11a59806905e4bed1<br><br>Depends: osmo-gsm-tester.git Change-Id I8a34871948425ea40f40dbb11a59806905e4bed1<br>Related: OS#3385<br>Change-Id: I89429a306d37e267fdb335d1c177c9ede3b64444<br>---<br>M Makefile.am<br>D OsmoGSMTester/Makefile.am<br>D OsmoGSMTester/chapters/config.adoc<br>D OsmoGSMTester/chapters/debugging.adoc<br>D OsmoGSMTester/chapters/install.adoc<br>D OsmoGSMTester/chapters/intro.adoc<br>D OsmoGSMTester/chapters/test_api.adoc<br>D OsmoGSMTester/chapters/trial.adoc<br>D OsmoGSMTester/osmo-gsm-tester-manual-docinfo.xml<br>D OsmoGSMTester/osmo-gsm-tester-manual.adoc<br>M configure.ac<br>11 files changed, 0 insertions(+), 1,543 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/Makefile.am b/Makefile.am</span><br><span>index fdafc0d..3552541 100644</span><br><span>--- a/Makefile.am</span><br><span>+++ b/Makefile.am</span><br><span>@@ -6,7 +6,6 @@</span><br><span> BUILT_SOURCES = $(top_srcdir)/.version</span><br><span> EXTRA_DIST = git-version-gen .version check-depends.sh $(share_files)</span><br><span> SUBDIRS = tests \</span><br><span style="color: hsl(0, 100%, 40%);">- OsmoGSMTester \</span><br><span> OsmoMGCP \</span><br><span> OsmoNAT \</span><br><span> OsmoNITB \</span><br><span>diff --git a/OsmoGSMTester/Makefile.am b/OsmoGSMTester/Makefile.am</span><br><span>deleted file mode 100644</span><br><span>index 4301ab9..0000000</span><br><span>--- a/OsmoGSMTester/Makefile.am</span><br><span>+++ /dev/null</span><br><span>@@ -1,10 +0,0 @@</span><br><span style="color: hsl(0, 100%, 40%);">-OSMO_GSM_MANUALS_DIR = $(top_srcdir)</span><br><span style="color: hsl(0, 100%, 40%);">-EXTRA_DIST = osmo-gsm-tester-manual.adoc \</span><br><span style="color: hsl(0, 100%, 40%);">- osmo-gsm-tester-manual-docinfo.xml \</span><br><span style="color: hsl(0, 100%, 40%);">- chapters</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-ASCIIDOC = osmo-gsm-tester-manual.adoc</span><br><span style="color: hsl(0, 100%, 40%);">-ASCIIDOC_DEPS = $(srcdir)/chapters/*.adoc</span><br><span style="color: hsl(0, 100%, 40%);">-include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.asciidoc.inc</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.common.inc</span><br><span>diff --git a/OsmoGSMTester/chapters/config.adoc b/OsmoGSMTester/chapters/config.adoc</span><br><span>deleted file mode 100644</span><br><span>index 7e250e0..0000000</span><br><span>--- a/OsmoGSMTester/chapters/config.adoc</span><br><span>+++ /dev/null</span><br><span>@@ -1,361 +0,0 @@</span><br><span style="color: hsl(0, 100%, 40%);">-== Configuration</span><br><span style="color: hsl(0, 100%, 40%);">-</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(0, 100%, 40%);">-</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(0, 100%, 40%);">-</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(0, 100%, 40%);">-</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(0, 100%, 40%);">-</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(0, 100%, 40%);">-</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(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-These are described in detail in the following sections.</span><br><span style="color: hsl(0, 100%, 40%);">-</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(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-'ip_address'::</span><br><span style="color: hsl(0, 100%, 40%);">- List of IP addresses to run osmo-nitb instances on. The main unit</span><br><span style="color: hsl(0, 100%, 40%);">- typically has a limited number of such IP addresses configured, which</span><br><span style="color: hsl(0, 100%, 40%);">- the connected BTS models can see on their network.</span><br><span style="color: hsl(0, 100%, 40%);">- 'addr':::</span><br><span style="color: hsl(0, 100%, 40%);">- IPv4 address of the local interface.</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%);">- List of available BTS hardware.</span><br><span style="color: hsl(0, 100%, 40%);">- 'label':::</span><br><span style="color: hsl(0, 100%, 40%);">- human readable label for your own reference</span><br><span style="color: hsl(0, 100%, 40%);">- 'type':::</span><br><span style="color: hsl(0, 100%, 40%);">- which way to launch this BTS, one of</span><br><span style="color: hsl(0, 100%, 40%);">- - 'osmo-bts-sysmo'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'osmo-bts-trx'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'osmo-bts-octphy'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'ipa-nanobts'</span><br><span style="color: hsl(0, 100%, 40%);">- 'ipa_unit_id':::</span><br><span style="color: hsl(0, 100%, 40%);">- ip.access unit id to be used by the BTS, written into BTS and BSC config.</span><br><span style="color: hsl(0, 100%, 40%);">- 'addr':::</span><br><span style="color: hsl(0, 100%, 40%);">- Remote IP address of the BTS for BTS like sysmoBTS, and local IP address</span><br><span style="color: hsl(0, 100%, 40%);">- to bind to for locally run BTS such as osmo-bts-trx.</span><br><span style="color: hsl(0, 100%, 40%);">- 'band':::</span><br><span style="color: hsl(0, 100%, 40%);">- GSM band that this BTS shoud use (*TODO*: allow multiple bands). One of:</span><br><span style="color: hsl(0, 100%, 40%);">- - 'GSM-1800'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'GSM-1900'</span><br><span style="color: hsl(0, 100%, 40%);">- - (*TODO*: more bands)</span><br><span style="color: hsl(0, 100%, 40%);">- 'trx_list':::</span><br><span style="color: hsl(0, 100%, 40%);">- Specific TRX configurations for this BTS. There should be as many of</span><br><span style="color: hsl(0, 100%, 40%);">- these as the BTS has TRXes. (*TODO*: a way to define >1 TRX without</span><br><span style="color: hsl(0, 100%, 40%);">- special configuration for them.)</span><br><span style="color: hsl(0, 100%, 40%);">- 'hw_addr'::::</span><br><span style="color: hsl(0, 100%, 40%);">- Hardware (MAC) address of the TRX in the form of '11:22:33:44:55:66',</span><br><span style="color: hsl(0, 100%, 40%);">- only used for osmo-bts-octphy. (*TODO*: and nanobts??)</span><br><span style="color: hsl(0, 100%, 40%);">- 'net_device'::::</span><br><span style="color: hsl(0, 100%, 40%);">- Local network device to reach the TRX's 'hw_addr' at, only used for</span><br><span style="color: hsl(0, 100%, 40%);">- osmo-bts-octphy. Example: 'eth0'.</span><br><span style="color: hsl(0, 100%, 40%);">- 'nominal_power'::::</span><br><span style="color: hsl(0, 100%, 40%);">- Nominal power to be used by the TRX.</span><br><span style="color: hsl(0, 100%, 40%);">- 'max_power_red'::::</span><br><span style="color: hsl(0, 100%, 40%);">- Max power reduction to apply to the nominal power of the TRX.</span><br><span style="color: hsl(0, 100%, 40%);">-'arfcn'::</span><br><span style="color: hsl(0, 100%, 40%);">- List of ARFCNs to use for running BTSes, which defines the actual RF</span><br><span style="color: hsl(0, 100%, 40%);">- frequency bands used.</span><br><span style="color: hsl(0, 100%, 40%);">- 'arfcn':::</span><br><span style="color: hsl(0, 100%, 40%);">- ARFCN number, see e.g.</span><br><span style="color: hsl(0, 100%, 40%);">- https://en.wikipedia.org/wiki/Absolute_radio-frequency_channel_number</span><br><span style="color: hsl(0, 100%, 40%);">- (note that the resource type 'arfcn' contains an item trait also named</span><br><span style="color: hsl(0, 100%, 40%);">- 'arfcn').</span><br><span style="color: hsl(0, 100%, 40%);">- 'band':::</span><br><span style="color: hsl(0, 100%, 40%);">- GSM band name to use this ARFCN for, same as for 'bts:band' above.</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%);">- List of modems reachable via ofono and information on the inserted SIM</span><br><span style="color: hsl(0, 100%, 40%);">- card. (Note: the MSISDN is allocated dynamically in test scripts).</span><br><span style="color: hsl(0, 100%, 40%);">- 'label':::</span><br><span style="color: hsl(0, 100%, 40%);">- Human readable label for your own reference, which also appears in logs.</span><br><span style="color: hsl(0, 100%, 40%);">- 'path':::</span><br><span style="color: hsl(0, 100%, 40%);">- Ofono's path for this modem, like '/modemkind_99'.</span><br><span style="color: hsl(0, 100%, 40%);">- 'imsi':::</span><br><span style="color: hsl(0, 100%, 40%);">- IMSI of the inserted SIM card, like '"123456789012345"'.</span><br><span style="color: hsl(0, 100%, 40%);">- 'ki':::</span><br><span style="color: hsl(0, 100%, 40%);">- 16 byte authentication/encryption KI of the inserted SIM card, in</span><br><span style="color: hsl(0, 100%, 40%);">- hexadecimal notation (32 characters) like +</span><br><span style="color: hsl(0, 100%, 40%);">- '"00112233445566778899aabbccddeeff"'.</span><br><span style="color: hsl(0, 100%, 40%);">- 'auth_algo':::</span><br><span style="color: hsl(0, 100%, 40%);">- Authentication algorithm to be used with the SIM card. One of:</span><br><span style="color: hsl(0, 100%, 40%);">- - 'none'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'xor'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'comp128v1'</span><br><span style="color: hsl(0, 100%, 40%);">- 'ciphers':::</span><br><span style="color: hsl(0, 100%, 40%);">- List of ciphers that this modem supports, used to match</span><br><span style="color: hsl(0, 100%, 40%);">- requirements in suites or scenarios. Any combination of:</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_2'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'a5_3'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'a5_4'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'a5_5'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'a5_6'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'a5_7'</span><br><span style="color: hsl(0, 100%, 40%);">- 'features':::</span><br><span style="color: hsl(0, 100%, 40%);">- List of features that this modem supports, used to match requirements in</span><br><span style="color: hsl(0, 100%, 40%);">- suites or scenarios. Any combination of:</span><br><span style="color: hsl(0, 100%, 40%);">- - 'sms'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'gprs'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'voice'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'ussd'</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Side note: at first sight it might make sense to the reader to rather structure</span><br><span style="color: hsl(0, 100%, 40%);">-e.g. the 'ip_address' or 'arfcn' configuration as +</span><br><span style="color: hsl(0, 100%, 40%);">-'"arfcn: GSM-1800: [512, 514, ...]"', +</span><br><span style="color: hsl(0, 100%, 40%);">-but the more verbose format is chosen to stay consistent with the general</span><br><span style="color: hsl(0, 100%, 40%);">-structure of resource configurations, which the resource allocation algorithm</span><br><span style="color: hsl(0, 100%, 40%);">-uses to resolve required resources according to their traits. These</span><br><span style="color: hsl(0, 100%, 40%);">-configurations look cumbersome because they exhibit only one trait / a trait</span><br><span style="color: hsl(0, 100%, 40%);">-that is repeated numerous times. No special notation for these cases is</span><br><span style="color: hsl(0, 100%, 40%);">-available (yet).</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-[[default_suites]]</span><br><span style="color: hsl(0, 100%, 40%);">-=== 'default-suites.conf' (optional)</span><br><span style="color: hsl(0, 100%, 40%);">-</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(0, 100%, 40%);">-combination strings as defined by the 'osmo-gsm-tester.py -s' commandline</span><br><span style="color: hsl(0, 100%, 40%);">-option. If invoking the 'osmo-gsm-tester.py' without any suite definitions, the</span><br><span style="color: hsl(0, 100%, 40%);">-'-s' arguments are taken from this file instead. Each of these suite + scenario</span><br><span style="color: hsl(0, 100%, 40%);">-combinations is run in sequence.</span><br><span style="color: hsl(0, 100%, 40%);">-</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(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-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(0, 100%, 40%);">-</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>-----</span><br><span style="color: hsl(0, 100%, 40%);">-- sms:sysmo</span><br><span style="color: hsl(0, 100%, 40%);">-- voice:sysmo+tch_f</span><br><span style="color: hsl(0, 100%, 40%);">-- voice:sysmo+tch_h</span><br><span style="color: hsl(0, 100%, 40%);">-- voice:sysmo+dyn_ts</span><br><span style="color: hsl(0, 100%, 40%);">-- sms:trx</span><br><span style="color: hsl(0, 100%, 40%);">-- voice:trx+tch_f</span><br><span style="color: hsl(0, 100%, 40%);">-- voice:trx+tch_h</span><br><span style="color: hsl(0, 100%, 40%);">-- voice:trx+dyn_ts</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-=== 'defaults.conf' (optional)</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Each binary run by osmo-gsm-tester, e.g. 'osmo-nitb' or 'osmo-bts-sysmo',</span><br><span style="color: hsl(0, 100%, 40%);">-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(0, 100%, 40%);">-</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 style="color: hsl(0, 100%, 40%);">-</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>-----</span><br><span style="color: hsl(0, 100%, 40%);">-nitb:</span><br><span style="color: hsl(0, 100%, 40%);">- net:</span><br><span style="color: hsl(0, 100%, 40%);">- mcc: 901</span><br><span style="color: hsl(0, 100%, 40%);">- mnc: 70</span><br><span style="color: hsl(0, 100%, 40%);">- short_name: osmo-gsm-tester-nitb</span><br><span style="color: hsl(0, 100%, 40%);">- long_name: osmo-gsm-tester-nitb</span><br><span style="color: hsl(0, 100%, 40%);">- auth_policy: closed</span><br><span style="color: hsl(0, 100%, 40%);">- encryption: a5_0</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-bsc:</span><br><span style="color: hsl(0, 100%, 40%);">- net:</span><br><span style="color: hsl(0, 100%, 40%);">- mcc: 901</span><br><span style="color: hsl(0, 100%, 40%);">- mnc: 70</span><br><span style="color: hsl(0, 100%, 40%);">- short_name: osmo-gsm-tester-msc</span><br><span style="color: hsl(0, 100%, 40%);">- long_name: osmo-gsm-tester-msc</span><br><span style="color: hsl(0, 100%, 40%);">- auth_policy: closed</span><br><span style="color: hsl(0, 100%, 40%);">- encryption: a5_0</span><br><span style="color: hsl(0, 100%, 40%);">- authentication: optional</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-msc:</span><br><span style="color: hsl(0, 100%, 40%);">- net:</span><br><span style="color: hsl(0, 100%, 40%);">- mcc: 901</span><br><span style="color: hsl(0, 100%, 40%);">- mnc: 70</span><br><span style="color: hsl(0, 100%, 40%);">- short_name: osmo-gsm-tester-msc</span><br><span style="color: hsl(0, 100%, 40%);">- long_name: osmo-gsm-tester-msc</span><br><span style="color: hsl(0, 100%, 40%);">- auth_policy: closed</span><br><span style="color: hsl(0, 100%, 40%);">- encryption: a5_0</span><br><span style="color: hsl(0, 100%, 40%);">- authentication: optional</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-bsc_bts:</span><br><span style="color: hsl(0, 100%, 40%);">- location_area_code: 23</span><br><span style="color: hsl(0, 100%, 40%);">- base_station_id_code: 63</span><br><span style="color: hsl(0, 100%, 40%);">- stream_id: 255</span><br><span style="color: hsl(0, 100%, 40%);">- osmobsc_bts_type: sysmobts</span><br><span style="color: hsl(0, 100%, 40%);">- trx_list:</span><br><span style="color: hsl(0, 100%, 40%);">- - nominal_power: 23</span><br><span style="color: hsl(0, 100%, 40%);">- max_power_red: 0</span><br><span style="color: hsl(0, 100%, 40%);">- arfcn: 868</span><br><span style="color: hsl(0, 100%, 40%);">- timeslot_list:</span><br><span style="color: hsl(0, 100%, 40%);">- - phys_chan_config: CCCH+SDCCH4</span><br><span style="color: hsl(0, 100%, 40%);">- - phys_chan_config: SDCCH8</span><br><span style="color: hsl(0, 100%, 40%);">- - phys_chan_config: TCH/F_TCH/H_PDCH</span><br><span style="color: hsl(0, 100%, 40%);">- - phys_chan_config: TCH/F_TCH/H_PDCH</span><br><span style="color: hsl(0, 100%, 40%);">- - phys_chan_config: TCH/F_TCH/H_PDCH</span><br><span style="color: hsl(0, 100%, 40%);">- - phys_chan_config: TCH/F_TCH/H_PDCH</span><br><span style="color: hsl(0, 100%, 40%);">- - phys_chan_config: TCH/F_TCH/H_PDCH</span><br><span style="color: hsl(0, 100%, 40%);">- - phys_chan_config: TCH/F_TCH/H_PDCH</span><br><span>-----</span><br><span>diff --git a/OsmoGSMTester/chapters/debugging.adoc b/OsmoGSMTester/chapters/debugging.adoc</span><br><span>deleted file mode 100644</span><br><span>index bea1e5c..0000000</span><br><span>--- a/OsmoGSMTester/chapters/debugging.adoc</span><br><span>+++ /dev/null</span><br><span>@@ -1,4 +0,0 @@</span><br><span style="color: hsl(0, 100%, 40%);">-[[debugging]]</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%);">-*TODO*: describe how to invoke 'ipdb3' and step into a suite's test script</span><br><span>diff --git a/OsmoGSMTester/chapters/install.adoc b/OsmoGSMTester/chapters/install.adoc</span><br><span>deleted file mode 100644</span><br><span>index d19f909..0000000</span><br><span>--- a/OsmoGSMTester/chapters/install.adoc</span><br><span>+++ /dev/null</span><br><span>@@ -1,664 +0,0 @@</span><br><span style="color: hsl(0, 100%, 40%);">-== Installation on Main Unit</span><br><span style="color: hsl(0, 100%, 40%);">-</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(0, 100%, 40%);">-</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(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-[[jenkins_deps]]</span><br><span style="color: hsl(0, 100%, 40%);">-==== Osmocom Build Dependencies</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Each of the jenkins builds requires individual dependencies. This is generally</span><br><span style="color: hsl(0, 100%, 40%);">-the same as for building the software outside of osmo-gsm-tester and will not</span><br><span style="color: hsl(0, 100%, 40%);">-be detailed here. For the Osmocom projects, refer to</span><br><span style="color: hsl(0, 100%, 40%);">-http://osmocom.org/projects/cellular-infrastructure/wiki/Build_from_Source . Be</span><br><span style="color: hsl(0, 100%, 40%);">-aware of specific requirements for BTS hardware: for example, the</span><br><span style="color: hsl(0, 100%, 40%);">-osmo-bts-sysmo build needs the sysmoBTS SDK installed on the build slave, which</span><br><span style="color: hsl(0, 100%, 40%);">-should match the installed sysmoBTS firmware.</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%);">-[[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(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-On the main unit, create a jenkins user:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-useradd -m jenkins</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-==== Install Java on Main Unit</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-To be able to launch the Jenkins build slave, a Java RE must be available on</span><br><span style="color: hsl(0, 100%, 40%);">-the main unit. For example:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-apt-get install default-jdk</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-==== Allow SSH Access from Jenkins Master</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Create an SSH keypair to be used for login on the osmo-gsm-tester. This may be</span><br><span style="color: hsl(0, 100%, 40%);">-entered on the jenkins web UI; alternatively, use the jenkins server's shell:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Login on the main jenkins server shell and create an SSH keypair, for example:</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%);">-$ mkdir -p /usr/local/jenkins/keys</span><br><span style="color: hsl(0, 100%, 40%);">-$ ssh-keygen</span><br><span style="color: hsl(0, 100%, 40%);">-Generating public/private rsa key pair.</span><br><span style="color: hsl(0, 100%, 40%);">-Enter file in which to save the key (/home/jenkins/.ssh/id_rsa): /usr/local/jenkins/keys/osmo-gsm-tester-rnd</span><br><span style="color: hsl(0, 100%, 40%);">-Enter passphrase (empty for no passphrase): <enter a passphrase></span><br><span style="color: hsl(0, 100%, 40%);">-Enter same passphrase again: <enter a passphrase></span><br><span style="color: hsl(0, 100%, 40%);">-Your identification has been saved in /usr/local/jenkins/keys/osmo-gsm-tester-rnd</span><br><span style="color: hsl(0, 100%, 40%);">-Your public key has been saved in /usr/local/jenkins/keys/osmo-gsm-tester-rnd.pub.</span><br><span style="color: hsl(0, 100%, 40%);">-The key fingerprint is:</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%);">-Copy the public key to the main unit, e.g. copy-paste:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-cat /usr/local/jenkins/keys/osmo-gsm-tester-rnd.pub</span><br><span style="color: hsl(0, 100%, 40%);">-# copy this public key</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-On the main unit:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-mkdir ~jenkins/.ssh</span><br><span style="color: hsl(0, 100%, 40%);">-cat > ~jenkins/.ssh/authorized_keys</span><br><span style="color: hsl(0, 100%, 40%);">-# paste above public key and hit Ctrl-D</span><br><span style="color: hsl(0, 100%, 40%);">-chown -R jenkins: ~jenkins/.ssh</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Make sure that the user running the jenkins master accepts the main unit's host</span><br><span style="color: hsl(0, 100%, 40%);">-identification. There must be an actual RSA host key available in the</span><br><span style="color: hsl(0, 100%, 40%);">-known_hosts file for the jenkins master to be able to log in. Simply calling</span><br><span style="color: hsl(0, 100%, 40%);">-ssh and accepting the host key as usual is not enough. Jenkins may continue to</span><br><span style="color: hsl(0, 100%, 40%);">-say "Host key verification failed".</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-To place an RSA host key in the jenkins' known_hosts file, you may do:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-On the Jenkins master:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-main_unit_ip=10.9.8.7</span><br><span style="color: hsl(0, 100%, 40%);">-ssh-keyscan -H $main_unit_ip >> ~jenkins/.ssh/known_hosts</span><br><span style="color: hsl(0, 100%, 40%);">-chown jenkins: ~jenkins/.ssh/known_hosts</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Verify that the jenkins user on the Jenkins master has SSH access to the main</span><br><span style="color: hsl(0, 100%, 40%);">-unit:</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%);">-main_unit_ip=10.9.8.7</span><br><span style="color: hsl(0, 100%, 40%);">-ssh -i /usr/local/jenkins/keys/osmo-gsm-tester-rnd jenkins@$main_unit_ip</span><br><span style="color: hsl(0, 100%, 40%);">-exit</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-[[install_add_jenkins_slave]]</span><br><span style="color: hsl(0, 100%, 40%);">-==== Add Jenkins Slave</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-In the jenkins web UI, add a new build slave for the osmo-gsm-tester:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-* 'Manage Jenkins'</span><br><span style="color: hsl(0, 100%, 40%);">-** 'Manage Nodes'</span><br><span style="color: hsl(0, 100%, 40%);">-*** 'New Node'</span><br><span style="color: hsl(0, 100%, 40%);">-**** Enter a node name, e.g. "osmo-gsm-tester-1" +</span><br><span style="color: hsl(0, 100%, 40%);">- (the "-1" is just some identification in case you'd like to add another</span><br><span style="color: hsl(0, 100%, 40%);">- setup later).</span><br><span style="color: hsl(0, 100%, 40%);">-**** 'Permanent Agent'</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Configure the node as:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-* '# of executors': 1</span><br><span style="color: hsl(0, 100%, 40%);">-* 'Remote root directory': "/home/jenkins"</span><br><span style="color: hsl(0, 100%, 40%);">-* 'Labels': "osmo-gsm-tester" +</span><br><span style="color: hsl(0, 100%, 40%);">- (This is a general label common to all osmo-gsm-tester build slaves you may set up in the future.)</span><br><span style="color: hsl(0, 100%, 40%);">-* 'Usage': 'Only build jobs with label expressions matching this node'</span><br><span style="color: hsl(0, 100%, 40%);">-* 'Launch method': 'Launch slave agents via SSH'</span><br><span style="color: hsl(0, 100%, 40%);">-** 'Host': your main unit's IP address</span><br><span style="color: hsl(0, 100%, 40%);">-** 'Credentials': choose 'Add' / 'Jenkins'</span><br><span style="color: hsl(0, 100%, 40%);">-*** 'Domain': 'Global credentials (unrestricted)'</span><br><span style="color: hsl(0, 100%, 40%);">-*** 'Kind': 'SSH Username with private key'</span><br><span style="color: hsl(0, 100%, 40%);">-*** 'Scope': 'Global'</span><br><span style="color: hsl(0, 100%, 40%);">-*** 'Username': "jenkins" +</span><br><span style="color: hsl(0, 100%, 40%);">- (as created on the main unit above)</span><br><span style="color: hsl(0, 100%, 40%);">-*** 'Private Key': 'From a file on Jenkins master'</span><br><span style="color: hsl(0, 100%, 40%);">-**** 'File': "/usr/local/jenkins/keys/osmo-gsm-tester-rnd"</span><br><span style="color: hsl(0, 100%, 40%);">-*** 'Passphrase': enter same passphrase as above</span><br><span style="color: hsl(0, 100%, 40%);">-*** 'ID': "osmo-gsm-tester-1"</span><br><span style="color: hsl(0, 100%, 40%);">-*** 'Name': "jenkins for SSH to osmo-gsm-tester-1"</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-The build slave should be able to start now.</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%);">-==== 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 style="color: hsl(0, 100%, 40%);">-==== Add Run Job</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-This is the jenkins job that runs the tests on the GSM hardware:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-* It sources the artifacts from jenkins' build jobs.</span><br><span style="color: hsl(0, 100%, 40%);">-* It runs on the osmo-gsm-tester main unit.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Here is the configuration for the run job:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-* 'Project name': "osmo-gsm-tester_run"</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': "osmo-gsm-tester" +</span><br><span style="color: hsl(0, 100%, 40%);">- (to match the 'Label' configured in <<install_add_jenkins_slave>>).</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%);">-**** 'Clean before checkout'</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. For this run job, it is suggested</span><br><span style="color: hsl(0, 100%, 40%);">- to rebuild:</span><br><span style="color: hsl(0, 100%, 40%);">-** after each of above build jobs that produced new artifacts: +</span><br><span style="color: hsl(0, 100%, 40%);">- 'Build after other projects are built': "osmo-gsm-tester_build-osmo-nitb,</span><br><span style="color: hsl(0, 100%, 40%);">- osmo-gsm-tester_build-osmo-bts-sysmo, osmo-gsm-tester_build-osmo-bts-trx" +</span><br><span style="color: hsl(0, 100%, 40%);">- (Add each build job name you configured above)</span><br><span style="color: hsl(0, 100%, 40%);">-** as well as 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%);">-** and, in addition, whenever the osmo-gsm-tester scripts have been modified: +</span><br><span style="color: hsl(0, 100%, 40%);">- 'Poll SCM': "H/5 * * * *" +</span><br><span style="color: hsl(0, 100%, 40%);">- (i.e. look every five minutes whether the upstream git has changed)</span><br><span style="color: hsl(0, 100%, 40%);">-* 'Build'</span><br><span style="color: hsl(0, 100%, 40%);">-** Copy artifacts from each build job you have set up:</span><br><span style="color: hsl(0, 100%, 40%);">-*** 'Copy artifacts from another project'</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%);">-**** 'Which build': 'Latest successful build'</span><br><span style="color: hsl(0, 100%, 40%);">-**** enable 'Stable build only'</span><br><span style="color: hsl(0, 100%, 40%);">-**** 'Artifacts to copy': "*.tgz, *.md5"</span><br><span style="color: hsl(0, 100%, 40%);">-*** Add a separate similar 'Copy artifacts...' section for each build job you</span><br><span style="color: hsl(0, 100%, 40%);">- have set up.</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%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-# debug: provoke a failure</span><br><span style="color: hsl(0, 100%, 40%);">-#export OSMO_GSM_TESTER_OPTS="-s debug -t fail"</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-PATH="$PWD/osmo-gsm-tester/src:$PATH" \</span><br><span style="color: hsl(0, 100%, 40%);">- ./osmo-gsm-tester/contrib/jenkins-run.sh</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-+</span><br><span style="color: hsl(0, 100%, 40%);">-Details:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-*** The 'jenkins-run.sh' script assumes to find the 'osmo-gsm-tester.py' in the</span><br><span style="color: hsl(0, 100%, 40%);">- '$PATH'. To use the most recent osmo-gsm-tester code here, we direct</span><br><span style="color: hsl(0, 100%, 40%);">- '$PATH' to the actual workspace checkout. This could also run from a sytem</span><br><span style="color: hsl(0, 100%, 40%);">- wide install, in which case you could omit the explicit PATH to</span><br><span style="color: hsl(0, 100%, 40%);">- "$PWD/osmo-gsm-tester/src".</span><br><span style="color: hsl(0, 100%, 40%);">-*** This assumes that there are configuration files for osmo-gsm-tester placed</span><br><span style="color: hsl(0, 100%, 40%);">- on the system (see <<config_paths>>).</span><br><span style="color: hsl(0, 100%, 40%);">-*** If you'd like to check the behavior of test failures, you can uncomment the</span><br><span style="color: hsl(0, 100%, 40%);">- line below "# debug" to produce a build failure on every run. Note that</span><br><span style="color: hsl(0, 100%, 40%);">- this test typically produces a quite empty run result, since it launches no</span><br><span style="color: hsl(0, 100%, 40%);">- NITB nor BTS.</span><br><span style="color: hsl(0, 100%, 40%);">-* 'Post-build Actions'</span><br><span style="color: hsl(0, 100%, 40%);">-** 'Archive the artifacts'</span><br><span style="color: hsl(0, 100%, 40%);">-*** 'Files to archive': "*-run.tgz, *-bin.tgz" +</span><br><span style="color: hsl(0, 100%, 40%);">- This stores the complete test report with config files, logs, stdout/stderr</span><br><span style="color: hsl(0, 100%, 40%);">- output, pcaps as well as the binaries used for the test run in artifacts.</span><br><span style="color: hsl(0, 100%, 40%);">- This allows analysis of older builds, instead of only the most recent build</span><br><span style="color: hsl(0, 100%, 40%);">- (which cleans up the jenkins workspace every time). The 'trial-N-run.tgz'</span><br><span style="color: hsl(0, 100%, 40%);">- and 'trial-N-bin.tgz' archives are produced by the 'jenkins-run.sh' script,</span><br><span style="color: hsl(0, 100%, 40%);">- both for successful and failing runs.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-=== Install osmo-gsm-tester on Main Unit</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-This assumes you have already created the jenkins user (see <<configure_jenkins_slave>>).</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-==== User Permissions</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-On the main unit, create a group for all users that should be allowed to use</span><br><span style="color: hsl(0, 100%, 40%);">-the osmo-gsm-tester, and add users (here 'jenkins') to this group.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-groupadd osmo-gsm-tester</span><br><span style="color: hsl(0, 100%, 40%);">-gpasswd -a jenkins osmo-gsm-tester</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-NOTE: you may also need to add users to the 'usrp' group, see</span><br><span style="color: hsl(0, 100%, 40%);">-<<user_config_uhd>>.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-A user added to a group needs to re-login for the group permissions to take</span><br><span style="color: hsl(0, 100%, 40%);">-effect.</span><br><span style="color: hsl(0, 100%, 40%);">-</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 style="color: hsl(0, 100%, 40%);">-===== Paths</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Assuming that you are using the example config, prepare a system wide state</span><br><span style="color: hsl(0, 100%, 40%);">-location in '/var/tmp':</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-mkdir -p /var/tmp/osmo-gsm-tester/state</span><br><span style="color: hsl(0, 100%, 40%);">-chown -R :osmo-gsm-tester /var/tmp/osmo-gsm-tester</span><br><span style="color: hsl(0, 100%, 40%);">-chmod -R g+rwxs /var/tmp/osmo-gsm-tester</span><br><span style="color: hsl(0, 100%, 40%);">-setfacl -d -m group:osmo-gsm-tester:rwx /var/tmp/osmo-gsm-tester/state</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-IMPORTANT: the state directory needs to be shared between all users potentially</span><br><span style="color: hsl(0, 100%, 40%);">-running the osmo-gsm-tester to resolve resource allocations. Above 'setfacl'</span><br><span style="color: hsl(0, 100%, 40%);">-command sets the access control to keep all created files group writable.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-With the jenkins build as described here, the trials will live in the build</span><br><span style="color: hsl(0, 100%, 40%);">-slave's workspace. Other modes of operation (a daemon scheduling concurrent</span><br><span style="color: hsl(0, 100%, 40%);">-runs, *TODO*) may use a system wide directory to manage trials to run:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-mkdir -p /var/tmp/osmo-gsm-tester/trials</span><br><span style="color: hsl(0, 100%, 40%);">-chown -R :osmo-gsm-tester /var/tmp/osmo-gsm-tester</span><br><span style="color: hsl(0, 100%, 40%);">-chmod -R g+rwxs /var/tmp/osmo-gsm-tester</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-===== Allow DBus Access to ofono</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Put a DBus configuration file in place that allows the 'osmo-gsm-tester' group</span><br><span style="color: hsl(0, 100%, 40%);">-to access the org.ofono DBus path:</span><br><span style="color: hsl(0, 100%, 40%);">-</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(0, 100%, 40%);">-<!-- Additional rules for the osmo-gsm-tester to access org.ofono from user</span><br><span style="color: hsl(0, 100%, 40%);">- land --></span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"</span><br><span style="color: hsl(0, 100%, 40%);">- "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"></span><br><span style="color: hsl(0, 100%, 40%);">-<busconfig></span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- <policy group="osmo-gsm-tester"></span><br><span style="color: hsl(0, 100%, 40%);">- <allow send_destination="org.ofono"/></span><br><span style="color: hsl(0, 100%, 40%);">- </policy></span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-</busconfig></span><br><span style="color: hsl(0, 100%, 40%);">-END</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-(No restart of dbus nor ofono necessary.)</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-[[install_capture_packets]]</span><br><span style="color: hsl(0, 100%, 40%);">-===== Capture Packets</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-In order to allow collecting pcap traces of the network communication for later</span><br><span style="color: hsl(0, 100%, 40%);">-reference, allow the osmo-gsm-tester group to capture packets using the 'tcpdump'</span><br><span style="color: hsl(0, 100%, 40%);">-program:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-chgrp osmo-gsm-tester /usr/sbin/tcpdump</span><br><span style="color: hsl(0, 100%, 40%);">-chmod 750 /usr/sbin/tcpdump</span><br><span style="color: hsl(0, 100%, 40%);">-setcap cap_net_raw,cap_net_admin=eip /usr/sbin/tcpdump</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Put 'tcpdump' in the '$PATH' -- assuming that 'tcpdump' is available for root:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-ln -s `which tcpdump` /usr/local/bin/tcpdump</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-TIP: Why a symlink in '/usr/local/bin'? On Debian, 'tcpdump' lives in</span><br><span style="color: hsl(0, 100%, 40%);">-'/usr/sbin', which is not part of the '$PATH' for non-root users. To avoid</span><br><span style="color: hsl(0, 100%, 40%);">-hardcoding non-portable paths in the osmo-gsm-tester source, 'tcpdump' must be</span><br><span style="color: hsl(0, 100%, 40%);">-available in the '$PATH'. There are various trivial ways to modify '$PATH' for</span><br><span style="color: hsl(0, 100%, 40%);">-login shells, but the jenkins build slave typically runs in a *non-login*</span><br><span style="color: hsl(0, 100%, 40%);">-shell; modifying non-login shell enviroments is not trivially possible without</span><br><span style="color: hsl(0, 100%, 40%);">-also interfering with files installed from debian packages. Probably the</span><br><span style="color: hsl(0, 100%, 40%);">-easiest way to allow all users and all shells to find the 'tcpdump' binary is</span><br><span style="color: hsl(0, 100%, 40%);">-to actually place a symbolic link in a directory that is already part of the</span><br><span style="color: hsl(0, 100%, 40%);">-non-login shell's '$PATH'. Above example places such in '/usr/local/bin'.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Verify that a non-login shell can find 'tcpdump':</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-su jenkins -c 'which tcpdump'</span><br><span style="color: hsl(0, 100%, 40%);">-# should print: "/usr/local/bin/tcpdump"</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-WARNING: When logged in via SSH on your main unit, running 'tcpdump' to capture</span><br><span style="color: hsl(0, 100%, 40%);">-packets may result in a feedback loop: SSH activity to send tcpdump's output to</span><br><span style="color: hsl(0, 100%, 40%);">-your terminal is in turn is picked up in the tcpdump trace, and so forth. When</span><br><span style="color: hsl(0, 100%, 40%);">-testing 'tcpdump' access, make sure to have proper filter expressions in place.</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 limit rule. Create a file with the required rule:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-sudo -s</span><br><span style="color: hsl(0, 100%, 40%);">-echo "@osmo-gsm-tester - core unlimited" > /etc/security/limits.d/osmo-gsm-tester_allow-core.conf</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Re-login the user to make these changes take effect.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Set the *kernel.core_pattern* sysctl to *core* (usually the default). For each</span><br><span style="color: hsl(0, 100%, 40%);">-binary run by osmo-gsm-tester, a core file will then appear in the same dir that</span><br><span style="color: hsl(0, 100%, 40%);">-contains stdout and stderr for that process (because this dir is set as CWD).</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-sysctl -w kernel.core_pattern=core</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-===== Allow Realtime Priority</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Certain binaries should be run with real-time priority, like 'osmo-bts-trx'.</span><br><span style="color: hsl(0, 100%, 40%);">-Add this permission on the main unit:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-sudo -s</span><br><span style="color: hsl(0, 100%, 40%);">-echo "@osmo-gsm-tester - rtprio 99" > /etc/security/limits.d/osmo-gsm-tester_allow-rtprio.conf</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-Re-login the user to make these changes take effect.</span><br><span style="color: hsl(0, 100%, 40%);">-</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(0, 100%, 40%);">-</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(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-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(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-To be able to set the following capability without being root, osmo-gsm-tester</span><br><span style="color: hsl(0, 100%, 40%);">-uses sudo to gain permissions to set the capability.</span><br><span style="color: hsl(0, 100%, 40%);">-</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(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-echo /usr/local/bin/osmo-gsm-tester_setcap_net_raw.sh <<EOF</span><br><span style="color: hsl(0, 100%, 40%);">-#!/bin/bash</span><br><span style="color: hsl(0, 100%, 40%);">-/sbin/setcap cap_net_raw+ep $1</span><br><span style="color: hsl(0, 100%, 40%);">-EOF</span><br><span style="color: hsl(0, 100%, 40%);">-chmod +x /usr/local/bin/osmo-gsm-tester_setcap_net_raw.sh</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</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(0, 100%, 40%);">-osmo-gsm-tester:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-echo "%osmo-gsm-tester ALL=(root) NOPASSWD: /usr/local/bin/osmo-gsm-tester_setcap_net_raw.sh" > /etc/sudoers.d/osmo-gsm-tester_setcap_net_raw</span><br><span style="color: hsl(0, 100%, 40%);">-chmod 0440 /etc/sudoers.d/osmo-gsm-tester_setcap_net_raw</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-The script file name 'osmo-gsm-tester_setcap_net_raw.sh' is important, as</span><br><span style="color: hsl(0, 100%, 40%);">-osmo-gsm-tester expects to find a script with this name in '$PATH' at run time.</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%);">-==== Log Rotation</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-To avoid clogging up /var/log, it makes sense to choose a sane maximum log size:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-echo maxsize 10M > /etc/logrotate.d/maxsize</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-==== Install Scripts</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-IMPORTANT: When using the jenkins build slave as configured above, *there is no</span><br><span style="color: hsl(0, 100%, 40%);">-need to install the osmo-gsm-tester sources on the main unit*. The jenkins job</span><br><span style="color: hsl(0, 100%, 40%);">-will do so implicitly by checking out the latest osmo-gsm-tester sources in the</span><br><span style="color: hsl(0, 100%, 40%);">-workspace for every run. If you're using only the jenkins build slave, you may</span><br><span style="color: hsl(0, 100%, 40%);">-skip this section.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-If you prefer to use a fixed installation of the osmo-gsm-tester sources</span><br><span style="color: hsl(0, 100%, 40%);">-instead of the jenkins workspace, you can:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-. From the run job configured above, remove the line that says</span><br><span style="color: hsl(0, 100%, 40%);">-+</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-PATH="$PWD/osmo-gsm-tester/src:$PATH" \</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-+</span><br><span style="color: hsl(0, 100%, 40%);">-so that this uses a system wide installation instead.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-. Install the sources e.g. in '/usr/local/src' as indicated below.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-On the main unit, to install the latest in '/usr/local/src':</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-apt-get install git</span><br><span style="color: hsl(0, 100%, 40%);">-mkdir -p /usr/local/src</span><br><span style="color: hsl(0, 100%, 40%);">-cd /usr/local/src</span><br><span style="color: hsl(0, 100%, 40%);">-git clone git://git.osmocom.org/osmo-gsm-tester</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-To allow all users to run 'osmo-gsm-tester.py', from login as well as non-login</span><br><span style="color: hsl(0, 100%, 40%);">-shells, the easiest solution is to place a symlink in '/usr/local/bin':</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-ln -s /usr/local/src/osmo-gsm-tester/src/osmo-gsm-tester.py /usr/local/bin/</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-(See also the tip in <<install_capture_packets>> for a more detailed</span><br><span style="color: hsl(0, 100%, 40%);">-explanation.)</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-The example configuration provided in the source is suitable for running as-is,</span><br><span style="color: hsl(0, 100%, 40%);">-*if* your hardware setup matches (you could technically use that directly by a</span><br><span style="color: hsl(0, 100%, 40%);">-symlink e.g. from '/usr/local/etc/osmo-gsm-tester' to the 'example' dir). If in</span><br><span style="color: hsl(0, 100%, 40%);">-doubt, rather copy the example, point 'paths.conf' at the 'suites' dir, and</span><br><span style="color: hsl(0, 100%, 40%);">-adjust your own configuration as needed. For example:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-cd /etc</span><br><span style="color: hsl(0, 100%, 40%);">-cp -R /usr/local/src/osmo-gsm-tester/example osmo-gsm-tester</span><br><span style="color: hsl(0, 100%, 40%);">-sed -i 's#\.\./suites#/usr/local/src/osmo-gsm-tester/suites#' osmo-gsm-tester/paths.conf</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-NOTE: The configuration will be looked up in various places, see</span><br><span style="color: hsl(0, 100%, 40%);">-<<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/OsmoGSMTester/chapters/intro.adoc b/OsmoGSMTester/chapters/intro.adoc</span><br><span>deleted file mode 100644</span><br><span>index 14daba4..0000000</span><br><span>--- a/OsmoGSMTester/chapters/intro.adoc</span><br><span>+++ /dev/null</span><br><span>@@ -1,400 +0,0 @@</span><br><span style="color: hsl(0, 100%, 40%);">-== Introduction with Examples</span><br><span style="color: hsl(0, 100%, 40%);">-</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(0, 100%, 40%);">-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(0, 100%, 40%);">-</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(0, 100%, 40%);">-</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(0, 100%, 40%);">-</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(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-.Typical osmo-gsm-tester setup</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=LR;</span><br><span style="color: hsl(0, 100%, 40%);">- jenkins</span><br><span style="color: hsl(0, 100%, 40%);">- subgraph cluster_gsm_hardware {</span><br><span style="color: hsl(0, 100%, 40%);">- label = "GSM Hardware";</span><br><span style="color: hsl(0, 100%, 40%);">- style=dotted</span><br><span style="color: hsl(0, 100%, 40%);">-</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(0, 100%, 40%);">- osmo_bts_sysmo [label="sysmocom sysmoBTS\nrunning osmo-bts-sysmo" shape=box]</span><br><span style="color: hsl(0, 100%, 40%);">- B200 [label="Ettus B200" shape=box]</span><br><span style="color: hsl(0, 100%, 40%);">- sysmoCell5K [label="sysmocom sysmoCell5000" shape=box]</span><br><span style="color: hsl(0, 100%, 40%);">- octphy [label="Octasic octphy BTS" shape=box]</span><br><span style="color: hsl(0, 100%, 40%);">- nanoBTS [label="ip.access nanoBTS" shape=box]</span><br><span style="color: hsl(0, 100%, 40%);">- rf_distribution [label="RF distribution"]</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- {modem0 modem1 osmo_bts_sysmo B200 octphy nanoBTS sysmoCell5K}->rf_distribution [dir=both arrowhead="curve" arrowtail="curve"]</span><br><span style="color: hsl(0, 100%, 40%);">- }</span><br><span style="color: hsl(0, 100%, 40%);">- subgraph cluster_main_unit {</span><br><span style="color: hsl(0, 100%, 40%);">- label = "Main Unit"</span><br><span style="color: hsl(0, 100%, 40%);">- osmo_gsm_tester [label="Osmo-GSM-Tester\ntest suites\n& scenarios"]</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%);">- ofono [label="ofono daemon"]</span><br><span style="color: hsl(0, 100%, 40%);">- osmo_trx [label="osmo-trx"]</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%);">- osmo_bts_octphy [label="osmo-bts-octphy"]</span><br><span style="color: hsl(0, 100%, 40%);">- OsmoNITB [label="BSC + Core Network\n(Osmo{NITB,MSC,BSC,HLR,...})"]</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%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- jenkins->osmo_gsm_tester [label="trial\n(binaries)"]</span><br><span style="color: hsl(0, 100%, 40%);">- 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(0, 100%, 40%);">- 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(0, 100%, 40%);">- 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(0, 100%, 40%);">- osmo_bts_octphy->octphy [label="raw eth"]</span><br><span style="color: hsl(0, 100%, 40%);">- {osmo_bts_sysmo nanoBTS}->OsmoNITB [label="IP"]</span><br><span style="color: hsl(0, 100%, 40%);">- {B200 octphy}->OsmoNITB [label="eth" style=invis]</span><br><span style="color: hsl(0, 100%, 40%);">- {osmo_bts_trx osmo_bts_octphy}->OsmoNITB</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 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/OsmoGSMTester/chapters/test_api.adoc b/OsmoGSMTester/chapters/test_api.adoc</span><br><span>deleted file mode 100644</span><br><span>index f541231..0000000</span><br><span>--- a/OsmoGSMTester/chapters/test_api.adoc</span><br><span>+++ /dev/null</span><br><span>@@ -1,4 +0,0 @@</span><br><span style="color: hsl(0, 100%, 40%);">-== Test API</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-*TODO* (in the meantime, look at src/osmo_gsm_tester/test.py, as well as</span><br><span style="color: hsl(0, 100%, 40%);">-suite.py, which calls the test's setup() function to get an idea)</span><br><span>diff --git a/OsmoGSMTester/chapters/trial.adoc b/OsmoGSMTester/chapters/trial.adoc</span><br><span>deleted file mode 100644</span><br><span>index bc9fe05..0000000</span><br><span>--- a/OsmoGSMTester/chapters/trial.adoc</span><br><span>+++ /dev/null</span><br><span>@@ -1,31 +0,0 @@</span><br><span style="color: hsl(0, 100%, 40%);">-[[trials]]</span><br><span style="color: hsl(0, 100%, 40%);">-== Trial: Binaries to be Tested</span><br><span style="color: hsl(0, 100%, 40%);">-</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(0, 100%, 40%);">-by jenkins using the build scripts found in osmo-gsm-tester's source in the</span><br><span style="color: hsl(0, 100%, 40%);">-'contrib/' dir, see <<install_add_jenkins_slave>>.</span><br><span style="color: hsl(0, 100%, 40%);">-</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(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-When the osmo-gsm-tester is invoked to run on such a trial directory, it will</span><br><span style="color: hsl(0, 100%, 40%);">-create a sub directory named 'inst' and unpack the tar archives into it.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-For each test run on this trial, a new subdirectory in the trial dir is</span><br><span style="color: hsl(0, 100%, 40%);">-created, named in the form of 'run.<timestamp>'. A symbolic link 'last-run'</span><br><span style="color: hsl(0, 100%, 40%);">-will point at the most recently created run dir. This run dir will accumulate:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-* the rendered configuration files used to run the binaries</span><br><span style="color: hsl(0, 100%, 40%);">-* stdout and stderr outputs of the binaries</span><br><span style="color: hsl(0, 100%, 40%);">-* pcap files for processes doing relevant network communication</span><br><span style="color: hsl(0, 100%, 40%);">-* a test log</span><br><span style="color: hsl(0, 100%, 40%);">-* jenkins parsable XML (Junit) reports</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-The script in 'contrib/jenkins-run.sh' takes care of related tasks such as</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-* creating the dir structure,</span><br><span style="color: hsl(0, 100%, 40%);">-* generating md5 sums for the various tar.gz containing software builds to be tested,</span><br><span style="color: hsl(0, 100%, 40%);">-* cleaning up after the build,</span><br><span style="color: hsl(0, 100%, 40%);">-* 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>diff --git a/OsmoGSMTester/osmo-gsm-tester-manual-docinfo.xml b/OsmoGSMTester/osmo-gsm-tester-manual-docinfo.xml</span><br><span>deleted file mode 100644</span><br><span>index 923b8ad..0000000</span><br><span>--- a/OsmoGSMTester/osmo-gsm-tester-manual-docinfo.xml</span><br><span>+++ /dev/null</span><br><span>@@ -1,47 +0,0 @@</span><br><span style="color: hsl(0, 100%, 40%);">-<revhistory></span><br><span style="color: hsl(0, 100%, 40%);">- <revision></span><br><span style="color: hsl(0, 100%, 40%);">- <revnumber>1</revnumber></span><br><span style="color: hsl(0, 100%, 40%);">- <date>April 13, 2017</date></span><br><span style="color: hsl(0, 100%, 40%);">- <authorinitials>NH</authorinitials></span><br><span style="color: hsl(0, 100%, 40%);">- <revremark></span><br><span style="color: hsl(0, 100%, 40%);">- Initial version.</span><br><span style="color: hsl(0, 100%, 40%);">- </revremark></span><br><span style="color: hsl(0, 100%, 40%);">- </revision></span><br><span style="color: hsl(0, 100%, 40%);">-</revhistory></span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-<authorgroup></span><br><span style="color: hsl(0, 100%, 40%);">- <author></span><br><span style="color: hsl(0, 100%, 40%);">- <firstname>Neels</firstname></span><br><span style="color: hsl(0, 100%, 40%);">- <surname>Hofmeyr</surname></span><br><span style="color: hsl(0, 100%, 40%);">- <email>nhofmeyr@sysmocom.de</email></span><br><span style="color: hsl(0, 100%, 40%);">- <authorinitials>NH</authorinitials></span><br><span style="color: hsl(0, 100%, 40%);">- <affiliation></span><br><span style="color: hsl(0, 100%, 40%);">- <shortaffil>sysmocom</shortaffil></span><br><span style="color: hsl(0, 100%, 40%);">- <orgname>sysmocom - s.f.m.c. GmbH</orgname></span><br><span style="color: hsl(0, 100%, 40%);">- <jobtitle>Senior Developer</jobtitle></span><br><span style="color: hsl(0, 100%, 40%);">- </affiliation></span><br><span style="color: hsl(0, 100%, 40%);">- </author></span><br><span style="color: hsl(0, 100%, 40%);">-</authorgroup></span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-<copyright></span><br><span style="color: hsl(0, 100%, 40%);">- <year>2017</year></span><br><span style="color: hsl(0, 100%, 40%);">- <holder>sysmocom - s.f.m.c. GmbH</holder></span><br><span style="color: hsl(0, 100%, 40%);">-</copyright></span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-<legalnotice></span><br><span style="color: hsl(0, 100%, 40%);">- <para></span><br><span style="color: hsl(0, 100%, 40%);">- Permission is granted to copy, distribute and/or modify this</span><br><span style="color: hsl(0, 100%, 40%);">- document under the terms of the GNU Free Documentation License,</span><br><span style="color: hsl(0, 100%, 40%);">- Version 1.3 or any later version published by the Free Software</span><br><span style="color: hsl(0, 100%, 40%);">- Foundation; with the Invariant Sections being just 'Foreword',</span><br><span style="color: hsl(0, 100%, 40%);">- 'Acknowledgements' and 'Preface', with no Front-Cover Texts,</span><br><span style="color: hsl(0, 100%, 40%);">- and no Back-Cover Texts. A copy of the license is included in</span><br><span style="color: hsl(0, 100%, 40%);">- the section entitled "GNU Free Documentation License".</span><br><span style="color: hsl(0, 100%, 40%);">- </para></span><br><span style="color: hsl(0, 100%, 40%);">- <para></span><br><span style="color: hsl(0, 100%, 40%);">- The Asciidoc source code of this manual can be found at</span><br><span style="color: hsl(0, 100%, 40%);">- <ulink url="http://git.osmocom.org/osmo-gsm-manuals/"></span><br><span style="color: hsl(0, 100%, 40%);">- http://git.osmocom.org/osmo-gsm-manuals/</span><br><span style="color: hsl(0, 100%, 40%);">- </ulink></span><br><span style="color: hsl(0, 100%, 40%);">- </para></span><br><span style="color: hsl(0, 100%, 40%);">-</legalnotice></span><br><span>diff --git a/OsmoGSMTester/osmo-gsm-tester-manual.adoc b/OsmoGSMTester/osmo-gsm-tester-manual.adoc</span><br><span>deleted file mode 100644</span><br><span>index 6f0edf7..0000000</span><br><span>--- a/OsmoGSMTester/osmo-gsm-tester-manual.adoc</span><br><span>+++ /dev/null</span><br><span>@@ -1,20 +0,0 @@</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(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-== WARNING: Work in Progress</span><br><span style="color: hsl(0, 100%, 40%);">-</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(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-include::{srcdir}/chapters/intro.adoc[]</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-include::{srcdir}/chapters/install.adoc[]</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-include::{srcdir}/chapters/config.adoc[]</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-include::{srcdir}/chapters/trial.adoc[]</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-include::{srcdir}/chapters/test_api.adoc[]</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-include::{srcdir}/chapters/debugging.adoc[]</span><br><span>diff --git a/configure.ac b/configure.ac</span><br><span>index a6f29a0..5d94e54 100644</span><br><span>--- a/configure.ac</span><br><span>+++ b/configure.ac</span><br><span>@@ -28,7 +28,6 @@</span><br><span> osmo-gsm-manuals.pc</span><br><span> Makefile</span><br><span> tests/Makefile</span><br><span style="color: hsl(0, 100%, 40%);">- OsmoGSMTester/Makefile</span><br><span> OsmoMGCP/Makefile</span><br><span> OsmoNAT/Makefile</span><br><span> OsmoNITB/Makefile</span><br><span></span><br></pre><p>To view, visit <a href="https://gerrit.osmocom.org/12000">change 12000</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/12000"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: osmo-gsm-manuals </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-MessageType: merged </div>
<div style="display:none"> Gerrit-Change-Id: I89429a306d37e267fdb335d1c177c9ede3b64444 </div>
<div style="display:none"> Gerrit-Change-Number: 12000 </div>
<div style="display:none"> Gerrit-PatchSet: 1 </div>
<div style="display:none"> Gerrit-Owner: osmith <osmith@sysmocom.de> </div>
<div style="display:none"> Gerrit-Reviewer: Jenkins Builder (1000002) </div>
<div style="display:none"> Gerrit-Reviewer: Pau Espin Pedrol <pespin@sysmocom.de> </div>
<div style="display:none"> Gerrit-Reviewer: osmith <osmith@sysmocom.de> </div>