From c0827c4287ece04aed7a7188a06422a7a9a9f893 Mon Sep 17 00:00:00 2001 From: Neels Hofmeyr Date: Sun, 23 Apr 2017 15:04:19 +0200 Subject: cosmetic: OsmoGSMTester: fix dir name All other subdirs are without dashes, but I added Osmo-GSM-Tester with dashes. Comply with the naming scheme and remove dashes. Change-Id: I36d0c94dde5deffba04b27436ae499a42c519bec --- doc/manuals/Makefile | 12 ++ doc/manuals/chapters/config.adoc | 225 +++++++++++++++++++++ doc/manuals/chapters/debugging.adoc | 4 + doc/manuals/chapters/intro.adoc | 269 +++++++++++++++++++++++++ doc/manuals/chapters/test_api.adoc | 3 + doc/manuals/chapters/trial.adoc | 21 ++ doc/manuals/osmo-gsm-tester-manual-docinfo.xml | 47 +++++ doc/manuals/osmo-gsm-tester-manual.adoc | 18 ++ 8 files changed, 599 insertions(+) create mode 100644 doc/manuals/Makefile create mode 100644 doc/manuals/chapters/config.adoc create mode 100644 doc/manuals/chapters/debugging.adoc create mode 100644 doc/manuals/chapters/intro.adoc create mode 100644 doc/manuals/chapters/test_api.adoc create mode 100644 doc/manuals/chapters/trial.adoc create mode 100644 doc/manuals/osmo-gsm-tester-manual-docinfo.xml create mode 100644 doc/manuals/osmo-gsm-tester-manual.adoc (limited to 'doc/manuals') diff --git a/doc/manuals/Makefile b/doc/manuals/Makefile new file mode 100644 index 0000000..79d414f --- /dev/null +++ b/doc/manuals/Makefile @@ -0,0 +1,12 @@ +TOPDIR := .. +ASCIIDOCS := osmo-gsm-tester-manual + +include $(TOPDIR)/build/Makefile.asciidoc.inc +include $(TOPDIR)/build/Makefile.inc + +osmo-gsm-tester-manual.pdf: chapters/*.adoc + +clean: + -rm -rf $(cleanfiles) + -rm osmo-gsm-tester-manual__*.svg + -rm osmo-gsm-tester-manual__*.png diff --git a/doc/manuals/chapters/config.adoc b/doc/manuals/chapters/config.adoc new file mode 100644 index 0000000..66f4b71 --- /dev/null +++ b/doc/manuals/chapters/config.adoc @@ -0,0 +1,225 @@ +== Configuration + +The osmo-gsm-tester looks for configuration files in various standard +directories in this order: + +- '$HOME/.config/osmo-gsm-tester/' +- '/usr/local/etc/osmo-gsm-tester/' +- '/etc/osmo-gsm-tester/' + +The config location can also be set by an environment variable +'$OSMO_GSM_TESTER_CONF', which then overrides the above locations. + +The osmo-gsm-tester expects to find the following configuration files in a +configuration directory: + +- 'paths.conf' +- 'resources.conf' +- 'default-suites.conf' (optional) +- 'defaults.conf' (optional) + +=== Format: YAML, and its Drawbacks + +The general configuration format used is YAML. The stock python YAML parser +does have several drawbacks: too many complex possibilities and alternative +ways of formatting a configuration, but at the time of writing seems to be the +only widely used configuration format that offers a simple and human readable +formatting as well as nested structuring. It is recommended to use only the +exact YAML subset seen in this manual in case the osmo-gsm-tester should move +to a less bloated parser in the future. + +Careful: if a configuration item consists of digits and starts with a zero, you +need to quote it, or it may be interpreted as an octal notation integer! Please +avoid using the octal notation on purpose, it is not provided intentionally. + +[[paths_conf]] +=== 'paths.conf' + +The 'paths.conf' file defines where to store the global state (of reserved +resources) and where to find suite and scenario definitions. + +Any relative paths found in a 'paths.conf' file are interpreted as relative to +the directory of that 'paths.conf' file. + +Example: + +---- +state_dir: '/var/run/osmo-gsm-tester' +suites_dir: './suites' +scenarios_dir: './scenarios' +---- + +If you would like to set up several separate 'paths.conf' files (not typical), +note that the 'state_dir' is used to reserve resources, which only works when +all configurations that share resources also use the same 'state_dir'. + +[[resources_conf]] +=== 'resources.conf' + +The 'resources.conf' file defines which hardware is connected to the main unit, +as well as which limited configuration items (like IP addresses or ARFCNs) +should be used. + +These resources are allocated dynamically and are not configured explicitly: + +- MSISDN: phone numbers are dealt out to test scripts in sequence on request. + +A 'resources.conf' is structured as a list of items for each resource type, +where each item has one or more settings -- for an example, see +<>. + +These kinds of resource are known: + +'nitb_iface':: + List of IP addresses to run osmo-nitb instances on. The main unit + typically has a limited number of such IP addresses configured, which + the connected BTS models can see on their network. + 'addr'::: + IPv4 address of the local interface. + +'bts':: + List of available BTS hardware. + 'label'::: + human readable label for your own reference + 'type'::: + which way to launch this BTS, one of + - 'osmo-bts-sysmo' + - 'osmo-bts-trx' + - 'osmo-bts-octphy' + - 'ipa-nanobts' + 'addr'::: + remote IP address of the BTS, used to start the BTS and tell it where + to find the OsmoNITB. + 'band'::: + GSM band that this BTS shoud use (*TODO*: allow multiple bands). One of: + - 'GSM-1800' + - 'GSM-1900' + - (*TODO*: more bands) + 'trx_list'::: + Specific TRX configurations for this BTS. There should be as many of + these as the BTS has TRXes. (*TODO*: a way to define >1 TRX without + special configuration for them.) + 'hw_addr':::: + Hardware (MAC) address of the TRX in the form of '11:22:33:44:55:66', + only used for osmo-bts-octphy. (*TODO*: and nanobts??) + 'net_device':::: + Local network device to reach the TRX's 'hw_addr' at, only used for + osmo-bts-octphy. + +'arfcn':: + List of ARFCNs to use for running BTSes, which defines the actual RF + frequency bands used. + 'arfcn'::: + ARFCN number, see e.g. + https://en.wikipedia.org/wiki/Absolute_radio-frequency_channel_number + (note that the resource type 'arfcn' contains an item trait also named + 'arfcn') + 'band'::: + GSM band name to use this ARFCN for, same as for 'bts:band' above. + +'modem':: + List of modems reachable via ofono and information on the inserted SIM + card. (Note: the MSISDN is allocated dynamically in test scripts) + 'label'::: + human readable label for your own reference + 'path'::: + ofono's path for this modem, like '/modemkind_99' + 'imsi'::: + IMSI of the inserted SIM card, like '"123456789012345"' + 'ki'::: + 16 byte authentication/encryption KI of the inserted SIM card, in + hexadecimal notation (32 characters) like + + '"00112233445566778899aabbccddeeff"' (*TODO*: authentication algorithm, + currently always comp128v1) + +Side note: at first sight it might make sense to the reader to rather structure +e.g. the 'nitb_iface' or 'arfcn' configuration as + +'"arfcn: GSM-1800: [512, 514, ...]"', + +but the more verbose format is chosen to stay consistent with the general +structure of resource configurations, which the resource allocation algorithm +uses to resolve required resources according to their traits. These +configurations look cumbersome because they exhibit only one trait / a trait +that is repeated numerous times. No special notation for these cases is +available (yet). + +[[default_suites]] +=== 'default-suites.conf' (optional) + +The 'default-suites.conf' file contains a list of 'suite:scenario+scenario+...' +combination strings as defined by the 'osmo-gsm-tester.py -s' commandline +option. If invoking the 'osmo-gsm-tester.py' without any suite definitions, the +'-s' arguments are taken from this file instead. Each of these suite + scenario +combinations is run in sequence. + +A suite name must match the name of a directory in the 'suites_dir' as defined +by 'paths.conf'. + +A scenario name must match the name of a configuration file in the +'scenarios_dir' as defined by 'paths.conf' (optionally without the '.conf' +suffix). + +For 'paths.conf', see <>. + +Example of a 'default-suites.conf' file: + +---- +- sms:sysmo +- voice:sysmo+tch_f +- voice:sysmo+tch_h +- voice:sysmo+dyn_ts +- sms:trx +- voice:trx+tch_f +- voice:trx+tch_h +- voice:trx+dyn_ts +---- + +=== 'defaults.conf' (optional) + +Each binary run by osmo-gsm-tester, e.g. 'osmo-nitb' or 'osmo-bts-sysmo', +typically has a configuration file template that is populated with values for a +trial run. + +Some of these values are provided by the 'resources.conf' from the allocated +resource(s), but not all values can be populated this way: some osmo-nitb +configuration values like the network name, encryption algorithm or timeslot +channel combinations are in fact not resources (only the nitb's interface +address is). These additional settings may be provided by the scenario +configurations, but in case the provided scenarios leave some values unset, +they are taken from this 'defaults.conf'. (A 'scenario.conf' providing a +similar setting always has precedence over the values given in a +'defaults.conf'). + +*TODO* better match this format with 'resources.conf'? + +Example of a 'defaults.conf': + +---- +nitb: + net: + mcc: 1 + mnc: 868 + short_name: osmo-gsm-tester + long_name: osmo-gsm-tester + auth_policy: closed + encryption: a5 0 + +nitb_bts: + location_area_code: 23 + base_station_id_code: 63 + stream_id: 255 + osmobsc_bts_type: sysmobts + trx_list: + - max_power_red: 22 + arfcn: 868 + timeslot_list: + - phys_chan_config: CCCH+SDCCH4 + - phys_chan_config: SDCCH8 + - phys_chan_config: TCH/F_TCH/H_PDCH + - phys_chan_config: TCH/F_TCH/H_PDCH + - phys_chan_config: TCH/F_TCH/H_PDCH + - phys_chan_config: TCH/F_TCH/H_PDCH + - phys_chan_config: TCH/F_TCH/H_PDCH + - phys_chan_config: TCH/F_TCH/H_PDCH +---- + +*TODO*: detailed descriptions diff --git a/doc/manuals/chapters/debugging.adoc b/doc/manuals/chapters/debugging.adoc new file mode 100644 index 0000000..bea1e5c --- /dev/null +++ b/doc/manuals/chapters/debugging.adoc @@ -0,0 +1,4 @@ +[[debugging]] +== Debugging + +*TODO*: describe how to invoke 'ipdb3' and step into a suite's test script diff --git a/doc/manuals/chapters/intro.adoc b/doc/manuals/chapters/intro.adoc new file mode 100644 index 0000000..c45e808 --- /dev/null +++ b/doc/manuals/chapters/intro.adoc @@ -0,0 +1,269 @@ +== Introduction with Examples + +The osmo-gsm-tester is software to run automated tests of real GSM hardware, +foremost to verify that ongoing Osmocom software development continues to work +with various BTS models, while being flexibly configurable and extendable. + +A 'main unit' (general purpose computer) is connected via ethernet and/or USB to +any number of BTS models and to any number of GSM modems via USB. The modems +and BTS instances' RF transceivers are typically wired directly to each other +via RF distribution chambers to bypass the air medium and avoid disturbing real +production cellular networks. Furthermore, the setup may include adjustable RF +attenuators to model various distances between modems and base stations. + +The osmo-gsm-tester software runs on the main unit to orchestrate the various +GSM hardware and run predefined test scripts. It typically receives binary +packages from a jenkins build service. It then automatically configures and +launches an Osmocom core network on the main unit and sets up and runs BTS +models as well as modems to form a complete ad-hoc GSM network. On this setup, +predefined test suites, combined with various scenario definitions, are run to +verify stability of the system. + +The osmo-gsm-tester is implemented in Python (version 3). It uses the ofono +daemon to control the modems connected via USB. BTS software is either run +directly on the main unit (e.g. for osmo-bts-trx, osmo-bts-octphy), run via SSH +(e.g. for a sysmoBTS) or assumed to run on a connected BTS model (e.g. for +ip.access nanoBTS). + +.Typical osmo-gsm-tester setup +[graphviz] +---- +digraph G { + rankdir=LR; + jenkins + subgraph cluster_gsm_hardware { + label = "GSM Hardware"; + style=dotted + + modem0 [shape=box label=Modem] + modem1 [shape=box label=Modem] + modem2 [shape=box label=Modem] + osmo_bts_sysmo [label="sysmocom sysmoBTS\nrunning osmo-bts-sysmo" shape=box] + B200 [label="Ettus B200" shape=box] + octphy [label="Octasic octphy BTS" shape=box] + nanoBTS [label="ip.access nanoBTS" shape=box] + rf_distribution [label="RF distribution"] + + {modem0 modem1 modem2 osmo_bts_sysmo B200 octphy nanoBTS}->rf_distribution [dir=both arrowhead="curve" arrowtail="curve"] + } + subgraph cluster_main_unit { + label = "Main Unit" + osmo_gsm_tester [label="Osmo-GSM-Tester\ntest suites\n& scenarios"] + ofono [label="ofono daemon"] + OsmoNITB + osmo_bts_trx [label="osmo-bts-trx"] + osmo_bts_octphy [label="osmo-bts-octphy"] + } + + + jenkins->osmo_gsm_tester [label="trial\n(binaries)"] + osmo_gsm_tester->jenkins [label="results"] + ofono->modem0 [label="USB"] + ofono->modem1 [label="USB"] + ofono->modem2 [label="USB"] + osmo_gsm_tester-> {OsmoNITB osmo_bts_trx osmo_bts_octphy} + osmo_gsm_tester-> osmo_bts_sysmo [taillabel="SSH"] + osmo_gsm_tester-> ofono [taillabel="DBus"] + osmo_bts_trx->B200 [label="USB"] + osmo_bts_octphy->octphy [label="raw eth"] + {osmo_bts_sysmo B200 octphy nanoBTS}->OsmoNITB [label="eth"] +} +---- + +=== Typical Test Script + +A typical single test script (part of a suite) may look like this: + +---- +#!/usr/bin/env python3 +from osmo_gsm_tester.test import * + +print('use resources...') +nitb = suite.nitb() +bts = suite.bts() +ms_mo = suite.modem() +ms_mt = suite.modem() + +print('start nitb and bts...') +nitb.bts_add(bts) +nitb.start() +sleep(1) +assert nitb.running() +bts.start() + +nitb.subscriber_add(ms_mo) +nitb.subscriber_add(ms_mt) + +ms_mo.connect(nitb) +ms_mt.connect(nitb) +wait(nitb.subscriber_attached, ms_mo, ms_mt) + +sms = ms_mo.sms_send(ms_mt.msisdn) +wait(ms_mt.sms_received, sms) +---- + +=== Resource Resolution + +- A global configuration defines which hardware is connected to the + osmo-gsm-tester main unit. +- Each suite contains a number of test scripts. The amount of resources a test + may use is defined by the test suite's 'suite.conf'. +- Which specific modems, BTS models, NITB IP addresses etc. are made available + to a test run is typically determined by a combination of scenario + configurations -- or picked automatically if not. + +[[resources_conf_example]] +=== Typical 'resources.conf' + +A global configuration of hardware may look like below; for details, see +<>. + +---- +nitb_iface: +- addr: 10.42.42.1 +- addr: 10.42.42.2 +- addr: 10.42.42.3 + +bts: +- label: sysmoBTS 1002 + type: osmo-bts-sysmo + addr: 10.42.42.114 + band: GSM-1800 + +- label: octBTS 3000 + type: osmo-bts-octphy + addr: 10.42.42.115 + band: GSM-1800 + trx_list: + - hw_addr: 00:0c:90:32:b5:8a + net_device: eth0.2342 + +- label: Ettus B210 + type: osmo-bts-trx + addr: 10.42.42.116 + band: GSM-1800 + +- label: nanoBTS 1900 + type: nanobts + addr: 10.42.42.190 + band: GSM-1900 + trx_list: + - hw_addr: 00:02:95:00:41:b3 + +arfcn: + - arfcn: 512 + band: GSM-1800 + - arfcn: 514 + band: GSM-1800 + + - arfcn: 540 + band: GSM-1900 + - arfcn: 542 + band: GSM-1900 + +modem: +- label: m7801 + path: '/wavecom_0' + imsi: 901700000007801 + ki: D620F48487B1B782DA55DF6717F08FF9 + +- label: m7802 + path: '/wavecom_1' + imsi: 901700000007802 + ki: 47FDB2D55CE6A10A85ABDAD034A5B7B3 + +- label: m7803 + path: '/wavecom_2' + imsi: 901700000007803 + ki: ABBED4C91417DF710F60675B6EE2C8D2 +---- + +=== Typical 'suites/*/suite.conf' + +The configuration that reserves a number of resources for a test suite may look +like this: + +---- +resources: + nitb_iface: + - times: 1 + bts: + - times: 1 + modem: + - times: 2 +---- + +It may also request e.g. specific BTS models, but this is typically left to +scenario configurations. + +=== Typical 'scenarios/*.conf' + +For a suite as above run as-is, any available resources are picked. This may be +combined with any number of scenario definitions to constrain which specific +resources should be used, e.g.: + +---- +resources: + bts: + - type: osmo-bts-sysmo +---- + +Which 'nitb_iface' or 'modem' is used in particular doesn't really matter, so +it can be left up to the osmo-gsm-tester to pick these automatically. + +Any number of such scenario configurations can be combined in the form +':++...', e.g. 'my_suite:sysmo+tch_f+amr'. + +=== Typical Invocations + +Each invocation of osmo-gsm-tester deploys a set of pre-compiled binaries for +the Osmocom core network as well as for the Osmocom based BTS models. To create +such a set of binaries, see <>. + +Examples for launching test trials: + +- Run the default suites (see <>) on a given set of binaries: + +---- +osmo-gsm-tester.py path/to/my-trial +---- + +- Run an explicit choice of 'suite:scenario' combinations: + +---- +osmo-gsm-tester.py path/to/my-trial -s sms:sysmo -s sms:trx -s sms:nanobts +---- + +- Run one 'suite:scenario' combination, setting log level to 'debug' and + enabling logging of full python tracebacks, and also only run just the + 'mo_mt_sms.py' test from the suite, e.g. to investigate a test failure: + +---- +osmo-gsm-tester.py path/to/my-trial -s sms:sysmo -l dbg -T -t mo_mt +---- + +A test script may also be run step-by-step in a python debugger, see +<>. + +=== Resource Reservation for Concurrent Trials + +While a test suite runs, the used resources are noted in a global state +directory in a reserved-resources file. This way, any number of trials may be +run consecutively without resource conflicts. Any test trial will only use +resources that are currently not reserved by any other test suite. The +reservation state is human readable. + +The global state directory is protected by a file lock to allow access by +separate processes. + +Also, the binaries from a trial are never installed system-wide, but are run +with a specific 'LD_LIBRARY_PATH' pointing at the trial's 'inst', so that +several trials can run consecutively without conflicting binary versions. + +Once a test suite run is complete, all its reserved resources are torn down (if +the test scripts have not done so already), and the reservations are released +automatically. + +If required resources are unavailable, the test trial fails. For consecutive +test trials, a test run needs to either wait for resources to become available, +or test suites need to be scheduled to make sense. (*<- TODO*) diff --git a/doc/manuals/chapters/test_api.adoc b/doc/manuals/chapters/test_api.adoc new file mode 100644 index 0000000..cabde4c --- /dev/null +++ b/doc/manuals/chapters/test_api.adoc @@ -0,0 +1,3 @@ +== Test API + +*TODO* diff --git a/doc/manuals/chapters/trial.adoc b/doc/manuals/chapters/trial.adoc new file mode 100644 index 0000000..16b3641 --- /dev/null +++ b/doc/manuals/chapters/trial.adoc @@ -0,0 +1,21 @@ +[[trials]] +== Trial: Binaries to be Tested + +A trial is a set of pre-built binaries to be tested. They are typically built +by jenkins using the build scripts found in osmo-gsm-tester's source in the +'contrib/' dir. + +A trial comes in the form of a directory containing a number of '*.tgz' tar +archives as well as a 'checksums.md5' file to verify the tar archives' +integrity. + +When the osmo-gsm-tester is invoked to run on such a trial directory, it will +create a sub directory named 'inst' and unpack the tar archives into it. + +For each test run on this trial, a new subdirectory in the trial dir is +created, named in the form of 'run.'. A symbolic link 'last-run' +will point at the most recently created run dir. This run dir will accumulate +the rendered configuration files used for the trial run as well as a test log +(<- *TODO*) and stdout and stderr outputs of the binaries run for the trial. +(*TODO*->) When the test is complete, jenkins parsable XML reports for the test +run will be written to the 'run.' subdir. diff --git a/doc/manuals/osmo-gsm-tester-manual-docinfo.xml b/doc/manuals/osmo-gsm-tester-manual-docinfo.xml new file mode 100644 index 0000000..923b8ad --- /dev/null +++ b/doc/manuals/osmo-gsm-tester-manual-docinfo.xml @@ -0,0 +1,47 @@ + + + 1 + April 13, 2017 + NH + + Initial version. + + + + + + + Neels + Hofmeyr + nhofmeyr@sysmocom.de + NH + + sysmocom + sysmocom - s.f.m.c. GmbH + Senior Developer + + + + + + 2017 + sysmocom - s.f.m.c. GmbH + + + + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with the Invariant Sections being just 'Foreword', + 'Acknowledgements' and 'Preface', with no Front-Cover Texts, + and no Back-Cover Texts. A copy of the license is included in + the section entitled "GNU Free Documentation License". + + + The Asciidoc source code of this manual can be found at + + http://git.osmocom.org/osmo-gsm-manuals/ + + + diff --git a/doc/manuals/osmo-gsm-tester-manual.adoc b/doc/manuals/osmo-gsm-tester-manual.adoc new file mode 100644 index 0000000..a3fb88c --- /dev/null +++ b/doc/manuals/osmo-gsm-tester-manual.adoc @@ -0,0 +1,18 @@ +Osmo-GSM-Tester Manual +====================== +Neels Hofmeyr + +== WARNING: Work in Progress + +*NOTE: The osmo-gsm-tester is still in pre-alpha stage: some parts are still +incomplete, and details will still change and move around.* + +include::chapters/intro.adoc[] + +include::chapters/config.adoc[] + +include::chapters/trial.adoc[] + +include::chapters/test_api.adoc[] + +include::chapters/debugging.adoc[] -- cgit v1.2.3 From 73207e1cee37979c69608527069956b33790b1ff Mon Sep 17 00:00:00 2001 From: Neels Hofmeyr Date: Fri, 5 May 2017 02:50:45 +0200 Subject: OsmoGSMTester: add / tweak overview graphs Some mistakes fixed (missing osmo-trx, B200 pointing at NITB instead of osmo-bts-trx) Add graph showing resource selection. Add graph showing a trial dir. Change-Id: I1cfcd99ee11b851095a75107246cb156ede7f4cf --- doc/manuals/chapters/intro.adoc | 105 +++++++++++++++++++++++++++++++++++----- 1 file changed, 94 insertions(+), 11 deletions(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/intro.adoc b/doc/manuals/chapters/intro.adoc index c45e808..46c5ec6 100644 --- a/doc/manuals/chapters/intro.adoc +++ b/doc/manuals/chapters/intro.adoc @@ -35,9 +35,9 @@ digraph G { label = "GSM Hardware"; style=dotted - modem0 [shape=box label=Modem] - modem1 [shape=box label=Modem] - modem2 [shape=box label=Modem] + modem0 [shape=box label="Modems..."] + modem1 [shape=box label="Modems..."] + modem2 [shape=box label="Modems..."] osmo_bts_sysmo [label="sysmocom sysmoBTS\nrunning osmo-bts-sysmo" shape=box] B200 [label="Ettus B200" shape=box] octphy [label="Octasic octphy BTS" shape=box] @@ -49,24 +49,107 @@ digraph G { subgraph cluster_main_unit { label = "Main Unit" osmo_gsm_tester [label="Osmo-GSM-Tester\ntest suites\n& scenarios"] - ofono [label="ofono daemon"] - OsmoNITB - osmo_bts_trx [label="osmo-bts-trx"] - osmo_bts_octphy [label="osmo-bts-octphy"] + subgraph { + rank=same + ofono [label="ofono daemon"] + OsmoNITB + osmo_bts_trx [label="osmo-bts-trx\n+ osmo-trx"] + osmo_bts_octphy [label="osmo-bts-octphy"] + } } jenkins->osmo_gsm_tester [label="trial\n(binaries)"] osmo_gsm_tester->jenkins [label="results"] - ofono->modem0 [label="USB"] - ofono->modem1 [label="USB"] - ofono->modem2 [label="USB"] + ofono->{modem0 modem1 modem2} [label="USB"] osmo_gsm_tester-> {OsmoNITB osmo_bts_trx osmo_bts_octphy} osmo_gsm_tester-> osmo_bts_sysmo [taillabel="SSH"] osmo_gsm_tester-> ofono [taillabel="DBus"] osmo_bts_trx->B200 [label="USB"] osmo_bts_octphy->octphy [label="raw eth"] - {osmo_bts_sysmo B200 octphy nanoBTS}->OsmoNITB [label="eth"] + {osmo_bts_sysmo nanoBTS}->OsmoNITB [label="eth"] + {B200 octphy}->OsmoNITB [label="eth" style=invis] + {osmo_bts_trx osmo_bts_octphy}->OsmoNITB +} +---- + +.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) +[graphviz] +---- +digraph G { + rankdir=TB; + + suite_scenarios [label="Suite+Scenarios selection\nsms:sysmo+band1800"] + + subgraph { + rank=same; + suite + scenarios + } + + subgraph cluster_scenarios { + label = "Scenarios"; + u_sysmoBTS [label="Scenario: sysmo\nbts: type: osmo-bts-sysmo"] + u_trx [label="Scenario: trx\nbts: type: osmo-bts-trx"] + u_arfcn [label="Scenario: band1800\narfcn: band: GSM-1800"] + } + + subgraph cluster_suite { + label = "Suite: sms"; + requires [label="Requirements (suite.conf):\nmodem: times: 2\nbts\nnitb_iface\narfcn"] + subgraph cluster_tests { + label = "Test Scripts (py)"; + mo_mt_sms + etc + } + } + + subgraph cluster_resources { + label = "Resources"; + rankdir=TB; + nitb_addr1 [label="NITB interface addr\n10.42.42.1"] + nitb_addr2 [label="NITB interface addr\n10.42.42.2"] + Modem0 + Modem1 + Modem2 + sysmoBTS [label="osmo-bts-sysmo"] + osmo_bts_trx [label="osmo-bts-trx"] + arfcn1 [label="arfcn: 512\nband: GSM-1800"] + arfcn2 [label="arfcn: 540\nband: GSM-1900"] + + arfcn1->arfcn2 [style=invis] + nitb_addr1->nitb_addr2 [style=invis] + Modem0 -> Modem1 -> Modem2 [style=invis] + sysmoBTS -> osmo_bts_trx [style=invis] + } + + suite_scenarios -> {suite scenarios} + scenarios -> { u_arfcn u_sysmoBTS } + + suite -> requires + requires -> Modem0 + requires -> Modem1 + requires -> sysmoBTS + requires -> arfcn1 + requires -> nitb_addr1 + + { u_sysmoBTS u_arfcn } -> requires [label="influences\nresource\nselection"] +} +---- + +.Example of a "trial" containing binaries built by a jenkins +[graphviz] +---- +digraph G { + subgraph cluster_trial { + label = "Trial (binaries)" + sysmo [label="osmo-bts-sysmo.build-23.tgz\n(osmo-bts-sysmo\n+ deps\ncompiled for sysmoBTS)"] + trx [label="osmo-bts-trx.build-5.tgz\n(osmo-trx + osmo-bts-trx\n+ deps\ncompiled for main unit)"] + nitb [label="osmo-nitb.build-42.tgz\n(osmo-nitb\n+ deps\ncompiled for main unit)"] + checksums [label="checksums.md5"] + + checksums -> {sysmo trx nitb} + } } ---- -- cgit v1.2.3 From b52df17e8bd62349f54b49a25e9eef93d153dbcf Mon Sep 17 00:00:00 2001 From: Neels Hofmeyr Date: Sun, 14 May 2017 20:09:35 +0200 Subject: OsmoGSMTester: add install docs; fixes and tweaks Change-Id: I574937dbf31bce49cfb7523f91041c20fecb421e --- doc/manuals/chapters/config.adoc | 17 +- doc/manuals/chapters/install.adoc | 600 ++++++++++++++++++++++++++++++++ doc/manuals/chapters/test_api.adoc | 3 +- doc/manuals/chapters/trial.adoc | 14 +- doc/manuals/osmo-gsm-tester-manual.adoc | 2 + 5 files changed, 624 insertions(+), 12 deletions(-) create mode 100644 doc/manuals/chapters/install.adoc (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/config.adoc b/doc/manuals/chapters/config.adoc index 66f4b71..f264284 100644 --- a/doc/manuals/chapters/config.adoc +++ b/doc/manuals/chapters/config.adoc @@ -1,5 +1,8 @@ == Configuration +[[config_paths]] +=== Config Paths + The osmo-gsm-tester looks for configuration files in various standard directories in this order: @@ -18,6 +21,8 @@ configuration directory: - 'default-suites.conf' (optional) - 'defaults.conf' (optional) +These are described in detail in the following sections. + === Format: YAML, and its Drawbacks The general configuration format used is YAML. The stock python YAML parser @@ -44,14 +49,14 @@ the directory of that 'paths.conf' file. Example: ---- -state_dir: '/var/run/osmo-gsm-tester' -suites_dir: './suites' +state_dir: '/var/tmp/osmo-gsm-tester/state' +suites_dir: '/usr/local/src/osmo-gsm-tester/suites' scenarios_dir: './scenarios' ---- -If you would like to set up several separate 'paths.conf' files (not typical), -note that the 'state_dir' is used to reserve resources, which only works when -all configurations that share resources also use the same 'state_dir'. +If you would like to set up several separate configurations (not typical), note +that the 'state_dir' is used to reserve resources, which only works when all +configurations that share resources also use the same 'state_dir'. [[resources_conf]] === 'resources.conf' @@ -173,6 +178,8 @@ Example of a 'default-suites.conf' file: - voice:trx+dyn_ts ---- +*TODO*: voice is not actually implemented yet + === 'defaults.conf' (optional) Each binary run by osmo-gsm-tester, e.g. 'osmo-nitb' or 'osmo-bts-sysmo', diff --git a/doc/manuals/chapters/install.adoc b/doc/manuals/chapters/install.adoc new file mode 100644 index 0000000..17905be --- /dev/null +++ b/doc/manuals/chapters/install.adoc @@ -0,0 +1,600 @@ +== Installation on Main Unit + +The main unit is a general purpose computer that orchestrates the tests. It +runs the core network components, controls the modems and so on. This can be +anything from a dedicated production rack unit to your laptop at home. + +This manual will assume that tests are run from a jenkins build slave, by a +user named 'jenkins'. The user configuration for manual test runs and/or a +different user name is identical, simply replace the user name. + +=== Dependencies + +On a Debian/Ubuntu based system, these commands install the packages needed to +run the osmo-gsm-tester.py code, i.e. install these on your main unit: + +---- +apt-get install \ + dbus \ + tcpdump \ + python3 \ + python3-yaml \ + python3-mako \ + python3-gi \ + ofono \ + python3-pip +pip3 install pydbus +---- + +IMPORTANT: ofono may need to be installed from source to contain the most +recent fixes needed to operate your modem. This depends on the modem hardware +used and the tests run. Please see <>. + +To run osmo-bts-trx with a USRP attached, you may need to install a UHD driver. +Please refer to http://osmocom.org/projects/osmotrx/wiki/OsmoTRX#UHD for +details; the following is an example for the B200 family USRP devices: + +---- +apt-get install libuhd-dev uhd-host +/usr/lib/uhd/utils/uhd_images_downloader.py +---- + +[[jenkins_deps]] +==== Jenkins Build Dependencies + +Each of the jenkins builds requires individual dependencies. This is generally +the same as for building the software outside of osmo-gsm-tester and will not +be detailed here. For the Osmocom projects, refer to +http://osmocom.org/projects/cellular-infrastructure/wiki/Build_from_Source . Be +aware of specific requirements for BTS hardware: for example, the +osmo-bts-sysmo build needs the sysmoBTS SDK installed on the build slave, which +should match the installed sysmoBTS firmware. + + +[[configure_build_slave]] +=== Jenkins Build Slave + +==== Create 'jenkins' User on Main Unit + +On the main unit, create a jenkins user: + +---- +useradd -m jenkins +---- + +==== Allow SSH Access from Jenkins Master + +Create an SSH keypair to be used for login on the osmo-gsm-tester. This may be +entered on the jenkins web UI; alternatively, use the jenkins server's shell: + +Login on the main jenkins server shell and create an SSH keypair, for example: + +---- +# su jenkins +$ ssh-keygen +Generating public/private rsa key pair. +Enter file in which to save the key (/home/jenkins/.ssh/id_rsa): /usr/local/jenkins/keys/osmo-gsm-tester-rnd +Enter passphrase (empty for no passphrase): +Enter same passphrase again: +Your identification has been saved in /usr/local/jenkins/keys/osmo-gsm-tester-rnd +Your public key has been saved in /usr/local/jenkins/keys/osmo-gsm-tester-rnd.pub. +The key fingerprint is: +... +---- + +Copy the public key to the main unit, e.g. copy-paste: + +---- +cat /usr/local/jenkins/keys/osmo-gsm-tester-rnd.pub +# copy this public key +---- + +On the main unit: + +---- +mkdir ~jenkins/.ssh +cat > ~jenkins/.ssh/authorized_keys +# paste above public key and hit Ctrl-D +chown -R jenkins: ~jenkins/.ssh +---- + +Make sure that the user running the jenkins master accepts the main unit's host +identification. There must be an actual RSA host key available in the +known_hosts file for the jenkins master to be able to log in. Simply calling +ssh and accepting the host key as usual is not enough. Jenkins may continue to +say "Host key verification failed". + +To place an RSA host key in the jenkins' known_hosts file, you may do: + +On the Jenkins master: + +---- +main_unit_ip=10.9.8.7 +ssh-keyscan -H $main_unit_ip >> ~jenkins/.ssh/known_hosts +chown jenkins: ~jenkins/.ssh/known_hosts +---- + +Verify that the jenkins user on the Jenkins master has SSH access to the main +unit: + +---- +su jenkins +main_unit_ip=10.9.8.7 +ssh jenkins@$main_unit_ip +exit +---- + +[[install_add_build_slave]] +==== Add Build Slave + +In the jenkins web UI, add a new build slave for the osmo-gsm-tester: + +* 'Manage Jenkins' +** 'Manage Nodes' +*** 'New Node' +**** Enter a node name, e.g. "osmo-gsm-tester-1" + + (the "-1" is just some identification in case you'd like to add another + setup later). +**** 'Permanent Agent' + +Configure the node as: + +* '# of executors': 1 +* 'Remote root directory': "/home/jenkins" +* 'Labels': "osmo-gsm-tester" + + (This is a general label common to all osmo-gsm-tester build slaves you may set up in the future.) +* 'Usage': 'Only build jobs with label expressions matching this node' +* 'Launch method': 'Launch slave agents via SSH' +** 'Host': your main unit's IP address +** 'Credentials': choose 'Add' / 'Jenkins' +*** 'Domain': 'Global credentials (unrestricted)' +*** 'Kind': 'SSH Username with private key' +*** 'Scope': 'Global' +*** 'Username': "jenkins" + + (as created on the main unit above) +*** 'Private Key': 'From a file on Jenkins master' +**** 'File': "/usr/local/jenkins/keys/osmo-gsm-tester-rnd" +*** 'Passphrase': enter same passphrase as above +*** 'ID': "osmo-gsm-tester-1" +*** 'Name': "jenkins for SSH to osmo-gsm-tester-1" + +The build slave should be able to start now. + + +==== Add Build Jobs + +There are various jenkins-build-* scripts in osmo-gsm-tester/contrib/, which +can be called as jenkins build jobs to build and bundle binaries as artifacts, +to be run on the osmo-gsm-tester main unit and/or BTS hardware. + +Be aware of the dependencies, as hinted at in <>. + +While the various binaries could technically be built on the osmo-gsm-tester +main unit, it is recommended to use a separate build slave, to take load off +of the main unit. + +On your jenkins master, set up build jobs to call these scripts -- typically +one build job per script. Look in contrib/ and create one build job for each of +the BTS types you would like to test, as well as one for the 'build-osmo-nitb'. + +These are generic steps to configure a jenkins build +job for each of these build scripts, by example of the +jenkins-build-osmo-nitb.sh script; all that differs to the other scripts is the +"osmo-nitb" part: + +* 'Project name': "osmo-gsm-tester_build-osmo-nitb" + + (Replace 'osmo-nitb' according to which build script this is for) +* 'Discard old builds' + + Configure this to taste, for example: +** 'Max # of build to keep': "20" +* 'Restrict where this project can be run': Choose a build slave label that + matches the main unit's architecture and distribution, typically a Debian + system, e.g.: "linux_amd64_debian8" +* 'Source Code Management': +** 'Git' +*** 'Repository URL': "git://git.osmocom.org/osmo-gsm-tester" +*** 'Branch Specifier': "*/master" +*** 'Additional Behaviors' +**** 'Check out to a sub-directory': "osmo-gsm-tester" +* 'Build Triggers' + + The decision on when to build is complex. Here are some examples: +** Once per day: + + 'Build periodically': "H H * * *" +** For the Osmocom project, the purpose is to verify our software changes. + Hence we would like to test every time our code has changed: +*** We could add various git repositories to watch, and enable 'Poll SCM'. +*** On jenkins.osmocom.org, we have various jobs that build the master branches + of their respective git repositories when a new change was merged. Here, we + can thus trigger e.g. an osmo-nitb build for osmo-gsm-tester everytime the + master build has run: + + 'Build after other projects are built': "OpenBSC" +*** Note that most of the Osmocom projects also need to be re-tested when their + dependencies like libosmo* have changed. Triggering on all those changes + typically causes more jenkins runs than necessary: for example, it rebuilds + once per each dependency that has rebuilt due to one libosmocore change. + There is so far no trivial way known to avoid this. It is indeed safest to + rebuild more often. +* 'Build' +** 'Execute Shell' ++ +---- +#!/bin/sh +set -e -x +./osmo-gsm-tester/contrib/jenkins-build-osmo-nitb.sh +---- ++ +(Replace 'osmo-nitb' according to which build script this is for) + +* 'Post-build Actions' +** 'Archive the artifacts': "*.tgz, *.md5" + + (This step is important to be able to use the built binaries in the run job + below.) + + +TIP: When you've created one build job, it is convenient to create further +build jobs by copying the first and, e.g., simply replacing all "osmo-nitb" +with "osmo-bts-trx". + +==== Add Run Job + +This is the build job that actually runs the tests on the GSM hardware: + +* It sources the artifacts from the build jobs. +* It runs on the osmo-gsm-tester main unit's build slave. + +Here is the configuration for the run job: + +* 'Project name': "osmo-gsm-tester_run" +* 'Discard old builds' + + Configure this to taste, for example: +** 'Max # of build to keep': "20" +* 'Restrict where this project can be run': "osmo-gsm-tester" + + (to match the 'Label' configured in <>). +* 'Source Code Management': +** 'Git' +*** 'Repository URL': "git://git.osmocom.org/osmo-gsm-tester" +*** 'Branch Specifier': "*/master" +*** 'Additional Behaviors' +**** 'Check out to a sub-directory': "osmo-gsm-tester" +**** 'Clean before checkout' +* 'Build Triggers' + + The decision on when to build is complex. For this run job, it is suggested + to rebuild: +** after each of above build jobs that produced new artifacts: + + 'Build after other projects are built': "osmo-gsm-tester_build-osmo-nitb, + osmo-gsm-tester_build-osmo-bts-sysmo, osmo-gsm-tester_build-osmo-bts-trx" + + (Add each build job name you configured above) +** as well as once per day: + + 'Build periodically': "H H * * *" +** and, in addition, whenever the osmo-gsm-tester scripts have been modified: + + 'Poll SCM': "H/5 * * * *" + + (i.e. look every five minutes whether the upstream git has changed) +* 'Build' +** Copy artifacts from each build job you have set up: +*** 'Copy artifacts from another project' +**** 'Project name': "osmo-gsm-tester_build-osmo-nitb" +**** 'Which build': 'Latest successful build' +**** enable 'Stable build only' +**** 'Artifacts to copy': "*.tgz, *.md5" +*** Add a separate similar 'Copy artifacts...' section for each build job you + have set up. +** 'Execute Shell' ++ +---- +#!/bin/sh +set -e -x + +# debug: provoke a failure +#export OSMO_GSM_TESTER_OPTS="-s debug -t fail" + +PATH="$PWD/osmo-gsm-tester/src:$PATH" \ + ./osmo-gsm-tester/contrib/jenkins-run.sh +---- ++ +Details: + +*** The 'jenkins-run.sh' script assumes to find the 'osmo-gsm-tester.py' in the + '$PATH'. To use the most recent osmo-gsm-tester code here, we direct + '$PATH' to the actual workspace checkout. This could also run from a sytem + wide install, in which case you could omit the explicit PATH to + "$PWD/osmo-gsm-tester/src". +*** This assumes that there are configuration files for osmo-gsm-tester placed + on the system (see <>). +*** If you'd like to check the behavior of test failures, you can uncomment the + line below "# debug" to produce a build failure on every run. Note that + this test typically produces a quite empty run result, since it launches no + NITB nor BTS. +* 'Post-build Actions' +** 'Archive the artifacts' +*** 'Files to archive': "*-run.tgz" + + This stores the complete test report with config files, logs, stdout/stderr + output as well as pcaps in an artifact. This allows analysis of older + builds, instead of only the most recent build (which cleans up the jenkins + workspace every time). The 'trial-N-run.tgz' archive is produced by the + 'jenkins-run.sh' script, both for successful and failing runs. + + +=== Install osmo-gsm-tester on Main Unit + +This assumes you have already created the jenkins user (see <>). + +==== Allow Core Files + +In case a binary run for the test crashes, a core file of the crash should be +written. This requires a limit rule. Copy the following config file from the +osmo-gsm-tester source tree to the main unit: + +---- +cp install/osmo-gsm-tester-limits.conf /etc/security/limits.d/ +---- + +==== User Permissions + +On the main unit, create a group for all users that should be allowed to use +the osmo-gsm-tester, and add users (here 'jenkins') to this group. + +---- +groupadd osmo-gsm-tester +gpasswd -a jenkins osmo-gsm-tester +---- + +NOTE: you may also need to add users to the 'usrp' group, see +<>. + +A user added to a group needs to re-login for the group permissions to take +effect. + +This group needs the following permissions: + +===== Paths + +Assuming that you are using the example config, prepare a system wide state +location in '/var/tmp': + +---- +mkdir -p /var/tmp/osmo-gsm-tester/state +chown -R :osmo-gsm-tester /var/tmp/osmo-gsm-tester +chmod -R g+rwxs /var/tmp/osmo-gsm-tester +setfacl -d -m group:osmo-gsm-tester:rwx /var/tmp/osmo-gsm-tester/state +---- + +IMPORTANT: the state directory needs to be shared between all users potentially +running the osmo-gsm-tester to resolve resource allocations. Above 'setfacl' +command sets the access control to keep all created files group writable. + +With the jenkins build as described here, the trials will live in the build +slave's workspace. Other modes of operation (a daemon scheduling concurrent +runs, *TODO*) may use a system wide directory to manage trials to run: + +---- +mkdir -p /var/tmp/osmo-gsm-tester/trials +chown -R :osmo-gsm-tester /var/tmp/osmo-gsm-tester +chmod -R g+rwxs /var/tmp/osmo-gsm-tester +---- + +===== Allow DBus Access to ofono + +Put a DBus configuration file in place that allows the 'osmo-gsm-tester' group +to access the org.ofono DBus path: + +---- +cat > /etc/dbus-1/system.d/osmo-gsm-tester.conf < + + + + + + + + + +END +---- + +(No restart of dbus nor ofono necessary.) + +[[install_capture_packets]] +===== Capture Packets + +In order to allow collecting pcap traces of the network communication for later +reference, allow the osmo-gsm-tester group to capture packets using the 'tcpdump' +program: + +---- +chgrp osmo-gsm-tester /usr/sbin/tcpdump +chmod 750 /usr/sbin/tcpdump +setcap cap_net_raw,cap_net_admin=eip /usr/sbin/tcpdump +---- + +Put 'tcpdump' in the '$PATH' -- assuming that 'tcpdump' is available for root: + +---- +ln -s `which tcpdump` /usr/local/bin/tcpdump +---- + +TIP: Why a symlink in '/usr/local/bin'? On Debian, 'tcpdump' lives in +'/usr/sbin', which is not part of the '$PATH' for non-root users. To avoid +hardcoding non-portable paths in the osmo-gsm-tester source, 'tcpdump' must be +available in the '$PATH'. There are various trivial ways to modify '$PATH' for +login shells, but the jenkins build slave typically runs in a *non-login* +shell; modifying non-login shell enviroments is not trivially possible without +also interfering with files installed from debian packages. Probably the +easiest way to allow all users and all shells to find the 'tcpdump' binary is +to actually place a symbolic link in a directory that is already part of the +non-login shell's '$PATH'. Above example places such in '/usr/local/bin'. + +Verify that a non-login shell can find 'tcpdump': + +---- +su jenkins -c 'which tcpdump' +# should print: "/usr/local/bin/tcpdump" +---- + +WARNING: When logged in via SSH on your main unit, running 'tcpdump' to capture +packets may result in a feedback loop: SSH activity to send tcpdump's output to +your terminal is in turn is picked up in the tcpdump trace, and so forth. When +testing 'tcpdump' access, make sure to have proper filter expressions in place. + +TODO: allow skipping pcaps by configuration if access to tcpdump is not wanted + +[[user_config_uhd]] +==== UHD + +Grant permission to use the UHD driver to run USRP devices for osmo-bts-trx, by +adding the jenkins user to the 'usrp' group: + +---- +gpasswd -a jenkins usrp +---- + +==== Install Scripts + +IMPORTANT: When using the jenkins build slave as configured above, *there is no +need to install the osmo-gsm-tester sources on the main unit*. The jenkins job +will do so implicitly by checking out the latest osmo-gsm-tester sources in the +workspace for every run. If you're using only the jenkins build slave, you may +skip this section. + +If you prefer to use a fixed installation of the osmo-gsm-tester sources +instead of the jenkins workspace, you can: + +. From the run job configured above, remove the line that says ++ +---- +PATH="$PWD/osmo-gsm-tester/src:$PATH" \ +---- ++ +so that this uses a system wide installation instead. + +. Install the sources e.g. in '/usr/local/src' as indicated below. + +On the main unit, to install the latest in '/usr/local/src': + +---- +apt-get install git +mkdir -p /usr/local/src +cd /usr/local/src +git clone git://git.osmocom.org/osmo-gsm-tester +---- + +To allow all users to run 'osmo-gsm-tester.py', from login as well as non-login +shells, the easiest solution is to place a symlink in '/usr/local/bin': + +---- +ln -s /usr/local/src/osmo-gsm-tester/src/osmo-gsm-tester.py /usr/local/bin/ +---- + +(See also the tip in <> for a more detailed +explanation.) + +The example configuration provided in the source is suitable for running as-is, +*if* your hardware setup matches (you could technically use that directly by a +symlink e.g. from '/usr/local/etc/osmo-gsm-tester' to the 'example' dir). If in +doubt, rather copy the example, point 'paths.conf' at the 'suites' dir, and +adjust your own configuration as needed. For example: + +---- +cd /etc +cp -R /usr/local/src/osmo-gsm-tester/example osmo-gsm-tester +sed -i 's#\.\./suites#/usr/local/src/osmo-gsm-tester/suites#' osmo-gsm-tester/paths.conf +---- + +NOTE: The configuration will be looked up in various places, see +<>. + + +== Hardware Choice and Configuration + +=== SysmoBTS + +To use the SysmoBTS in the osmo-gsm-tester, the following systemd services must +be disabled: + +---- +systemctl mask osmo-nitb +systemctl mask sysmobts +systemctl mask sysmopcu +systemctl mask sysmobts-mgr +---- + +This stops the stock setup keeping the BTS in operation and hence allows the +osmo-gsm-tester to install and launch its own versions of the SysmoBTS +software. + +==== IP Address + +To ensure that the SysmoBTS is always reachable at a fixed known IP address, +configure the eth0 to use a static IP address: + +Adjust '/etc/network/interfaces' and replace the line + +---- +iface eth0 inet dhcp +---- + +with + +---- +iface eth0 inet static + address 10.42.42.114 + netmask 255.255.255.0 + gateway 10.42.42.1 +---- + +You may set the name server in '/etc/resolve.conf' (most likely to the IP of +the gateway), but this is not really needed by the osmo-gsm-tester. + +==== SSH Access + +Copy an SSH public key from the system/user that runs the osmo-gsm-tester, +presumably user 'jenkins' on the *main unit* (not from the jenkins master!), to +the 'authorized_keys' file of user 'root' on the SysmoBTS. + +If the 'jenkins' user on the *main unit* has no key pair yet, generate one +first, with an empty passphrase: + +---- +ssh jenkins@my_main_unit +ssh-keygen +---- + +Then copy the public key to the SysmoBTS: + +---- +ssh jenkins@my_main_unit +cat ~/.ssh/id_rsa.pub +# copy this public key +---- + +---- +sysmobts=root@10.42.42.114 +ssh $sysmobts +cat id_rsa.pub >> ~/.ssh/authorized_keys +# paste above public key and hit Ctrl-D +---- + +==== Allow Core Files + +In case a binary run for the test crashes, a core file of the crash should be +written. This requires a limit rule. Copy the following config file from the +osmo-gsm-tester source tree to the SysmoBTS: + +---- +sysmobts=root@10.42.42.114 +scp install/osmo-gsm-tester-limits.conf $sysmobts:/etc/security/limits.d/ +---- + + +[[hardware_modems]] +=== Modems + +TODO: describe modem choices and how to run ofono + +[[hardware_trx]] +=== osmo-bts-trx + +TODO: describe B200 family + diff --git a/doc/manuals/chapters/test_api.adoc b/doc/manuals/chapters/test_api.adoc index cabde4c..f541231 100644 --- a/doc/manuals/chapters/test_api.adoc +++ b/doc/manuals/chapters/test_api.adoc @@ -1,3 +1,4 @@ == Test API -*TODO* +*TODO* (in the meantime, look at src/osmo_gsm_tester/test.py, as well as +suite.py, which calls the test's setup() function to get an idea) diff --git a/doc/manuals/chapters/trial.adoc b/doc/manuals/chapters/trial.adoc index 16b3641..928ee28 100644 --- a/doc/manuals/chapters/trial.adoc +++ b/doc/manuals/chapters/trial.adoc @@ -3,7 +3,7 @@ A trial is a set of pre-built binaries to be tested. They are typically built by jenkins using the build scripts found in osmo-gsm-tester's source in the -'contrib/' dir. +'contrib/' dir, see <>. A trial comes in the form of a directory containing a number of '*.tgz' tar archives as well as a 'checksums.md5' file to verify the tar archives' @@ -14,8 +14,10 @@ create a sub directory named 'inst' and unpack the tar archives into it. For each test run on this trial, a new subdirectory in the trial dir is created, named in the form of 'run.'. A symbolic link 'last-run' -will point at the most recently created run dir. This run dir will accumulate -the rendered configuration files used for the trial run as well as a test log -(<- *TODO*) and stdout and stderr outputs of the binaries run for the trial. -(*TODO*->) When the test is complete, jenkins parsable XML reports for the test -run will be written to the 'run.' subdir. +will point at the most recently created run dir. This run dir will accumulate: + +* the rendered configuration files used to run the binaries +* stdout and stderr outputs of the binaries +* a test log +* *TODO*: jenkins parsable XML reports + diff --git a/doc/manuals/osmo-gsm-tester-manual.adoc b/doc/manuals/osmo-gsm-tester-manual.adoc index a3fb88c..b728384 100644 --- a/doc/manuals/osmo-gsm-tester-manual.adoc +++ b/doc/manuals/osmo-gsm-tester-manual.adoc @@ -9,6 +9,8 @@ incomplete, and details will still change and move around.* include::chapters/intro.adoc[] +include::chapters/install.adoc[] + include::chapters/config.adoc[] include::chapters/trial.adoc[] -- cgit v1.2.3 From 7b8dbd81f2bc716aa1335c4adacf1764834c3bce Mon Sep 17 00:00:00 2001 From: Neels Hofmeyr Date: Mon, 15 May 2017 15:28:34 +0200 Subject: OsmoGSMTester: say 'modems', not 'modem' (sounds like it supports only one) Change-Id: Ib59788a50754ea5290e665a9f9376d70e01c9be5 --- doc/manuals/chapters/install.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/install.adoc b/doc/manuals/chapters/install.adoc index 17905be..2a20ebd 100644 --- a/doc/manuals/chapters/install.adoc +++ b/doc/manuals/chapters/install.adoc @@ -27,7 +27,7 @@ pip3 install pydbus ---- IMPORTANT: ofono may need to be installed from source to contain the most -recent fixes needed to operate your modem. This depends on the modem hardware +recent fixes needed to operate your modems. This depends on the modem hardware used and the tests run. Please see <>. To run osmo-bts-trx with a USRP attached, you may need to install a UHD driver. -- cgit v1.2.3 From 5d0330fa456cbc2cbfc318b9886c04a8457b807b Mon Sep 17 00:00:00 2001 From: Neels Hofmeyr Date: Thu, 18 May 2017 18:38:50 +0200 Subject: apply rename of resource nitb_iface to ip_address See osmo-gsm-tester change-id I829903d7b2111ab5ee106bce52d6121204a5a401 Change-Id: Icbbb7d921e7340739883650f778d5a7341840875 --- doc/manuals/chapters/config.adoc | 4 ++-- doc/manuals/chapters/intro.adoc | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/config.adoc b/doc/manuals/chapters/config.adoc index f264284..7c06392 100644 --- a/doc/manuals/chapters/config.adoc +++ b/doc/manuals/chapters/config.adoc @@ -75,7 +75,7 @@ where each item has one or more settings -- for an example, see These kinds of resource are known: -'nitb_iface':: +'ip_address':: List of IP addresses to run osmo-nitb instances on. The main unit typically has a limited number of such IP addresses configured, which the connected BTS models can see on their network. @@ -138,7 +138,7 @@ These kinds of resource are known: currently always comp128v1) Side note: at first sight it might make sense to the reader to rather structure -e.g. the 'nitb_iface' or 'arfcn' configuration as + +e.g. the 'ip_address' or 'arfcn' configuration as + '"arfcn: GSM-1800: [512, 514, ...]"', + but the more verbose format is chosen to stay consistent with the general structure of resource configurations, which the resource allocation algorithm diff --git a/doc/manuals/chapters/intro.adoc b/doc/manuals/chapters/intro.adoc index 46c5ec6..8a09910 100644 --- a/doc/manuals/chapters/intro.adoc +++ b/doc/manuals/chapters/intro.adoc @@ -96,7 +96,7 @@ digraph G { subgraph cluster_suite { label = "Suite: sms"; - requires [label="Requirements (suite.conf):\nmodem: times: 2\nbts\nnitb_iface\narfcn"] + requires [label="Requirements (suite.conf):\nmodem: times: 2\nbts\nip_address\narfcn"] subgraph cluster_tests { label = "Test Scripts (py)"; mo_mt_sms @@ -202,7 +202,7 @@ A global configuration of hardware may look like below; for details, see <>. ---- -nitb_iface: +ip_address: - addr: 10.42.42.1 - addr: 10.42.42.2 - addr: 10.42.42.3 @@ -268,7 +268,7 @@ like this: ---- resources: - nitb_iface: + ip_address: - times: 1 bts: - times: 1 @@ -291,7 +291,7 @@ resources: - type: osmo-bts-sysmo ---- -Which 'nitb_iface' or 'modem' is used in particular doesn't really matter, so +Which 'ip_address' or 'modem' is used in particular doesn't really matter, so it can be left up to the osmo-gsm-tester to pick these automatically. Any number of such scenario configurations can be combined in the form -- cgit v1.2.3 From 05eb779ce914d6d79eb9a6a3f576b233ebfb8ac6 Mon Sep 17 00:00:00 2001 From: Neels Hofmeyr Date: Tue, 23 May 2017 17:07:12 +0200 Subject: OsmoGSMTester: add rtprio conf, tweak core dump conf Change-Id: I284c3bfb15e914f1f6ab00f15874fe5ea6190c5c --- doc/manuals/chapters/install.adoc | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/install.adoc b/doc/manuals/chapters/install.adoc index 2a20ebd..8ace16f 100644 --- a/doc/manuals/chapters/install.adoc +++ b/doc/manuals/chapters/install.adoc @@ -325,9 +325,24 @@ written. This requires a limit rule. Copy the following config file from the osmo-gsm-tester source tree to the main unit: ---- -cp install/osmo-gsm-tester-limits.conf /etc/security/limits.d/ +sudo -s +echo "@osmo-gsm-tester - core unlimited" > /etc/security/limits.d/osmo-gsm-tester_allow-core.conf ---- +Re-login the user to make these changes take effect. + +==== Allow Realtime Priority + +Certain binaries should be run with real-time priority, like 'osmo-bts-trx'. +Add this permission on the main unit: + +---- +sudo -s +echo "@osmo-gsm-tester - rtprio 99" > /etc/security/limits.d/osmo-gsm-tester_allow-rtprio.conf +---- + +Re-login the user to make these changes take effect. + ==== User Permissions On the main unit, create a group for all users that should be allowed to use -- cgit v1.2.3 From 9711069e532ee8057607ba65b4ebed49065005e3 Mon Sep 17 00:00:00 2001 From: Neels Hofmeyr Date: Sat, 3 Jun 2017 15:20:28 +0200 Subject: OsmoGSMTester: add sqlite3 as dependency Needed to setup the initial hlr db using the hlr.sql file from osmo-hlr since osmo-gsm-tester commit 798e592fd642a1dd86380c412a9501931b9048e1 "MSC+BSC: add test api to run OsmoMSC and OsmoBSC with AoIP" Change-Id: Ic19f93a69df4062364da8523b5d30a1611a0eb77 --- doc/manuals/chapters/install.adoc | 1 + 1 file changed, 1 insertion(+) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/install.adoc b/doc/manuals/chapters/install.adoc index 8ace16f..9900e6b 100644 --- a/doc/manuals/chapters/install.adoc +++ b/doc/manuals/chapters/install.adoc @@ -17,6 +17,7 @@ run the osmo-gsm-tester.py code, i.e. install these on your main unit: apt-get install \ dbus \ tcpdump \ + sqlite3 \ python3 \ python3-yaml \ python3-mako \ -- cgit v1.2.3 From ee57f0952a68cd3ffa1c7421d4a9fce8caec869f Mon Sep 17 00:00:00 2001 From: Neels Hofmeyr Date: Sat, 3 Jun 2017 15:20:50 +0200 Subject: OsmoGSMTester: tweak sysmobts: systemctl, ssh, limits, reboot Simpler systemctl rule to disable stock services. Fix the limits config, which was not the right way for sysmoBTS. SSH access: apparently no need to create an ssh key at all, login is permitted right away. Add hint to reboot at the right time. Change-Id: I8e686383318ee2eece908a4e690e5061ade0cd02 --- doc/manuals/chapters/install.adoc | 49 ++++++++++++++++----------------------- 1 file changed, 20 insertions(+), 29 deletions(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/install.adoc b/doc/manuals/chapters/install.adoc index 9900e6b..41c85e4 100644 --- a/doc/manuals/chapters/install.adoc +++ b/doc/manuals/chapters/install.adoc @@ -530,10 +530,7 @@ To use the SysmoBTS in the osmo-gsm-tester, the following systemd services must be disabled: ---- -systemctl mask osmo-nitb -systemctl mask sysmobts -systemctl mask sysmopcu -systemctl mask sysmobts-mgr +systemctl mask osmo-nitb sysmobts sysmopcu sysmobts-mgr ---- This stops the stock setup keeping the BTS in operation and hence allows the @@ -563,46 +560,40 @@ iface eth0 inet static You may set the name server in '/etc/resolve.conf' (most likely to the IP of the gateway), but this is not really needed by the osmo-gsm-tester. -==== SSH Access - -Copy an SSH public key from the system/user that runs the osmo-gsm-tester, -presumably user 'jenkins' on the *main unit* (not from the jenkins master!), to -the 'authorized_keys' file of user 'root' on the SysmoBTS. +==== Allow Core Files -If the 'jenkins' user on the *main unit* has no key pair yet, generate one -first, with an empty passphrase: +In case a binary run for the test crashes, a core file of the crash should be +written. This requires a limits rule. Append a line to /etc/limits like: ---- -ssh jenkins@my_main_unit -ssh-keygen +ssh root@10.42.42.114 +echo "* C16384" >> /etc/limits ---- -Then copy the public key to the SysmoBTS: +==== Reboot ----- -ssh jenkins@my_main_unit -cat ~/.ssh/id_rsa.pub -# copy this public key ----- +Reboot the BTS and make sure that the IP address for eth0 is now indeed +10.42.42.114, and that no osmo* programs are running. ---- -sysmobts=root@10.42.42.114 -ssh $sysmobts -cat id_rsa.pub >> ~/.ssh/authorized_keys -# paste above public key and hit Ctrl-D +ip a +ps w | grep osmo ---- -==== Allow Core Files +==== SSH Access -In case a binary run for the test crashes, a core file of the crash should be -written. This requires a limit rule. Copy the following config file from the -osmo-gsm-tester source tree to the SysmoBTS: +Make sure that the jenkins user on the main unit is able to login on the +sysmoBTS, possibly erasing outdated host keys after a new rootfs was loaded: + +On the main unit, for example do: ---- -sysmobts=root@10.42.42.114 -scp install/osmo-gsm-tester-limits.conf $sysmobts:/etc/security/limits.d/ +su - jenkins +ssh root@10.42.42.114 ---- +Fix any problems until you get a login on the sysmoBTS. + [[hardware_modems]] === Modems -- cgit v1.2.3 From 422f8bae65964d577b84d7f75dc512570492116b Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Wed, 14 Jun 2017 15:57:12 +0200 Subject: OsmoGsmTester: Update sample test script Copied from newest mo_mt_sms.py test. Change-Id: I49644f6f8223d45bccbcbb3aa8325c20c06dcdbe --- doc/manuals/chapters/intro.adoc | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/intro.adoc b/doc/manuals/chapters/intro.adoc index 8a09910..50b6dff 100644 --- a/doc/manuals/chapters/intro.adoc +++ b/doc/manuals/chapters/intro.adoc @@ -161,7 +161,6 @@ A typical single test script (part of a suite) may look like this: #!/usr/bin/env python3 from osmo_gsm_tester.test import * -print('use resources...') nitb = suite.nitb() bts = suite.bts() ms_mo = suite.modem() @@ -170,19 +169,21 @@ ms_mt = suite.modem() print('start nitb and bts...') nitb.bts_add(bts) nitb.start() -sleep(1) -assert nitb.running() bts.start() nitb.subscriber_add(ms_mo) nitb.subscriber_add(ms_mt) -ms_mo.connect(nitb) -ms_mt.connect(nitb) +ms_mo.connect(nitb.mcc_mnc()) +ms_mt.connect(nitb.mcc_mnc()) + +print('waiting for modems to attach...') +wait(ms_mo.is_connected, nitb.mcc_mnc()) +wait(ms_mt.is_connected, nitb.mcc_mnc()) wait(nitb.subscriber_attached, ms_mo, ms_mt) -sms = ms_mo.sms_send(ms_mt.msisdn) -wait(ms_mt.sms_received, sms) +sms = ms_mo.sms_send(ms_mt) +wait(ms_mt.sms_was_received, sms) ---- === Resource Resolution -- cgit v1.2.3 From 8d72cd68c18ab4b31f028bc21bf14edc1262838b Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Wed, 14 Jun 2017 16:02:34 +0200 Subject: OsmoGsmTester: Add missing dependency python-smpplib Change-Id: I9a6ad33d41c8a90317d079ff0d1f9640c48a2353 --- doc/manuals/chapters/install.adoc | 1 + 1 file changed, 1 insertion(+) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/install.adoc b/doc/manuals/chapters/install.adoc index 41c85e4..ae8412a 100644 --- a/doc/manuals/chapters/install.adoc +++ b/doc/manuals/chapters/install.adoc @@ -25,6 +25,7 @@ apt-get install \ ofono \ python3-pip pip3 install pydbus +pip3 install git+git://github.com/podshumok/python-smpplib.git ---- IMPORTANT: ofono may need to be installed from source to contain the most -- cgit v1.2.3 From b825f790d7c3c3a685669f7e4b7a5ebf09d74eda Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Wed, 14 Jun 2017 16:03:05 +0200 Subject: OsmoGsmTester: install.adoc: Remove trailing whitespace My editor is removing it automatically. Change-Id: I25c8d179a21c66ab3424204e12215f8e1ddd8e54 --- doc/manuals/chapters/install.adoc | 1 - 1 file changed, 1 deletion(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/install.adoc b/doc/manuals/chapters/install.adoc index ae8412a..b2f0082 100644 --- a/doc/manuals/chapters/install.adoc +++ b/doc/manuals/chapters/install.adoc @@ -605,4 +605,3 @@ TODO: describe modem choices and how to run ofono === osmo-bts-trx TODO: describe B200 family - -- cgit v1.2.3 From 8d8a136aec6970423ed2982052be935022545b51 Mon Sep 17 00:00:00 2001 From: Neels Hofmeyr Date: Sun, 18 Jun 2017 02:31:38 +0200 Subject: OsmoGSMTester: update run-job post-build artifact archiving rule Change-Id: I73c1a6793369604cbe494c83b595a4130a44adc9 --- doc/manuals/chapters/install.adoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/install.adoc b/doc/manuals/chapters/install.adoc index b2f0082..b703498 100644 --- a/doc/manuals/chapters/install.adoc +++ b/doc/manuals/chapters/install.adoc @@ -308,13 +308,13 @@ Details: NITB nor BTS. * 'Post-build Actions' ** 'Archive the artifacts' -*** 'Files to archive': "*-run.tgz" + +*** 'Files to archive': "*-run.tgz, *-bin.tgz" + This stores the complete test report with config files, logs, stdout/stderr - output as well as pcaps in an artifact. This allows analysis of older - builds, instead of only the most recent build (which cleans up the jenkins - workspace every time). The 'trial-N-run.tgz' archive is produced by the - 'jenkins-run.sh' script, both for successful and failing runs. - + output, pcaps as well as the binaries used for the test run in artifacts. + This allows analysis of older builds, instead of only the most recent build + (which cleans up the jenkins workspace every time). The 'trial-N-run.tgz' + and 'trial-N-bin.tgz' archives are produced by the 'jenkins-run.sh' script, + both for successful and failing runs. === Install osmo-gsm-tester on Main Unit -- cgit v1.2.3 From 3f596ed018020602a5facc2e49f8082540f3a30d Mon Sep 17 00:00:00 2001 From: Neels Hofmeyr Date: Fri, 14 Jul 2017 00:04:40 +0200 Subject: osmo-gsm-tester: jenkins fixes: install JDK, SSH instructions Add instructions to install Java JDK for jenkins build slave. Minor fixes to SSH key instructions. Change-Id: Ib2c1adc2ddee3be016e4d253451593b19dbe133a --- doc/manuals/chapters/install.adoc | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/install.adoc b/doc/manuals/chapters/install.adoc index b703498..0c69dcd 100644 --- a/doc/manuals/chapters/install.adoc +++ b/doc/manuals/chapters/install.adoc @@ -64,6 +64,15 @@ On the main unit, create a jenkins user: useradd -m jenkins ---- +==== Install Java on Main Unit + +To be able to launch the Jenkins build slave, a Java RE must be available on +the main unit. For example: + +---- +apt-get install default-jdk +---- + ==== Allow SSH Access from Jenkins Master Create an SSH keypair to be used for login on the osmo-gsm-tester. This may be @@ -73,6 +82,7 @@ Login on the main jenkins server shell and create an SSH keypair, for example: ---- # su jenkins +$ mkdir -p /usr/local/jenkins/keys $ ssh-keygen Generating public/private rsa key pair. Enter file in which to save the key (/home/jenkins/.ssh/id_rsa): /usr/local/jenkins/keys/osmo-gsm-tester-rnd @@ -122,7 +132,7 @@ unit: ---- su jenkins main_unit_ip=10.9.8.7 -ssh jenkins@$main_unit_ip +ssh -i /usr/local/jenkins/keys/osmo-gsm-tester-rnd jenkins@$main_unit_ip exit ---- -- cgit v1.2.3 From be69b6b183e601c10205b454ec5a2840a8c10e16 Mon Sep 17 00:00:00 2001 From: Max Date: Mon, 3 Jul 2017 19:03:25 +0200 Subject: OsmoGSMTester: use proper systemd service names * use osmo-bts-sysmo for sysmoBTS systemd service name which is available since 114293a414bd5b7c86622ec8c293c4034c80d243 * use osmo-pcu for OsmoPCU systemd service name which is available since 241f5bcb00f9c6fee4200a3aea9aa497bf0d3eee Change-Id: Ie017946b9099460ac6758ff84ec7a10df13390a1 --- doc/manuals/chapters/install.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/install.adoc b/doc/manuals/chapters/install.adoc index 0c69dcd..f58c611 100644 --- a/doc/manuals/chapters/install.adoc +++ b/doc/manuals/chapters/install.adoc @@ -541,7 +541,7 @@ To use the SysmoBTS in the osmo-gsm-tester, the following systemd services must be disabled: ---- -systemctl mask osmo-nitb sysmobts sysmopcu sysmobts-mgr +systemctl mask osmo-nitb osmo-bts-sysmo osmo-pcu sysmobts-mgr ---- This stops the stock setup keeping the BTS in operation and hence allows the -- cgit v1.2.3 From 018e1048b46434e8a87cd654da970b27ae3d22db Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Mon, 28 Aug 2017 11:58:25 +0200 Subject: OsmoGsmTester: Move coredump section and add reference to kernel.core_pattern sysctl This section is moved further below in order to have it after section which explains how to create user jenkins and osmo-gsm-tester group, as we need this group already created anyway for the config to work correctly. Change-Id: I5bdde0a9960f9806f081e9a876b8b66db9e7f37c --- doc/manuals/chapters/install.adoc | 57 ++++++++++++++++++++++----------------- 1 file changed, 32 insertions(+), 25 deletions(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/install.adoc b/doc/manuals/chapters/install.adoc index f58c611..4d2b677 100644 --- a/doc/manuals/chapters/install.adoc +++ b/doc/manuals/chapters/install.adoc @@ -330,31 +330,6 @@ Details: This assumes you have already created the jenkins user (see <>). -==== Allow Core Files - -In case a binary run for the test crashes, a core file of the crash should be -written. This requires a limit rule. Copy the following config file from the -osmo-gsm-tester source tree to the main unit: - ----- -sudo -s -echo "@osmo-gsm-tester - core unlimited" > /etc/security/limits.d/osmo-gsm-tester_allow-core.conf ----- - -Re-login the user to make these changes take effect. - -==== Allow Realtime Priority - -Certain binaries should be run with real-time priority, like 'osmo-bts-trx'. -Add this permission on the main unit: - ----- -sudo -s -echo "@osmo-gsm-tester - rtprio 99" > /etc/security/limits.d/osmo-gsm-tester_allow-rtprio.conf ----- - -Re-login the user to make these changes take effect. - ==== User Permissions On the main unit, create a group for all users that should be allowed to use @@ -467,6 +442,38 @@ testing 'tcpdump' access, make sure to have proper filter expressions in place. TODO: allow skipping pcaps by configuration if access to tcpdump is not wanted +==== Allow Core Files + +In case a binary run for the test crashes, a core file of the crash should be +written. This requires a limit rule. Create a file with the required rule: + +---- +sudo -s +echo "@osmo-gsm-tester - core unlimited" > /etc/security/limits.d/osmo-gsm-tester_allow-core.conf +---- + +Re-login the user to make these changes take effect. + +Set the *kernel.core_pattern* sysctl to *core* (usually the default). For each +binary run by osmo-gsm-tester, a core file will then appear in the same dir that +contains stdout and stderr for that process (because this dir is set as CWD). + +---- +sysctl -w kernel.core_pattern=core +---- + +==== Allow Realtime Priority + +Certain binaries should be run with real-time priority, like 'osmo-bts-trx'. +Add this permission on the main unit: + +---- +sudo -s +echo "@osmo-gsm-tester - rtprio 99" > /etc/security/limits.d/osmo-gsm-tester_allow-rtprio.conf +---- + +Re-login the user to make these changes take effect. + [[user_config_uhd]] ==== UHD -- cgit v1.2.3 From 74689530457a1e32e5ad05e35d8a4a5c423fa002 Mon Sep 17 00:00:00 2001 From: Neels Hofmeyr Date: Tue, 5 Sep 2017 19:43:02 +0200 Subject: OsmoGSMTester: document logrotate maxsize Change-Id: Ib3e7143eb5d90eea4860a0a334da25efe926a231 --- doc/manuals/chapters/install.adoc | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/install.adoc b/doc/manuals/chapters/install.adoc index 4d2b677..6eef2fa 100644 --- a/doc/manuals/chapters/install.adoc +++ b/doc/manuals/chapters/install.adoc @@ -484,6 +484,14 @@ adding the jenkins user to the 'usrp' group: gpasswd -a jenkins usrp ---- +==== Log Rotation + +To avoid clogging up /var/log, it makes sense to choose a sane maximum log size: + +---- +echo maxsize 10M > /etc/logrotate.d/maxsize +---- + ==== Install Scripts IMPORTANT: When using the jenkins build slave as configured above, *there is no -- cgit v1.2.3 From 607229a77573cb197b728a17c15426c229f2b672 Mon Sep 17 00:00:00 2001 From: Neels Hofmeyr Date: Thu, 19 Oct 2017 05:11:57 +0200 Subject: refactor Makefile build rules, don't use the FORCE The initial goal was to make sure we don't have overall FORCE rules causing unnecessary rebuilds -- annoying while writing documentation. As I looked through possible dependencies, I finally understood what's going on here. Remove code dup and nicely sort which belongs where in build/Makefile.*.inc. In each, describe in a top comment how to use it, and also unify how they are used: - Rename Makefile.inc to Makefile.docbook.inc and refactor - Add Makefile.vty-reference.inc - Add Makefile.common.inc Make sure that we accurately pick up all dependencies. Drop use of the macro called 'command', that silenced the actual command lines invoked and replaced them with short strings: it obscures what is actually going on and makes the Makefiles hard to read and understand. Each manual's makefile is greatly reduced to few definitions and a Makefile include, e.g. one for asciidoc, one for VTY reference. Move common/bsc_vty_additions.xml to OsmoBSC/vty/libbsc_vty_additions.xml, link from OsmoNITB. It applies only to OsmoBSC and OsmoNITB. Add a script that combines a VTY reference file with *all* additions files found in a manual's vty/ dir. Call this from Makefile.vty-reference.inc. Change-Id: I9758e04162a480e28c7dc83475b514cf7fd25ec0 --- doc/manuals/Makefile | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) (limited to 'doc/manuals') diff --git a/doc/manuals/Makefile b/doc/manuals/Makefile index 79d414f..43c5a37 100644 --- a/doc/manuals/Makefile +++ b/doc/manuals/Makefile @@ -1,12 +1,7 @@ -TOPDIR := .. -ASCIIDOCS := osmo-gsm-tester-manual +TOPDIR = .. +ASCIIDOC = osmo-gsm-tester-manual.adoc +ASCIIDOC_DEPS = chapters/*.adoc include $(TOPDIR)/build/Makefile.asciidoc.inc -include $(TOPDIR)/build/Makefile.inc -osmo-gsm-tester-manual.pdf: chapters/*.adoc - -clean: - -rm -rf $(cleanfiles) - -rm osmo-gsm-tester-manual__*.svg - -rm osmo-gsm-tester-manual__*.png +include $(TOPDIR)/build/Makefile.common.inc -- cgit v1.2.3 From 48d2564f2c0aaf24232f10580e6c4765c1e7f6d4 Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Thu, 2 Nov 2017 14:03:58 +0100 Subject: OsmoGSMTester: Improve setup graph * Add sysmocell5000 * Remove 1 modem, showing 2 of them is enough * Split osmo-bts-trx from osmo-trx node as sysmocell500 doesn't use the later. * Update OsmoNITB node to show we also support split openbsc.git components. Change-Id: I893beb114d47edd3f67183dd9ea5acc19462496c --- doc/manuals/chapters/intro.adoc | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/intro.adoc b/doc/manuals/chapters/intro.adoc index 50b6dff..557c2f3 100644 --- a/doc/manuals/chapters/intro.adoc +++ b/doc/manuals/chapters/intro.adoc @@ -37,14 +37,14 @@ digraph G { modem0 [shape=box label="Modems..."] modem1 [shape=box label="Modems..."] - modem2 [shape=box label="Modems..."] osmo_bts_sysmo [label="sysmocom sysmoBTS\nrunning osmo-bts-sysmo" shape=box] B200 [label="Ettus B200" shape=box] + sysmoCell5K [label="sysmocom sysmoCell5000" shape=box] octphy [label="Octasic octphy BTS" shape=box] nanoBTS [label="ip.access nanoBTS" shape=box] rf_distribution [label="RF distribution"] - {modem0 modem1 modem2 osmo_bts_sysmo B200 octphy nanoBTS}->rf_distribution [dir=both arrowhead="curve" arrowtail="curve"] + {modem0 modem1 osmo_bts_sysmo B200 octphy nanoBTS sysmoCell5K}->rf_distribution [dir=both arrowhead="curve" arrowtail="curve"] } subgraph cluster_main_unit { label = "Main Unit" @@ -52,22 +52,24 @@ digraph G { subgraph { rank=same ofono [label="ofono daemon"] - OsmoNITB - osmo_bts_trx [label="osmo-bts-trx\n+ osmo-trx"] + osmo_trx [label="osmo-trx"] + osmo_bts_trx [label="osmo-bts-trx"] osmo_bts_octphy [label="osmo-bts-octphy"] + OsmoNITB [label="BSC + Core Network\n(Osmo{NITB,MSC,BSC,HLR,...})"] } } jenkins->osmo_gsm_tester [label="trial\n(binaries)"] osmo_gsm_tester->jenkins [label="results"] - ofono->{modem0 modem1 modem2} [label="USB"] - osmo_gsm_tester-> {OsmoNITB osmo_bts_trx osmo_bts_octphy} - osmo_gsm_tester-> osmo_bts_sysmo [taillabel="SSH"] - osmo_gsm_tester-> ofono [taillabel="DBus"] - osmo_bts_trx->B200 [label="USB"] + ofono->{modem0 modem1} [label="USB"] + osmo_gsm_tester->{OsmoNITB osmo_bts_trx osmo_bts_octphy} + osmo_gsm_tester->osmo_bts_sysmo [taillabel="SSH"] + osmo_gsm_tester->ofono [taillabel="DBus"] + osmo_trx->B200 [label="USB"] + osmo_bts_trx->{osmo_trx sysmoCell5K} [dir=both label="UDP"] osmo_bts_octphy->octphy [label="raw eth"] - {osmo_bts_sysmo nanoBTS}->OsmoNITB [label="eth"] + {osmo_bts_sysmo nanoBTS}->OsmoNITB [label="IP"] {B200 octphy}->OsmoNITB [label="eth" style=invis] {osmo_bts_trx osmo_bts_octphy}->OsmoNITB } -- cgit v1.2.3 From cb474072ca807becb5eae5caee66e4e45fbf3c24 Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Thu, 2 Nov 2017 14:13:54 +0100 Subject: OsmoGSMTester: Update trial graph with current data The osmo-bts-trx tgz doesn't exist anymore and it does not contain osmo-trx, which comes in its own tgz. Change-Id: Id803eca3791137b04bc24d195119d5c511fcfc49 --- doc/manuals/chapters/intro.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/intro.adoc b/doc/manuals/chapters/intro.adoc index 557c2f3..cc37e88 100644 --- a/doc/manuals/chapters/intro.adoc +++ b/doc/manuals/chapters/intro.adoc @@ -146,7 +146,7 @@ digraph G { subgraph cluster_trial { label = "Trial (binaries)" sysmo [label="osmo-bts-sysmo.build-23.tgz\n(osmo-bts-sysmo\n+ deps\ncompiled for sysmoBTS)"] - trx [label="osmo-bts-trx.build-5.tgz\n(osmo-trx + osmo-bts-trx\n+ deps\ncompiled for main unit)"] + trx [label="osmo-bts.build-5.tgz\n(osmo-bts-octphy + osmo-bts-trx\n+ deps\ncompiled for main unit)"] nitb [label="osmo-nitb.build-42.tgz\n(osmo-nitb\n+ deps\ncompiled for main unit)"] checksums [label="checksums.md5"] -- cgit v1.2.3 From c8cd1fa7c59ab0ea4f5f699206937374dd4201c2 Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Thu, 2 Nov 2017 14:15:46 +0100 Subject: OsmoGSMTester: Update sample test script with an AoIP example Change-Id: I7978c7e96c8f1d43837271c94dd64893649974e0 --- doc/manuals/chapters/intro.adoc | 34 +++++++++++++++++++++++----------- 1 file changed, 23 insertions(+), 11 deletions(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/intro.adoc b/doc/manuals/chapters/intro.adoc index cc37e88..b405e1f 100644 --- a/doc/manuals/chapters/intro.adoc +++ b/doc/manuals/chapters/intro.adoc @@ -163,26 +163,38 @@ A typical single test script (part of a suite) may look like this: #!/usr/bin/env python3 from osmo_gsm_tester.test import * -nitb = suite.nitb() +hlr = suite.hlr() bts = suite.bts() +mgcpgw = suite.mgcpgw(bts_ip=bts.remote_addr()) +msc = suite.msc(hlr, mgcpgw) +bsc = suite.bsc(msc) +stp = suite.stp() ms_mo = suite.modem() ms_mt = suite.modem() -print('start nitb and bts...') -nitb.bts_add(bts) -nitb.start() +hlr.start() +stp.start() +msc.start() +mgcpgw.start() + +bsc.bts_add(bts) +bsc.start() + bts.start() -nitb.subscriber_add(ms_mo) -nitb.subscriber_add(ms_mt) +hlr.subscriber_add(ms_mo) +hlr.subscriber_add(ms_mt) + +ms_mo.connect(msc.mcc_mnc()) +ms_mt.connect(msc.mcc_mnc()) -ms_mo.connect(nitb.mcc_mnc()) -ms_mt.connect(nitb.mcc_mnc()) +ms_mo.log_info() +ms_mt.log_info() print('waiting for modems to attach...') -wait(ms_mo.is_connected, nitb.mcc_mnc()) -wait(ms_mt.is_connected, nitb.mcc_mnc()) -wait(nitb.subscriber_attached, ms_mo, ms_mt) +wait(ms_mo.is_connected, msc.mcc_mnc()) +wait(ms_mt.is_connected, msc.mcc_mnc()) +wait(msc.subscriber_attached, ms_mo, ms_mt) sms = ms_mo.sms_send(ms_mt) wait(ms_mt.sms_was_received, sms) -- cgit v1.2.3 From dc53c9c4665cd91975fcc8871f1c09f7c07fb2b1 Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Thu, 2 Nov 2017 14:19:32 +0100 Subject: OsmoGSMTester: Improve Resource Resolution section content Change-Id: Ice37093dc9f8e03a2a9f5e3f7df79d1b589b6991 --- doc/manuals/chapters/intro.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/intro.adoc b/doc/manuals/chapters/intro.adoc index b405e1f..e2156df 100644 --- a/doc/manuals/chapters/intro.adoc +++ b/doc/manuals/chapters/intro.adoc @@ -202,12 +202,12 @@ wait(ms_mt.sms_was_received, sms) === Resource Resolution -- A global configuration defines which hardware is connected to the +- A global configuration 'resources.conf' defines which hardware is connected to the osmo-gsm-tester main unit. - Each suite contains a number of test scripts. The amount of resources a test may use is defined by the test suite's 'suite.conf'. - Which specific modems, BTS models, NITB IP addresses etc. are made available - to a test run is typically determined by a combination of scenario + to a test run is typically determined by 'suite.conf' and a combination of scenario configurations -- or picked automatically if not. [[resources_conf_example]] -- cgit v1.2.3 From c9cbbc6f383c06ab901485999a177e669708a3b9 Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Thu, 2 Nov 2017 14:23:35 +0100 Subject: OsmoGSMTester: Use a more up-to-date resources.conf example It showcases new features such as osmo-trx support, cipher support, modem features support, etc. Change-Id: I66bbcd028f03290797c2c467271d0f0982698b47 --- doc/manuals/chapters/intro.adoc | 89 +++++++++++++++++++++++++++-------------- 1 file changed, 58 insertions(+), 31 deletions(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/intro.adoc b/doc/manuals/chapters/intro.adoc index e2156df..8c106b7 100644 --- a/doc/manuals/chapters/intro.adoc +++ b/doc/manuals/chapters/intro.adoc @@ -218,62 +218,89 @@ A global configuration of hardware may look like below; for details, see ---- ip_address: -- addr: 10.42.42.1 - addr: 10.42.42.2 - addr: 10.42.42.3 +- addr: 10.42.42.4 +- addr: 10.42.42.5 +- addr: 10.42.42.6 bts: - label: sysmoBTS 1002 type: osmo-bts-sysmo + ipa_unit_id: 1 addr: 10.42.42.114 band: GSM-1800 + ciphers: + - a5_0 + - a5_1 + - a5_3 -- label: octBTS 3000 - type: osmo-bts-octphy - addr: 10.42.42.115 +- label: Ettus B200 + type: osmo-bts-trx + ipa_unit_id: 6 + addr: 10.42.42.50 band: GSM-1800 - trx_list: - - hw_addr: 00:0c:90:32:b5:8a - net_device: eth0.2342 + launch_trx: true + ciphers: + - a5_0 + - a5_1 -- label: Ettus B210 +- label: sysmoCell 5000 type: osmo-bts-trx - addr: 10.42.42.116 + ipa_unit_id: 7 + addr: 10.42.42.51 band: GSM-1800 + trx_remote_ip: 10.42.42.112 + ciphers: + - a5_0 + - a5_1 -- label: nanoBTS 1900 - type: nanobts - addr: 10.42.42.190 - band: GSM-1900 +- label: OCTBTS 3500 + type: osmo-bts-octphy + ipa_unit_id: 8 + addr: 10.42.42.52 + band: GSM-1800 trx_list: - - hw_addr: 00:02:95:00:41:b3 + - hw_addr: 00:0c:90:2e:80:1e + net_device: eth1 + - hw_addr: 00:0c:90:2e:87:52 + net_device: eth1 arfcn: - arfcn: 512 band: GSM-1800 - arfcn: 514 band: GSM-1800 - - - arfcn: 540 + - arfcn: 516 + band: GSM-1800 + - arfcn: 546 band: GSM-1900 - - arfcn: 542 + - arfcn: 548 band: GSM-1900 modem: -- label: m7801 - path: '/wavecom_0' - imsi: 901700000007801 - ki: D620F48487B1B782DA55DF6717F08FF9 - -- label: m7802 - path: '/wavecom_1' - imsi: 901700000007802 - ki: 47FDB2D55CE6A10A85ABDAD034A5B7B3 - -- label: m7803 - path: '/wavecom_2' - imsi: 901700000007803 - ki: ABBED4C91417DF710F60675B6EE2C8D2 +- label: sierra_1 + path: '/sierra_1' + imsi: '901700000009031' + ki: '80A37E6FDEA931EAC92FFA5F671EFEAD' + auth_algo: 'xor' + ciphers: + - a5_0 + - a5_1 + features: + - 'sms' + - 'voice' + +- label: gobi_0 + path: '/gobi_0' + imsi: '901700000009030' + ki: 'BB70807226393CDBAC8DD3439FF54252' + auth_algo: 'xor' + ciphers: + - a5_0 + - a5_1 + features: + - 'sms' ---- === Typical 'suites/*/suite.conf' -- cgit v1.2.3 From 3ed0391ab30178f0c8e518935b4e8d3268f6e94d Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Thu, 2 Nov 2017 14:25:39 +0100 Subject: OsmoGSMTester: Update suite.conf example This is the one we are usig nowadays in suite.conf, which explicitly asks to be run with modems supporting sms features. Change-Id: If5dbc3b4689b282db6fae4668e2838be59e88da8 --- doc/manuals/chapters/intro.adoc | 2 ++ 1 file changed, 2 insertions(+) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/intro.adoc b/doc/manuals/chapters/intro.adoc index 8c106b7..6e377da 100644 --- a/doc/manuals/chapters/intro.adoc +++ b/doc/manuals/chapters/intro.adoc @@ -316,6 +316,8 @@ resources: - times: 1 modem: - times: 2 + features: + - sms ---- It may also request e.g. specific BTS models, but this is typically left to -- cgit v1.2.3 From 627aea5142d0f3826fcd7c807f5799bec98f9a09 Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Thu, 2 Nov 2017 15:03:58 +0100 Subject: OsmoGSMTester: Explain patchelf is used sometimes to modify RPATH Change-Id: I7bb811bc984c8d576984b038b391cf8130cc465e --- doc/manuals/chapters/intro.adoc | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/intro.adoc b/doc/manuals/chapters/intro.adoc index 6e377da..55f1a5e 100644 --- a/doc/manuals/chapters/intro.adoc +++ b/doc/manuals/chapters/intro.adoc @@ -385,7 +385,11 @@ separate processes. Also, the binaries from a trial are never installed system-wide, but are run with a specific 'LD_LIBRARY_PATH' pointing at the trial's 'inst', so that -several trials can run consecutively without conflicting binary versions. +several trials can run consecutively without conflicting binary versions. For +some specific binaries which require extra permissions (such as osmo-bts-octphy +requiring 'CAP_NET_RAW'), 'patchelf' program is used to modify the binary +'RPATH' field instead because the OS dynamic linker skips 'LD_LIBRARY_PATH' for +binaries with special permissions. Once a test suite run is complete, all its reserved resources are torn down (if the test scripts have not done so already), and the reservations are released -- cgit v1.2.3 From accd74fb0adf767a5559867dea27cd310c9b8d96 Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Thu, 2 Nov 2017 15:09:39 +0100 Subject: OSmoGsmTester: Specify group in Main unit intro Change-Id: I132bf7681a1a435c161c4048e41c28dc75c1fa28 --- doc/manuals/chapters/install.adoc | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/install.adoc b/doc/manuals/chapters/install.adoc index 6eef2fa..8397459 100644 --- a/doc/manuals/chapters/install.adoc +++ b/doc/manuals/chapters/install.adoc @@ -4,9 +4,10 @@ The main unit is a general purpose computer that orchestrates the tests. It runs the core network components, controls the modems and so on. This can be anything from a dedicated production rack unit to your laptop at home. -This manual will assume that tests are run from a jenkins build slave, by a -user named 'jenkins'. The user configuration for manual test runs and/or a -different user name is identical, simply replace the user name. +This manual will assume that tests are run from a jenkins build slave, by a user +named 'jenkins' that belong to group 'osmo-gsm-tester'. The user configuration +for manual test runs and/or a different user name is identical, simply replace +the user name or group. === Dependencies -- cgit v1.2.3 From 1ba1f5aa7b6076d5d8035ad3649272726228a898 Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Thu, 2 Nov 2017 15:11:30 +0100 Subject: OsmoGSMTester: Add deps required for osmo-bts-octphy support Change-Id: I384ec8cd55cfaa68ee1f461de99ceac78c5d8414 --- doc/manuals/chapters/install.adoc | 3 +++ 1 file changed, 3 insertions(+) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/install.adoc b/doc/manuals/chapters/install.adoc index 8397459..112d4f9 100644 --- a/doc/manuals/chapters/install.adoc +++ b/doc/manuals/chapters/install.adoc @@ -24,6 +24,9 @@ apt-get install \ python3-mako \ python3-gi \ ofono \ + patchelf \ + sudo \ + libcap2-bin \ python3-pip pip3 install pydbus pip3 install git+git://github.com/podshumok/python-smpplib.git -- cgit v1.2.3 From f5c83dae62311a671cd37733cba666331b9b0e74 Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Thu, 2 Nov 2017 15:48:10 +0100 Subject: OsmoGSMTester: Installation: change some confusing terminology It's difficult to understand when it referrs to jenkins job in general and when it talks about specific jenkins jobs that builds binaries required for osmo-gsm-tester and the ones which run osmo-gsm-tester. As a result, it's difficult to understand which sections apply to each host in case more than one host is used. Change-Id: I5c882e77b469629028b8d773053783e18f3d1737 --- doc/manuals/chapters/install.adoc | 22 +++++++++++----------- doc/manuals/chapters/trial.adoc | 3 +-- 2 files changed, 12 insertions(+), 13 deletions(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/install.adoc b/doc/manuals/chapters/install.adoc index 112d4f9..5f6f1bc 100644 --- a/doc/manuals/chapters/install.adoc +++ b/doc/manuals/chapters/install.adoc @@ -9,7 +9,7 @@ named 'jenkins' that belong to group 'osmo-gsm-tester'. The user configuration for manual test runs and/or a different user name is identical, simply replace the user name or group. -=== Dependencies +=== Osmo-gsm-tester Dependencies On a Debian/Ubuntu based system, these commands install the packages needed to run the osmo-gsm-tester.py code, i.e. install these on your main unit: @@ -46,7 +46,7 @@ apt-get install libuhd-dev uhd-host ---- [[jenkins_deps]] -==== Jenkins Build Dependencies +==== Osmocom Build Dependencies Each of the jenkins builds requires individual dependencies. This is generally the same as for building the software outside of osmo-gsm-tester and will not @@ -57,8 +57,8 @@ osmo-bts-sysmo build needs the sysmoBTS SDK installed on the build slave, which should match the installed sysmoBTS firmware. -[[configure_build_slave]] -=== Jenkins Build Slave +[[configure_jenkins_slave]] +=== Jenkins Build and Run Slave ==== Create 'jenkins' User on Main Unit @@ -140,8 +140,8 @@ ssh -i /usr/local/jenkins/keys/osmo-gsm-tester-rnd jenkins@$main_unit_ip exit ---- -[[install_add_build_slave]] -==== Add Build Slave +[[install_add_jenkins_slave]] +==== Add Jenkins Slave In the jenkins web UI, add a new build slave for the osmo-gsm-tester: @@ -253,10 +253,10 @@ with "osmo-bts-trx". ==== Add Run Job -This is the build job that actually runs the tests on the GSM hardware: +This is the jenkins job that runs the tests on the GSM hardware: -* It sources the artifacts from the build jobs. -* It runs on the osmo-gsm-tester main unit's build slave. +* It sources the artifacts from jenkins' build jobs. +* It runs on the osmo-gsm-tester main unit. Here is the configuration for the run job: @@ -265,7 +265,7 @@ Here is the configuration for the run job: Configure this to taste, for example: ** 'Max # of build to keep': "20" * 'Restrict where this project can be run': "osmo-gsm-tester" + - (to match the 'Label' configured in <>). + (to match the 'Label' configured in <>). * 'Source Code Management': ** 'Git' *** 'Repository URL': "git://git.osmocom.org/osmo-gsm-tester" @@ -332,7 +332,7 @@ Details: === Install osmo-gsm-tester on Main Unit -This assumes you have already created the jenkins user (see <>). +This assumes you have already created the jenkins user (see <>). ==== User Permissions diff --git a/doc/manuals/chapters/trial.adoc b/doc/manuals/chapters/trial.adoc index 928ee28..86bf12b 100644 --- a/doc/manuals/chapters/trial.adoc +++ b/doc/manuals/chapters/trial.adoc @@ -3,7 +3,7 @@ A trial is a set of pre-built binaries to be tested. They are typically built by jenkins using the build scripts found in osmo-gsm-tester's source in the -'contrib/' dir, see <>. +'contrib/' dir, see <>. A trial comes in the form of a directory containing a number of '*.tgz' tar archives as well as a 'checksums.md5' file to verify the tar archives' @@ -20,4 +20,3 @@ will point at the most recently created run dir. This run dir will accumulate: * stdout and stderr outputs of the binaries * a test log * *TODO*: jenkins parsable XML reports - -- cgit v1.2.3 From 68ac2401d47bf5aef4d6316f0b1d051806da9ef6 Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Thu, 2 Nov 2017 15:56:04 +0100 Subject: OsmoGSMTester: Move TODO comment to a redmine task Following task has been created: OS#2612 Change-Id: I79837e49f3e6af4254e9f0c7f53037eae66cda6d --- doc/manuals/chapters/install.adoc | 2 -- 1 file changed, 2 deletions(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/install.adoc b/doc/manuals/chapters/install.adoc index 5f6f1bc..aaf4d39 100644 --- a/doc/manuals/chapters/install.adoc +++ b/doc/manuals/chapters/install.adoc @@ -444,8 +444,6 @@ packets may result in a feedback loop: SSH activity to send tcpdump's output to your terminal is in turn is picked up in the tcpdump trace, and so forth. When testing 'tcpdump' access, make sure to have proper filter expressions in place. -TODO: allow skipping pcaps by configuration if access to tcpdump is not wanted - ==== Allow Core Files In case a binary run for the test crashes, a core file of the crash should be -- cgit v1.2.3 From 8ad5e6abbcccb02e40d8377d6ff0c922a37b1a1d Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Thu, 2 Nov 2017 16:08:05 +0100 Subject: OsmoGSMTester: Document how to setup main unit to set CAP_NET_RAW as non-root Change-Id: I011beaa929efcabe9a9dc4f9c7222ba36fa2aae4 --- doc/manuals/chapters/install.adoc | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/install.adoc b/doc/manuals/chapters/install.adoc index aaf4d39..146dae1 100644 --- a/doc/manuals/chapters/install.adoc +++ b/doc/manuals/chapters/install.adoc @@ -486,6 +486,36 @@ adding the jenkins user to the 'usrp' group: gpasswd -a jenkins usrp ---- +==== Allow CAP_NET_RAW capability + +Certain binaries require 'CAP_NET_RAW' to be set, like 'osmo-bts-octphy' as it +uses a 'AF_PACKET' socket. + +To be able to set the following capability without being root, osmo-gsm-tester +uses sudo to gain permissions to set the capability. + +This is the script that osmo-gsm-tester expects on the main unit: + +---- +echo /usr/local/bin/osmo-gsm-tester_setcap_net_raw.sh < /etc/sudoers.d/osmo-gsm-tester_setcap_net_raw +chmod 0440 /etc/sudoers.d/osmo-gsm-tester_setcap_net_raw +---- + +The script file name 'osmo-gsm-tester_setcap_net_raw.sh' is important, as +osmo-gsm-tester expects to find a script with this name in '$PATH' at run time. + + ==== Log Rotation To avoid clogging up /var/log, it makes sense to choose a sane maximum log size: -- cgit v1.2.3 From 264829e1365a7e1a3450a779cfa2f9f0137356ed Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Thu, 2 Nov 2017 16:43:04 +0100 Subject: OsmoGSMTester: Update resources cfg documentation Change-Id: I6ec9fc5468ce6ead52d9c8b35d8991cac4bfa97e --- doc/manuals/chapters/config.adoc | 49 +++++++++++++++++++++++++++++++--------- 1 file changed, 38 insertions(+), 11 deletions(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/config.adoc b/doc/manuals/chapters/config.adoc index 7c06392..335a603 100644 --- a/doc/manuals/chapters/config.adoc +++ b/doc/manuals/chapters/config.adoc @@ -92,9 +92,11 @@ These kinds of resource are known: - 'osmo-bts-trx' - 'osmo-bts-octphy' - 'ipa-nanobts' + 'ipa_unit_id'::: + ip.access unit id to be used by the BTS, written into BTS and BSC config. 'addr'::: - remote IP address of the BTS, used to start the BTS and tell it where - to find the OsmoNITB. + Remote IP address of the BTS for BTS like sysmoBTS, and local IP address + to bind to for locally run BTS such as osmo-bts-trx. 'band'::: GSM band that this BTS shoud use (*TODO*: allow multiple bands). One of: - 'GSM-1800' @@ -109,8 +111,11 @@ These kinds of resource are known: only used for osmo-bts-octphy. (*TODO*: and nanobts??) 'net_device':::: Local network device to reach the TRX's 'hw_addr' at, only used for - osmo-bts-octphy. - + osmo-bts-octphy. Example: 'eth0'. + 'nominal_power':::: + Nominal power to be used by the TRX. + 'max_power_red':::: + Max power reduction to apply to the nominal power of the TRX. 'arfcn':: List of ARFCNs to use for running BTSes, which defines the actual RF frequency bands used. @@ -118,24 +123,46 @@ These kinds of resource are known: ARFCN number, see e.g. https://en.wikipedia.org/wiki/Absolute_radio-frequency_channel_number (note that the resource type 'arfcn' contains an item trait also named - 'arfcn') + 'arfcn'). 'band'::: GSM band name to use this ARFCN for, same as for 'bts:band' above. 'modem':: List of modems reachable via ofono and information on the inserted SIM - card. (Note: the MSISDN is allocated dynamically in test scripts) + card. (Note: the MSISDN is allocated dynamically in test scripts). 'label'::: - human readable label for your own reference + Human readable label for your own reference, which also appears in logs. 'path'::: - ofono's path for this modem, like '/modemkind_99' + Ofono's path for this modem, like '/modemkind_99'. 'imsi'::: - IMSI of the inserted SIM card, like '"123456789012345"' + IMSI of the inserted SIM card, like '"123456789012345"'. 'ki'::: 16 byte authentication/encryption KI of the inserted SIM card, in hexadecimal notation (32 characters) like + - '"00112233445566778899aabbccddeeff"' (*TODO*: authentication algorithm, - currently always comp128v1) + '"00112233445566778899aabbccddeeff"'. + 'auth_algo'::: + Authentication algorithm to be used with the SIM card. One of: + - 'none' + - 'xor' + - 'comp128v1' + 'ciphers'::: + List of ciphers that this modem supports, used to match + requirements in suites or scenarios. Any combination of: + - 'a5_0' + - 'a5_1' + - 'a5_2' + - 'a5_3' + - 'a5_4' + - 'a5_5' + - 'a5_6' + - 'a5_7' + 'features'::: + List of features that this modem supports, used to match requirements in + suites or scenarios. Any combination of: + - 'sms' + - 'gprs' + - 'voice' + - 'ussd' Side note: at first sight it might make sense to the reader to rather structure e.g. the 'ip_address' or 'arfcn' configuration as + -- cgit v1.2.3 From 122306cf57b0119df399a27988e63b2bfd603b8b Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Thu, 2 Nov 2017 16:45:12 +0100 Subject: OsmoGSMTester: Remove resolved TODO Change-Id: Ie0f18293e566a690d2434d08cbaaf2fdf71d88e4 --- doc/manuals/chapters/config.adoc | 2 -- 1 file changed, 2 deletions(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/config.adoc b/doc/manuals/chapters/config.adoc index 335a603..8176b45 100644 --- a/doc/manuals/chapters/config.adoc +++ b/doc/manuals/chapters/config.adoc @@ -205,8 +205,6 @@ Example of a 'default-suites.conf' file: - voice:trx+dyn_ts ---- -*TODO*: voice is not actually implemented yet - === 'defaults.conf' (optional) Each binary run by osmo-gsm-tester, e.g. 'osmo-nitb' or 'osmo-bts-sysmo', -- cgit v1.2.3 From 6fa619923789a9169a15291047928510ef34d499 Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Thu, 2 Nov 2017 16:57:22 +0100 Subject: OsmoGSMTester: Update defaults.conf example Change-Id: If12df88b4088ecec6d6cb20c83a693c019b8af4a --- doc/manuals/chapters/config.adoc | 45 +++++++++++++++++++++++++++------------- 1 file changed, 31 insertions(+), 14 deletions(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/config.adoc b/doc/manuals/chapters/config.adoc index 8176b45..3f8cb44 100644 --- a/doc/manuals/chapters/config.adoc +++ b/doc/manuals/chapters/config.adoc @@ -217,31 +217,50 @@ configuration values like the network name, encryption algorithm or timeslot channel combinations are in fact not resources (only the nitb's interface address is). These additional settings may be provided by the scenario configurations, but in case the provided scenarios leave some values unset, -they are taken from this 'defaults.conf'. (A 'scenario.conf' providing a -similar setting always has precedence over the values given in a -'defaults.conf'). - -*TODO* better match this format with 'resources.conf'? +they are taken from this 'defaults.conf'. (A 'scenario.conf' or a +'resources.conf' providing a similar setting always has precedence over the +values given in a 'defaults.conf'). Example of a 'defaults.conf': ---- nitb: net: - mcc: 1 - mnc: 868 - short_name: osmo-gsm-tester - long_name: osmo-gsm-tester + mcc: 901 + mnc: 70 + short_name: osmo-gsm-tester-nitb + long_name: osmo-gsm-tester-nitb + auth_policy: closed + encryption: a5_0 + +bsc: + net: + mcc: 901 + mnc: 70 + short_name: osmo-gsm-tester-msc + long_name: osmo-gsm-tester-msc auth_policy: closed - encryption: a5 0 + encryption: a5_0 + authentication: optional -nitb_bts: +msc: + net: + mcc: 901 + mnc: 70 + short_name: osmo-gsm-tester-msc + long_name: osmo-gsm-tester-msc + auth_policy: closed + encryption: a5_0 + authentication: optional + +bsc_bts: location_area_code: 23 base_station_id_code: 63 stream_id: 255 osmobsc_bts_type: sysmobts trx_list: - - max_power_red: 22 + - nominal_power: 23 + max_power_red: 0 arfcn: 868 timeslot_list: - phys_chan_config: CCCH+SDCCH4 @@ -253,5 +272,3 @@ nitb_bts: - phys_chan_config: TCH/F_TCH/H_PDCH - phys_chan_config: TCH/F_TCH/H_PDCH ---- - -*TODO*: detailed descriptions -- cgit v1.2.3 From 0b512ba1b90f27d995a4ce22660f7e9ee34b6ec9 Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Thu, 2 Nov 2017 17:16:21 +0100 Subject: OsmoGSMTester: Improve Trial section content Change-Id: I8d74b02166ea33ad9ab7f987894f4f02064fbebc --- doc/manuals/chapters/trial.adoc | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/trial.adoc b/doc/manuals/chapters/trial.adoc index 86bf12b..bc9fe05 100644 --- a/doc/manuals/chapters/trial.adoc +++ b/doc/manuals/chapters/trial.adoc @@ -18,5 +18,14 @@ will point at the most recently created run dir. This run dir will accumulate: * the rendered configuration files used to run the binaries * stdout and stderr outputs of the binaries +* pcap files for processes doing relevant network communication * a test log -* *TODO*: jenkins parsable XML reports +* jenkins parsable XML (Junit) reports + +The script in 'contrib/jenkins-run.sh' takes care of related tasks such as + +* creating the dir structure, +* generating md5 sums for the various tar.gz containing software builds to be tested, +* cleaning up after the build, +* saving extra logs such as journalctl output from ofonod, +* generating a final .tar.gz file with all the logs and reports. -- cgit v1.2.3 From 6131f35c80c8b4abe7cdef5aced559014502b0fc Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Thu, 2 Nov 2017 14:45:46 +0100 Subject: OsmoGSMTester: Add scenarios_dir section It explains how scenario combination works Change-Id: I3f89bd3d71400da14cda7ea8bb9c190fe80a539f --- doc/manuals/chapters/config.adoc | 55 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/config.adoc b/doc/manuals/chapters/config.adoc index 3f8cb44..a56c4ad 100644 --- a/doc/manuals/chapters/config.adoc +++ b/doc/manuals/chapters/config.adoc @@ -58,6 +58,61 @@ If you would like to set up several separate configurations (not typical), note that the 'state_dir' is used to reserve resources, which only works when all configurations that share resources also use the same 'state_dir'. +[[scenarios_dir]] +==== 'scenarios_dir' + +This dir contains scenario configuration files. + +Scenarios define constraints to serve the resource requests of a 'suite.conf', +to select specific resources from the general resource pool specified in 'resources.conf'. + +All 'times' attributes are expanded before matching. For example, if a 'suite.conf' +requests two BTS, we may enforce that both BTS should be of type 'osmo-bts-sysmo' in +these ways: + +---- +resources: + bts: + - type: osmo-bts-sysmo + - type: osmo-bts-sysmo +---- + +or alternatively, + +---- +resources: + bts: + - times: 2 + type: osmo-bts-sysmo +---- + +If only one resource is specified in the scenario, then the resource allocator +assumes the restriction is to be applied to the first resource and that remaining +resources have no restrictions to be taken into consideration. + +To apply restrictions only on the second resource, the first element can be left +emtpy, like: + +---- +resources: + bts: + - {} + - type: osmo-bts-sysmo +---- + +On the 'osmo_gsm_tester.py' command line and the 'default_suites.conf', any number of +such scenario configurations can be combined in the form: + +---- +:[+[+...]] +---- + +e.g. + +---- +my_suite:sysmo+tch_f+amr +---- + [[resources_conf]] === 'resources.conf' -- cgit v1.2.3 From dfdb7033c3192ecfe42b113126907cbb68e9c704 Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Thu, 2 Nov 2017 17:50:08 +0100 Subject: OsmoGSMTester: Add suites_dir section Change-Id: Ie25fd742f484981f5e5b25397c2637eda38f0424 --- doc/manuals/chapters/config.adoc | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/config.adoc b/doc/manuals/chapters/config.adoc index a56c4ad..def9843 100644 --- a/doc/manuals/chapters/config.adoc +++ b/doc/manuals/chapters/config.adoc @@ -58,6 +58,16 @@ If you would like to set up several separate configurations (not typical), note that the 'state_dir' is used to reserve resources, which only works when all configurations that share resources also use the same 'state_dir'. +[[suites_dir]] +==== 'suites_dir' + +Suites contain a set of tests which are designed to be run together to test a +set of features given a specific set of resources. As a result, resources are +allocated per suite and not per test. + +Tests for a given suite are located in the form of '.py' python scripts in the +same directory where the 'suite.conf' lays. + [[scenarios_dir]] ==== 'scenarios_dir' -- cgit v1.2.3 From 21f2b8f1298b120f13af10dc6fec0d905b6ba9ee Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Thu, 2 Nov 2017 17:57:58 +0100 Subject: OsmoGSMTester: Add state_dir section Change-Id: Ie12e3933747a4e698de59ff9ac57281e9f261d3d --- doc/manuals/chapters/config.adoc | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/config.adoc b/doc/manuals/chapters/config.adoc index def9843..7e250e0 100644 --- a/doc/manuals/chapters/config.adoc +++ b/doc/manuals/chapters/config.adoc @@ -54,10 +54,32 @@ suites_dir: '/usr/local/src/osmo-gsm-tester/suites' scenarios_dir: './scenarios' ---- +[[state_dir]] +==== 'state_dir' + +It contains global or system-wide state for osmo-gsm-tester. In a typical state +dir you can find the following files: + +'last_used_msisdn.state':: + Contains last used msisdn number, which is automatically increased every + time osmo-gsm-tester needs to assign a new subscriber in a test. +'lock':: + Lock file used to implement a mutual exclusion zone around the + 'reserved_resources.state' file. +'reserved_resources.state':: + File containing a set of reserved resources by any number of + osmo-gsm-tester instances. Each osmo-gsm-tester instance is responsible + to clear its resources from the list once it is done using them and are + no longer reserved. + If you would like to set up several separate configurations (not typical), note that the 'state_dir' is used to reserve resources, which only works when all configurations that share resources also use the same 'state_dir'. +This way, several concurrent users of osmo-gsm-tester (ie. several +osmo-gsm-tester processes running in parallel) can run without interfering with +each other (e.g. using same ARFCN, same IP or same ofono modem path). + [[suites_dir]] ==== 'suites_dir' -- cgit v1.2.3 From e617d2a844d55615748e60dd3791ccc50307fefb Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Thu, 2 Nov 2017 18:04:06 +0100 Subject: OsmoGsmTester: Put several permission categories under cat User Permission Change-Id: Ie9f846af0311d768c5dd6f9da572c8f6482f4d39 --- doc/manuals/chapters/install.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/install.adoc b/doc/manuals/chapters/install.adoc index 146dae1..d19f909 100644 --- a/doc/manuals/chapters/install.adoc +++ b/doc/manuals/chapters/install.adoc @@ -444,7 +444,7 @@ packets may result in a feedback loop: SSH activity to send tcpdump's output to your terminal is in turn is picked up in the tcpdump trace, and so forth. When testing 'tcpdump' access, make sure to have proper filter expressions in place. -==== Allow Core Files +===== Allow Core Files In case a binary run for the test crashes, a core file of the crash should be written. This requires a limit rule. Create a file with the required rule: @@ -464,7 +464,7 @@ contains stdout and stderr for that process (because this dir is set as CWD). sysctl -w kernel.core_pattern=core ---- -==== Allow Realtime Priority +===== Allow Realtime Priority Certain binaries should be run with real-time priority, like 'osmo-bts-trx'. Add this permission on the main unit: @@ -477,7 +477,7 @@ echo "@osmo-gsm-tester - rtprio 99" > /etc/security/limits.d/osmo-gsm-tester_all Re-login the user to make these changes take effect. [[user_config_uhd]] -==== UHD +===== UHD Grant permission to use the UHD driver to run USRP devices for osmo-bts-trx, by adding the jenkins user to the 'usrp' group: @@ -486,7 +486,7 @@ adding the jenkins user to the 'usrp' group: gpasswd -a jenkins usrp ---- -==== Allow CAP_NET_RAW capability +===== Allow CAP_NET_RAW capability Certain binaries require 'CAP_NET_RAW' to be set, like 'osmo-bts-octphy' as it uses a 'AF_PACKET' socket. -- cgit v1.2.3 From 4c47659fb50ae9cc3b66d75e257d590ee8b52e08 Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Fri, 17 Nov 2017 17:16:54 +0100 Subject: OsmoGSMTester: Update import test->testenv Latest changes in osmo-gsm-tester require this import change. Depends on: osmo-gsm-tester I520bd046cb09042b5567d967f951f050e4e02e85 Change-Id: I0f7f7d0353014b7ef8a0c5a7707c91b2613be79a --- doc/manuals/chapters/intro.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/manuals') diff --git a/doc/manuals/chapters/intro.adoc b/doc/manuals/chapters/intro.adoc index 55f1a5e..14daba4 100644 --- a/doc/manuals/chapters/intro.adoc +++ b/doc/manuals/chapters/intro.adoc @@ -161,7 +161,7 @@ A typical single test script (part of a suite) may look like this: ---- #!/usr/bin/env python3 -from osmo_gsm_tester.test import * +from osmo_gsm_tester.testenv import * hlr = suite.hlr() bts = suite.bts() -- cgit v1.2.3