nntool.eu

Overview

BEREC–the Body of European Regulators for Electronic Communications–assigned the contract for development, implementation and validation of the Net Neutrality (NN) Reference Measurement System in July 2018.

The system enables the monitoring of the Quality of Service (QoS) and Quality of Experience (QoE) of Internet Access Services (IAS) as well as aspects of traffic management and serves as a reference for regulatory authorities (NRAs). This decision is another important milestone in the harmonization and standardization of broadband testing in Europe.

The objective of the measurement tool is to provide a reference system for monitoring the QoS aspects of IAS, such as speed and delay, as well as aspects of traffic management such as the blocking and throttling of Internet-based applications.

A specific objective is increased levels of harmonization of NN-related IAS measurement metrics and methodology.

In the long term, the BEREC tool could be a platform enabling NRAs to share knowledge, experience and expertise, including providing a basis for further piloting and researching the area of measuring quality of internet access services.

Visit https://net-neutrality.tools/ for more information.

Structure

General Components

• docs: Contains the non-component specific documentation, detailed build instructions and the logic to render a single, composite documentation file.

• gradle: Contains gradle related configuration.

• support: Contains the required configuration to run docker with default configuration for the necessary databases.

Libraries

• nettest-shared: Contains resources shared with servers, apps, etc.

• nettest-shared-server: Contains shared resources for the backend.

• couchdb-client/couchdb-spring-boot-autoconfigure/couchdb-spring-boot-starter/spring-data-couchdb: Contains configuration and boilerplate code for the couchDB connection used by the server components.

• ias: Contains the javascript internet access speed measurement code, used by the nntool website.

• ias-android-common: Contains tools needed by the android-demo-app (which are not included in the general android-app).

• ias-android-speed: Contains the java wrapper around the C++ based internet access speed library.

• ias-cpp: Contains the C++ based internet access speed code.

• ias-desktop: Contains the javascript internet access speed code as used by the desktop clients. Additional provides a demo html file with which the internet access speed code can be tested.

• ias-libnntool: Contains utility functionality for the ias-cpp module.

• measurement-agent-swift: Contains extended measurement functionality for the ios-app.

• nettest-shared-server-opendata: Contains shared functionality for providing the measurement data to end users.

• nettest-shared-server-storage-couchdb: Contains shared functionality for interacting with the couchDB.

• nettest-shared-server-storage-postgresql: Contains shared functionality for interacting with the PostgreSQL.

• nntool-shared-swift: Contains utility functionality for the ios-app.

• qos-client-java: Contains the java based Quality of Service measurement code.

• qos-client-android: Contains the Quality of Service measurement code to be used in the android-app.

• qos-client-swift: Contains the Quality of Service measurement code to be used in the ios-app.

• qos-cpp: Contains the C++ based Quality of Service measurement code.

Server Components

• controller-service: Server component that registers measurement agents and gives measurement parameters.

• collector-service: Server component that receives and stores measurements.

• statistic-service: Server component that is responsible for open-data export, generation of statistics and search.

• ias-server: Server component that is the remote counterpart for all internet access speed measurements.

• loadbalancing-service: Server component that assigns each measurement request its ias-server. Manages the workloads for each ias-server instance, so that no measurements are limited on the server side.

• map-service: Server component that provides image overlay tiles for the map display in the client components.

• opendata-collector-service: Server component that receives and stores measurements, for use as opendata.

• qos-service: Server component that is the remote counterpart for Quality of Service measurements.

• result-service: Server component to fetch measurements results from.

• search-service: Server component to provide Elasticsearch based results.

Client Components

• android-app: Code for the android application.

• ios-app: Code for the iOS application.

• nntool-typescript: Code for all supported websites, i.e. the general nettest website, the portal website and the electron-based, desktop apps.

• ias-android-demo: Code for the demo android application, contains only a bare-bones user interface around the ias-android-speed library.

• ias-ios: Code for the iOS speed measurement and the demo iOS application.

Usage Guide

controller-service

The controller-service can be started as standalone Java application as well as deployed to a servlet container (e.g. Tomcat).

• To start the controller on the command line run ./gradlew bootRun -p controller-service inside the Git repository root directory (Starts the embedded server on port 8080).

• To start the controller in an IDE run the main method of the class at.alladin.nettest.service.controller.ControllerServiceApplication

Swagger-UI will then be available via http://localhost:<port>/swagger-ui.html.

collector-service

The collector-service can be started as standalone Java application as well as deployed to a servlet container (e.g. Tomcat).

• To start the collector on the command line run ./gradlew bootRun -p collector-service inside the Git repository root directory (Starts the embedded server on port 8081).

• To start the collector in an IDE run the main method of the class at.alladin.nettest.service.collector.CollectorServiceApplication

Swagger-UI will then be available via http://localhost:<port>/swagger-ui.html.

statistic-service

The statistic-service can be started as standalone Java application as well as deployed to a servlet container (e.g. Tomcat).

• To start the collector on the command line run ./gradlew bootRun -p statistic-service inside the Git repository root directory (Starts the embedded server on port 8083).

• To start the collector in an IDE run the main method of the class at.alladin.nettest.service.statistic.StatisticServiceApplication

Swagger-UI will then be available via http://localhost:<port>/swagger-ui.html.

loadbalancing-service

The loadbalancing-service can be started as standalone Java application as well as deployed to a servlet container (e.g. Tomcat).

• To start the collector on the command line run ./gradlew bootRun -p loadbalancing-service inside the Git repository root directory (Starts the embedded server on port 8087).

• To start the collector in an IDE run the main method of the class at.alladin.nettest.service.loadbalancing.LoadbalancingServiceApplication

Swagger-UI will then be available via http://localhost:<port>/swagger-ui.html.

map-service

The map-service can be started as standalone Java application as well as deployed to a servlet container (e.g. Tomcat).

• To start the collector on the command line run ./gradlew bootRun -p map-service inside the Git repository root directory (Starts the embedded server on port 8084).

• To start the collector in an IDE run the main method of the class at.alladin.nettest.service.map.MapServiceApplication

Swagger-UI will then be available via http://localhost:<port>/swagger-ui.html.

opendata-collector-service

The opendata-collector-service can be started as standalone Java application as well as deployed to a servlet container (e.g. Tomcat).

• To start the collector on the command line run ./gradlew bootRun -p opendata-collector-service inside the Git repository root directory (Starts the embedded server on port 8086).

• To start the collector in an IDE run the main method of the class at.alladin.nettest.service.collector.opendata.OpendataCollectorServiceApplication

Swagger-UI will then be available via http://localhost:<port>/swagger-ui.html.

qos-service

The qos-service can be started as standalone Java application as well as deployed to a servlet container (e.g. Tomcat).

• To start the collector in an IDE run the main method of the class at.alladin.nntool.qos.testserver.TestServer

result-service

The result-service can be started as standalone Java application as well as deployed to a servlet container (e.g. Tomcat).

• To start the collector on the command line run ./gradlew bootRun -p result-service inside the Git repository root directory (Starts the embedded server on port 8082).

• To start the collector in an IDE run the main method of the class at.alladin.nettest.service.result.ResultServiceApplication

Swagger-UI will then be available via http://localhost:<port>/swagger-ui.html.

search-service

The search-service can be started as standalone Java application as well as deployed to a servlet container (e.g. Tomcat).

• To start the collector on the command line run ./gradlew bootRun -p search-service inside the Git repository root directory (Starts the embedded server on port 8083).

• To start the collector in an IDE run the main method of the class at.alladin.nettest.service.search.SearchServiceApplication

Swagger-UI will then be available via http://localhost:<port>/swagger-ui.html.

Development

For development with Eclipse make sure to run ./gradlew eclipse task to generate eclipse project files to make annotation processing work.

Milestones

Milestone 1

Deliverables for milestone 1 are located inside docs/project_management/milestones/1/deliverables directory.

Table 1. Deliverables

Deliverable	Description	Files
Deliverable 1	The data models of the applicable measurement function-specific subtrees of the base LMAP control data model given in YANG, JSON Schema or as an OpenAPI specification	control_data_model_json_schema.json, controller_service_open_api_spec.yaml, controller_service_swagger_2.0_spec.json
Deliverable 2	The data models of the applicable measurement function-specific subtrees of the base LMAP report data model given in YANG, JSON Schema or as an OpenAPI specification	report_data_model_json_schema.json, collector_service_open_api_spec.yaml, collector_service_swagger_2.0_spec.json
Deliverable 3	Example JSON configuration files for above models	example_control_initiate_measurement.json, example_control_measurement_parameters.json, example_report_send_result_to_server.json, example_get_measurement_from_server.json
Deliverable 4	Specification of the Public REST API for retrieving results as Open data	statistic_service_open_api_spec.yaml, statistic_service_swagger_2.0_spec.json
Deliverable 5	Specification of the storage structures (e.g. database ERM diagrams, JSON-Schema files for document-based storage)	primary_db_data_model_json_schema.json, secondary_db_postgresql_schema.sql, secondary_db_postgresql_eer_diagram.svg, secondary_db_postgresql_eer_diagram.pdf

Table 2. Content Description

File	Description
control_data_model_json_schema.json	Contains the control data model of the controller REST API as JSON Schema.
controller_service_open_api_spec.yaml	Contains the controller’s entire REST API specification in OpenAPI 3.0 format. Converted from controller_service_swagger_2.0_spec.json.
report_data_model_json_schema.json	Contains the report data model of the collector REST API as JSON Schema.
collector_service_open_api_spec.yaml	Contains the collector’s entire REST API specification in OpenAPI 3.0 format. Converted from collector_service_swagger_2.0_spec.json.
example_control_initiate_measurement.json	Example request body sent from the client to the server to initiate a measurement.
example_control_measurement_parameters.json	Example response body including measurement parameters sent by the server to the client as response to the initiation request.
example_report_send_result_to_server.json	Example request body sent from the client to the server to submit measurement results.
example_get_measurement_from_server.json	Example response body sent from the server to the client when accessing a measurement from the database. Open-Data export uses the same model but is anonymized.
statistic_service_open_api_spec.yaml	Contains the export and open-data REST API documentation as OpenAPI 3.0 specification.
primary_nosql_db_data_model_json_schema.json	Contains the data model used for the primary NoSQL database, which will be either a document or key/value store database.
secondary_db_postgresql_schema.sql	Contains the SQL schema (PostgreSQL specific) for the secondary database, which will be used to calculate statistics, heat maps, etc.
secondary_db_postgresql_eer_diagram.svg	Contains the EER diagram for the secondary database according to the SQL schema as SVG file.
secondary_db_postgresql_eer_diagram.pdf	Contains the EER diagram for the secondary database according to the SQL schema as PDF file.

Table 3. Additional Files

File	Description
collector_service_swagger_2.0_spec.json	Collector service Swagger 2.0 API specification generated by springfox/swagger.
controller_service_swagger_2.0_spec.json	Controller service Swagger 2.0 API specification generated by springfox/swagger.
statistic_service_swagger_2.0_spec.json	Statistic service Swagger 2.0 API specification generated by springfox/swagger.

Table 4. Diagrams (directly inside /docs directory)

File	Description
reference_system_architecture.pdf	This diagram shows the overall system architecture (servers, components, connections) of the reference system.
portal_architecture.pdf	This diagram shows the architecture of the portal including the open-data import mechanism.
measurement_sequence_diagram.pdf	This sequence diagram shows the workflow of a single IAS and QoS measurement from the initation to the result submission.
registration_sequence_diagram.pdf	This sequence diagram shows how clients are registered on the controller.
history_sequence_diagram.pdf	This sequence diagram shows the workflow when the client requests its own measurement history and a single result.